documents.js 1.32.0 → 1.33.0

package/README.md

@@ -1,14 +1,20 @@
 # documents.js
 
-> Bidirectional docx/pptx ⇄ PDF conversion and a read+write editable OOXML document model, built on [ooxml.js](https://github.com/ExaDev/ooxml.js) and Zod 4 codecs.
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js) [![npm](https://img.shields.io/npm/v/documents.js?logo=npm)](https://www.npmjs.com/package/documents.js) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
 
-`documents.js` depends on `ooxml.js` for lossless docx/pptx/xlsx ⇄ JSON handling and extends it in two directions `ooxml.js` deliberately does not cover: full PDF support, and a read-**and-write** manipulation API for docx/pptx content (`ooxml.js`'s own typed readers are one-way and explicitly forbid write-back). PDF reading, writing, and the docx⇄pdf/pptx⇄pdf conversion codecs are entirely hand-written — no external PDF library is a dependency.
+> Bidirectional docx/pptx ⇄ PDF conversion, a read-and-write live-view editor for docx/pptx content, and a fully hand-written PDF codec, built on [ooxml.js](https://github.com/ExaDev/ooxml.js).
 
-**Status: early bootstrap.** This repository currently contains only project scaffolding; the source tree, tooling, and package have not been built yet.
+`documents.js` depends on `ooxml.js` for lossless docx/pptx/xlsx ⇄ JSON handling and extends it in two directions `ooxml.js` deliberately does not cover: full PDF support (parsing arbitrary real-world PDFs and generating new ones), and a read-**and-write** manipulation API for docx/pptx content — `ooxml.js`'s own typed readers (`readDocx`/`readPptx`) are one-way and explicitly forbid write-back. PDF reading, writing, and the docx⇄PDF/pptx⇄PDF conversion pipeline are entirely hand-written: no external PDF library (`pdf-lib`, `pdfjs-dist`, `mupdf`, or any other) is a dependency. The one exception is [`fflate`](https://github.com/101arrowz/fflate) for raw DEFLATE/zlib compression underneath PDF's `FlateDecode` filter and PNG's `IDAT` chunks — the same dependency `ooxml.js` itself already relies on for ZIP handling.
+
+## Why
+
+Converting docx/pptx to PDF and back is usually solved by wrapping a mature third-party PDF library. This package takes the opposite approach: every layer of the PDF format — the object model, the cross-reference table, the content-stream operators, standard-font metrics, the parser's cross-reference/object-stream resolution and content-stream interpreter — is hand-written against the ISO 32000-1 specification. That is a genuinely large undertaking (the PDF codec is comparable in size to the rest of the package combined), and it comes with an honest trade-off spelled out in [Fidelity](#fidelity) below: this is not, and does not attempt to be, as robust against adversarial or badly malformed real-world PDFs as a library with 15+ years of hardening. What it buys instead is a dependency-free, fully auditable PDF implementation with no supply-chain surface beyond `ooxml.js` and `fflate`.
+
+The read-and-write editor exists because `ooxml.js`'s own typed readers are a deliberate one-way, lossy projection — reading is fine, but there is no way to add a paragraph, style a run, or insert an image and get a valid docx/pptx back out. `documents.js`'s editors are live views directly over the `XmlElement` objects inside a decoded `Package`: a mutation edits that tree in place, and everything you don't touch round-trips byte-faithful, because it never stopped being the original XML.
 
 ## Getting started
 
-Requires Node.js `>=20` and pnpm `11.6.0` (pinned via `packageManager` in `package.json`, once it exists).
+Requires Node.js `>=20` and pnpm `11.6.0` (pinned via `packageManager` in `package.json`).
 
 ```sh
 pnpm install
@@ -22,9 +28,96 @@ pnpm add documents.js
 npm install documents.js
 ```
 
-## Build, test, and lint
+## Usage
+
+The four ergonomic conversions:
+
+```ts
+import { docxToPdf, pdfToDocx, pptxToPdf, pdfToPptx } from 'documents.js';
+
+const pdfBytes = docxToPdf(docxBytes);
+const docxBytes2 = pdfToDocx(pdfBytes);
+
+const pdfFromSlides = pptxToPdf(pptxBytes);
+const pptxBytes2 = pdfToPptx(pdfFromSlides);
+```
+
+Each accepts an optional `signal` (`AbortSignal`) and either a `onSubstitution` callback (docx/pptx → PDF, called once per character not representable in a standard-14 font) or a `sink` (PDF → docx/pptx, called once per recoverable parse diagnostic).
+
+The same four conversions behind a swappable port, for a caller that wants to inject a different implementation later without changing call sites:
+
+```ts
+import { createLocalDocumentConverter } from 'documents.js';
+
+const converter = createLocalDocumentConverter();
+const { document, diagnostics } = await converter.convert(
+  { source: { format: 'docx', bytes: docxBytes }, targetFormat: 'pdf' },
+  { signal: new AbortController().signal },
+);
+```
+
+Reading and editing docx/pptx content directly, without going through PDF at all:
+
+```ts
+import { openDocx, createDocx } from 'documents.js';
+
+const editor = openDocx(existingDocxBytes);
+const paragraph = editor.body.appendParagraph({ alignment: 'center' });
+const run = paragraph.appendRun({ text: 'Hello' });
+run.bold = true;
+run.color = { r: 1, g: 0, b: 0 };
+const bytes = editor.toBytes();
+
+// or start from nothing:
+const fresh = createDocx();
+fresh.body.appendParagraph().appendRun({ text: 'New document' });
+```
+
+`openPptx`/`createPptx` and `PptxSlide`/`PptxShape` are the pptx equivalent (`slide.addTextBox`, `slide.addImage`, `shape.setParagraphs` for multi-paragraph styled text).
+
+Reading and writing PDF bytes directly, without going through docx/pptx:
+
+```ts
+import { readPdf, writePdf } from 'documents.js';
+
+const layout = readPdf(pdfBytes); // -> LayoutDocument: pages of positioned text/image/rect/link items
+const bytes = writePdf(layout);
+```
+
+The same three round trips (PDF ⇄ `LayoutDocument`, docx ⇄ PDF, pptx ⇄ PDF) are each also available as a schema-validated [`z.codec()`](https://zod.dev) pair, mirroring `ooxml.js`'s own `packageCodec` — `z.decode`/`z.encode` validate both the raw bytes (against the magic-byte schemas below) and the parsed value (against `LayoutDocumentSchema`) on every call, catching a malformed value that a bare function call wouldn't. This is the no-extra-options form: `readPdf`/`writePdf`/`docxToPdf`/etc. remain the entry points for cancellation (`signal`), diagnostics (`sink`), or substitution reporting (`onSubstitution`), none of which fit `z.codec()`'s fixed `decode(input)`/`encode(output)` signature.
 
-Once the tooling scaffold lands, the scripts mirror `ooxml.js` exactly:
+```ts
+import { z } from 'zod';
+import { docxPdfCodec, pdfCodec, pptxPdfCodec } from 'documents.js';
+
+const layout = z.decode(pdfCodec, pdfBytes); // throws a ZodError if pdfBytes has no %PDF- header
+const pdfBytes2 = z.encode(pdfCodec, layout);
+
+const pdfFromDocx = z.decode(docxPdfCodec, docxBytes);
+const docxBack = z.encode(docxPdfCodec, pdfFromDocx);
+```
+
+`readDocxContent`/`readPptxContent` (docx/pptx → `ContentDocument`), `convertWordprocessingToLayout`/`convertPresentationToLayout` (`ContentDocument` → `LayoutDocument`), and `reconstructWordprocessing`/`reconstructPresentation` (`LayoutDocument` → `ContentDocument`) are each exported individually too, for a caller that wants one stage of the pipeline without the rest.
+
+## Architecture
+
+The package is layered from generic primitives outward to the two conversion directions:
+
+- **`src/model/`** — Zod schemas only, no behaviour: unit conversions (EMU/twip/point/half-point), geometry (`Box`, `PageSize`, `Margins`, the one deliberate `flipY` between OOXML's top-left/y-down space and PDF's bottom-left/y-up space), colour, and the two pivot models — `LayoutDocument` (the PDF-side pivot: pages of positioned text/image/rect/line/ellipse/link items, PDF-native coordinates and units) and `ContentDocument` (the semantic pivot: a discriminated union of `wordprocessing` and `presentation` variants sharing paragraph/run/table/image building blocks).
+- **`src/bytes/`** and **`src/image/`** — generic byte and image-container primitives with zero PDF or OOXML knowledge: a chunked byte writer, a backtracking byte reader, CRC32, and a hand-written PNG decoder/encoder (palette/gray/RGB/alpha, multi-`IDAT` files, all five scanline filters) plus JPEG marker scanning for dimensions only — JPEG's compressed bytes pass through completely unchanged in both directions. `src/bytes/flate.ts` is the only file that imports `fflate`, mirroring how `ooxml.js`'s own `src/zip.ts` wraps it for ZIP handling.
+- **`src/xml/`** and **`src/opc/`** — parent-aware XML query/mutation and OPC package mechanics (relationship IDs, content-type entries, atomic media-part insertion) built over `ooxml.js`'s `Package`/`XmlNode`, needed because `ooxml.js`'s own XML nodes have no parent pointers and `ooxml.js` never writes new parts into an existing package.
+- **`src/edit/`** — the read-and-write editable model: live-view classes (`DocxEditor`/`DocxParagraph`/`DocxRun`/`DocxTable`, `PptxEditor`/`PptxSlide`/`PptxShape`) wrapping the actual `XmlElement` objects inside a decoded `Package`, plus `buildDocxPackage`/`buildPptxPackage` bridging a `ContentDocument` to a fresh package built entirely through those same primitives.
+- **`src/pdf/`** — the hand-written PDF codec, importing only `model`/`bytes`/`image` (no OOXML knowledge at all):
+  - **Write**: `objects.ts` (the `PdfObject` discriminated union), `afm-widths.ts`/`encoding.ts`/`winansi.ts`/`fonts.ts` (standard-14 metrics, WinAnsi encoding, family resolution), `measure.ts`/`text-layout.ts` (greedy line-wrapping), `matrix.ts`, `content-write.ts` (`LayoutItem[]` → content-stream operators), `write.ts` (the full object graph, classic cross-reference table, trailer).
+  - **Read**: `lexer.ts`/`parse.ts` (byte tokenizer and tokens → `PdfObject`), `filters.ts`/`predictors.ts` (Flate/LZW/ASCII85/ASCIIHex/RunLength, TIFF/PNG predictors), `xref.ts`/`document.ts` (classic and cross-reference-stream resolution, object streams, `/Prev` chains, linear-scan recovery, the page tree with attribute inheritance), `content-read.ts`/`interpret.ts` (the content-stream tokenizer and graphics/text state machine, including form-XObject recursion), `cmap.ts`/`font-style.ts`/`font-read.ts` (`/ToUnicode` CMaps, font-dictionary resolution), `images-read.ts` (Image XObjects → PNG/JPEG bytes), `read.ts` (`readPdf`, assembling all of the above into a `LayoutDocument`).
+  - `codec.ts` — `pdfCodec`, a `z.codec()` pair over `readPdf`/`writePdf` (PDF bytes ⇄ `LayoutDocument`).
+- **`src/ooxml/`** — resolves a `Package` into a `ContentDocument`: `docx/styles.ts` implements the full docx style cascade (`docDefaults` → named-style `basedOn` chains → paragraph-mark run properties → character styles → direct formatting) and `docx/read.ts` walks `word/document.xml`; `pptx/inherit.ts` implements the placeholder → layout → master → theme inheritance cascade (the single highest-value correctness feature for pptx, since most real shapes carry no position of their own) and `pptx/read.ts` walks the slide tree, resolving slide order through the presentation's own relationships rather than filename order.
+- **`src/layout/`** — the pure conversion algorithms, importing only `model` (no I/O): `engine.ts` (`ContentDocument` wordprocessing → `LayoutDocument`: flow, line-breaking, pagination), `slides.ts` (`ContentDocument` presentation → `LayoutDocument`: direct EMU-to-point placement, no pagination needed), `reconstruct.ts` (`LayoutDocument` → `ContentDocument`, both variants: baseline-proximity line clustering, then paragraph/text-block clustering from geometry — PDF has no semantic paragraph or shape structure to recover, only positioned glyphs).
+- **`src/convert/`** — `convert.ts` (the four ergonomic wrappers), `codec.ts` (`docxPdfCodec`/`pptxPdfCodec`, a `z.codec()` pair over each), `port.ts`/`local.ts` (the swappable `DocumentConverter` contract and its synchronous local implementation).
+
+Dependency direction is strictly downward and checkable: `model`/`bytes` import nothing local; `image` imports `bytes` only; `pdf` imports `model`+`bytes`+`image` only; `ooxml/*` imports `xml`/`model` only (no PDF knowledge); `layout` imports `model` only; `convert` composes everything else. No `PdfObject`/`PdfDict`/`PdfStream` type appears outside `src/pdf/`.
+
+## Build, test, and lint
 
 ```sh
 pnpm build         # tsdown -> dist/ (ESM + CJS + .d.ts)
@@ -32,40 +125,53 @@ pnpm typecheck     # tsc --noEmit
 pnpm lint          # eslint . --max-warnings 0
 pnpm test          # vitest run --project unit
 pnpm test:watch    # vitest --project unit
-pnpm test:smoke    # rebuilds dist/, then verifies ESM/CJS parity
-pnpm test:corpus   # optional real-world PDF conformance checks against a local, gitignored test/corpus/
+pnpm test:smoke    # rebuilds dist/, then verifies ESM/CJS parity and a real docxToPdf/pdfToDocx round trip from the built CJS bundle
+pnpm test:corpus   # optional real-world PDF conformance checks against a local, gitignored test/corpus/ (see Fidelity)
 ```
 
 To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 
-## Architecture
-
-The package is layered from a lossless OOXML core (delegated entirely to `ooxml.js`) outward to conversion and editing:
-
-- **`src/model/`** — Zod schemas only: unit conversions (EMU/twip/point/half-point), geometry, color, and the two pivot models — `LayoutDocument` (the PDF-side pivot: pages of positioned text/image/rect/line/ellipse/link items, PDF-native coordinates) and `ContentDocument` (the semantic pivot: a discriminated union of `wordprocessing` and `presentation` variants sharing paragraph/run/table/image building blocks).
-- **`src/bytes/`** and **`src/image/`** — generic byte and image-container primitives (PNG decode/encode, JPEG marker scanning) with zero PDF or OOXML knowledge. `src/bytes/flate.ts` is the only file that imports `fflate`, mirroring how `ooxml.js`'s own `src/zip.ts` wraps `fflate` for ZIP handling.
-- **`src/xml/`** and **`src/opc/`** — parent-aware XML query/mutation and OPC package mechanics (relationships, content types, media parts) built over `ooxml.js`'s `Package`/`XmlNode`.
-- **`src/edit/`** — the read+write editable model: live-view wrappers over the actual `XmlElement` objects inside a decoded `Package`, so mutations edit the tree in place and untouched content stays byte-faithful on save. This is the novel piece beyond what `ooxml.js` itself provides.
-- **`src/pdf/`** — a fully hand-written PDF codec: object model, writer (content-stream generation, standard-14 font metrics, xref table), and reader (tokenizer, cross-reference/object-stream resolution, content-stream interpreter, font/Unicode recovery). No external PDF library.
-- **`src/ooxml/`** — resolves a `Package` into a `ContentDocument`: the docx style cascade (`basedOn` chains, theme fonts, toggle properties) and the pptx placeholder→layout→master→theme inheritance cascade.
-- **`src/layout/`** — the conversion algorithms: `ContentDocument → LayoutDocument` (docx flow/pagination; pptx direct EMU-to-point placement) and the reverse (`LayoutDocument → ContentDocument`, via line/paragraph/shape clustering).
-- **`src/convert/`** — the `DocumentConverter` port/contract and its local adapter, plus the `docxPdfCodec`/`pptxPdfCodec` Zod codecs and ergonomic `docxToPdf`/`pdfToDocx`/`pptxToPdf`/`pdfToPptx` wrappers.
-
 ## Conventions
 
-- **Zod-first schema/type/guard**, matching `ooxml.js`: every model type is inferred from its Zod schema, never hand-written. Recursive types (`ContentBlock`, mirroring `ooxml.js`'s `XmlNode`) use a hand-written structural guard + `z.custom`, not `z.lazy`.
-- **No type assertions.** Every third-party or loosely-typed value (from `fast-xml-parser` via `ooxml.js`) is narrowed through a type guard or a Zod parse at the boundary. `src/pdf/`'s own object model narrows natively on its `kind` discriminant, so it needs no such guard.
-- **Dependency direction is strictly downward and checkable**: `model`/`bytes` import nothing local; `image` imports `bytes` only; `pdf` imports `model`+`bytes`+`image` only (no OOXML knowledge); `ooxml/*` imports `xml`/`model` only (no PDF knowledge); `layout` imports `model` only (pure, no I/O); `convert` composes everything else. No `PdfObject`/`PdfDict`/`PdfStream` type may appear outside `src/pdf/`.
+- **Zod-first schema/type/guard**, matching `ooxml.js`: every model type is inferred from its Zod schema, never hand-written. `ContentBlock` (recursive, mirroring `ooxml.js`'s own `XmlNode` treatment) uses a hand-written structural guard + `z.custom`, not `z.lazy`, which collapses to `unknown` for recursive element-children in the pinned Zod version.
+- **`z.codec()` for every schema-to-schema round trip**, matching `ooxml.js`'s `packageCodec`/`xmlCodec`: `pdfCodec` (PDF bytes ⇄ `LayoutDocument`) and `docxPdfCodec`/`pptxPdfCodec` (docx/pptx bytes ⇄ PDF bytes) each wrap an already-independently-tested function pair, adding automatic two-way schema validation. These are deliberately the no-options form — `readPdf`/`writePdf`/`docxToPdf`/`pdfToDocx`/`pptxToPdf`/`pdfToPptx` remain the primary entry points wherever a caller needs an `AbortSignal`, a `PdfDiagnosticSink`, or an `onSubstitution` callback, since `z.codec()`'s fixed `decode(input)`/`encode(output)` signature has no room for side-channel options.
+- **`PdfObject` has no Zod schema at all**, deliberately: it never crosses a public boundary or round-trips through JSON, and is constructed exclusively by this package's own parser — validating it would just be validating our own output. It narrows natively on its own `kind` discriminant instead, the same reasoning `ooxml.js` applies when it picks a hand-written `isXmlNode` guard over `z.lazy`.
+- **No type assertions anywhere.** Every third-party or loosely-typed value is narrowed through a type guard or a Zod parse at the boundary.
+- **Live views, not flatten-and-regenerate.** `src/edit/*`'s editor classes hold a reference directly into the real `Package`/`XmlElement` objects; saving is `encodePackage(pkg)`, nothing more. This is what makes "everything you didn't touch stays byte-faithful" a structural guarantee rather than a best effort.
+- **A three-tier PDF-read failure policy**, applied consistently across every `src/pdf/*` read module: throw a typed `PdfParseError`/`PdfEncryptedError` for a file that cannot be meaningfully processed at all; recover with a `PdfDiagnostic` (`severity: 'warning'`) for something malformed but salvageable (a bad `startxref`, a wrong stream `/Length`); degrade with a diagnostic for an individual unsupported feature (an unimplemented filter, an unrecognised colour space) while the rest of the document still reads.
 - **Conventional commits**, enforced via commitlint + husky, matching `ooxml.js`.
 
 ## Gotchas and quirks
 
-- **`ooxml.js`'s typed readers (`readDocx`/`readPptx`) are not used as a basis for conversion.** They flatten body content with a recursive-descendant search (destroying document order for paragraphs inside tables) and carry no font/size/color/geometry data. `documents.js` walks `word/document.xml`/`ppt/slides/slideN.xml` directly.
-- **The docx⇄pdf and pptx⇄pdf conversion codecs are explicitly not round-trip-lossless** — in deliberate contrast to `ooxml.js`'s own `packageCodec`, which is. A `z.codec()` here means a validated, named pair of format-*converting* transforms, not a lossless round-trip guarantee.
-- **PDF output uses standard-14 fonts only (no embedding).** Helvetica/Times-Roman are metric-compatible substitutes for Arial/Times New Roman, but Word's actual default fonts (Calibri, Aptos) are not — expect a faithful visual approximation, not a line-identical reproduction of Word/PowerPoint's own rendering.
-- **Reading arbitrary real-world PDFs is the hardest part of this package.** The hand-written parser targets cleanly-generated output from mainstream producers (Word, PowerPoint, Chrome, LibreOffice, Acrobat) and fails loudly and specifically on adversarial or badly malformed files, rather than matching a mature library's robustness.
-- **Encrypted PDFs are unsupported** (`/Encrypt` present → throws), including the common empty-user-password case.
-- **JPEG images pass through losslessly** (embedded/extracted via PDF's `DCTDecode` filter with no decode/re-encode); PNG-sourced images go through a real, narrowly-scoped hand-written codec.
+- **`ooxml.js`'s typed readers (`readDocx`/`readPptx`) are not used as a basis for conversion, and are deliberately not re-exported from this package's own public surface.** They flatten body content with a recursive-descendant search (destroying document order for paragraphs inside tables) and carry no font/size/colour/geometry data. `documents.js` walks `word/document.xml`/`ppt/slides/slideN.xml` directly, and exposing both `ContentDocument` and `ooxml.js`'s typed readers in one API would be a trap — two competing, differently-lossy document models.
+- **The docx⇄PDF and pptx⇄PDF conversions are explicitly not round-trip-lossless** — in deliberate contrast to `ooxml.js`'s own `packageCodec`, which is byte/part-faithful by design. See [Fidelity](#fidelity).
+- **PDF output uses the standard 14 fonts only — no font embedding.** Helvetica/Times-Roman are genuinely metric-compatible substitutes for Arial/Times New Roman, but Word's actual current defaults (Calibri, Aptos) are not, so line wrapping and pagination will drift slightly from what Word itself would produce. Expect a faithful visual approximation, not a line-identical reproduction.
+- **Reading arbitrary real-world PDFs is the single largest risk surface in this package**, and the parser is honest about its design target: cleanly-generated output from mainstream producers (Word, PowerPoint, Chrome, LibreOffice, Acrobat), recovering from the malformations those producers and their downstream tooling actually create, and failing loudly and specifically on anything else — not matching a mature library's robustness against adversarial input.
+- **Encrypted PDFs are unsupported.** `/Encrypt` present in the trailer throws `PdfEncryptedError`, even for the common empty-user-password case.
+- **`CCITTFaxDecode`/`JBIG2Decode`/`JPXDecode` PDF images are unsupported** (scanned-fax and JPEG2000 formats) — the image is skipped with a diagnostic, the rest of the page still reads. JPEG images (`DCTDecode`) pass through completely losslessly in both directions; PNG-sourced images go through a real, narrowly-scoped hand-written codec.
+- **PDF → docx/pptx reconstruction has no table or vector-shape recovery.** A PDF has no semantic table structure to recover — a wide horizontal gap on a line becomes a tab character, not a reconstructed grid. General vector paths, curves, gradients, and shadings are not recovered either.
+- **Table cell `colSpan`/`rowSpan` and pptx shape rotation are read from a `ContentDocument` but not yet written back** by `buildDocxPackage`/`buildPptxPackage` — a merged cell round-trips as an ordinary unmerged one, and a rotated shape round-trips unrotated. Both are bounded, tracked gaps (the cell's own text content and the shape's own position are still correct), not silent ones.
+- **docx headers/footers, live `PAGE`/`NUMPAGES` field substitution, and inline images are not read** by `readDocxContent` — a deliberate, tracked scope narrowing from the original design, not an oversight.
+
+## Fidelity
+
+**docx/pptx → PDF** is a genuine layout render: the docx flow/pagination engine and the pptx direct-placement engine both produce real positioned text, images, tables, and (for docx) numbered/bulleted lists, styled through the full cascade (theme fonts/colours, `basedOn` chains, placeholder inheritance). It is a faithful **visual approximation**, not a pixel- or line-identical reproduction of what Word/PowerPoint would themselves render — see the standard-14 font substitution gotcha above.
+
+**PDF → docx/pptx** is necessarily a **best-effort reconstruction** from geometry: a PDF page is just positioned glyphs and images, with no semantic paragraph or shape structure to recover. Reading order, bold/italic/colour/font-size, and page/slide count are preserved; paragraph and text-block boundaries are inferred from baseline spacing and left-margin indentation, not recovered exactly.
+
+Neither direction is round-trip-lossless, and the two conversions are not inverses of each other — `pdfToDocx(docxToPdf(x))` will not reproduce `x` exactly, and is not intended to. This is a deliberate, permanent contrast with `ooxml.js`'s own `packageCodec`, which genuinely is a lossless round trip. `docxPdfCodec`/`pptxPdfCodec`/`pdfCodec` share `packageCodec`'s *mechanism* (`z.codec()`, schema-validated both ways) but not its *guarantee* — wrapping a lossy conversion in `z.codec()` validates the shape of what comes out, not its fidelity to what went in.
+
+**Optional real-world corpus.** `test/corpus/` (gitignored, never committed) holds a `pnpm test:corpus` vitest project for manual conformance checking against real PDFs a hand-built fixture can't fully stand in for — a Word "Save as PDF", a PowerPoint "Save as PDF", a Chrome "Print to PDF", a LibreOffice export. It is not part of `pnpm test` and does not gate CI; drop files in locally before a significant parser change.
+
+## Release and publishing
+
+`.github/workflows/ci.yml` runs commitlint, lint, typecheck, the unit suite, and the smoke test on every push and pull request. On a push to `main` where those all pass, `release.config.ts` drives [semantic-release](https://semantic-release.gitbook.io/semantic-release): commit history since the last tag decides the version bump, `CHANGELOG.md` and `package.json` are committed back to `main`, a GitHub Release is cut, and the package publishes to [npmjs.org](https://www.npmjs.com/package/documents.js) — via npm's OIDC trusted publishing, so no `NPM_TOKEN` exists anywhere in the pipeline.
+
+Whether that release actually published a new version is detected by diffing `package.json`'s version before and after the release step, not by trusting a third-party action's own detection. Two further jobs gate on that: one republishes the same build under the scoped `@exadev/documents.js` alias to GitHub Packages (which has no OIDC exchange of its own, so it authenticates with `GITHUB_TOKEN` instead), and one packs the release into its own directory, generates an SPDX SBOM (`pnpm sbom`), and signs both an SBOM and a build-provenance attestation against that exact tarball — verifiable independently of the registry, and still present if the package is later unpublished.
+
+## Contributing
+
+Commits follow Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`, …), enforced by commitlint (`commitlint.config.ts`) via a husky `commit-msg` hook and a CI `commitlint` job — semantic-release's version bump depends on these being well-formed, not just style. A husky `pre-commit` hook runs `lint-staged` (`eslint --fix` on staged `*.ts` files) and `pre-push` runs the test suite. There is a single `main` branch and no open pull request workflow established so far.
 
 ## References
 

package/dist/index.cjs

@@ -270,7 +270,7 @@ const LayoutMetadataSchema = zod.z.object({
 	createdIso: zod.z.string().optional(),
 	modifiedIso: zod.z.string().optional()
 });
-zod.z.object({
+const LayoutDocumentSchema = zod.z.object({
 	formatVersion: zod.z.literal(1),
 	metadata: LayoutMetadataSchema,
 	pages: zod.z.array(LayoutPageSchema),
@@ -386,6 +386,45 @@ const ContentDocumentSchema = zod.z.discriminatedUnion("kind", [zod.z.object({
 	slides: zod.z.array(ContentSlideSchema)
 })]);
 //#endregion
+//#region src/model/bytes.ts
+const ZIP_LOCAL_FILE_HEADER = [
+	80,
+	75,
+	3,
+	4
+];
+const PDF_HEADER = [
+	37,
+	80,
+	68,
+	70,
+	45
+];
+const PDF_HEADER_SEARCH_WINDOW = 1024;
+function startsWithBytes(bytes, signature) {
+	if (bytes.length < signature.length) return false;
+	for (let i = 0; i < signature.length; i++) if (bytes[i] !== signature[i]) return false;
+	return true;
+}
+function containsBytesWithin(bytes, signature, window) {
+	const limit = Math.min(bytes.length - signature.length, window);
+	for (let start = 0; start <= limit; start++) {
+		let matched = true;
+		for (let i = 0; i < signature.length; i++) if (bytes[start + i] !== signature[i]) {
+			matched = false;
+			break;
+		}
+		if (matched) return true;
+	}
+	return false;
+}
+function zipBytesSchema(label) {
+	return zod.z.instanceof(Uint8Array).refine((bytes) => startsWithBytes(bytes, ZIP_LOCAL_FILE_HEADER), { message: `not a valid ${label} file: missing the ZIP local-file-header signature` });
+}
+const DocxBytesSchema = zipBytesSchema("docx");
+const PptxBytesSchema = zipBytesSchema("pptx");
+const PdfBytesSchema = zod.z.instanceof(Uint8Array).refine((bytes) => containsBytesWithin(bytes, PDF_HEADER, PDF_HEADER_SEARCH_WINDOW), { message: "not a valid PDF file: missing the %PDF- header" });
+//#endregion
 //#region src/xml/fragment.ts
 function el(tag, attrs = {}, children = []) {
 	return {
@@ -6737,6 +6776,12 @@ function writePdf(doc, options = {}) {
 	return writer.toBytes();
 }
 //#endregion
+//#region src/pdf/codec.ts
+const pdfCodec = zod.z.codec(PdfBytesSchema, LayoutDocumentSchema, {
+	decode: (bytes) => readPdf(bytes),
+	encode: (doc) => writePdf(doc)
+});
+//#endregion
 //#region src/ooxml/core-properties.ts
 const CORE_PROPERTIES_PATH = "docProps/core.xml";
 const APP_PROPERTIES_PATH = "docProps/app.xml";
@@ -8782,6 +8827,16 @@ function pdfToPptx(bytes, options) {
 	return (0, ooxml_js.encodePackage)(buildPptxPackage(content));
 }
 //#endregion
+//#region src/convert/codec.ts
+const docxPdfCodec = zod.z.codec(DocxBytesSchema, PdfBytesSchema, {
+	decode: (docxBytes) => docxToPdf(docxBytes),
+	encode: (pdfBytes) => pdfToDocx(pdfBytes)
+});
+const pptxPdfCodec = zod.z.codec(PptxBytesSchema, PdfBytesSchema, {
+	decode: (pptxBytes) => pptxToPdf(pptxBytes),
+	encode: (pdfBytes) => pdfToPptx(pdfBytes)
+});
+//#endregion
 //#region src/convert/local.ts
 const SUPPORTED_CONVERSIONS = [
 	{
@@ -8944,6 +8999,7 @@ Object.defineProperty(exports, "DefinedNameSchema", {
 		return ooxml_js.DefinedNameSchema;
 	}
 });
+exports.DocxBytesSchema = DocxBytesSchema;
 exports.DocxEditor = DocxEditor;
 exports.DocxParagraph = DocxParagraph;
 exports.DocxRun = DocxRun;
@@ -8966,8 +9022,10 @@ Object.defineProperty(exports, "PartSchema", {
 		return ooxml_js.PartSchema;
 	}
 });
+exports.PdfBytesSchema = PdfBytesSchema;
 exports.PdfEncryptedError = PdfEncryptedError;
 exports.PdfParseError = PdfParseError;
+exports.PptxBytesSchema = PptxBytesSchema;
 exports.PptxEditor = PptxEditor;
 exports.PptxShape = PptxShape;
 exports.PptxSlide = PptxSlide;
@@ -9088,6 +9146,7 @@ Object.defineProperty(exports, "decodePackage", {
 		return ooxml_js.decodePackage;
 	}
 });
+exports.docxPdfCodec = docxPdfCodec;
 exports.docxToPdf = docxToPdf;
 Object.defineProperty(exports, "elementsWithTag", {
 	enumerable: true,
@@ -9148,8 +9207,10 @@ Object.defineProperty(exports, "parseXml", {
 		return ooxml_js.parseXml;
 	}
 });
+exports.pdfCodec = pdfCodec;
 exports.pdfToDocx = pdfToDocx;
 exports.pdfToPptx = pdfToPptx;
+exports.pptxPdfCodec = pptxPdfCodec;
 exports.pptxToPdf = pptxToPdf;
 exports.readDocxContent = readDocxContent;
 exports.readPdf = readPdf;

package/dist/index.d.cts

@@ -745,6 +745,11 @@ declare const AlignmentSchema: z.ZodEnum<{
 }>;
 type Alignment = z.infer<typeof AlignmentSchema>;
 //#endregion
+//#region src/model/bytes.d.ts
+declare const DocxBytesSchema: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+declare const PptxBytesSchema: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+declare const PdfBytesSchema: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+//#endregion
 //#region src/edit/docx/image.d.ts
 interface ImageInit$1 {
   readonly format: 'png' | 'jpeg';
@@ -1002,6 +1007,125 @@ interface WritePdfOptions {
 }
 declare function writePdf(doc: LayoutDocument, options?: WritePdfOptions): Uint8Array<ArrayBuffer>;
 //#endregion
+//#region src/pdf/codec.d.ts
+declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodObject<{
+  formatVersion: z.ZodLiteral<1>;
+  metadata: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    creator: z.ZodOptional<z.ZodString>;
+    producer: z.ZodOptional<z.ZodString>;
+    createdIso: z.ZodOptional<z.ZodString>;
+    modifiedIso: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  pages: z.ZodArray<z.ZodObject<{
+    widthPt: z.ZodNumber;
+    heightPt: z.ZodNumber;
+    items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+      kind: z.ZodLiteral<"text">;
+      text: z.ZodString;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      font: z.ZodObject<{
+        family: z.ZodString;
+        weight: z.ZodEnum<{
+          bold: "bold";
+          normal: "normal";
+        }>;
+        style: z.ZodEnum<{
+          italic: "italic";
+          normal: "normal";
+        }>;
+      }, z.core.$strip>;
+      sizePt: z.ZodNumber;
+      color: z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>;
+      widthPt: z.ZodOptional<z.ZodNumber>;
+      rotationDeg: z.ZodOptional<z.ZodNumber>;
+      underline: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"image">;
+      imageId: z.ZodString;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+      rotationDeg: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"rect">;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+      fill: z.ZodOptional<z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>>;
+      stroke: z.ZodOptional<z.ZodObject<{
+        color: z.ZodObject<{
+          r: z.ZodNumber;
+          g: z.ZodNumber;
+          b: z.ZodNumber;
+        }, z.core.$strip>;
+        widthPt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"line">;
+      x1Pt: z.ZodNumber;
+      y1Pt: z.ZodNumber;
+      x2Pt: z.ZodNumber;
+      y2Pt: z.ZodNumber;
+      color: z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>;
+      widthPt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"ellipse">;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+      fill: z.ZodOptional<z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>>;
+      stroke: z.ZodOptional<z.ZodObject<{
+        color: z.ZodObject<{
+          r: z.ZodNumber;
+          g: z.ZodNumber;
+          b: z.ZodNumber;
+        }, z.core.$strip>;
+        widthPt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"link">;
+      uri: z.ZodString;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+    }, z.core.$strip>], "kind">>;
+  }, z.core.$strip>>;
+  images: z.ZodRecord<z.ZodString, z.ZodObject<{
+    format: z.ZodEnum<{
+      png: "png";
+      jpeg: "jpeg";
+    }>;
+    base64: z.ZodString;
+    widthPx: z.ZodNumber;
+    heightPx: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+//#endregion
 //#region src/ooxml/docx/read.d.ts
 declare function readDocxContent(pkg: Package$1): ContentDocument;
 //#endregion
@@ -1063,6 +1187,10 @@ interface PdfToDocumentOptions {
 declare function pdfToDocx(bytes: Uint8Array<ArrayBuffer>, options?: PdfToDocumentOptions): Uint8Array<ArrayBuffer>;
 declare function pdfToPptx(bytes: Uint8Array<ArrayBuffer>, options?: PdfToDocumentOptions): Uint8Array<ArrayBuffer>;
 //#endregion
+//#region src/convert/codec.d.ts
+declare const docxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const pptxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+//#endregion
 //#region src/convert/port.d.ts
 type DocumentFormat = 'docx' | 'pptx' | 'pdf';
 interface DocumentPayload {
@@ -1107,4 +1235,4 @@ declare function fixedClock(date: Date): ClockPort;
 //#region src/ports/abort.d.ts
 declare function throwIfAborted(signal: AbortSignal | undefined): void;
 //#endregion
-export { type Alignment, type Attribute, AttributeSchema, type BinaryPart, BinaryPartSchema, type Box, COLOR_BLACK, CONTENT_FORMAT_VERSION, type ClockPort, type Comment, CommentSchema, type CompactAttrPairs, type CompactPackage, CompactPackageSchema, type CompactPart, CompactPartSchema, type CompactXmlNode, CompactXmlNodeSchema, type ContentBlock, ContentBlockSchema, type ContentDocument, ContentDocumentSchema, type ContentImageBlock, ContentImageBlockSchema, type ContentListMembership, type ContentPageBreak, ContentPageBreakSchema, type ContentParagraph, ContentParagraphSchema, type ContentRun, ContentRunSchema, type ContentSection, ContentSectionSchema, type ContentShape, ContentShapeSchema, type ContentSlide, ContentSlideSchema, type ContentTable, type ContentTableCell, ContentTableCellSchema, type ContentTableRow, ContentTableRowSchema, ContentTableSchema, type ConversionRequest, type ConversionResult, DEFAULT_LAYOUT_FONT, type DefinedName, DefinedNameSchema, type Diagnostic, type DocumentConverter, type DocumentFormat, type DocumentPayload, type DocumentToPdfOptions, type DocxBody, DocxEditor, DocxParagraph, DocxRun, DocxTable, DocxTableCell, DocxTableRow, type DrawingParagraphInit, type DrawingRunInit, type EngineLayoutOptions, LAYOUT_FORMAT_VERSION, type LayoutColor, type LayoutDocument, type LayoutEllipse, type LayoutFont, type LayoutImage, type LayoutImageAsset, type LayoutItem, type LayoutLine, type LayoutLink, type LayoutMetadata, type LayoutPage, type LayoutRect, type LayoutText, type Margins, NOOP_DIAGNOSTIC_SINK, PAGE_SIZE_A4, PAGE_SIZE_LETTER, type Package, PackageSchema, type PageSize, type Part, PartSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfParseError, type PdfToDocumentOptions, PptxEditor, PptxShape, PptxSlide, type ReadPdfOptions, type ReconstructOptions, type Relationship, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, type SlideImageInit, type SlidesLayoutOptions, type TextBoxInit, type WinAnsiSubstitution, type WritePdfOptions, type XmlCdata, XmlCdataSchema, type XmlComment, XmlCommentSchema, type XmlDeclaration, XmlDeclarationSchema, type XmlElement, XmlElementSchema, type XmlNode, XmlNodeSchema, type XmlPart, XmlPartSchema, type XmlPi, XmlPiSchema, type XmlText, XmlTextSchema, attr, base64ToBytes, buildDocxPackage, buildPptxPackage, buildXml, bytesToBase64, childrenWithTag, compactCodec, compactPackageCodec, convertPresentationToLayout, convertWordprocessingToLayout, createDocx, createLocalDocumentConverter, createPptx, decodeCompactPackage, decodeEntities, decodePackage, docxToPdf, elementsWithTag, encodeCompactPackage, encodePackage, fixedClock, flipY, fromCompact, isCompactXmlNode, isContentBlock, isXmlNode, openDocx, openPptx, packageCodec, parsePackage, parseXml, pdfToDocx, pdfToPptx, pptxToPdf, readDocxContent, readPdf, readPptxContent, reconstructPresentation, reconstructWordprocessing, resolveRelationships, rgbHexToColor, rootElement, serializePackage, systemClock, textContent, throwIfAborted, toCompact, unzipPackage, walk, writePdf, xmlCodec, zipPackage };
+export { type Alignment, type Attribute, AttributeSchema, type BinaryPart, BinaryPartSchema, type Box, COLOR_BLACK, CONTENT_FORMAT_VERSION, type ClockPort, type Comment, CommentSchema, type CompactAttrPairs, type CompactPackage, CompactPackageSchema, type CompactPart, CompactPartSchema, type CompactXmlNode, CompactXmlNodeSchema, type ContentBlock, ContentBlockSchema, type ContentDocument, ContentDocumentSchema, type ContentImageBlock, ContentImageBlockSchema, type ContentListMembership, type ContentPageBreak, ContentPageBreakSchema, type ContentParagraph, ContentParagraphSchema, type ContentRun, ContentRunSchema, type ContentSection, ContentSectionSchema, type ContentShape, ContentShapeSchema, type ContentSlide, ContentSlideSchema, type ContentTable, type ContentTableCell, ContentTableCellSchema, type ContentTableRow, ContentTableRowSchema, ContentTableSchema, type ConversionRequest, type ConversionResult, DEFAULT_LAYOUT_FONT, type DefinedName, DefinedNameSchema, type Diagnostic, type DocumentConverter, type DocumentFormat, type DocumentPayload, type DocumentToPdfOptions, type DocxBody, DocxBytesSchema, DocxEditor, DocxParagraph, DocxRun, DocxTable, DocxTableCell, DocxTableRow, type DrawingParagraphInit, type DrawingRunInit, type EngineLayoutOptions, LAYOUT_FORMAT_VERSION, type LayoutColor, type LayoutDocument, type LayoutEllipse, type LayoutFont, type LayoutImage, type LayoutImageAsset, type LayoutItem, type LayoutLine, type LayoutLink, type LayoutMetadata, type LayoutPage, type LayoutRect, type LayoutText, type Margins, NOOP_DIAGNOSTIC_SINK, PAGE_SIZE_A4, PAGE_SIZE_LETTER, type Package, PackageSchema, type PageSize, type Part, PartSchema, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfParseError, type PdfToDocumentOptions, PptxBytesSchema, PptxEditor, PptxShape, PptxSlide, type ReadPdfOptions, type ReconstructOptions, type Relationship, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, type SlideImageInit, type SlidesLayoutOptions, type TextBoxInit, type WinAnsiSubstitution, type WritePdfOptions, type XmlCdata, XmlCdataSchema, type XmlComment, XmlCommentSchema, type XmlDeclaration, XmlDeclarationSchema, type XmlElement, XmlElementSchema, type XmlNode, XmlNodeSchema, type XmlPart, XmlPartSchema, type XmlPi, XmlPiSchema, type XmlText, XmlTextSchema, attr, base64ToBytes, buildDocxPackage, buildPptxPackage, buildXml, bytesToBase64, childrenWithTag, compactCodec, compactPackageCodec, convertPresentationToLayout, convertWordprocessingToLayout, createDocx, createLocalDocumentConverter, createPptx, decodeCompactPackage, decodeEntities, decodePackage, docxPdfCodec, docxToPdf, elementsWithTag, encodeCompactPackage, encodePackage, fixedClock, flipY, fromCompact, isCompactXmlNode, isContentBlock, isXmlNode, openDocx, openPptx, packageCodec, parsePackage, parseXml, pdfCodec, pdfToDocx, pdfToPptx, pptxPdfCodec, pptxToPdf, readDocxContent, readPdf, readPptxContent, reconstructPresentation, reconstructWordprocessing, resolveRelationships, rgbHexToColor, rootElement, serializePackage, systemClock, textContent, throwIfAborted, toCompact, unzipPackage, walk, writePdf, xmlCodec, zipPackage };

package/dist/index.d.ts

@@ -745,6 +745,11 @@ declare const AlignmentSchema: z.ZodEnum<{
 }>;
 type Alignment = z.infer<typeof AlignmentSchema>;
 //#endregion
+//#region src/model/bytes.d.ts
+declare const DocxBytesSchema: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+declare const PptxBytesSchema: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+declare const PdfBytesSchema: z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>;
+//#endregion
 //#region src/edit/docx/image.d.ts
 interface ImageInit$1 {
   readonly format: 'png' | 'jpeg';
@@ -1002,6 +1007,125 @@ interface WritePdfOptions {
 }
 declare function writePdf(doc: LayoutDocument, options?: WritePdfOptions): Uint8Array<ArrayBuffer>;
 //#endregion
+//#region src/pdf/codec.d.ts
+declare const pdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodObject<{
+  formatVersion: z.ZodLiteral<1>;
+  metadata: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    author: z.ZodOptional<z.ZodString>;
+    subject: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    creator: z.ZodOptional<z.ZodString>;
+    producer: z.ZodOptional<z.ZodString>;
+    createdIso: z.ZodOptional<z.ZodString>;
+    modifiedIso: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+  pages: z.ZodArray<z.ZodObject<{
+    widthPt: z.ZodNumber;
+    heightPt: z.ZodNumber;
+    items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+      kind: z.ZodLiteral<"text">;
+      text: z.ZodString;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      font: z.ZodObject<{
+        family: z.ZodString;
+        weight: z.ZodEnum<{
+          bold: "bold";
+          normal: "normal";
+        }>;
+        style: z.ZodEnum<{
+          italic: "italic";
+          normal: "normal";
+        }>;
+      }, z.core.$strip>;
+      sizePt: z.ZodNumber;
+      color: z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>;
+      widthPt: z.ZodOptional<z.ZodNumber>;
+      rotationDeg: z.ZodOptional<z.ZodNumber>;
+      underline: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"image">;
+      imageId: z.ZodString;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+      rotationDeg: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"rect">;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+      fill: z.ZodOptional<z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>>;
+      stroke: z.ZodOptional<z.ZodObject<{
+        color: z.ZodObject<{
+          r: z.ZodNumber;
+          g: z.ZodNumber;
+          b: z.ZodNumber;
+        }, z.core.$strip>;
+        widthPt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"line">;
+      x1Pt: z.ZodNumber;
+      y1Pt: z.ZodNumber;
+      x2Pt: z.ZodNumber;
+      y2Pt: z.ZodNumber;
+      color: z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>;
+      widthPt: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"ellipse">;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+      fill: z.ZodOptional<z.ZodObject<{
+        r: z.ZodNumber;
+        g: z.ZodNumber;
+        b: z.ZodNumber;
+      }, z.core.$strip>>;
+      stroke: z.ZodOptional<z.ZodObject<{
+        color: z.ZodObject<{
+          r: z.ZodNumber;
+          g: z.ZodNumber;
+          b: z.ZodNumber;
+        }, z.core.$strip>;
+        widthPt: z.ZodNumber;
+      }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+      kind: z.ZodLiteral<"link">;
+      uri: z.ZodString;
+      xPt: z.ZodNumber;
+      yPt: z.ZodNumber;
+      widthPt: z.ZodNumber;
+      heightPt: z.ZodNumber;
+    }, z.core.$strip>], "kind">>;
+  }, z.core.$strip>>;
+  images: z.ZodRecord<z.ZodString, z.ZodObject<{
+    format: z.ZodEnum<{
+      png: "png";
+      jpeg: "jpeg";
+    }>;
+    base64: z.ZodString;
+    widthPx: z.ZodNumber;
+    heightPx: z.ZodNumber;
+  }, z.core.$strip>>;
+}, z.core.$strip>>;
+//#endregion
 //#region src/ooxml/docx/read.d.ts
 declare function readDocxContent(pkg: Package$1): ContentDocument;
 //#endregion
@@ -1063,6 +1187,10 @@ interface PdfToDocumentOptions {
 declare function pdfToDocx(bytes: Uint8Array<ArrayBuffer>, options?: PdfToDocumentOptions): Uint8Array<ArrayBuffer>;
 declare function pdfToPptx(bytes: Uint8Array<ArrayBuffer>, options?: PdfToDocumentOptions): Uint8Array<ArrayBuffer>;
 //#endregion
+//#region src/convert/codec.d.ts
+declare const docxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const pptxPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+//#endregion
 //#region src/convert/port.d.ts
 type DocumentFormat = 'docx' | 'pptx' | 'pdf';
 interface DocumentPayload {
@@ -1107,4 +1235,4 @@ declare function fixedClock(date: Date): ClockPort;
 //#region src/ports/abort.d.ts
 declare function throwIfAborted(signal: AbortSignal | undefined): void;
 //#endregion
-export { type Alignment, type Attribute, AttributeSchema, type BinaryPart, BinaryPartSchema, type Box, COLOR_BLACK, CONTENT_FORMAT_VERSION, type ClockPort, type Comment, CommentSchema, type CompactAttrPairs, type CompactPackage, CompactPackageSchema, type CompactPart, CompactPartSchema, type CompactXmlNode, CompactXmlNodeSchema, type ContentBlock, ContentBlockSchema, type ContentDocument, ContentDocumentSchema, type ContentImageBlock, ContentImageBlockSchema, type ContentListMembership, type ContentPageBreak, ContentPageBreakSchema, type ContentParagraph, ContentParagraphSchema, type ContentRun, ContentRunSchema, type ContentSection, ContentSectionSchema, type ContentShape, ContentShapeSchema, type ContentSlide, ContentSlideSchema, type ContentTable, type ContentTableCell, ContentTableCellSchema, type ContentTableRow, ContentTableRowSchema, ContentTableSchema, type ConversionRequest, type ConversionResult, DEFAULT_LAYOUT_FONT, type DefinedName, DefinedNameSchema, type Diagnostic, type DocumentConverter, type DocumentFormat, type DocumentPayload, type DocumentToPdfOptions, type DocxBody, DocxEditor, DocxParagraph, DocxRun, DocxTable, DocxTableCell, DocxTableRow, type DrawingParagraphInit, type DrawingRunInit, type EngineLayoutOptions, LAYOUT_FORMAT_VERSION, type LayoutColor, type LayoutDocument, type LayoutEllipse, type LayoutFont, type LayoutImage, type LayoutImageAsset, type LayoutItem, type LayoutLine, type LayoutLink, type LayoutMetadata, type LayoutPage, type LayoutRect, type LayoutText, type Margins, NOOP_DIAGNOSTIC_SINK, PAGE_SIZE_A4, PAGE_SIZE_LETTER, type Package, PackageSchema, type PageSize, type Part, PartSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfParseError, type PdfToDocumentOptions, PptxEditor, PptxShape, PptxSlide, type ReadPdfOptions, type ReconstructOptions, type Relationship, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, type SlideImageInit, type SlidesLayoutOptions, type TextBoxInit, type WinAnsiSubstitution, type WritePdfOptions, type XmlCdata, XmlCdataSchema, type XmlComment, XmlCommentSchema, type XmlDeclaration, XmlDeclarationSchema, type XmlElement, XmlElementSchema, type XmlNode, XmlNodeSchema, type XmlPart, XmlPartSchema, type XmlPi, XmlPiSchema, type XmlText, XmlTextSchema, attr, base64ToBytes, buildDocxPackage, buildPptxPackage, buildXml, bytesToBase64, childrenWithTag, compactCodec, compactPackageCodec, convertPresentationToLayout, convertWordprocessingToLayout, createDocx, createLocalDocumentConverter, createPptx, decodeCompactPackage, decodeEntities, decodePackage, docxToPdf, elementsWithTag, encodeCompactPackage, encodePackage, fixedClock, flipY, fromCompact, isCompactXmlNode, isContentBlock, isXmlNode, openDocx, openPptx, packageCodec, parsePackage, parseXml, pdfToDocx, pdfToPptx, pptxToPdf, readDocxContent, readPdf, readPptxContent, reconstructPresentation, reconstructWordprocessing, resolveRelationships, rgbHexToColor, rootElement, serializePackage, systemClock, textContent, throwIfAborted, toCompact, unzipPackage, walk, writePdf, xmlCodec, zipPackage };
+export { type Alignment, type Attribute, AttributeSchema, type BinaryPart, BinaryPartSchema, type Box, COLOR_BLACK, CONTENT_FORMAT_VERSION, type ClockPort, type Comment, CommentSchema, type CompactAttrPairs, type CompactPackage, CompactPackageSchema, type CompactPart, CompactPartSchema, type CompactXmlNode, CompactXmlNodeSchema, type ContentBlock, ContentBlockSchema, type ContentDocument, ContentDocumentSchema, type ContentImageBlock, ContentImageBlockSchema, type ContentListMembership, type ContentPageBreak, ContentPageBreakSchema, type ContentParagraph, ContentParagraphSchema, type ContentRun, ContentRunSchema, type ContentSection, ContentSectionSchema, type ContentShape, ContentShapeSchema, type ContentSlide, ContentSlideSchema, type ContentTable, type ContentTableCell, ContentTableCellSchema, type ContentTableRow, ContentTableRowSchema, ContentTableSchema, type ConversionRequest, type ConversionResult, DEFAULT_LAYOUT_FONT, type DefinedName, DefinedNameSchema, type Diagnostic, type DocumentConverter, type DocumentFormat, type DocumentPayload, type DocumentToPdfOptions, type DocxBody, DocxBytesSchema, DocxEditor, DocxParagraph, DocxRun, DocxTable, DocxTableCell, DocxTableRow, type DrawingParagraphInit, type DrawingRunInit, type EngineLayoutOptions, LAYOUT_FORMAT_VERSION, type LayoutColor, type LayoutDocument, type LayoutEllipse, type LayoutFont, type LayoutImage, type LayoutImageAsset, type LayoutItem, type LayoutLine, type LayoutLink, type LayoutMetadata, type LayoutPage, type LayoutRect, type LayoutText, type Margins, NOOP_DIAGNOSTIC_SINK, PAGE_SIZE_A4, PAGE_SIZE_LETTER, type Package, PackageSchema, type PageSize, type Part, PartSchema, PdfBytesSchema, type PdfDiagnostic, type PdfDiagnosticSeverity, type PdfDiagnosticSink, PdfEncryptedError, PdfParseError, type PdfToDocumentOptions, PptxBytesSchema, PptxEditor, PptxShape, PptxSlide, type ReadPdfOptions, type ReconstructOptions, type Relationship, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, type SlideImageInit, type SlidesLayoutOptions, type TextBoxInit, type WinAnsiSubstitution, type WritePdfOptions, type XmlCdata, XmlCdataSchema, type XmlComment, XmlCommentSchema, type XmlDeclaration, XmlDeclarationSchema, type XmlElement, XmlElementSchema, type XmlNode, XmlNodeSchema, type XmlPart, XmlPartSchema, type XmlPi, XmlPiSchema, type XmlText, XmlTextSchema, attr, base64ToBytes, buildDocxPackage, buildPptxPackage, buildXml, bytesToBase64, childrenWithTag, compactCodec, compactPackageCodec, convertPresentationToLayout, convertWordprocessingToLayout, createDocx, createLocalDocumentConverter, createPptx, decodeCompactPackage, decodeEntities, decodePackage, docxPdfCodec, docxToPdf, elementsWithTag, encodeCompactPackage, encodePackage, fixedClock, flipY, fromCompact, isCompactXmlNode, isContentBlock, isXmlNode, openDocx, openPptx, packageCodec, parsePackage, parseXml, pdfCodec, pdfToDocx, pdfToPptx, pptxPdfCodec, pptxToPdf, readDocxContent, readPdf, readPptxContent, reconstructPresentation, reconstructWordprocessing, resolveRelationships, rgbHexToColor, rootElement, serializePackage, systemClock, textContent, throwIfAborted, toCompact, unzipPackage, walk, writePdf, xmlCodec, zipPackage };

package/dist/index.js

@@ -269,7 +269,7 @@ const LayoutMetadataSchema = z.object({
 	createdIso: z.string().optional(),
 	modifiedIso: z.string().optional()
 });
-z.object({
+const LayoutDocumentSchema = z.object({
 	formatVersion: z.literal(1),
 	metadata: LayoutMetadataSchema,
 	pages: z.array(LayoutPageSchema),
@@ -385,6 +385,45 @@ const ContentDocumentSchema = z.discriminatedUnion("kind", [z.object({
 	slides: z.array(ContentSlideSchema)
 })]);
 //#endregion
+//#region src/model/bytes.ts
+const ZIP_LOCAL_FILE_HEADER = [
+	80,
+	75,
+	3,
+	4
+];
+const PDF_HEADER = [
+	37,
+	80,
+	68,
+	70,
+	45
+];
+const PDF_HEADER_SEARCH_WINDOW = 1024;
+function startsWithBytes(bytes, signature) {
+	if (bytes.length < signature.length) return false;
+	for (let i = 0; i < signature.length; i++) if (bytes[i] !== signature[i]) return false;
+	return true;
+}
+function containsBytesWithin(bytes, signature, window) {
+	const limit = Math.min(bytes.length - signature.length, window);
+	for (let start = 0; start <= limit; start++) {
+		let matched = true;
+		for (let i = 0; i < signature.length; i++) if (bytes[start + i] !== signature[i]) {
+			matched = false;
+			break;
+		}
+		if (matched) return true;
+	}
+	return false;
+}
+function zipBytesSchema(label) {
+	return z.instanceof(Uint8Array).refine((bytes) => startsWithBytes(bytes, ZIP_LOCAL_FILE_HEADER), { message: `not a valid ${label} file: missing the ZIP local-file-header signature` });
+}
+const DocxBytesSchema = zipBytesSchema("docx");
+const PptxBytesSchema = zipBytesSchema("pptx");
+const PdfBytesSchema = z.instanceof(Uint8Array).refine((bytes) => containsBytesWithin(bytes, PDF_HEADER, PDF_HEADER_SEARCH_WINDOW), { message: "not a valid PDF file: missing the %PDF- header" });
+//#endregion
 //#region src/xml/fragment.ts
 function el(tag, attrs = {}, children = []) {
 	return {
@@ -6736,6 +6775,12 @@ function writePdf(doc, options = {}) {
 	return writer.toBytes();
 }
 //#endregion
+//#region src/pdf/codec.ts
+const pdfCodec = z.codec(PdfBytesSchema, LayoutDocumentSchema, {
+	decode: (bytes) => readPdf(bytes),
+	encode: (doc) => writePdf(doc)
+});
+//#endregion
 //#region src/ooxml/core-properties.ts
 const CORE_PROPERTIES_PATH = "docProps/core.xml";
 const APP_PROPERTIES_PATH = "docProps/app.xml";
@@ -8781,6 +8826,16 @@ function pdfToPptx(bytes, options) {
 	return encodePackage$1(buildPptxPackage(content));
 }
 //#endregion
+//#region src/convert/codec.ts
+const docxPdfCodec = z.codec(DocxBytesSchema, PdfBytesSchema, {
+	decode: (docxBytes) => docxToPdf(docxBytes),
+	encode: (pdfBytes) => pdfToDocx(pdfBytes)
+});
+const pptxPdfCodec = z.codec(PptxBytesSchema, PdfBytesSchema, {
+	decode: (pptxBytes) => pptxToPdf(pptxBytes),
+	encode: (pdfBytes) => pdfToPptx(pdfBytes)
+});
+//#endregion
 //#region src/convert/local.ts
 const SUPPORTED_CONVERSIONS = [
 	{
@@ -8886,4 +8941,4 @@ function fixedClock(date) {
 	return { now: () => date };
 }
 //#endregion
-export { AttributeSchema, BinaryPartSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, CommentSchema, CompactPackageSchema, CompactPartSchema, CompactXmlNodeSchema, ContentBlockSchema, ContentDocumentSchema, ContentImageBlockSchema, ContentPageBreakSchema, ContentParagraphSchema, ContentRunSchema, ContentSectionSchema, ContentShapeSchema, ContentSlideSchema, ContentTableCellSchema, ContentTableRowSchema, ContentTableSchema, DEFAULT_LAYOUT_FONT, DefinedNameSchema, DocxEditor, DocxParagraph, DocxRun, DocxTable, DocxTableCell, DocxTableRow, LAYOUT_FORMAT_VERSION, NOOP_DIAGNOSTIC_SINK, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PackageSchema, PartSchema, PdfEncryptedError, PdfParseError, PptxEditor, PptxShape, PptxSlide, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, XmlCdataSchema, XmlCommentSchema, XmlDeclarationSchema, XmlElementSchema, XmlNodeSchema, XmlPartSchema, XmlPiSchema, XmlTextSchema, attr, base64ToBytes, buildDocxPackage, buildPptxPackage, buildXml, bytesToBase64, childrenWithTag, compactCodec, compactPackageCodec, convertPresentationToLayout, convertWordprocessingToLayout, createDocx, createLocalDocumentConverter, createPptx, decodeCompactPackage, decodeEntities, decodePackage, docxToPdf, elementsWithTag, encodeCompactPackage, encodePackage, fixedClock, flipY, fromCompact, isCompactXmlNode, isContentBlock, isXmlNode, openDocx, openPptx, packageCodec, parsePackage, parseXml, pdfToDocx, pdfToPptx, pptxToPdf, readDocxContent, readPdf, readPptxContent, reconstructPresentation, reconstructWordprocessing, resolveRelationships, rgbHexToColor, rootElement, serializePackage, systemClock, textContent, throwIfAborted, toCompact, unzipPackage, walk, writePdf, xmlCodec, zipPackage };
+export { AttributeSchema, BinaryPartSchema, COLOR_BLACK, CONTENT_FORMAT_VERSION, CommentSchema, CompactPackageSchema, CompactPartSchema, CompactXmlNodeSchema, ContentBlockSchema, ContentDocumentSchema, ContentImageBlockSchema, ContentPageBreakSchema, ContentParagraphSchema, ContentRunSchema, ContentSectionSchema, ContentShapeSchema, ContentSlideSchema, ContentTableCellSchema, ContentTableRowSchema, ContentTableSchema, DEFAULT_LAYOUT_FONT, DefinedNameSchema, DocxBytesSchema, DocxEditor, DocxParagraph, DocxRun, DocxTable, DocxTableCell, DocxTableRow, LAYOUT_FORMAT_VERSION, NOOP_DIAGNOSTIC_SINK, PAGE_SIZE_A4, PAGE_SIZE_LETTER, PackageSchema, PartSchema, PdfBytesSchema, PdfEncryptedError, PdfParseError, PptxBytesSchema, PptxEditor, PptxShape, PptxSlide, SLIDE_SIZE_STANDARD, SLIDE_SIZE_WIDESCREEN, XmlCdataSchema, XmlCommentSchema, XmlDeclarationSchema, XmlElementSchema, XmlNodeSchema, XmlPartSchema, XmlPiSchema, XmlTextSchema, attr, base64ToBytes, buildDocxPackage, buildPptxPackage, buildXml, bytesToBase64, childrenWithTag, compactCodec, compactPackageCodec, convertPresentationToLayout, convertWordprocessingToLayout, createDocx, createLocalDocumentConverter, createPptx, decodeCompactPackage, decodeEntities, decodePackage, docxPdfCodec, docxToPdf, elementsWithTag, encodeCompactPackage, encodePackage, fixedClock, flipY, fromCompact, isCompactXmlNode, isContentBlock, isXmlNode, openDocx, openPptx, packageCodec, parsePackage, parseXml, pdfCodec, pdfToDocx, pdfToPptx, pptxPdfCodec, pptxToPdf, readDocxContent, readPdf, readPptxContent, reconstructPresentation, reconstructWordprocessing, resolveRelationships, rgbHexToColor, rootElement, serializePackage, systemClock, textContent, throwIfAborted, toCompact, unzipPackage, walk, writePdf, xmlCodec, zipPackage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "documents.js",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Bidirectional docx/pptx <-> PDF conversion and a read+write editable OOXML document model, built on ooxml.js and Zod 4 codecs.",
   "type": "module",
   "repository": {