pdf2 1.4.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) | 410 421 B | 155 131 B | 160 KiB |
| WASI binary (`wasm32-wasip1`, release) | 479 415 B | 179 922 B | 187 KiB |

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

**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 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` | 883 830 B | 307 582 B |
| `pdf2_wasm.js` (glue) | 19 047 B | 4 833 B |

**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 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
```