pdf2 1.7.0

A PDF 2.0 (ISO 32000-2) reader, writer and text extractor.
Documentation
# Performance and memory

Numbers measured by `crates/pdf2-bench` and checked in CI against
[`performance-baseline.json`](performance-baseline.json).

## Method

```sh
cargo run --release -p pdf2-bench -- --check            # the gate CI runs
cargo run --release -p pdf2-bench                       # measure and print
cargo run --release -p pdf2-bench -- --json             # machine-readable
cargo run --release -p pdf2-bench -- --write-baseline docs/performance-baseline.json
```

The binary has no dependencies of its own. It builds one corpus, measures it and
reports five metrics per corpus group plus one process-level number:

| Metric | What it measures | Unit |
| --- | --- | --- |
| `read_mb_s` | open + page walk with content decoding + text extraction, per file size | MB/s (higher better) |
| `pages_s` | pages walked with their content decoded | pages/s (higher better) |
| `text_pages_s` | pages whose text was extracted | pages/s (higher better) |
| `allocations` | allocation calls for one full read pass | count (lower better) |
| `alloc_bytes` | bytes requested for one full read pass | bytes (lower better) |
| `process.peak_rss_kib` | process high-water resident memory | KiB (informational) |

Measurement details, so a number can be reproduced and judged:

- Timings are the **median of 7 samples**; each sample repeats the operation
  enough times to last at least 20 ms, and one warm-up sample is discarded.
  Without that batching, a 500-byte fixture would be a few microseconds and the
  median would track the scheduler rather than the code.
- Allocation numbers come from a counting `GlobalAlloc` installed by the
  benchmark. They are deterministic for a given input: on this machine they are
  bit-identical between runs, which is what makes them a reliable gate.
- Peak RSS uses `VmHWM` on Linux; macOS only exposes the current RSS via
  `ps -o rss=`, so it is recorded but not gated (allocation counts are the
  memory guard).
- The corpus is the committed fixtures (minus the encrypted one) plus files
  generated by this crate's own writer: 1, 100 and 1000 pages, and a 1 MB
  content stream. `PDF2_CORPUS=<dir>` adds real-world PDFs to the report; those
  numbers are never gated because they are not part of the committed baseline.

## The gate

```sh
cargo run --release -p pdf2-bench -- --check
```

- **Deterministic metrics** (`allocations`, `alloc_bytes`) are compared on every
  platform, against whichever baseline entry has them. Growing more than **10%**
  fails the run. This is what CI gates: the runner is Linux and has no timing
  baseline of its own.
- **Timing metrics** are compared against the entry for the current `os-arch`
  only. A platform without an entry has its timings printed and skipped, never
  guessed. The tolerance is the same **10%**; when a metric looks broken the
  benchmark measures once more before failing, so ordinary scheduler noise does
  not trip the gate (the observed cross-process spread is up to ~15% for the
  sub-millisecond groups on the reference machine, so the retry matters).
- `--tolerance <fraction>` overrides the tolerance for an experiment;
  `--runs <n>` changes the sample count.

## Reference numbers

Measured 2026-11-17 with the committed baseline, release profile,
`rustc 1.100.0`, Apple M3 (8 cores), macOS `aarch64`:

| Group | `read_mb_s` | `pages_s` | `text_pages_s` | allocations | alloc bytes |
| --- | --- | --- | --- | --- | --- |
| fixtures (36 files) | 139.0 | 182 294 | 127 825 | 9 765 | 828 464 |
| objects-65000 | 347.5 | 93 | 93 | 86 763 | 9 153 927 |
| pages-1 | 65.7 | 75 651 | 69 934 | 223 | 20 312 |
| pages-100 | 31.9 | 421 873 | 296 852 | 9 654 | 986 492 |
| pages-1000 | 30.5 | 423 671 | 295 639 | 95 313 | 9 843 844 |
| stream-1mb | 582.7 | 8 693 | 574 | 257 | 16 797 071 |

Peak RSS for the whole run: 27 504 KiB.

The `fixtures` group is every `*.pdf` in `tests/fixtures` except the encrypted
one, so **adding a fixture moves these five numbers** and the baseline must be
re-recorded in the same change — that is why the four fixtures of 1.4.0 (tiling,
colour-key, `Tr` and the Type 3 clip) each arrived with a baseline commit.

What the numbers say:

- Opening is dominated by cross-reference work, so `read_mb_s` grows with page
  count but not with stream size; a 1 MB stream is read at ~580 MB/s because it
  is mostly copied rather than parsed.
- Text extraction costs roughly 0.7× the page walk on generated pages (same
  glyph mapping path, plus the interpreter), and is the slowest metric for the
  1 MB stream because the content stream is one long text run.
- Per-page allocations are flat at ~95 per generated page (96.5 at 100 pages,
  95.3 at 1000), which is the number to watch when touching the object model.

## Render time

The oracle job times each case's render and compares it with
`corpus/render-budget.tsv`; a page over its budget fails the job with `SLOW`,
the same way a page outside its pixel tolerance fails with `OVER`. The timed
region is the render alone — parsing is what the benchmark suite measures — and
the number is printed beside the verdict so a failure says how far over it went.

The committed budgets were set from the first measured run (2026-11-15,
`ubuntu-latest`, release build, 144 dpi) at **twice** the measured time, or 25 ms
where the page renders in a couple of milliseconds and runner noise dominates:

| Case | Measured | Budget |
| --- | --- | --- |
| `book#1` (embedded TrueType, prose page) | 436.8 ms | 900 ms |
| `calibration#3` (Bézier circle, dashes) | 8.8 ms | 25 ms |
| `calibration#1`, `#2` (colour, caps and joins) | 1.2–2.0 ms | 25 ms |
| `calibration#4`, `#5`, `#9`–`#11` | 0.7–1.1 ms | 25 ms |

`book#1` dominates because it parses and rasterises an embedded font's outlines
for a page of text; that is the case a regression would show up in first.

## Wasm sizes

The smoke crate measures two wasm artifacts and fails when they grow past the
documented budget (`crates/pdf2-wasm-smoke/smoke.mjs`, run by CI):

```sh
cargo build -p pdf2-wasm-smoke --release --target wasm32-unknown-unknown --lib
cargo build -p pdf2-wasm-smoke --release --target wasm32-wasip1 --bin pdf2-wasi-smoke
node --no-warnings crates/pdf2-wasm-smoke/smoke.mjs
```

| Artifact | Raw | Gzip | Gzip budget |
| --- | --- | --- | --- |
| browser module (`wasm32-unknown-unknown`, release) | 443 820 B | 169 974 B | 170 KiB |
| WASI binary (`wasm32-wasip1`, release) | 514 067 B | 192 662 B | 193 KiB |

Measured 2026-11-15 with `rustc 1.99.1` and the release profile.

**All four budgets moved on 2026-11-18 for the painted glyph boxes** (`GlyphBox`,
`render_page_traced`, `PdfDocument.glyphs`): the walker records one entry per glyph it paints and the
binding converts them to page space, which costs **+1 015 gzip** on the browser module (168 959 →
169 974), **+1 097** on the WASI binary (191 565 → 192 662), **+5 561** on the npm bundle (387 275 →
392 836 — the CJK and search tables had already taken it to within 340 bytes of 384 KiB) and **+3 262**
on the demo bundle (531 069 → 534 331). The new ceilings are 170, 193, 388 and 528 KiB. The trade is
the demo's selection bug: a selection over painted text covered a quarter less than the glyphs it
crossed, because only the renderer knows where a glyph landed.

**The WASI budget moved from 180 KiB to 187 KiB on 2026-11-16 for the
two-dimensional fax decoder**: the changing-element model, its mode table and the
reference-position bookkeeping cost **+4 763 gzip bytes** (179 922 → 184 685 as
measured in CI). It is what turns G4 and G3 mixed-mode scans — the format of every
scanned document a decade old — from a reported image into a drawn one, and it is
in-crate: no dependency, so no `no_std` verdict was needed.

**The WASI budget moved from 175 KiB to 180 KiB on 2026-11-16, deliberately**:
the decoded-stream budget (256 MiB, `Error::Limit`, a capped inflate) cost
**+4 620 gzip bytes** on that artifact — 175 302 → 179 922, which is the
security fix's price: refusing a decompression bomb instead of allocating it. The
browser artifact stayed inside its 160 KiB.

**The WASI budget moved from 187 KiB to 188 KiB, and the demo artifact from 516 to
520 KiB, on 2026-11-17, for the same CMap table**: the `UniJIS-UCS2-H` coverage that
took the browser module to 168 959 gzip put the WASI binary at **191 565** (77 bytes
over 187 KiB, measured in CI) and the demo bundle at **531 069** (2 685 over 516 KiB).
Both steps are recorded with their numbers in the same table and paragraph, because a
budget moved without a measurement is just a number that stopped meaning anything.

**The browser budget moved from 162 KiB to 166 KiB on 2026-11-17, for the second CMap
family**: `UniJIS-UCS2-H` is a *Unicode* CMap, so its table is coverage rather than
mapping — stored as 4 629 runs of codes, 9 294 bytes raw — and the artifact measured
**168 959 gzip**, **+4 489** over the 162 KiB build. That is the price of a CJK page
whose font declares a UCS-2 encoding instead of a Shift-JIS one, and it is recorded
rather than hidden: the ASCII half of the CMap is *not* covered (Adobe's `UniJIS`
targets the Japanese CIDs, and the table refuses a code it does not list instead of
inventing it).

**The browser budget moved from 160 KiB to 162 KiB on 2026-11-17, for the extraction
work**: positioned text, search and `/ActualText` live in the library, so the browser
artifact carries them whether or not the renderer is linked — **164 470 gzip** measured
after the `/ActualText` round, against the 160 KiB budget the module was last measured
under at 155 131. The remaining headroom is ~1.4 KiB; the next extraction feature that
does not fit should be a deliberate move again, not a silent one.

**The browser budget moved from 150 KiB to 160 KiB on 2026-11-15, deliberately**:
the crate now ships one predefined CMap, the Adobe-Japan1 `90ms-RKSJ-H` code →
text table (`src/data/japan1_90ms_rksj.bin`, 19 967 B raw, generated by
`cargo xtask cmaps`), which is what makes CJK text extractable at all. It costs
**+13.5 KB gzip** (141 655 → 155 131 with the rest of the 1.2 work). The table is
varint-delta encoded for that reason: as fixed `(code, text)` pairs it cost
31 KB gzip, because pairs of Unicode ideographs do not compress, and the deltas
do. A second CMap is another ~15 KB, so the next one needs the same conversation
rather than a silent bump. `twiggy top`
shows where the bytes go — the largest single contributors after the name and
`.rodata` sections are `sha2::sha512::compress512` (11.2 KB), `miniz_oxide`
inflate (9.4 KB), `sha2::sha256::compress256` (7.9 KB) and
`TextInterpreter::run` (7.1 KB). The budgets leave ~25% headroom, so a normal
refactor fits; a deliberate jump means updating the budget and saying why.

## Wasm package sizes

The `pdf2-wasm` bundle that ships to a browser (wasm-bindgen output: the module
plus its JS glue) is measured by `crates/pdf2-wasm/check.mjs`, which CI runs:

```sh
cargo build -p pdf2-wasm --release --target wasm32-unknown-unknown
wasm-bindgen --target web --no-typescript --out-dir crates/pdf2-wasm/demo/pkg \
    target/wasm32-unknown-unknown/release/pdf2_wasm.wasm
node --no-warnings crates/pdf2-wasm/check.mjs
```

| File | Raw | Gzip |
| --- | --- | --- |
| `pdf2_wasm_bg.wasm` | 1 042 710 B | 360 895 B |
| `pdf2_wasm.js` (glue) | 19 006 B | 4 810 B |

**JPEG 2000 and JBIG2 are features, and the npm bundle did not move for them**
(2026-11-17, [ADR 0007](adr/0007-decoder-features.md)): `/JPXDecode` costs
**+77 523** gzip and `/JBIG2Decode` **+64 145** (both **+140 747**) when they are
compiled in, against **365 734** with neither — measured on the 1.4.0 tree by the
commands above, with `--features jpx,jbig2` on the `cargo build` and gzip level 9.
The default keeps its 364 KiB budget, so the npm package decodes neither; the demo
site loads a second, decoder-enabled artefact with its own **516 KiB** budget
(measured **526 482 gzip** in CI after `/ActualText`; 522 616 after the search tables,
506 481 before them), and `crates/pdf2-oracle` enables
both through its `decoders` feature because it is evidence rather than a shipped
artefact. `check.mjs` measures both artefacts and also asserts the site's bundle is
more than 100 KiB larger than the package's — a demo that silently fell back to the
lean build would otherwise show a blank page where it claims a codec.

The measurement has a trap worth recording: a build that links the decoders only far
enough to read a codestream header measures **+23 410** for both, because the decode
path is unreachable and link-time dead-code elimination removes it. A decoder costs
what its pixels drag in, so the number has to come from a build that decodes.

**The npm budget moved from 378 KiB to 384 KiB on 2026-11-17, for the second CMap
family**: the same `UniJIS-UCS2-H` coverage table that took the browser artifact from
164 470 to 168 959 gzip took the npm bundle from 382 781 to **387 275** — a 203-byte
overrun of 378 KiB, which is a budget that had been chasing one feature at a time.
The step to 384 KiB is deliberately larger than the gap, so the next extraction change
does not spend a round on arithmetic; CI's number runs a few kilobytes above this
machine's, and that is inside the new headroom.

**The bundle moved from 320 KiB to 336 KiB on the same day, for shadings**:
`sh` plus the `/Function` evaluator cost **+7 465 gzip bytes** (327 567 →
335 032) — a gradient is a function evaluated per pixel, and the calculator's
operators are the bulk of it.

**The npm bundle budget moved from 368 KiB to 378 KiB on 2026-11-17, for search**:
`Document::search` is case-insensitive, and Unicode case folding brings its tables
with it — **+11 661 gzip bytes** on the npm bundle (370 258 → 381 919, measured
locally; the 368 KiB budget was set from CI's number, which runs ~3 KB higher). The
alternative was an ASCII-only fold, which would report "case-insensitive" and mean
"for English"; the tables are the price of the claim being true.

**The npm bundle budget moved from 364 KiB to 368 KiB on 2026-11-17, for positioned
text**: the extractor learned `q`/`Q`/`cm` and the text matrix so `Document::spans`
can return page-space line boxes (`ADR 0008`), which cost **+7 474 gzip bytes** —
365 757 → 373 231 measured in CI (370 258 locally, the same ~3 KB toolchain gap the
CFF move recorded). The budget is set from CI's number with the next few kilobytes of
headroom, because CI's is the one the gate compares.

**The npm bundle budget moved from 356 KiB to 364 KiB on 2026-11-17, for tiling
patterns**: the lattice painter, the pattern-dictionary parser and the
parent-stream state stack cost **+4 189 gzip bytes** (361 056 → 365 245, measured in
CI). It buys the two corpus pages that fill with a `/PatternType 1` cell, one of
which selects its pattern from inside a Type 3 char procedure.

**The npm bundle budget moved from 336 KiB to 356 KiB on 2026-11-16, for the
simple-font CFF and Type 3 fonts**: reading a bare CFF's charset *names* and
matching them against the encoding's characters costs **+2 156 gzip bytes**
locally (344 064 → 346 220), and Type 3 glyph procedures — a nested content walk
with its own resources and state — **+7 179** on top (CI measured 353 399). The
two measurements differ by toolchain: a local `wasm32-unknown-unknown` build
produced 346 220 where the release workflow's produced 353 399, so **the budget is
set from CI's number**, with the next 8 KiB step of headroom. The library cost is
what turns an embedded `/Type1C` or Type 3 font from the fallback bitmap alphabet
into the document's own glyphs; no dependency was added for either.

**The npm bundle budget moved from 260 KiB to 320 KiB on 2026-11-16,
deliberately**: `/DCTDecode` support (`zune-jpeg`) costs **+66 759 gzip bytes** on
the module — 241 174 → 307 582 — because a JPEG decoder reads tables, does
Huffman and hands back RGB. The bundle was 245 656 gzip before the feature and
312 415 after. It is the price of drawing the images every office PDF contains
without a C build, and the feature is optional: a size-sensitive caller builds
`pdf2-render` with `default-features = false` and the dependency is not linked.
| **total** | 572 387 B | **198 732 B** |

### Rank 8's budget: 65 000 objects

`crates/pdf2-bench` generates a one-page document with **65 000 objects** in its
cross-reference (`corpus::document_with_objects`, written to the run's scratch
directory, never committed — a four-megabyte table in `tests/fixtures` would be
read by every other measurement, which is the same reason the decompression bomb
is built at test time). It is measured like any group, so the baseline states what
parsing one costs:

| Metric | Value |
| --- | --- |
| `objects-65000.read_mb_s` | 346 MB/s (3.76 MB file) |
| `objects-65000.pages_s` | 93 (≈ 10.7 ms per open and page walk) |
| `objects-65000.allocations` | 86 763 |
| `objects-65000.alloc_bytes` | 9 153 927 |

That is the budget the release claims: opening the file and walking its page tree
stays inside ~11 ms and 9 MB on an `aarch64` machine, and `Document::set_object_limit`
bounds what may be held if a caller wants less.

Budget: **260 KiB gzip** for the pair, ~30% above the measured size, so a
normal change fits and a deliberate jump has to update both the budget here and
the constant in `check.mjs`.

## Budgets

- Allocation counts and bytes: **no growth** is expected; anything above 10% is
  treated as a regression and should either be fixed or the baseline updated
  deliberately, with the reason in the commit message.
- Throughput: within 10% of the committed baseline for a platform that has one.
- Peak RSS: recorded for observation; the allocation counts are the enforced
  memory metric.
- Wasm: gzip size of both artifacts within the table above, checked on every CI
  run.

## Updating the baseline

`--write-baseline docs/performance-baseline.json` replaces this platform's entry
and keeps the others, so a Linux number can be added from CI or a Linux machine
without losing the macOS one. Commit the file only when the change is
intentional, and say which metric moved and why in the commit message.

```sh
# on the machine whose measurements should be recorded:
cargo run --release -p pdf2-bench -- --write-baseline docs/performance-baseline.json
```