pdf2 1.1.0

A PDF 2.0 (ISO 32000-2) reader, writer and text extractor.
Documentation
# The corpus run: what this library does with 23 real files

First measurement of the proof strategy in [`docs/PROOF.md`](PROOF.md): Tier A,
23 files from the pdf.js test suite, pinned and hashed in
[`corpus/manifest.json`](../corpus/manifest.json), run on 2026-11-14 with
`pdf2 1.0.0` and `pdf2-render 1.1.0`.

## The result, before and after opening the header gate

**Before** (2026-11-14, `pdf2 1.0.0`): all 23 files rejected at the header, not one
construct reached.

```
$ target/debug/pdf2 info corpus/tier-a/Embedded_font.pdf
error: … malformed only PDF 2.x is supported at offset 0
```

`src/document.rs:486` required the header version to start with `2.`, and
`src/document.rs:967` asserted that `%PDF-1.7` is an error. Deliberate policy —
and the single most consequential fact in the survey, because the real world is
PDF 1.4–1.7.

**After** the spike relaxed that one condition (accept `1.x` and `2.x`, refuse
everything else; no other code is version-gated), measured with
`cargo xtask corpus`:

| Measure | Files | Note |
| --- | --- | --- |
| parse (`pdf2 info`) | 21 of 23 | two fail before the header is useful: one xref edge case, one encrypted file |
| fully readable (`check` + `text`) | 14 of 23 | |
| page 1 rendered | 21 of 23 | the two that do not parse do not draw either |

Failure taxonomy, and every class maps to a gap already in the scorecard:

| Class | Files | Which |
| --- | --- | --- |
| `unsupported: composite (Type0) fonts` (text extraction) | 7 | `90ms_rksj_h_sample`, `ArabicCIDTrueType`, `Embedded_font`, `arial_unicode_ab_cidfont`, `arial_unicode_en_cidfont`, `cid_cff`, `cidfont_cmap_overflow` — all seven **do render** |
| `malformed cross-reference generation at offset 2111` | 1 | `ContentStreamCycleType3insideType3.pdf` — a 1.x xref edge case |
| `malformed object number must be positive at offset 0` | 1 | `encrypted-attachment.pdf` — 1.x-era RC4/AES-128 `/Encrypt`, which this library does not implement (it has AES-256 revision 6 only) |

Read that table as the first honest measurement of the library on real files: the
renderer is much further along than the extractor, and the three failure classes
are exactly gaps 1, 9 and 7 of `docs/GAPS.md`.

## What the corpus contains

Every file was chosen to exercise a construct this repository cannot generate:

| File | Bytes | Construct the upstream test targets |
| --- | --- | --- |
| `90ms_rksj_h_sample.pdf` | 1 039 | CJK text, Identity-H |
| `ArabicCIDTrueType.pdf` | 39 370 | Arabic, CID TrueType |
| `arial_unicode_ab_cidfont.pdf` | 13 110 | Arabic CID font |
| `arial_unicode_en_cidfont.pdf` | 15 779 | English CID font |
| `IdentityToUnicodeMap_charCodeOf.pdf` | small | `/ToUnicode` mapping |
| `cid_cff.pdf` | 19 970 | CID font with CFF outlines |
| `cidfont_cmap_overflow.pdf` | 94 168 | CMap edge case |
| `ContentStreamCycleType3insideType3.pdf` | 2 440 | Type 3 inside Type 3 |
| `Type3WordSpacing.pdf` | 2 693 | Type 3 metrics |
| `issue18768_type3_wide_glyph.pdf` | 1 059 | Type 3 wide glyph |
| `bug_jpx.pdf` | 5 451 | JPEG 2000 image |
| `ccitt_EndOfBlock_false.pdf` | 3 256 | CCITT image |
| `cmykjpeg.pdf` | 374 080 | CMYK JPEG |
| `ShowText-ShadingPattern.pdf` | 4 671 | shading pattern fill |
| `axial_shading_many_inputs.pdf` | 3 336 | axial shading |
| `function_based_shading.pdf` | 3 869 | function-based shading |
| `function_based_shading_cmyk.pdf` | 3 266 | CMYK shading |
| `alphatrans.pdf` | 16 910 | transparency |
| `blendmode.pdf` | 50 567 | blend modes |
| `colorkeymask.pdf` | 161 533 | `/Mask` colour key |
| `Embedded_font.pdf` | 3 323 | embedded font program |
| `TrueType_without_cmap.pdf` | 3 989 | font without a cmap |
| `encrypted-attachment.pdf` | 2 719 | encryption with an attachment |

Total 827 249 bytes; the manifest records each SHA-256 and the pdf.js commit
(`d60bc7426aa0968d5b95ff8ca3a76dbc6ce23a3a`).

## What the measurement changed

- **The gate was the whole blocker.** One condition plus its test; nothing else
  in the tree branches on the header version. The 2.0-only policy was buying
  nothing except unmeasurability.
- **Type 0 extraction is now confirmed by real files**, not by inference: seven
  of the twenty-three, and all seven render — the renderer/extractor split the
  ADR's D1 is about, visible in one table.
- **A new gap surfaced**: `/Encrypt` revisions 2–4 (RC4 and AES-128) are 1.x-era
  and unimplemented; the library has AES-256 revision 6 only. It goes into
  `docs/GAPS.md` with this file as evidence.
- **Images are not the blocker they were assumed to be**: `bug_jpx.pdf`,
  `ccitt_EndOfBlock_false.pdf`, `cmykjpeg.pdf` and `colorkeymask.pdf` all parse
  and render, because the renderer draws unsupported images as blanks and
  reports them rather than failing the page.
- **Tier B is now worth fetching**: a batch run over 690 pdf.js files would
  measure the same classes at scale.

## Reproducing

```sh
cargo xtask corpus
```

The chore builds the CLI and the renderer, runs `check`, `text` and page 1 of
every Tier A file, and prints the counts and the failure classes above.

## Method

```sh
# every file, three ways, 2026-11-14
for f in corpus/tier-a/*.pdf; do
  target/debug/pdf2 info  "$f"; target/debug/pdf2 check "$f"; target/debug/pdf2 text "$f"
  target/debug/pdf2-render-golden --fixture "$f" --page 1 --scale 1 --bless --out /tmp/x.png
done
```

The run is reproducible from the manifest alone; the oracle calibration promised
in `docs/PROOF.md` is not attempted here because the files never reach a
rasteriser.