oxideav-pdf

Pure-Rust PDF writer + reader for the oxideav framework. The writer emits PDF 1.4 vector documents from VectorFrame / Scene inputs (paths stay paths, fills stay fills); the reader walks bytes back into a Scene, with optional decryption for password-protected files. Zero C dependencies.

Part of the oxideav framework — a pure-Rust media stack. Codec, container, and filter crates are implemented from the spec (no C codec libraries linked or wrapped, no *-sys crates).

What round 1 supports

• Paths: MoveTo (m), LineTo (l), CubicCurveTo (c), QuadCurveTo (lifted to cubic via the 2/3 * (control - endpoint) trick), ArcTo (flattened to cubic per SVG 1.1 Appendix F.6.5), Close (h).
• Fills: Paint::Solid (DeviceRGB sc), Paint::LinearGradient (axial pattern shading, Pattern Type 2 + Function Type 2), Paint::RadialGradient (radial shading, Function Type 3).
• Strokes: width (w), cap (J), join (j), miter limit (M), dash pattern (d).
• Transforms: every Group::transform emits one cm operator.
• Groups: q ... Q save/restore brackets around children. Group opacity becomes an ExtGState resource referenced via /GSx gs.
• Clip paths: emitted before the children's content stream as W n (or W* n for even-odd fill rule).
• Fill rules: NonZero (f / B) vs. EvenOdd (f* / B*).
• Embedded raster: ImageRef whose underlying VideoFrame is RGBA8 lands as a FlateDecode Image XObject and is painted with Do.

Encryption decode (full Standard handler)

The reader handles password-protected PDFs under the standard security handler across the full revision range ISO 32000 defines:

• R=2 — RC4-40 (V=1, Length=40).
• R=3 — RC4-128 (V=2, Length=128).
• R=4 — AES-128 CBC or RC4-128, picked from the crypt-filter CFM (AESV2 vs V2).
• R=5 — AES-256 CBC, V=5, CFM=AESV3. Adobe extension level 3 (PDF 1.7); plain SHA-256 password derivation with validation + key salts.
• R=6 — AES-256 CBC, V=5, CFM=AESV3. ISO 32000-2:2020 (PDF 2.0); iterated SHA-256/384/512 hash chain (Algorithm 2.B) plus /Perms block validation (Algorithm 13).

Both user and owner passwords authenticate (Algorithms 6 + 7 for R≤4; Algorithms 11 + 12 for R≥5); the default empty user password is tried first so PDFs encrypted "just for permission flags" open with no caller intervention. Strings and stream payloads are decrypted via per-object keys (Algorithm 1) for R≤4 and via the file key directly (no per-object derivation) for R≥5.

let pdf = std::fs::read("locked.pdf")?;
// Default API tries the empty user password.
match oxideav_pdf::read_pdf_to_scene(&pdf) {
    Ok(scene) => println!("opened: {} pages", scene.pages.unwrap().len()),
    Err(_)    => {
        // Password-protected — supply one.
        let scene = oxideav_pdf::read_pdf_to_scene_with_password(&pdf, b"hunter2")?;
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())

Per-stream crypt-filter overrides land in a follow-up round.

Public-key encryption (decode + encode)

The reader and writer both handle public-key-encrypted PDFs under the adbe.pkcs7.s3 / s4 / s5 SubFilters of the public-key security handler (ISO 32000-1 §7.6.4 + ISO 32000-2 §7.6.5):

• adbe.pkcs7.s3 — RC4-40, V=1, SHA-1 file-key derivation.
• adbe.pkcs7.s4 — RC4-128, V=2, SHA-1.
• adbe.pkcs7.s5, V=4 — RC4-128 or AES-128 CBC via CFM (V2 / AESV2).
• adbe.pkcs7.s5, V=5 — AES-256 CBC, CFM=AESV3, SHA-256.

The trailer's /Recipients array (or /CF /<StmF> /Recipients for s5) carries one CMS EnvelopedData (RFC 5652 §6.1) per access- permission set; each envelope's KeyTransRecipientInfo SET wraps the content-encryption key with RSAES-PKCS1-v1_5 to a recipient's RSA public key. The reader matches by either IssuerAndSerialNumber (CMS v0) or SubjectKeyIdentifier (CMS v2 — RFC 5280 §4.2.1.2 method 1 SHA-1 of the SPKI BIT STRING contents), RSA-decrypts the wrapped CEK, decrypts the envelope contents (RC4 / AES-128 / AES-256 CBC), then derives the file encryption key per §7.6.4.3 / §7.6.5.3.

use oxideav_pdf::{read_pdf_to_scene_with_certificate, PubSecCredential};

let cert_der    = std::fs::read("user.cert.der")?;
let pkcs8_der   = std::fs::read("user.key.pkcs8.der")?;
let credential  = PubSecCredential::from_der(&cert_der, &pkcs8_der)?;
let scene = read_pdf_to_scene_with_certificate(&pdf_bytes, &credential)?;
# Ok::<(), Box<dyn std::error::Error>>(())

Round 11 lands the symmetric encoder side: the writer emits public-key-encrypted PDFs that round-trip through the reader.

use oxideav_pdf::{
    write_pdf_from_scene_pubsec_encrypted, PubSecEncoderConfig, PubSecRecipient,
};

// One recipient — IssuerAndSerial form.
let recipient = PubSecRecipient::from_issuer_and_serial(
    issuer_der,           // recipient cert's `issuer` SEQUENCE bytes
    serial_bytes,         // recipient cert's serial INTEGER body
    rsa_public_key,
);
let cfg = PubSecEncoderConfig::pkcs7_s5_v5_aes256(vec![recipient]);
let pdf = write_pdf_from_scene_pubsec_encrypted(&scene, &cfg)?;
# Ok::<(), oxideav_pdf::PdfError>(())

PubSecRecipient also exposes from_subject_key_identifier(ski, key) for the CMS v2 form. Round 12 adds per-crypt-filter recipient lists — write_pdf_from_scene_pubsec_multi_cf + PubSecMultiCfConfig

• PubSecCfGroup emit a doc with multiple permission sets (each its own envelope), and open_with_certificate_with_permissions surfaces the matched recipient's permission mask. Round 12 lands the CMS KARI decoder (RFC 5652 §6.2.2) — KeyAgree (ECDH/DH) recipients parse structurally. Round 14 closes the unwrap: P-256 ECDH + RFC 5753 §7.1.2 X9.63-SHA-256 KDF + RFC 3394 AES Key Wrap (128/192/256-bit) for the dhSinglePass-stdDH-sha256kdf-scheme KEA OID. Round 15 extends the curve set: P-384 (dhSinglePass-stdDH-sha384kdf-scheme, X9.63-SHA-384) and X25519 (RFC 8418 §2.1, secg-scheme …sha256kdf + id-X25519) join P-256 — pass PubSecCredential::from_parsed_ec(cert, KariCurve::P384, scalar) (or P256 / X25519) and the KARI envelope opens through the same read_pdf_to_scene_with_certificate entry point as KTRI. Round 15 also lands the writer-side KARI encode: write_pdf_from_scene_pubsec_kari(scene, &PubSecKariConfig) mirrors the round-11 KTRI writer — each KariRecipient { curve, … } becomes one CMS KARI envelope with AES-256-WRAP. Round 16 lands P-521 (dhSinglePass-stdDH-sha512kdf-scheme, X9.63-SHA-512) + RFC 8418 §2.2 HKDF binding for X25519 (dhSinglePass-stdDH-hkdf-sha256/384/512-scheme, smime-alg 19/20/21). Round 24 closes the RFC 8418 curve set with X448 (RFC 7748 §5 / RFC 8410 §3 — id-X448 1.3.101.111, 56-byte raw u-coordinate, 224-bit security level): pass KariCurve::X448 and the same writer + reader entry points handle it. Default KDF is X9.63-SHA-512 (security-strength match); HKDF SHA-256/384/512 are also valid via the KariRecipient::x448_hkdf_* constructors. Cross-checked against the RFC 7748 §6.2 Alice/Bob shared-secret vector byte-for-byte. Round 17 closes the long-term-cert originator gap: when a KARI envelope's OriginatorIdentifierOrKey is IssuerAndSerial or SubjectKeyIdentifier rather than the in-band OriginatorPublicKey, the recipient resolves the originator cert through a TrustStore — pass it via read_pdf_to_scene_with_certificate_and_trust_store(pdf, &cred, &store). Round 17 also adds read-only decode for legacy RC2-CBC (RFC 2268 + RFC 3217) and DES-EDE3-CBC (3DES, RFC 3370 §5.2) envelope content algorithms so PDF 2.0-deprecated archives still open; no encode-side support — the writer always uses AES. Round 18 surfaces previously-discarded CMS metadata: the envelope's OriginatorInfo (RFC 5652 §10.2.1 — certs[] / crls[]) is now exposed via EnvelopedData::originator_info(), and the RecipientKeyIdentifier's OPTIONAL date (GeneralizedTime) + other (OtherKeyAttribute) fields are captured by the parser. New TrustStore::find_with_temporal_validity(ski, instant) uses the RKID date to pick the cert generation that was active when the envelope was authored — useful for long-lived archives where multiple cert generations exist for the same SKI. The Certificate parser now also extracts the validity window (notBefore / notAfter), normalising UTCTime to GeneralizedTime per RFC 5280 §4.1.2.5.1's 1950..2049 pivot for direct byte-comparison. Round 19 ships two orthogonal additions. Document-level XMP /Metadata stream end-to-end (ISO 32000-1 §14.3.2 + Adobe XMP Spec 2012): writer entry write_pdf_from_scene_with_xmp(scene, xmp_bytes) attaches the raw XMP RDF/XML packet to the catalog as a /Type /Metadata /Subtype /XML stream (no /Filter); reader accessor DocumentReader::xmp_metadata() returns Some(bytes) for documents that carry one. CMS SignedData parser scaffolding (RFC 5652 §5 — PKCS#7): pubsec::signed_data::parse_signed_data decodes id-signedData blobs into typed SignedData { digest_algorithms, encap_content, certs, crls, signer_infos } + SignerInfo (sid, digest / signature OIDs, signed / unsigned attribute lists with raw-DER values, raw signature octets).

Round 20 closes the round-19 verification deferral. New pubsec::verify::verify_signature(signer, certs, content) resolves the signer's certificate from a pool by IssuerAndSerial or SubjectKeyIdentifier, hashes the canonical (universal-SET-tag) re-encoding of signedAttrs per digestAlgorithm, and verifies the hash against signature per signatureAlgorithm (RFC 5652 §5.4 + §11.2). Hash side: SHA-1 / SHA-256 / SHA-384 / SHA-512. Signature side: RSA-PKCS#1 v1.5 (the rsaEncryption + four sha*WithRSA OIDs all map here), RSA-PSS (id-RSASSA-PSS), and ECDSA on P-256 / P-384 / P-521 (curve dispatch by the cert SPKI's named-curve OID per RFC 5480 §2.1.1.1). When signedAttrs is present, the verifier also cross-checks the messageDigest attribute against the eContent hash (RFC 5652 §11.2) — so a tampered eContent fails even when the outer signature still verifies. Detached signatures (PAdES — eContent absent) feed the document bytes through AttachedContent::External(&[u8]). Round-20 also extends x509::Certificate to capture spki_algorithm_oid + spki_algorithm_params so the verifier can route ECDSA on the named-curve OID without re-parsing the certificate.

Round 21 closes the reader half of the round-20 follow-up list: PDF /Sig annotation reader (ISO 32000-1 §12.7.4.5 + §12.8.1). DocumentReader::signatures() walks the catalog → /AcroForm /Fields tree (honouring /FT inheritance through non-terminal /Kids parents per §12.7.3.1) and surfaces one [PdfSignature] per /V signature dictionary it can parse. Each value carries the [a, b, c, d] /ByteRange, the hex-decoded /Contents blob, the /SubFilter (adbe.pkcs7.detached / ETSI.CAdES.detached etc.), the optional metadata fields (/Name, /Reason, /Location, /ContactInfo, /M), and — for the CMS-detached SubFilters — the parsed [pubsec::signed_data::SignedData]. PdfSignature::signed_message(pdf) concatenates the two /ByteRange-named slices into the byte string the signing tool hashed; pass it as AttachedContent::External(...) to the existing [pubsec::verify::verify_signature] for a full end-to-end verify.

use oxideav_pdf::reader::DocumentReader;
use oxideav_pdf::pubsec::verify::{verify_signature, AttachedContent};
use oxideav_pdf::pubsec::x509::parse_certificate;

let mut r = DocumentReader::open(&pdf_bytes)?;
for sig in r.signatures()? {
    if !sig.is_cms_detached() { continue; }
    let signed = sig.signed_message(&pdf_bytes)?;
    let sd = sig.signed_data.as_ref().expect("CMS-detached parsed");
    let certs: Vec<_> = sd.certs.iter()
        .filter_map(|der| parse_certificate(der).ok())
        .collect();
    let ok = verify_signature(
        &sd.signer_infos[0],
        &certs,
        AttachedContent::External(&signed),
    )?;
    println!("signature verifies: {ok}");
}
# Ok::<(), oxideav_pdf::PdfError>(())

The reader is tolerant of unsigned slots (a Sig form field whose /V is absent — common for "approval line still pending" templates), of non-terminal parent fields without their own /V, and of malformed /Contents blobs (the dict surfaces but signed_data is None).

Round 30 closes the symmetric writer half: the new oxideav_pdf::sig module emits signed PDFs with valid /ByteRange

• PKCS#7 / CMS SignedData /Contents blobs (ISO 32000-1 §12.7.4.5 + §12.8.1 + §7.5.6 + RFC 5652 §5 + §5.4 + §11.2). The classic "ByteRange-placeholder fill-in" pattern is implemented end-to-end — build PDF with a fixed-width /ByteRange [?? ?? ?? ??] + a /Contents <0…0> placeholder (8192 hex chars = 4096 raw bytes, enough for any RSA-2048 / ECDSA-P256 SHA-256 SignedData with a single signer + cert), patch /ByteRange with the computed offsets, hash the bytes spanned by /ByteRange, wrap into a CAdES-BES-style CMS SignedData with signedAttrs = { contentType, messageDigest } per RFC 5652 §11.1+§11.2, hex-encode, overwrite the placeholder. A [Signer] trait decouples the crypto: bring your own ring / rsa / p256 / HSM impl, or use the reference [RsaPkcs1v15Sha256Signer] / [EcdsaP256Sha256Signer] that wrap the in-crate deps.

use oxideav_pdf::{sign_pdf_from_scene, RsaPkcs1v15Sha256Signer, SignerIdentity};

let private_key = rsa::RsaPrivateKey::new(&mut rsa::rand_core::OsRng, 2048)?;
let signer = RsaPkcs1v15Sha256Signer::new(private_key);
let identity = SignerIdentity::from_signer_cert_der(cert_der)?;
let signed_pdf = sign_pdf_from_scene(&scene, &signer, identity)?;
# Ok::<(), Box<dyn std::error::Error>>(())

Round-30 ships RSA-PKCS#1 v1.5 + SHA-256 and ECDSA-P256 + SHA-256. RSA-PSS, ECDSA on P-384 / P-521, and Ed25519 plug in through the same [Signer] trait without touching the writer surface. The output is accepted by qpdf --check and verifies end-to-end against the round-27 PKCS#7 verify dispatch.

Encryption encode (writer side)

The writer emits password-protected PDFs across the same revision range the reader handles. [oxideav_pdf::write_pdf_from_scene_encrypted] takes a [Scene] and an [encrypt::EncryptionConfig] and produces bytes that round-trip through read_pdf_to_scene_with_password:

use oxideav_pdf::encrypt::EncryptionConfig;

let cfg = EncryptionConfig::aes_256_r6(b"hunter2", b"FILE-ID-16-BYTES");
let pdf = oxideav_pdf::write_pdf_from_scene_encrypted(&scene, &cfg)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Writer-side coverage matches the reader: R=2 (RC4-40), R=3 (RC4-128), R=4 (AES-128 / RC4 via CFM), R=5 (Adobe ext L3), R=6 (ISO 2.0). /O, /U, /OE, /UE, and /Perms come from the canonical algorithms (3, 4, 5 for V≤4; 8, 9, 10 for V=5); per-object key derivation is Algorithm 1 (V≤4) or the file key directly (V=5).

Cross-reference streams

Both reader and writer support the binary cross-reference stream form introduced in PDF 1.5 (ISO 32000-1 §7.5.8): a /Type /XRef stream object whose body packs each entry into /W [w1 w2 w3] big-endian fields, Flate-compressed with /Predictor 12 (PNG-Up). The classical xref-keyword form (PDF 1.0..1.4) is also accepted on input and remains the writer's default; opt into the stream form via [oxideav_pdf::write_pdf_from_scene_xref_stream].

Hybrid-reference files (§7.5.8.4) are also accepted on the read path. A hybrid PDF carries a classical xref subsection (so pre-PDF-1.5 tools can still find the catalog and page tree) plus an /XRefStm offset entry in the same update trailer that points at a supplementary /Type /XRef stream. The supplementary stream surfaces the compressed-object slots the classical subsection marks free. The reader follows the §7.5.8.4 resolution order — current section's classical entries first, then its /XRefStm entries, then walk /Prev — and applies a newer-wins merge so hidden compressed slots override the classical free markers they shadow. Chained /XRefStm references are bounded at 32 hops and short-circuit on cycles, the same guards the /Prev-section walker already enforces.

§7.5.8.3 forward-compat. Unknown entry types (≥ 3) are resolved as references to the null object per spec — "any other value shall be interpreted as a reference to the null object, thus permitting new entry types to be defined in the future." The /W array's zero-width defaults are honoured (w[0] == 0 ⇒ type field defaults to 1; w[2] == 0 ⇒ generation defaults to 0 per Table 18 Type 1 field 3). Multi-subsection /Index arrays walk per-subsection starting object numbers rather than implicitly numbering from zero.

Object streams

Both reader and writer support PDF 1.5+ object streams (/Type /ObjStm, ISO 32000-1 §7.5.7). The reader resolves Compressed xref entries by fetching the containing object stream, parsing its (obj_num offset) header, and returning the body bytes from the matching slot. The writer packs every compressible indirect object (every dict that isn't a stream and isn't the Catalog) into one ObjStm container — opt in via [oxideav_pdf::write_pdf_from_scene_object_stream]. Stream objects (content streams, image XObjects, the xref stream itself) cannot be compressed per §7.5.7 and remain at their own byte offsets.

Stream filters (round 104 adds the /Predictor post-filter)

decode_stream recovers a stream's raw payload by applying its /Filter (single Name or Array chain, §7.4.1). The generic decompression filters are all handled in array order, so chains like [/ASCII85Decode /LZWDecode] (§7.4.4 Example 2) round-trip:

• /FlateDecode (§7.4.4) — zlib DEFLATE; the writer's default.
• /LZWDecode (§7.4.4.2) — variable-width (9..=12-bit) MSB-first LZW, the TIFF flavour. Round 98 wires this through decode_stream plus the round-23 image-XObject and round-35 inline-image filter peels. The /EarlyChange parameter (§7.4.4.3 Table 8) is honoured from /DecodeParms, defaulting to 1 (TIFF/PDF default); the KwKwK self-reference and clear-table (256) / EOD (257) codes are handled, and a truncated stream returns its partial decode.
• /ASCII85Decode (§7.4.3), /ASCIIHexDecode (§7.4.2), /RunLengthDecode (§7.4.5) — also accepted in single + chain position, including the inline-image abbreviations (/Fl, /LZW, /A85, /AHx, /RL).

Round 104 wires the /DecodeParms /Predictor post-filter (§7.4.4.4) into decode_stream, so a /FlateDecode or /LZWDecode stream whose /DecodeParms carries /Predictor > 1 is un-differenced after inflating — the same path the xref-stream walker already used, now reaching every generic stream:

• PNG predictors (/Predictor 10..=15, Table 10) — each row's leading algorithm tag (Table 9: None / Sub / Up / Average / Paeth) is authoritative, with the "left"/"upper-left" neighbours taken bpp = ceil(Colors * BitsPerComponent / 8) bytes back.
• TIFF Predictor 2 (/Predictor 2) — per-component left differencing, with sub-byte /BitsPerComponent (1 / 2 / 4) unpacked, summed modulo 2^bpc, and repacked; 8- and 16-bit components run byte/word-wise.

/Colors, /BitsPerComponent, and /Columns are read from the same parameter dict (Table 8 defaults 1 / 8 / 1). /Predictor 1 (or no /DecodeParms) is a no-op passthrough.

Terminal image-codec filters (/DCTDecode, /JPXDecode, /JBIG2Decode, /CCITTFaxDecode) are not decoded here — they keep routing to the dedicated image walkers that hand the opaque payload to a codec crate.

Validated against ISO 32000-1:2008 §7.4.4.2 Example 2's packed vector (80 0B 60 50 22 0C 0C 85 01 → 45 45 45 45 45 65 45 45 45 66), plus PNG (Sub / Up / Average / Paeth) and TIFF-2 (8-bit, RGB-interleaved, 4-bit) predictor round-trips.

Indirect stream /Length (round 91)

The reader resolves stream-object /Length entries that are indirect references rather than direct integers, per ISO 32000-1 §7.3.10 Example 3:

7 0 obj
    << /Length 8 0 R >>
stream
    BT /F1 12 Tf 72 712 Td ( ... ) Tj ET
endstream
endobj

8 0 obj
    77
endobj

This shape is what every one-pass PDF writer produces — the encoder doesn't know the compressed body length until after deflating it, so the dict carries a forward reference to an integer object written after the stream. Real-world spec PDFs (e.g. docs/video/mpeg1/ISO_IEC_11172-2-MPEG1-Video-1993.pdf) use this on every content stream. Before round 91 the reader rejected them outright; now it consults the xref table, fetches the length-carrying integer, and patches the resolved direct value into the stream dictionary so downstream consumers (decode_stream, encryption length tracking) never see the stale Reference.

The resolver is exposed at the parser level as Parser::parse_indirect_with_length_resolver(&mut dyn LengthResolver) — callers that already have an xref table provide a closure, callers that don't (the xref-stream parser itself, before any xref has been built) pass NoLengthResolver and indirect /Length is rejected per §7.5.8's effective direct-integer requirement. Compressed-target lookups (length integer stored inside an ObjStm) surface a clear error rather than mis-resolving; not yet seen in the wild.

Incremental updates

[oxideav_pdf::write_pdf_incremental_update] appends new revisions to a previously-written PDF per ISO 32000-1 §7.5.6 — the new revision's body is appended verbatim, followed by a new xref subsection that lists only the changed slots, plus a trailer carrying /Prev <prev_xref_off> pointing back at the original revision. The reader follows the /Prev chain and merges entries: the newest revision wins on overlap.

let original = oxideav_pdf::write_pdf_from_scene(&scene_v1)?;
// ... time passes; user adds two pages ...
let updated = oxideav_pdf::write_pdf_incremental_update(&original, &new_pages)?;
// `updated` starts with `original` byte-for-byte, then appends.

Per-stream /Crypt /Identity opt-out

ISO 32000-1 §7.6.5 lets a single stream opt out of per-object encryption by listing /Crypt as its first /Filter with /DecodeParms /Name /Identity (or no /Name — the default per §7.4.10 Table 24). The writer leaves such streams untouched while encrypting the rest of the file; the reader applies the same rule on input. The classic consumer is XMP metadata streams that need to remain searchable in encrypted PDFs.

Linearization (Fast Web View)

Round 9 emits Linearized PDF per ISO 32000-1 §7.5.6 + Annex F. [write_pdf_from_scene_linearized] produces a PDF whose first 1024 bytes carry a complete linearization parameter dictionary (/Linearized 1 + /L + /H + /O + /E + /N + /T); the on-wire layout follows F.3.1 (header → lin-dict → first-page xref → catalog → hint stream → first-page section → remaining pages → main xref). startxref at EOF points at the first-page xref; the first-page trailer's /Prev points at the main xref. The output is also a valid plain PDF — readers ignoring /Linearized walk the same Catalog + Pages tree + page content.

The hint stream emits the page offset table (F.4.1) with full per-page entries (round 13: items 1, 2, 6, 7 — object count, page length, content stream offset relative to page start, content stream length) at fixed 32-bit width, plus minimal shared-object (F.4.2), thumbnail (F.4.3), and outline (F.4.4) header sections. Entry counts for the latter three are zero so no per-shared-object / per-thumbnail / per-outline bytes are generated. The hint dict carries /S, /T, /O offsets into the decoded hint stream so a reader walking the optional tables sees a fully-formed (if empty) layout. Extended generic (F.4.5) and embedded-file-stream (F.4.6) tables are still deferred — we generate no interactive forms / structure trees / embedded files.

Text extraction (round 22)

[DocumentReader::text_extraction] walks every page's content stream and emits one [TextRun] per Tj / TJ / ' / " operator, with the text-matrix origin and Tf font + size resolved per ISO 32000-1 §9.4.4. Encoded glyphs are mapped back to Unicode through the font's /ToUnicode CMap when present (parsing the bfchar / bfrange blocks defined in §9.10.3 + Adobe Tech Note #5014); for Identity-H Type 0 fonts without /ToUnicode the walker falls back to interpreting each 2-byte CID as a BMP code point. Simple fonts honour /Encoding /WinAnsiEncoding and /Encoding /MacRomanEncoding (Annex D.2), with a Latin-1 fallback for everything else.

Round 182 closes the mixed-width /ToUnicode codespace gap. Before this round the CMap parser skipped every codespacerange block and the decoder assumed a single global byte-width inferred from the first bfchar / bfrange source operand — which silently mis-decoded any real-world CMap that mixes a 1-byte ASCII passthrough with a 2-byte CJK territory (the Adobe-Japan1 / Adobe-GB1 / Adobe-CNS1 / Adobe-Korea1 shape). The parser now captures every begincodespacerange ... endcodespacerange entry, and the FontDecoder::ToUnicode decode path walks bytes left-to-right selecting the first declared codespace whose byte-component bounds cover the candidate input prefix (per Adobe Tech Note #5411 §2 + Tech Note #5014 §3.1). Per §3.1 the match is byte-component, not a linear u32 interval: <8140>..<FCFC> accepts 81 75 (low byte 0x75 in [0x40..=0xFC]) but rejects 81 39 (low byte 0x39 below 0x40) — exactly the rule the naive interval comparison would get wrong. Unmatched input emits U+FFFD and the decoder advances one byte so subsequent in-codespace input still resolves. Adds three end-to-end integration tests (mixed-width decode, out-of-codespace replacement, inter-range byte rejection) plus eight CMap-parser unit tests. CMaps that omit the §9.10.3 mandatory header (rare, hand-crafted) continue to decode through the legacy single-width fallback path.

Round 188 closes the TJ word-break gap. Per §9.4.3 (Table 109 + Figure 46) a numeric TJ array element is expressed in thousandths of a text-space unit and is subtracted from the horizontal coordinate, so a negative number opens a rightward gap before the next glyph. Many producers encode the space between two words purely as such a displacement, with no literal space glyph in the strings — before this round the walker concatenated every string fragment and dropped the numeric elements, extracting helloworld from text that reads hello world. The walker now sums the rightward gap between fragments and inserts a single U+0020 when it reaches a quarter-em (250 thousandths). The threshold sits above the Figure 46 intra-word kerns (−120 / −95 inside "AWAY", which stay joined) and below a typical space advance, so genuine word boundaries are recovered without false-splitting tightly-kerned runs. Positive (leftward / overlap) adjustments never break, a leading adjustment emits no dangling space, and a fragment already ending in a space is not doubled. Adds six end-to-end tests in tests/tj_word_break_round188.rs.

Round 267 surfaces the text rendering mode (Tr, §9.3.6 Table 106) on every [TextRun]. Before this round the walker dropped the Tr operand, so a text-extraction consumer could not tell visible body text apart from the invisible (3 Tr) OCR text layer scanned PDFs stack behind a page image. The new typed TextRenderMode enum (Fill / Stroke / FillStroke / Invisible / FillClip / StrokeClip / FillStrokeClip / Clip) carries the mode in force at the moment of each show, defaulting to Fill per the §9.3.1 default text state. TextRun::render_mode lets a keyword-search consumer keep the OCR layer while a "what the eye sees" consumer drops it via render_mode.paints_glyphs() (false only for the Invisible and clip-only Clip modes — the two that add nothing to the page raster). The mode persists across BT/ET (Table 105 — Tr is a graphics-state text parameter, not a text-object parameter) and is saved / restored by q/Q. Adds seven end-to-end tests in tests/text_render_mode_round267.rs.

Round 299 folds the text rise (Ts, §9.4.4 + §9.3.7 Table 105) into every [TextRun] origin. Before this round the walker dropped the Ts operand (batched with Tc/Tw/Tz as geometry-only state), so a 4 Ts superscript footnote marker reported the same position as the surrounding baseline text — a layout / accessibility consumer could not tell them apart. The walker now tracks the most-recent Ts and applies it to each run's origin per the §9.4.4 text-rendering matrix: the rise translates the rendering origin by Trise along the text matrix's vertical basis (c, d), so the reported origin is (c·Trise + e, d·Trise + f). For the common axis-aligned Tm this is simply the baseline shifted up (superscript) or down (subscript) in y; for a rotated Tm the offset follows the rotated basis. The raw rise is also surfaced on TextRun::text_rise so a consumer can classify a run as super/subscript without reverse-engineering the offset from the position delta. Ts persists across BT/ET (Table 105 — a graphics-state text parameter, not a text-object parameter) and is saved / restored by q/Q; an explicit 0 Ts restores the §9.3.1 default baseline. Adds seven end-to-end tests in tests/text_rise_round299.rs.

use oxideav_pdf::reader::DocumentReader;

let pdf = std::fs::read("invoice.pdf")?;
let mut reader = DocumentReader::open(&pdf)?;
let extraction = reader.text_extraction()?;
for run in &extraction.runs {
    println!("@({:.0},{:.0}) {}/{}: {}",
        run.position.0, run.position.1,
        run.font_name, run.font_size, run.text);
}
println!("flat: {}", extraction.flat_text());
# Ok::<(), Box<dyn std::error::Error>>(())

Runs come out in stream order — the rendering order the page would have laid down. Reading-order reconstruction (column / paragraph segmentation) is a future-round followup; round 22 gives the raw runs plus matrix positions so a downstream layout pass can do its own segmentation.

JPEG passthrough on Image XObjects (round 23)

[DocumentReader::image_xobjects] walks every page's /Resources /XObject subdict and surfaces every Image XObject whose final filter is /DCTDecode (ISO 32000-1 §7.4.8). The returned [PdfImageXObject] carries the unmodified JPEG bytes — the exact JPEG-1 / JFIF stream a JPEG decoder needs — plus the dictionary's /Width, /Height, /ColorSpace (mapped to the [ColorSpace] tag: DeviceRGB / DeviceCMYK / DeviceGray / Indexed / Other), and /BitsPerComponent. Wrapping /ASCII85Decode / /ASCIIHexDecode / /FlateDecode filters preceding /DCTDecode are unwrapped before the JPEG payload is returned, so callers always get a self-contained JPEG stream (the standard pdfimages -all shape).

use oxideav_pdf::reader::DocumentReader;

let pdf = std::fs::read("photos.pdf")?;
let mut reader = DocumentReader::open(&pdf)?;
for (id, image) in reader.image_xobjects()? {
    let path = format!("xobj-{}.jpg", id.number);
    std::fs::write(&path, &image.data)?;
    println!("{} ({}x{} {:?}, {} bpc)", path,
        image.width, image.height, image.color_space,
        image.bits_per_component);
}
# Ok::<(), Box<dyn std::error::Error>>(())

The same XObject referenced from multiple pages is returned once (deduplicated by ObjectId). Image XObjects with non-DCTDecode filters (FlateDecode-only raster XObjects, JBIG2Decode, JPXDecode, CCITTFaxDecode) are silently skipped — the round-23 walker is JPEG-only. Cross-checked against pdfimages -all (poppler-utils): the bytes are byte-identical.

Inline-image extraction (round 35)

[DocumentReader::inline_images] walks every page's content stream and surfaces every BI … ID … EI triplet (ISO 32000-1 §8.9.7) as a [PdfInlineImage] — the content-stream-level counterpart of the round-23 Image XObject walker. Both abbreviated (Table 93 — /W, /H, /CS /RGB, /F /DCT) and long-form (/Width, /ColorSpace /DeviceRGB, /Filter /DCTDecode) keys are accepted on input.

Filter coverage mirrors the round-23 XObject walker: wrapping /A85, /AHx, /Fl, /RL are peeled before the payload reaches the caller; terminal codec filters (/DCT, /JPX, /JBIG2, /CCF) are left in place and surface as an [InlineImageFilter] tag so a downstream JPEG / JPEG2000 / JBIG2 / CCITT-Fax decoder can take over.

The /IM true image-mask flag is preserved (1-bit stencil that takes its colour from the current path-paint state); source_page_index and source_page_obj are filled in so callers can locate where in the document the inline image was painted.

use oxideav_pdf::reader::{DocumentReader, InlineImageFilter};

let pdf = std::fs::read("scan.pdf")?;
let mut reader = DocumentReader::open(&pdf)?;
for img in reader.inline_images()? {
    println!("page {} {}x{} bpc={} filter={:?} {} bytes",
        img.source_page_index, img.width, img.height,
        img.bits_per_component, img.filter, img.data.len());
    if matches!(img.filter, InlineImageFilter::DctDecode) {
        std::fs::write(format!("inline-p{}.jpg", img.source_page_index),
                       &img.data)?;
    }
}
# Ok::<(), Box<dyn std::error::Error>>(())

§8.9.7 framing detail: the EI terminator must be preceded by a whitespace byte and followed by whitespace or EOF — embedded EI sequences inside the payload (with no surrounding whitespace) are preserved as data, matching pdfimages -all's extraction behaviour.

Optional Content / OCG layers (round 95)

[DocumentReader::optional_content] walks the catalog's /OCProperties entry and surfaces every Optional Content Group + configuration (ISO 32000-1 §8.11 + §7.7.2 Table 28). PDFs with toggleable "layers" — CAD drawings, multi-language alternates, watermark / content separations — store one [OptionalContentGroup] per /Type /OCG indirect object, with /Name UI label, optional /Intent (View / Design), and optional /Usage filters (language / zoom / print / view / export / page-element).

The configuration dictionary's /BaseState (ON / OFF / Unchanged) + /ON + /OFF arrays apply per §8.11.4.5 algorithm steps (a)+(b)+(c), giving each group a resolved boolean state. OptionalContent::is_visible(group_id) is the lookup; states_for_config(&alt) re-resolves under any of the /Configs alternate configurations.

use oxideav_pdf::reader::DocumentReader;
let mut r = DocumentReader::open(&pdf_bytes)?;
if let Some(oc) = r.optional_content()? {
    println!("{} layers, default cfg = {:?}",
        oc.groups.len(), oc.default_config.name);
    for g in &oc.groups {
        println!("  {:?} {} ({})", g.id, g.name,
            if oc.is_visible(g.id) { "ON" } else { "OFF" });
    }
}
# Ok::<(), oxideav_pdf::PdfError>(())

Optional Content Membership Dictionaries (OCMDs, Table 99) are also covered — parse_membership(reader, dict) decodes the /OCGs reference list, the /P policy (AllOn / AnyOn / AnyOff / AllOff), and the /VE visibility expression (PDF 1.6 — [/And …] / [/Or …] / [/Not e], recursively nested). OptionalContent::evaluate_membership(&mem) plugs an OCMD into the current state map and returns the boolean visibility per §8.11.2.2's NOTE 2 (when /VE is present, the expression wins over /P). The configuration's /Order array parses into a tree of [OcOrderItem::Group] leaves and [OcOrderItem::Subtree { label, items }] nodes — both the labelled- collection form ([(Frog Anatomy) g1 g2]) and the sublayer-nesting form ([g1 [g2 g3]]).

Action enumeration (round 36)

[DocumentReader::actions] walks every place an action can hide in a PDF and surfaces each as a [PdfAction] — the audit-grade counterpart to the round-25 link reader (links only) and the round-26 annotation reader (annotations only). Sources walked (ISO 32000-1 §12.6):

• Catalog /OpenAction (§7.7.2 Table 28) — fires on document open. Action-dict form lands; destination-array form is purely navigation and is skipped.
• Catalog /AA additional actions (§12.6.3 Table 197) — WC, WS, DS, WP, DP.
• Page /AA (§12.6.3 Table 196) — O (page open), C (page close).
• Annotation /A + /AA (§12.5.3 Table 165) — E/X/D/U/ Fo/Bl/PO/PC/PV/PI plus the primary /A.
• Form-field /A + /AA (§12.7.4 Table 220 + Table 196 events K/F/V/C) walked through the /AcroForm /Fields tree, with /Kids recursion bounded at depth 32.
• Catalog /Names /JavaScript name tree (§7.7.4 Table 31 + §7.9.6) — every JavaScript function the document defines.

Each action's /Next chain (§12.6.3) is followed recursively up to depth 32, with indirect-reference dedup to break malformed cycles. The carrier action and every chained-/Next action surface as their own [PdfAction] with progressively-higher chain_depth.

Per-type payload decodes the high-signal entries Table 198 calls out:

• /URI (§12.6.4.7 Table 206) — URI text + /IsMap.
• /JavaScript (§12.6.4.16 Table 217) — /JS is decoded from literal-string / hex-string / stream form, recognising UTF-8 BOM (EF BB BF), UTF-16BE BOM (FE FF), UTF-16LE BOM (FF FE), or PDFDocEncoding fallback.
• /Launch (§12.6.4.5 Table 202) — /F filename + /NewWindow.
• /GoToR (§12.6.4.3 Table 200) / /GoToE (§12.6.4.4 Table 201) — /F filespec + raw /D destination.
• /SubmitForm (§12.7.5.2 Tables 236+237) — /F URL + /Flags bitfield (Include/Exclude / IncludeNoValueFields / ExportFormat / GetMethod / SubmitCoordinates / XFDF …).
• /ResetForm (§12.7.5.3 Table 239), /ImportData (§12.7.5.4 Table 240), /Hide (§12.6.4.10 Table 209), /Named (§12.6.4.11 Table 211), /SetOCGState (§12.6.4.12 Table 212 — On/Off/Toggle counts), /GoTo (§12.6.4.2 — page index resolved when /D is an explicit array).
• The remaining Table 198 types (/Thread, /Sound, /Movie, /Rendition, /Trans, /GoTo3DView) surface as their unit variants; unknown /S values fall through to ActionKind::Other { kind } with the raw name preserved.

use oxideav_pdf::reader::{ActionKind, ActionTrigger, DocumentReader};

let mut r = DocumentReader::open(&pdf_bytes)?;
for action in r.actions()? {
    match (&action.trigger, &action.kind) {
        (ActionTrigger::CatalogOpen, ActionKind::JavaScript { script }) => {
            println!("OPEN-JS (auto-fires!): {script}");
        }
        (_, ActionKind::Launch { file, .. }) => {
            println!("launches binary: {:?}", file);
        }
        (_, ActionKind::SubmitForm { url, flags }) => {
            println!("submits form to {:?} (flags {flags:#x})", url);
        }
        (trg, kind) => println!("[{trg:?}] {kind:?}"),
    }
}
# Ok::<(), oxideav_pdf::PdfError>(())

The walker is tolerant of malformed action dicts (skipped silently), of /Next chains that loop back on themselves (the indirect-ref visited-set cuts the loop), and of action types this round doesn't decode (ActionKind::Other preserves the raw /S name so callers walking a forensic / unknown PDF still get a complete enumeration).

Annotations beyond Link + XMP packet fields (round 26)

[DocumentReader::annotations] walks every page's /Annots array and surfaces every entry as a [PdfAnnotation] (ISO 32000-1 §12.5.6 Tables 169..209). Per-subtype payload covers /Text (sticky notes — /Open, /Name icon, /State, /StateModel), /FreeText (/DA, /Q quadding, /RC, /IT intent), /Stamp (icon name), the four text-markup variants /Highlight / /Underline / /Squiggly / /StrikeOut (/QuadPoints), /Square + /Circle (/IC, /RD), /Link (re-uses the round-25 go-to / URI decoder), and /Widget (/FT, /T, /V). Round 197 closes six more subtypes — /Line (§12.5.6.7 Table 175 — /L endpoints, /LE line-ending styles, /IC interior colour, /LL / /LLE / /LLO leader geometry, /Cap caption flag, /IT intent), /Polygon + /PolyLine (§12.5.6.9 Table 178 — /Vertices, /LE, /IC, /IT for the PolygonCloud / PolyLineDimension / PolygonDimension intents), /Ink (§12.5.6.13 Table 182 — /InkList of strokes, closing the round-trip with the round-32 write_pdf_with_annotations Ink writer), /Caret (§12.5.6.11 Table 180 — /RD, /Sy paragraph symbol), /Popup (§12.5.6.14 Table 183 — /Parent indirect ref preserved as an ObjectId, /Open flag), and /FileAttachment (§12.5.6.15 Table 184 — /Name icon, filespec-resolved user-visible name via the same /UF-preferred / /F fallback path the round-33 attachment reader uses, closing the round-trip with the round-33 write_pdf_with_attachments annotation marker). Round 204 closes two more — /Watermark (§12.5.6.22 Table 190 — optional /FixedPrint Table 191 sub-dict surfaced through a new [FixedPrint] struct carrying /Matrix six-number affine + /H

• /V media-relative percentages, each reverting to its Table 191 default when the entry is absent) and /Redact (§12.5.6.23 Table 192 — /QuadPoints content region, three-component DeviceRGB /IC interior fill, /RO overlay-appearance Form XObject preserved as an ObjectId, /OverlayText + /Repeat
• /DA + /Q overlay text). The redact reader is non-destructive — it surfaces the metadata so a privacy-audit consumer can enumerate what would be removed by a PDF 1.7-compliant redactor without performing the destructive content-removal step described by §12.5.6.23 NOTE. Round 209 closes three more — /Sound (§12.5.6.16 Table 185 — the required §13.3 sound stream surfaced as an ObjectId so callers re-resolve through their own audio plumbing, plus the /Name icon defaulting to Speaker per Table 185), /Movie (§12.5.6.17 Table 186 — /T title used by §12.6.4.9 movie actions, the required §13.4 /Movie dict preserved as an ObjectId, and /A collapsed to a new MovieActivation tri-state — Play for true or absent per Table 186 default, Dont for false, Custom(id) for an indirect reference to a §13.4 movie-activation dict), and /Screen (§12.5.6.18 Table 187 — /T title plus appearance-characteristics /MK, action /A, and additional-actions /AA indirect refs preserved as ObjectIds so callers re-resolve through the round-36 actions reader and the §12.6.4.13 rendition-action target). Round 215 closes two more — /PrinterMark (§12.5.6.20 Table 362 — PDF 1.4 production mark such as a registration target, colour bar, cut mark, or page-information bar; surfaces the /MN mark-name Name verbatim so a colour-management tool can match its own taxonomy without pattern-matching on Table 362's open-ended set) and /TrapNet (§12.5.6.21 Table 366 — PDF 1.3 page-level trap network; surfaces either /LastModified or the /Version + /AnnotStates pair — Table 366 makes them mutually exclusive but the reader stays tolerant of malformed annots — plus the optional /FontFauxing array of substituted-font references, enough for a regenerator to decide whether the cached traps are still valid). Neither carries any cross-crate plumbing dependency: the rendering itself lives in the Form-XObject appearance stream referenced from /AP /N (§8.10) and stays routed through the existing Form-XObject walker. Round 220 closes one more — /3D (§13.6.2 Table 298 — PDF 1.6 3D artwork annotation, the means by which U3D / PRC artwork is embedded in a PDF document). The new AnnotationKind::ThreeD variant surfaces the /3DD artwork reference (§13.6.3 stream or §13.6.3.3 reference dictionary, preserved as ObjectId since this crate doesn't decode 3D artwork), the /3DV initial-view selector collapsed into a new ThreeDViewSelector four-shape union (View(ObjectId) for a 3D view-dict reference, Index(i64) for a /VA-array index, Name(String) for a text-string match against a view's /IN, and Symbolic(String) for the F / L / D first/last/default selector — matching Table 298's four spec alternatives), the /3DA activation dictionary decoded into a new ThreeDActivation struct carrying every Table 299 field (/A, /AIS, /D, /DIS, plus the PDF 1.7 /TB and /NP toolbar / navigation-panel flags), the /3DI interactive-use flag (Table 298 default true when absent), and the /3DB 3D view box rectangle. The activation dict resolves through DocumentReader::deref so inline and indirect-ref forms decode uniformly; unknown Name values in /A / /AIS / /D / /DIS pass through verbatim so a forensic walk sees what the producer wrote (the spec enumerations are open-ended in practice). The actual 3D artwork payload stays out of scope — this crate does not bundle a 3D-graphics decoder. The remaining long-tail subtypes (RichMedia, Projection) still surface as AnnotationKind::Other { subtype } — they need cross-crate plumbing (ISO 32000-2 §13.7 rich-media) the round-26 reader doesn't reach. Common Table 164 fields (/Rect, /Contents, /NM, /M, /F, /C, /Border) are decoded for every subtype.

use oxideav_pdf::{reader::DocumentReader, AnnotationKind};

let mut r = DocumentReader::open(&pdf_bytes)?;
for a in r.annotations()? {
    println!("page {} {:?}: {}", a.source_page_index, a.rect,
        a.contents.as_deref().unwrap_or(""));
    if let AnnotationKind::Stamp { icon } = &a.kind {
        println!("  stamp icon: {icon}");
    }
}
# Ok::<(), oxideav_pdf::PdfError>(())

[DocumentReader::xmp_packet] parses the document-level XMP packet round-19 surfaces into a structured [XmpPacket] (ISO 32000-1 §14.3.2 + Adobe XMP Spec 2012 / ISO 16684-1 / ISO 19005-1..3 §6.x). Covers the most-used Dublin Core (dc:title through rdf:Alt, dc:creator through rdf:Seq, dc:subject rdf:Bag, dc:rights, dc:format), XMP Basic (xmp:CreateDate / xmp:ModifyDate / xmp:MetadataDate / xmp:CreatorTool), PDF schema (pdf:Producer / pdf:Keywords / pdf:PDFVersion / pdf:Trapped), and PDF/A identification (pdfaid:part / pdfaid:conformance) fields. Element and attribute forms both recognised; XML entities (& / < / > / " / ') plus numeric character references decode. XmpPacket::is_pdf_a() + pdf_a_conformance() collapse the pair into a 1B-style PDF/A conformance designator.

let mut r = oxideav_pdf::reader::DocumentReader::open(&pdf_bytes)?;
if let Some(p) = r.xmp_packet()? {
    println!("title:    {:?}", p.dc_title);
    println!("creator:  {:?}", p.dc_creator);
    println!("producer: {:?}", p.pdf_producer);
    if p.is_pdf_a() {
        println!("PDF/A conformance: {:?}", p.pdf_a_conformance());
    }
}
# Ok::<(), oxideav_pdf::PdfError>(())

Simple-font /Encoding /Differences resolver (round 28)

Simple Type 1 / TrueType / Type 3 fonts may carry their /Encoding as a dictionary that overlays a /Differences array on top of a named /BaseEncoding (ISO 32000-1 §9.6.6.1). The reader resolves this properly: the array's flat [N name1 name2 … M nameK …] form is parsed (numeric tokens reset the running code; names land at consecutive slots), and each glyph name maps to its Unicode scalar through the Adobe Glyph List (subset staged under docs/document/pdf/agl/subset.txt, ~320 glyph names). The resolver plugs into the [DocumentReader::text_extraction] path so a /Differences-using font decodes correctly to Unicode.

use oxideav_pdf::reader::{
    apply_encoding_differences, parse_encoding_differences, BaseEncoding,
    EncodingMap,
};
// Imagine an inline encoding dict resolved from a PDF font:
//   /Encoding << /BaseEncoding /WinAnsiEncoding
//                /Differences [24 /breve /caron /circumflex] >>
let diffs = parse_encoding_differences(&diffs_array)?;
let base  = EncodingMap::from_base(BaseEncoding::WinAnsi);
let map   = apply_encoding_differences(&base, &diffs);
assert_eq!(map.decode(&[0x18]), "\u{02D8}"); // breve
# Ok::<(), oxideav_pdf::PdfError>(())

Unknown glyph names emit U+FFFD as a marker (matching what pdftotext --raw does for un-resolvable glyphs). Multi-character glyph expansions (/fi → "fi", /fl → "fl") are accommodated. Six base encodings are recognised: WinAnsi / MacRoman / MacExpert / Standard / Symbol / ZapfDingbats. Full AGL coverage (CJK, Cyrillic, Devanagari) is round-29+.

Round 175 closes the AGL Public Implementation Notes §3 uniXXXX... / uXXXXXXXX Unicode-by-name escape gap. A /Differences entry of the form /uni201C resolves to U+201C and /u1F600 resolves to U+1F600 GRINNING FACE — supplementary-plane codepoints are reachable through the same path that AGL-aliased names use. The uni prefix accepts one or more consecutive 4-digit hex groups (each a BMP code point) and concatenates them into a single glyph expansion; the u prefix accepts a single 4-, 5-, or 6-digit hex code point including supplementary planes. Surrogate halves (U+D800..=U+DFFF) and the U+FFFF noncharacter are rejected per the AGL PIN. Lowercase hex is rejected (canonical AGL is uppercase). Producers that emit the escape directly instead of the AGL alias now resolve through this path; the static AGL subset is still preferred when both forms collide so the common case stays allocation-free.

Reading-order layout pass (round 29)

[DocumentReader::read_in_logical_order] walks the catalog's /StructTreeRoot /K tree and emits text runs in author-intended reading order rather than the painter's raster order (ISO 32000-1 §14.6 + §14.7 + §14.8 — Tagged PDF). For a 2-column document, naive raster extraction interleaves column 1's first row, column 2's first row, column 1's second row, …; the round-29 pass walks [Sect_col1, Sect_col2] and emits all of column 1 before any of column 2. The walker handles every leaf shape ISO 32000-1 §14.7.4.4 defines: bare-integer MCID kids (resolve against the ancestor's inheritable /Pg), <</Type /MCR /Pg p /MCID m>> marked-content references with their own /Pg overrides (cross-page tables), <</Type /OBJR …>> object references (skipped — they reference annotations, not text), and nested /StructElem kids which recurse with a 64-deep cycle guard.

use oxideav_pdf::reader::{DocumentReader, LayoutMode};

let mut r = DocumentReader::open(&pdf_bytes)?;
let result = r.read_in_logical_order()?;
match result.mode {
    LayoutMode::Tagged => println!("logical reading order:"),
    LayoutMode::Raster => println!("raster fallback (no /StructTreeRoot):"),
}
for run in &result.runs {
    println!("  {}", run.text);
}
# Ok::<(), oxideav_pdf::PdfError>(())

Documents without a /StructTreeRoot (or with a malformed / empty tree) fall back to the existing raster-order extraction with LayoutMode::Raster set on the return so callers can branch. The pass also exposes extract_text_marked(reader) which emits every text run alongside the marked-content /MCID it was painted under (for callers that want to assemble a custom logical order outside the StructTreeRoot — e.g. PDF/UA accessibility audits).

AcroForm interactive-widget writer (round 31)

[write_pdf_with_form] is the writer-side counterpart of the round-26 AnnotationKind::Widget reader. Given a Scene in pages mode plus a slice of FormField specs it emits a PDF whose Catalog carries /AcroForm and whose page /Annots arrays carry the matching /Subtype /Widget annotations (ISO 32000-1 §12.7).

All four canonical field types per §12.7.4 land:

• Text (/FT /Tx) — FormFieldText with optional default value, /MaxLen, /Q justification (left/centre/right per Table 222), and /Ff bit 12 (multi-line) per Table 228.
• Checkbox (/FT /Btn) — FormFieldCheckbox keyed by /Yes and /Off appearance states per Table 228. /V, /DV, and /AS stay consistent.
• Radio group (/FT /Btn with Radio + NoToggleToOff flags) — FormFieldRadioGroup becomes one aggregate field with /Kids referring to one widget per option; the selected option's /AS carries its export-value Name, others carry /Off.
• Choice (/FT /Ch) — FormFieldChoice with /Opt array and optional /V. /Ff bit 18 selects combo-box vs. list-box.
• Signature (/FT /Sig) — FormFieldSignature wraps a Box<dyn Signer> + SignerIdentity and re-uses the round-30 /Contents placeholder pattern. Only one signature field per call.

use oxideav_pdf::{
    write_pdf_with_form, FieldJustification, FormField, FormFieldText,
    FormFieldCheckbox,
};

let fields = vec![
    FormField::Text(FormFieldText {
        name: "FullName".into(),
        rect: [20.0, 150.0, 180.0, 170.0],
        page_index: 0,
        value: Some("Jane Doe".into()),
        max_length: Some(64),
        multi_line: false,
        justification: FieldJustification::Left,
        default_appearance: None,
    }),
    FormField::Checkbox(FormFieldCheckbox {
        name: "Accept".into(),
        rect: [20.0, 100.0, 40.0, 120.0],
        page_index: 0,
        checked: true,
        default_appearance: None,
    }),
];
let pdf = write_pdf_with_form(&scene, &fields)?;
# Ok::<(), oxideav_pdf::PdfError>(())

The AcroForm dict gets /DA "(/Helv 12 Tf 0 g)" per §12.7.3.3 (the caller can override per field), /NeedAppearances true so viewers regenerate /AP at open time, and /SigFlags 3 when a signature field is present. qpdf --check accepts the output; the round-26 reader round-trips field_type / field_name / value for every widget.

General annotations writer (round 32)

[write_pdf_with_annotations] is the symmetric writer side of the round-26 generic annotation reader. Where round 25 emitted only /Subtype /Link and round 31 emitted /Subtype /Widget, round 32 covers the rest of the §12.5.6 subtype taxonomy that authoring tools produce in the wild: Text, Link, FreeText, Highlight, Underline, Squiggly, StrikeOut, Stamp, Square, Circle, and Ink.

Five most-common interactive PDF subtypes (Text/Link/FreeText/ Highlight/Stamp) plus three markup ones (Square/Circle/Ink) are all wired into a single Annotation struct + WriterAnnotationKind enum, with cross-subtype Table 164 fields (/T author, /M modified-date, /F flags, /C colour, /Border) hanging off the struct itself:

use oxideav_pdf::{
    write_pdf_with_annotations, Annotation, FreeTextQuadding,
    WriterAnnotationKind,
};

let annots = vec![
    Annotation {
        source_page_index: 0,
        rect: [10.0, 10.0, 30.0, 30.0],
        author: Some("Jane Reviewer".into()),
        modified: None,
        flags: None,
        colour: Some(vec![1.0, 1.0, 0.0]),
        border: None,
        kind: WriterAnnotationKind::Text {
            contents: "Please clarify".into(),
            icon: Some("Comment".into()),
            open: true,
        },
    },
    Annotation {
        source_page_index: 0,
        rect: [40.0, 60.0, 200.0, 80.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Link {
            uri: "https://example.com".into(),
        },
    },
    Annotation {
        source_page_index: 0,
        rect: [40.0, 100.0, 200.0, 130.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::FreeText {
            contents: "header".into(),
            default_appearance: None,
            quadding: FreeTextQuadding::Center,
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Highlight/Underline/Squiggly/StrikeOut take a Vec<[f32; 8]> of quads (lowered to the spec's 8N-real /QuadPoints array); Ink takes a Vec<Vec<f32>> of strokes (each [x0, y0, x1, y1, …]). qpdf --check accepts the output; the round-26 reader round-trips every subtype.

Round 227 extends the writer with the line-family that the round-197 reader already decodes — WriterAnnotationKind::Line (§12.5.6.7 Table 175), WriterAnnotationKind::Polygon, and WriterAnnotationKind::PolyLine (§12.5.6.9 Table 178). Line carries the required /L four-real endpoint array plus every Table 175 optional (/LE two-name line-ending pair per Table 176, /IC interior colour, /LL / /LLE / /LLO leader-line geometry, /Cap caption flag, /IT intent name). Polygon / PolyLine carry the required /Vertices flat coordinate list (validated even-length ≥ 4) plus the Table 178 optionals (PolyLine adds /LE; Polygon closes back to its start so it has no line endings). The writer omits each default-value field (so a write-then-read cycle through read_pdf_annotations yields the same AnnotationKind shape the reader test expects — /Cap false is an absent key, not an explicit /Cap false token).

use oxideav_pdf::{write_pdf_with_annotations, Annotation, WriterAnnotationKind};

let annots = vec![
    Annotation {
        source_page_index: 0,
        rect: [10.0, 20.0, 110.0, 60.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Line {
            endpoints: [10.0, 20.0, 110.0, 60.0],
            line_endings: Some(["OpenArrow".into(), "ClosedArrow".into()]),
            interior_colour: Some(vec![1.0, 0.0, 0.0]),
            leader_line: Some(8.0),
            leader_line_extension: Some(3.5),
            leader_line_offset: None,
            cap: true,
            intent: Some("LineArrow".into()),
        },
    },
    Annotation {
        source_page_index: 0,
        rect: [20.0, 20.0, 80.0, 80.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Polygon {
            vertices: vec![20.0, 20.0, 80.0, 20.0, 80.0, 80.0],
            interior_colour: Some(vec![0.7, 0.7, 0.95]),
            intent: Some("PolygonCloud".into()),
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Round 232 extends the writer with the markup-editing pair the round-197 reader already decodes: WriterAnnotationKind::Caret (§12.5.6.11 Table 180) and WriterAnnotationKind::Popup (§12.5.6.14 Table 183). Caret carries the optional /RD rectangle differences (each component validated ≥ 0; the left+right and top+bottom insets must fit inside the outer /Rect per Table 180) plus a CaretSymbol enum modelling the two Table 180 values (None default ⇒ /Sy entry omitted, Paragraph ⇒ /Sy /P). Popup carries an optional parent_index: Option<usize> that the writer resolves to the actual on-wire object id of the parent markup annotation (a two-pass id allocation makes earlier-in-the -slice Popups able to reference later-in-the-slice parents); the writer rejects out-of-range, self-cycle, and Popup-pointing-at -Popup configurations (a Popup's parent must be a markup annotation per §12.5.6.14). /Open defaults to false and the writer omits the entry on false, so a write-then-read cycle through read_pdf_annotations yields the same AnnotationKind::Caret { symbol: "None", .. } / AnnotationKind::Popup { parent: Some(_), open: false } shape the round-197 reader test expects.

use oxideav_pdf::{
    write_pdf_with_annotations, Annotation, CaretSymbol, WriterAnnotationKind,
};

let annots = vec![
    // The edit position the reviewer is pointing at.
    Annotation {
        source_page_index: 0,
        rect: [10.0, 20.0, 18.0, 60.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Caret {
            rect_diffs: Some([2.0, 3.0, 4.0, 5.0]),
            symbol: CaretSymbol::Paragraph,
        },
    },
    // The note text the Popup will display for editing.
    Annotation {
        source_page_index: 0,
        rect: [40.0, 100.0, 200.0, 130.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::FreeText {
            contents: "rewrite this paragraph".into(),
            default_appearance: None,
            quadding: oxideav_pdf::FreeTextQuadding::Left,
        },
    },
    // Hangs off the FreeText (index 1 in this slice).
    Annotation {
        source_page_index: 0,
        rect: [50.0, 50.0, 200.0, 150.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Popup {
            parent_index: Some(1),
            open: true,
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Round 238 folds /Subtype /FileAttachment (§12.5.6.15 Table 184) into the generic annotation surface so callers no longer have to drop down to the dedicated write_pdf_with_attachments writer just to pin one file to a page. The new WriterAnnotationKind::FileAttachment variant takes a file_name, the raw file_bytes, an optional mime_type, and an optional /Name icon (defaulting to /PushPin per Table 184). The writer additionally materialises (a) a /Type /EmbeddedFile stream (§7.11.4 Table 45 — FlateDecode-compressed when smaller), (b) a /Type /Filespec dictionary (§7.11.3 Table 44 — /F PDFDocEncoded, /UF UTF-16BE-with-BOM, and /EF pointing at the stream), and (c) a catalog /Names → /EmbeddedFiles name-tree leaf keyed on file_name (§7.7.4 + §7.9.6.2 — keys sorted byte-wise) per FileAttachment annotation. The annotation's /FS entry then resolves to the filespec, so read_pdf_attachments enumerates the same files the FileAttachment markers point at.

use oxideav_pdf::{write_pdf_with_annotations, Annotation, WriterAnnotationKind};

let annots = vec![
    Annotation {
        source_page_index: 0,
        rect: [10.0, 20.0, 30.0, 40.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::FileAttachment {
            icon: None,
            file_name: "notes.txt".into(),
            file_bytes: b"hello, pdf attachment\n".to_vec(),
            mime_type: Some("text/plain".into()),
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Empty file_name is rejected at validation (§7.11.2 requires a non-empty file name). Two FileAttachment annotations on the same document each contribute one filespec to the shared name tree, which the round-33 read_pdf_attachments enumerator surfaces in byte-wise lexicographic order.

Round 245 extends the writer with /Subtype /Sound (§12.5.6.16 Table 185 + §13.3 Table 294) so callers can pin an embedded audio clip to a page alongside the existing Text / Stamp / Highlight markup. The new WriterAnnotationKind::Sound variant takes the raw sample bytes plus the §13.3 stream metadata (sampling rate, channel count, bits-per-sample, and a SoundEncoding selector covering the four Table 294 values — Raw default, Signed, MuLaw, ALaw) plus an optional /Name icon defaulting to /Speaker per Table 185. The writer's pre-pass materialises one /Type /Sound stream object per Sound annotation, emitting each Table 294 field at its non-default value only (so a write-then-read cycle through read_pdf_annotations yields the same absent-equals-default branch the round-209 reader exercises on producer files), and the annotation's /Sound entry resolves to that stream's indirect reference.

use oxideav_pdf::{
    write_pdf_with_annotations, Annotation, SoundEncoding, WriterAnnotationKind,
};

let samples: Vec<u8> = telephony_recording_mulaw_8khz_mono();
let annots = vec![
    Annotation {
        source_page_index: 0,
        rect: [10.0, 20.0, 30.0, 40.0],
        author: Some("Voice memo".into()),
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Sound {
            icon: Some("Mic".into()),
            sampling_rate: 8000.0,
            channels: 1,
            bits_per_sample: 8,
            encoding: SoundEncoding::MuLaw,
            sound_samples: samples,
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Validation rejects a non-finite sample rate, a non-positive sample rate, zero channels, zero bits-per-sample, and an empty sample buffer (the four shapes that would produce a §13.3 stream carrying no playable content). The §13.3 portability guidance for sample rate / channels / bits / encoding combinations is the writer's intended target, but every Table 294 value is accepted on the positive-validation path so authoring tools that produce, e.g., 44.1 kHz stereo 16-bit Signed recordings round-trip too.

Round 252 extends the writer with /Subtype /Watermark (§12.5.6.22 Table 190 + Table 191), closing the writer-side symmetry for the fixed-print annotation the round-204 reader already decodes. The new WriterAnnotationKind::Watermark variant carries an optional FixedPrintSpec sub-dict mirroring the round-204 reader-side FixedPrint shape — /Matrix six-number affine transform, /H and /V printed-media translation percentages. Each FixedPrintSpec field is Option<…>; the writer omits any entry whose value is None, so a Some(FixedPrintSpec::default()) produces the minimal /Type /FixedPrint marker dict (no per-field overrides) and a write-then-read cycle through read_pdf_annotations lands on the same "absent → default" reader branch producer files use. Watermarks constructed with fixed_print: None skip the /FixedPrint entry entirely, matching the Table 190 wording: "If this entry is not present, the annotation shall be drawn without any special consideration for the dimensions of the target media."

use oxideav_pdf::{
    write_pdf_with_annotations, Annotation, FixedPrintSpec, WriterAnnotationKind,
};

let annots = vec![
    // Bare watermark — printed without media-relative positioning.
    Annotation {
        source_page_index: 0,
        rect: [10.0, 20.0, 30.0, 40.0],
        author: Some("Approval mark".into()),
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Watermark { fixed_print: None },
    },
    // Page-number stamp pinned to 50 % across, 5 % down the printed
    // media.
    Annotation {
        source_page_index: 0,
        rect: [50.0, 60.0, 70.0, 80.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::Watermark {
            fixed_print: Some(FixedPrintSpec {
                matrix: None,
                h: Some(0.5),
                v: Some(0.05),
            }),
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Validation rejects negative /H / /V (Table 191 wording: "Negative values should not be used, since they may cause content to be drawn off the page") and any /Matrix slot that is not finite (NaN or infinity would describe an undefined affine transform per §8.3.4).

Round 257 extends the writer with /Subtype /PrinterMark (§12.5.6.20 Table 362), closing the writer-side symmetry for the production-printer-mark annotation the round-215 reader already decodes. The new WriterAnnotationKind::PrinterMark variant carries the optional /MN (mark-name) Name selector identifying the kind of mark — common Table 362 values include /ColorBar, /RegistrationTarget, /CutMark, and /PageInformation, but the spec does not enumerate a closed set so any caller-supplied Name passes through verbatim. A None omits the /MN entry entirely so a write-then-read cycle through read_pdf_annotations lands on the round-215 reader's absent-equals-None branch.

use oxideav_pdf::{write_pdf_with_annotations, Annotation, WriterAnnotationKind};

let annots = vec![
    // Colour-bar production mark along the bottom of the sheet.
    Annotation {
        source_page_index: 0,
        rect: [0.0, 0.0, 300.0, 12.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::PrinterMark {
            mark_name: Some("ColorBar".into()),
        },
    },
    // Registration-target crosshair top-left corner.
    Annotation {
        source_page_index: 0,
        rect: [4.0, 286.0, 16.0, 298.0],
        author: None,
        modified: None,
        flags: None,
        colour: None,
        border: None,
        kind: WriterAnnotationKind::PrinterMark {
            mark_name: Some("RegistrationTarget".into()),
        },
    },
];
let pdf = write_pdf_with_annotations(&scene, &annots)?;
# Ok::<(), oxideav_pdf::PdfError>(())

Validation rejects Some(String::new()) per §7.3.5 (a Name token must be at least one byte; a zero-byte mark name would serialise as a bare / token that round-trips as the absent-entry case). The Table-363 /MarkStyle and /Colorants entries hang off the form- XObject appearance stream referenced from /AP /N (not the annotation dict itself), and stay routed through the §8.10 Form XObject walker — out of scope for this round just as they are for the round-215 reader.

Embedded file attachments (round 33)

write_pdf_with_attachments(scene, &[Attachment]) embeds arbitrary files inside the PDF as /Type /EmbeddedFile streams, materialises one /Type /Filespec dictionary per attachment (ISO 32000-1 §7.11.3 Table 44 + §7.11.4 Table 45 + §3.10), registers each filespec in the catalog's /Names → /EmbeddedFiles name tree (§7.7.4 Table 31 + §7.9.6 Name trees), and optionally drops a /FileAttachment annotation marker (§12.5.6.15 Table 187) on a chosen page. The embedded-file stream body is FlateDecode-compressed when that shrinks; otherwise stored cleartext.

use oxideav_pdf::{write_pdf_with_attachments, Attachment};

let pdf = write_pdf_with_attachments(&scene, &[
    Attachment::new("notes.txt", b"Hello PDF.\n".to_vec())
        .with_mime_type("text/plain")
        .with_modified("D:20260515120000Z"),
    Attachment::new("logo.png", png_bytes)
        .with_mime_type("image/png")
        .with_annotation(0, [10.0, 10.0, 30.0, 30.0]),
])?;
# Ok::<(), oxideav_pdf::PdfError>(())

Each attachment's /F entry is the PDFDocEncoded name (literal string for ASCII; UTF-16BE-with-BOM hex string otherwise), the /UF entry is always UTF-16BE for full Unicode coverage (PDF 1.7+), and /EF /F and /EF /UF both point at the same embedded-file stream. Name-tree keys are emitted in byte-wise lexicographic order per §7.9.6.2.

The reader-side counterpart [read_pdf_attachments] walks the same name tree back into Vec<PdfAttachment { name, mime_type, bytes, modified, af_relationship }>. qpdf --check and qpdf --json both accept the output; qpdf --json lists each embedded file by name.

PDF 2.0 Associated Files (/AFRelationship + /AF, round 194)

Round 194 surfaces ISO 32000-2 §14.13 Associated Files. Each [Attachment] now carries an optional [AfRelationship] enum (per §7.11.3 Table 44) whose eight values match the spec verbatim: Source, Data, Alternative, Supplement, EncryptedPayload, FormData, Schema, Unspecified. Setting it via with_af_relationship(rel) stamps three additions onto the wire:

• /AFRelationship /<Name> on the filespec dict (§7.11.3 Table 44).
• The filespec reference in the catalog /AF array (§14.13.3 + §7.7.2 Table 29), so any PDF/A-3-aware consumer can enumerate the associated source content document-wide.
• The same reference in the per-page /AF array (§14.13.4 + §7.7.3.3) when the attachment also carries a FileAttachment annotation on that page.

use oxideav_pdf::{write_pdf_with_attachments, AfRelationship, Attachment};

let pdf = write_pdf_with_attachments(&scene, &[
    Attachment::new("invoice.xml", invoice_xml)
        .with_mime_type("application/xml")
        .with_af_relationship(AfRelationship::Source),  // PDF/A-3-shaped
    Attachment::new("data.csv", csv_bytes)
        .with_mime_type("text/csv")
        .with_af_relationship(AfRelationship::Data)
        .with_annotation(0, [10.0, 10.0, 30.0, 30.0]),  // also in page /AF
])?;
# Ok::<(), oxideav_pdf::PdfError>(())

The reader-side [read_pdf_attachments] now surfaces af_relationship: Option<AfRelationship> on each PdfAttachment: None when the producer omitted the entry (PDF 1.x behaviour), or a vendor / second-class Name (§Annex E) sat in the slot — the reader refuses to coerce unknown Names; the eight enumerated values round-trip exactly. An attachment that does not call with_af_relationship preserves the round-33 byte shape exactly: no /AFRelationship Name, no /AF arrays on the catalog or page. qpdf --check accepts the round-194 output.

Document time-stamp signatures (round 34)

add_document_timestamp(pdf, tsa) appends an RFC 3161 Document Time-Stamp revision (ISO 32000-1 §12.8.5) to an existing (signed-or-unsigned) PDF. The new revision adds a /FT /Sig field whose /V is a sig dictionary with /Type /DocTimeStamp + /SubFilter /ETSI.RFC3161, and whose /Contents <…hex…> holds a full RFC 3161 TimeStampToken (a CMS SignedData ContentInfo over a TSTInfo SEQUENCE). The byte-range placeholder pattern of round 30 is reused, so a doc-timestamp can coexist with one or more regular signatures in the same document — each is its own incremental update per ISO 32000-1 §7.5.6.

use oxideav_pdf::{add_document_timestamp, MockTsaSigner, SignerIdentity};
let tsa = MockTsaSigner::new(rsa_priv, identity, b"20260517000000Z".to_vec())?;
let stamped = add_document_timestamp(&signed_pdf, &tsa)?;

The [TsaSigner] trait is the integration seam for production TSAs (RFC 3161 §3 HTTP transport, RFC 5816 ESSCertIDv2 — both out of scope for round 34). The in-tree [MockTsaSigner] short-circuits the network round-trip with a self-signed RSA-2048 / SHA-256 token — handy for tests and for self-contained roundtrips. The reader side surfaces timestamps separately via DocumentReader::doc_timestamps() (or the free fn [read_pdf_doc_timestamps]). qpdf --check accepts the output; when openssl ts -verify is on PATH, it accepts the embedded TST.

Content-stream DeviceCMYK colour (round 115)

The content-stream parser now honours the k (fill) and K (stroke) DeviceCMYK colour operators (ISO 32000-1 §8.6.4.4). Because the vector IR carries only DeviceRGB, each CMYK colour is converted via §10.3.5 ("Conversion from DeviceCMYK to DeviceRGB") — red = 1 − min(1, cyan + black) and the magenta/yellow counterparts, no black generation or undercolour removal. Pure cyan/magenta/yellow inks reconstruct as (0,255,255) / (255,0,255) / (255,255,0) and 0 0 0 1 k as black, where the parser previously collapsed every CMYK colour to opaque black. Out-of-range operands are clamped to 0.0..=1.0 first (§10.3.4 NOTE 4).

Content-stream colour-space selection (round 118)

The content-stream parser now honours the cs / CS colour-space operators and interprets the following sc / scn / SC / SCN colour values against the selected space (ISO 32000-1 §8.6.8 Table 74

• §8.6.4). Where the round-3 parser collapsed every sc/scn to opaque black, a document setting colour via /DeviceRGB cs 1 0 0 sc (instead of the 1 0 0 rg shorthand) now reconstructs red. The three device families resolve by name — /DeviceGray (1 component), /DeviceRGB (3), /DeviceCMYK (4, via the §10.3.5 conversion), plus the abbreviated inline-image spellings G / RGB / CMYK. The implicit-space operators (g/rg/k, G/RG/K) also record their space so a subsequent bare sc/scn resolves correctly, and a bare cs/CS initialises the colour to black per §8.6.4.2..4.

/Pattern, a trailing /Name pattern operand (§8.7.3.3), CIE-based (CalRGB / CalGray / Lab) and DeviceN spaces keep the conservative black fallback — they need a gamut-mapping pass or a multi-input tint-transform evaluation this layer doesn't yet carry. (Single-input Separation tint transforms over a device alternate are evaluated as of round 311 — see below.)

Resource colour spaces: ICCBased + Indexed (round 275)

Round 275 plumbs the page's resolved /Resources /ColorSpace subdictionary into the content parser so a cs / CS naming a resource key (rather than a bare device family) resolves against it (ISO 32000-1 §8.6.8 Table 74). Two non-CIE families reduce to a device fallback the round-118 parser previously collapsed to black:

• ICCBased (§8.6.5.5) — the /Alternate device space is used when present, otherwise the profile's /N component count selects DeviceGray (1) / DeviceRGB (3) / DeviceCMYK (4), exactly the fallback the spec authorises for a reader that does not process the embedded profile ("if this entry is omitted and the conforming reader does not understand the ICC profile data, the colour space that shall be used is DeviceGray, DeviceRGB, or DeviceCMYK …"). The ICC profile bytes are never interpreted.
• Indexed (§8.6.6.3) — when the base reduces to a device family, a subsequent sc/scn index selects the corresponding m-byte table entry. The index is rounded to the nearest integer and clamped into 0..=hival; each byte is scaled 0..255 → the base component range; a bare cs initialises the colour to table entry 0. A base that is itself Indexed (forbidden by §8.6.6.3) or non-device, a truncated table, or an out-of-range index falls back gracefully without an out-of-bounds read.

The document-level [resolve_color_space_resources] helper mirrors the round-125 gs / round-128 font / round-259 shading resolvers: it dereferences the /ColorSpace dict one hop, replaces an ICC profile stream with its dictionary (so /N + /Alternate are reachable) and an Indexed lookup stream (PDF 1.2) with its decoded bytes (so the table is self-contained). The new [parse_content_stream_full_with_color_space] entry point takes the resolved dict; the legacy entry points keep their round-118 behaviour (non-device names stay Unknown, sc/scn keeps the black fallback).

Separation colour space + Type 2/3 tint transforms (round 311)

Round 311 evaluates the /Separation colour space (ISO 32000-1 §8.6.6.4) when its alternate reduces to a device family. A Separation space carries a single tint component in 0.0..=1.0; setting it as the current space and painting via sc/scn runs the tint through the space's tint-transform function (§7.10) to produce the alternate device space's component values, which are then rendered to RGB. The round-118 parser collapsed every Separation sc/scn to black; a document painting a spot colour such as the §8.6.6.4 EXAMPLE 2 [ /Separation /LogoGreen /DeviceCMYK 12 0 R ] now reconstructs the approximated colour.

This round adds a self-contained evaluator for the two dictionary-shaped function types §7.10 defines that are common as tint transforms:

• Type 2 — exponential interpolation (§7.10.3 Table 40): f(x) = C0 + x^N · (C1 − C0), one input, n outputs. C0 / C1 default to [0.0] / [1.0]; N is the interpolation exponent.
• Type 3 — stitching (§7.10.4 Table 41): a 1-input function partitioned across k subdomains by Bounds, each child function reached after the §7.10.4 Encode/Interpolate input remap (the half-open [b_{i-1}, b_i) intervals, last closed on the right, including the degenerate last-bound-equals-Domain1 case).

Both honour the §7.10.1 Table 38 Domain (input clip) and optional Range (per-output clip). The Separation tint itself is clamped into the §8.6.6.4 0.0..=1.0 colour range first, and the initial colour is tint 1.0 ("The initial value … shall be 1.0"), so a bare cs paints the full-tint colour rather than black. The special colorant names /All and /None are recognised — /None produces no visible output (no paint), and /All is approximated through the alternate.

A Separation whose alternate isn't a device family (CIE-based / Indexed / another special space — the latter forbidden by §8.6.6.4), or whose tint transform is a Type 0 (sampled) or Type 4 (PostScript-calculator) function (which arrive as streams, not evaluated this round), stays Unknown with the conservative black fallback. The document-level resolver normalises [ /Separation name alt tintTransform ] so the content parser sees a self-contained array (the alternate prepared recursively, the tint-transform function dereferenced and — for Type 3 — its /Functions sub-functions prepared in turn), mirroring the round-275 ICCBased / Indexed normalisation. Thirteen tests cover the function evaluator (Type 2 interpolation / exponent / range clip, Type 3 subdomain routing, Type 0/4 rejection) and the end-to-end Separation paths (CMYK / Gray alternates, Type 3 tint, /None, full- tint default, out-of-range clamp, non-device-alternate and unevaluable-tint fallbacks). DeviceN (multi-input tint transforms) and Type 0/4 functions remain a follow-up.

Marked-content operators (BMC/BDC/EMC/MP/DP, round 292)

Round 292 surfaces the five marked-content operators of ISO 32000-1 §14.6 (Table 320), which the round-3 parser previously collapsed into the catch-all no-op. They fall into two shapes:

• Points — tag MP and tag properties DP designate a single marked-content point in the stream.
• Sequences — tag BMC and tag properties BDC begin a sequence terminated by a balancing EMC.

The new [parse_content_stream_full_with_properties] entry point (and the page walker) emit one [ContentMarkedContent] per operator into [ParsedContent::marked_content] in stream order, each carrying the operator discriminator ([MarkedContentOp]), the tag Name, the resolved property list (DP/BDC only), and the sequence-nesting depth. A downstream consumer can rebuild the marked-content tree — e.g. to read an /OC optional-content membership tag (§8.11.3.2) or an /ActualText / /Alt accessibility entry (§14.9.4) off the property list.

The properties operand is resolved per §14.6.2: when every value is a direct object it may be written inline as << … >> (a new content-stream inline-dictionary operand, parsed by the same object parser the body uses) and is captured verbatim; otherwise it is a /Name looked up one hop in the page's /Resources /Properties subdictionary (resolve_properties_resources, mirroring the round-125 gs / round-128 font / round-259 shading / round-275 colour-space resolvers). The walker never interprets the property list — /OC, /MCID, /ActualText, /Alt, etc. stay verbatim.

Nesting depth is tracked with a saturating counter across BMC/BDC/EMC: a BMC/BDC reports the depth of the sequence it opens (0 for top-level), the matching EMC reports the same depth, and an MP/DP point reports the depth of the sequence enclosing it. An unbalanced EMC (no open sequence) saturates at depth 0 and is tolerated, matching the parser's salvage stance. Like the round-128 text_shows and round-259 shadings, marked-content events surface from every ParsedContent-returning entry point; named-property resolution and the page-walker plumbing are what the new entry adds. The graphics bracketed by a sequence still paint normally — the marked-content operators annotate, they do not suppress.

Content-stream Tj / TJ text-show with /Resources /Font (round 128)

The content-stream parser now resolves text-show operators against the page's /Resources /Font subdictionary (ISO 32000-1 §9.4 + Table 105 + Table 108 + Table 109). A new [parse_content_stream_full(input, ext_gstate, fonts)] entry point returns a [ParsedContent { root, text_shows }] carrying one [ContentTextShow] per Tj / TJ / ' / " show, each with the resolved font dictionary, the Tf-recorded font name + size, the decoded operand bytes (literal-string escapes + hex-pair decoding both handled per §7.3.4), the text-matrix origin at the moment of the show, and a [TextShowOp] discriminator naming the originating operator.

Text-state operators (BT / ET / Tf / Tm / Td / TD / T* / TL) are honoured per §9.4.2 Table 108 — the text matrix resets to identity on every BT, advances by the explicit displacement on Td/TD/Tm, and steps down by the current leading on T* / implicit-T* from ' and ". TJ's per-element numeric kerning displacements are dropped because they affect only glyph positioning, not the decoded text payload — the strings are concatenated in array order.

The page walker plumbs the page's /Resources /Font through a new single-hop indirect-dereference helper (resolve_font_resources) mirroring the round-125 resolve_ext_gstate shape. A Tf against a font name that isn't present in the resources dict still emits the show — the consumer learns the font wasn't resolved via font_dict = None rather than the show silently disappearing. The round-22 [DocumentReader::text_extraction] walker still owns the byte→Unicode mapping (encoding / /ToUnicode CMap resolution); this round-128 surface is the narrower path a consumer that already has the page resources resolved can use.

The legacy [parse_content_stream] and [parse_content_stream_with_resources] entry points keep their round-3 / round-125 no-op behaviour — text-show operands are dropped silently so existing callers don't see new events appear.

Content-stream gs ExtGState resolution (round 125)

The content-stream parser now honours the gs graphics-state operator (ISO 32000-1 §8.4.5 + Table 57). Each page's /Resources /ExtGState subdictionary is plumbed through to the parser; a /GSx gs looks /GSx up there and applies the Table-58 entries that map onto the round-3 vector IR:

• LW — line width (overrides the w operator).
• LC — line cap (Butt / Round / Square).
• LJ — line join (Miter / Round / Bevel).
• ML — miter limit.
• D — [dashArray dashPhase] pair (the same shape d takes).
• CA — stroking alpha constant (§11.6.4.4); multiplies into the current stroke paint's alpha channel.
• ca — nonstroking alpha constant; multiplies into the current fill paint's alpha.

Multiple gs invocations cumulate — an earlier /GW gs carrying only LW survives a later /GA gs carrying only CA, matching the §8.4.5 "results of gs shall be cumulative" rule. Other Table-58 keys (BM, OP / op / OPM, SMask, Font, BG / UCR / TR / HT, RI, SA, AIS, TK, FL, SM) are tolerated as silent no-ops — they need IR plumbing the vector model doesn't yet carry, so honouring them now would be misleading rather than additive.

Fuzz harness (round 145)

The crate ships a cargo-fuzz harness under fuzz/ with three panic-free decode-side targets. PDF has no external library worth pulling in as a cross-decode oracle (and the clean-room wall bars qpdf / pdfium / poppler / mupdf source anyway), so this is a decode-only contract: feed arbitrary bytes to the public reader entry points and assert they always return a Result rather than panicking, aborting, or OOMing.

• parse — drives read_pdf_to_scene end-to-end (§7.5 file structure + §7.8 page tree + §8/§9 content streams + §7.4 stream filters) plus the three standalone reader entry points parse_linearization_dict (§7.5.2), extract_inline_images_from_stream (§8.9.7), and parse_content_stream (§8/§9).
• xref — drives the §7.5.4 classic xref-table parser, the §7.5.8 cross-reference-stream parser, and the §7.5.8.4 hybrid-reference merge directly: both the one-shot parse_xref entry point and the two-step find_startxref_offset + parse_xref_at split, the latter with a fuzz-derived out-of-range offset pulled from the input.
• decrypt — drives read_pdf_to_scene_with_password with an arbitrary password split out of the fuzzer input. Exercises §7.6 standard-handler dispatch (R=2 RC4-40, R=3 RC4-128, R=4 AES-128 / RC4-128 with crypt filters, R=5 / R=6 AES-256 with SHA-256/384/512 key derivation per ISO 32000-2:2020 §7.6.4.4.3 Algorithm 2.B).

The corpus is seeded with the existing in-tree fixtures (tests/fixtures/{font_resources,gs_ext_gstate,hybrid_xrefstm}.pdf) plus minimal scaffolds. Round 1 of the harness ran ~5 M execs per target locally and surfaced two reader-side panics (a §7.7.3.2 /Pages-tree cycle that recursed forever, and a §7.3.4.2 literal string with a trailing \ that overran the slice index), both fixed in this round with regression coverage under tests/fuzz_regressions.rs. Round 191 fixed a third — a §7.5.7 Type-2 xref entry whose container number was itself a Type-2 entry (forbidden by spec — "object streams shall not contain object streams") looped resolve → decode_objstm_container → resolve forever before the cycle guard caught it, blowing the call stack under AddressSanitizer. The resolver now rejects such entries statically from the xref table, and Parser::parse_array / parse_dict_or_stream carry a hard MAX_PARSE_DEPTH = 256 ceiling so a deeply-nested-composite-only sibling input surfaces a clean error instead of overflowing. CI runs the suite daily under .github/workflows/fuzz.yml with a 30-minute total budget split across the three targets.

Criterion bench harness (round 148)

The crate ships three Criterion bench binaries under benches/ that measure the reader hot paths against writer-emitted PDFs. The writer-side cost is paid in the per-bench setup step (outside the timed region) so each iteration measures only the reader. Per the workspace "saturated → fuzz/bench/profile" memo this round adds the bench surface so future reader / writer rounds can A/B their parser tweaks against a stable baseline.

• reader_open — drives read_pdf_to_scene end-to-end on single-page / 10-page / 50-page documents emitted via the three top-level writer entry points (write_pdf_from_scene for the classic §7.5.4 xref table, write_pdf_from_scene_xref_stream for the §7.5.8 cross-reference stream, and write_pdf_from_scene_object_stream for the §7.5.7 ObjStm container).
• xref — drives parse_xref directly on the same three document families, isolating the §7.5.4 / §7.5.8 cross-reference parser cost from the rest of the open path.
• content_stream — drives parse_content_stream on four synthetic operator-stream bodies covering the §8 / §9 hot paths: a short single-rectangle path, 100 small polygons, 50 nested q ... Q save/restore brackets with W n clip paths, and a 500-group "mixed-realistic" mix of cm / q / Q / m / l / c / h / f / B / S / rg / RG.

Local headline numbers on the round-148 host (macOS-aarch64, cargo bench, smoke-quick mode):

bench	size	throughput
read_pdf_to_scene/open_single_page_classic_xref	581 B	138 MiB/s
read_pdf_to_scene/open_ten_page_classic_xref	5993 B	209 MiB/s
read_pdf_to_scene/open_fifty_page_xref_stream	25105 B	175 MiB/s
read_pdf_to_scene/open_fifty_page_object_stream	9463 B	54.6 MiB/s
parse_xref/parse_xref_classic_table_10p	3716 B	1.90 GiB/s
parse_xref/parse_xref_classic_table_50p	17729 B	2.68 GiB/s
parse_xref/parse_xref_stream_50p	14951 B	1.13 GiB/s
parse_xref/parse_xref_stream_with_objstm_50p	8203 B	560 MiB/s
parse_content_stream/content_short_path_only	88 B	130 MiB/s
parse_content_stream/content_long_path_100	5282 B	161 MiB/s
parse_content_stream/content_groups_and_clips	5939 B	154 MiB/s
parse_content_stream/content_mixed_realistic	48473 B	181 MiB/s

Round-151 closed the §7.5.7 compressed-object resolver hot path: [DocumentReader] now memoises each ObjStm container's Flate-decompressed payload + parsed (obj_num, abs_payload_offset) header slot table on first access. Resolving M compressed objects against the same container drops from O(M²) (every resolve(compressed) call re-decompressed the full payload

• re-parsed every header pair) to O(M) for the first call + O(1) per subsequent slot. The 50-page ObjStm bench moved from 3.10 MiB/s to 54.6 MiB/s (≈ 17.6× wall-clock, -94% time) on the round-148 host; classic-xref + xref-stream paths unchanged within ±3% noise. The remaining ~3× gap to the classic-xref scenario is the per-call decode-stream cost (one decompression for the container shared across all M slots) which is irreducible without cross-DocumentReader caching (out of scope).

Run a single bench with:

cargo bench -p oxideav-pdf --bench reader_open
cargo bench -p oxideav-pdf --bench xref
cargo bench -p oxideav-pdf --bench content_stream

Round-285 profiling — content-stream number conversion

Depth-mode profiling round on the bytes → Scene read path. examples/profile_read.rs is the reproducible harness: it emits three heavy writer-produced documents (120 pages × ~220 path segments, alternating solid / gradient fills) through the classic §7.5.4 xref-table, §7.5.8 xref-stream, and §7.5.7 ObjStm writer entry points, loops read_pdf_to_scene, and prints per-scenario wall-clock plus FNV-1a fingerprints of the parsed-scene {:?} serialization and of the fixture corpus (scene + extracted text) so any reader change can be A/B'd for output identity.

Sampling-profiler ranking on the round-285 host (macOS-aarch64, release + debuginfo, ~7.7k samples):

1. decimal→f32 conversion of content-stream numeric operands — ≈ 33% of all samples (str::from_utf8 validation + the general-purpose decimal-float parser behind str::parse);
2. allocator traffic from per-operator operand Vec churn (malloc/free ≈ 20%);
3. the content tokenizer loop proper;
4. everything else (object parser / lexer / xref) under 2% each.

The round lands a fast path for hotspot #1: a §7.3.3 number is sign? digits? ("." digits?)? — no exponent — so its value is significand / 10^frac. When the significand is < 2²⁴ (exact in f32) and the fraction is ≤ 10 digits (10¹⁰ = 5¹⁰·2¹⁰ and 5¹⁰ < 2²⁴, so the divisor is exact too), IEEE-754 division of two exact operands is correctly rounded — and the correctly rounded result is unique, hence bit-identical to str::parse::<f32> on the same bytes. Wider inputs fall back to str::parse; a 2000-case generated parity test pins the bit-identity contract. Both content-stream number sites (operand scanner + TJ/dash-array reader) share the new scan_number.

Measured on the harness (1500 iterations/scenario, sequential):

scenario	before	after	Δ
classic_xref_120p	2.910 ms/doc	2.063 ms/doc	−29.1%
xref_stream_120p	2.955 ms/doc	2.050 ms/doc	−30.6%
objstm_120p	3.019 ms/doc	2.109 ms/doc	−30.1%

Output identity: all three scenario scene-hashes and every fixture scene/text fingerprint are byte-identical before vs after. Next hotspot (deferred): operand-Vec allocation churn in the content-stream dispatcher (take_numbers + per-operator operands reallocation), now ≈ 20% of samples.

Round-306 — /FlateDecode backend on the workspace compcol

The crate's RFC 1950 (zlib) / RFC 1951 (DEFLATE) layer behind /FlateDecode (ISO 32000-1 §7.4.4) now runs on compcol, Karpelès Lab's compression collection — the same workspace-wide DEFLATE/zlib backend the sibling format crates (png, tiff, mov, id3) already use. The previous third-party flate2/miniz_oxide dependency is dropped.

Every FlateDecode site routes through one private zlib module (flate_compress / flate_decompress): the reader's content-stream and cross-reference-stream inflate paths, and the writer's image- XObject, object-stream, cross-reference-stream, and embedded-file- stream deflate paths. All 1061 tests pass unchanged — including the full write→read round-trip suite — confirming byte-level output identity across the swap.

Deferred

• Text emission — writer-side BT … Tj … ET for Node::Text using Type 0 fonts with a CIDFont built via oxideav-ttf/oxideav-otf. The reader-side extraction surface landed in round 22 (see above).
• Writer-side JPEG passthrough on ImageRef (DCTDecode XObject) — needs core IR support for "raw codec bytes" alongside the decoded VideoFrame so the writer can emit /Filter /DCTDecode instead of re-encoding every JPEG to FlateDecoded raw RGBA. The reader-side surface landed in round 23 (see above).
• Extended generic hint tables (F.4.5) and embedded-file-stream hint tables (F.4.6) for linearized output — we generate no interactive forms / structure trees / embedded files, so the per-table content would be empty anyway.
• Ed25519 / Ed448 signature dispatch in pubsec::verify — round 20 covers RSA-PKCS#1 v1.5 / RSA-PSS / ECDSA on P-256 / P-384 / P-521; EdDSA needs an ed25519-dalek (or ed448-goldilocks) dep.
• Transparency groups beyond a per-Group /ca+/CA opacity.

Usage

[dependencies]
oxideav-core = "0.1"
oxideav-pdf  = "0.0"

use oxideav_core::{
    FillRule, Group, Node, Paint, Path, PathNode, Point, Rgba, VectorFrame,
};
use oxideav_core::TimeBase;

let mut p = Path::new();
p.move_to(Point::new(10.0, 10.0))
    .line_to(Point::new(110.0, 10.0))
    .line_to(Point::new(110.0, 60.0))
    .line_to(Point::new(10.0, 60.0))
    .close();

let frame = VectorFrame {
    width: 200.0,
    height: 100.0,
    view_box: None,
    root: Group {
        children: vec![Node::Path(PathNode {
            path: p,
            fill: Some(Paint::Solid(Rgba::opaque(0xFF, 0x80, 0x00))),
            stroke: None,
            fill_rule: FillRule::NonZero,
        })],
        ..Group::default()
    },
    pts: None,
    time_base: TimeBase::new(1, 1),
};

let pdf = oxideav_pdf::write_pdf(&frame).expect("vector → PDF");
std::fs::write("out.pdf", pdf).unwrap();
# Ok::<(), Box<dyn std::error::Error>>(())

License

MIT — see LICENSE.