pdf2 1.0.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-14 with the committed baseline, release profile,
`rustc 1.99.1`, Apple M3 (8 cores), macOS `aarch64`:

| Group | `read_mb_s` | `pages_s` | `text_pages_s` | allocations | alloc bytes |
| --- | --- | --- | --- | --- | --- |
| fixtures (9 files) | 77.3 | 147 626 | 115 004 | 2 195 | 246 987 |
| pages-1 | 70.5 | 80 758 | 74 614 | 223 | 41 072 |
| pages-100 | 32.5 | 433 382 | 303 205 | 9 459 | 1 050 024 |
| pages-1000 | 30.9 | 432 968 | 303 141 | 93 317 | 10 129 018 |
| stream-1mb | 587.9 | 8 501 | 580 | 257 | 14 720 753 |

Peak RSS for the whole run: 14 640 KiB.

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 ~92 allocations per generated page, which is
  the number to watch when touching the object model.

## 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) | 325 973 B | 120 232 B | 150 KiB |
| WASI binary (`wasm32-wasip1`, release) | 384 483 B | 139 435 B | 175 KiB |

Measured 2026-11-14 with `rustc 1.99.1` and the release profile. `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` | 554 051 B | 194 065 B |
| `pdf2_wasm.js` (glue) | 18 336 B | 4 667 B |
| **total** | 572 387 B | **198 732 B** |

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