js.documents 4.0.20 → 4.4.6

package/README.md

@@ -1,8 +1,8 @@
 # documents.js
 
-[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/documents.js) [![Release](https://img.shields.io/github/v/release/ExaDev/documents.js)](https://github.com/ExaDev/documents.js/releases/latest) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/documents.js/ci.yml?branch=main)](https://github.com/ExaDev/documents.js/actions)
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/documents.js/tree/main/packages/documents.js) [![npm](https://img.shields.io/badge/npm-CB3837?logo=npm&logoColor=white)](https://www.npmjs.com/package/documents.js) [![npm version](https://img.shields.io/npm/v/documents.js)](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)
 
-> Converts between any two compatible document formats through a shared content/layout pivot. docx, pptx, odt, odp, ods, odg, xlsx, csv (TSV is the same format with a tab delimiter), svg, and markdown all read into and build from the same shared `ContentDocument` model (reported to callers as the tree-form `DocumentPackage`), with PDF — reached through pdf-codec's own `LayoutDocument` view — as the one format every variant can reach. A composition engine (`convertDocument`) routes 111 (source, target) pairs across the ten content formats and PDF, including twenty PDF-pivot round trips (the eight layout-engine formats, plus xlsx and csv composing through ods), twenty-four cross-format bridge functions (same-variant direct copies, cross-variant semantic transforms, and PDF-composed), plus special-case conversions for `.odm` master documents, `.odb` database front-ends (HSQLDB and Firebird, four storage tiers), standalone `.odf` formula documents, and a bounded SQL/rpt-formula engine for `.odb` reports. Also includes: read-and-write live-view editors for all six editable formats, docx comment/footnote/header-footer exposure via `readDocxExtras`, real font resolution (source-embedded faces ahead of caller-supplied, vendored substitutes, and the standard 14), a hand-written MathML typesetting engine with embedded-font PDF rendering and a matching MathML ⇄ OMML translator, LaTeX lowering into the schema's two-layer semantic math core (pinned temml parser, symbol tables from prose, a coherence lint), and a fully hand-written PDF codec. Built on [ooxml.js](https://github.com/ExaDev/ooxml.js), [odf.js](https://github.com/ExaDev/odf.js), [pdf-codec](https://github.com/ExaDev/pdf-codec), [markdown-codec](https://github.com/ExaDev/markdown-codec), and [document-schema.js](https://github.com/ExaDev/document-schema.js).
+> Converts between any two compatible document formats through a shared content/layout pivot. docx, pptx, odt, odp, ods, odg, xlsx, csv (TSV is the same format with a tab delimiter), svg, and markdown all read into and build from the same shared `ContentDocument` model (reported to callers as the tree-form `DocumentPackage`), with PDF — reached through pdf-codec's own `LayoutDocument` view — as the one format every variant can reach. A composition engine (`convertDocument`) routes 111 (source, target) pairs across the ten content formats and PDF, including twenty PDF-pivot round trips (the eight layout-engine formats, plus xlsx and csv composing through ods), twenty-four cross-format bridge functions (same-variant direct copies, cross-variant semantic transforms, and PDF-composed), plus special-case conversions for `.odm` master documents, `.odb` database front-ends (HSQLDB and Firebird, four storage tiers), standalone `.odf` formula documents, and a bounded SQL/rpt-formula engine for `.odb` reports. Also includes: read-and-write live-view editors for all six editable formats, docx comment/footnote/header-footer exposure via `readDocxExtras`, real font resolution (source-embedded faces ahead of caller-supplied, vendored substitutes, and the standard 14), a hand-written MathML typesetting engine with embedded-font PDF rendering and a matching MathML ⇄ OMML translator, LaTeX lowering into the schema's two-layer semantic math core (pinned temml parser, symbol tables from prose, a coherence lint), and a fully hand-written PDF codec. Built on [ooxml.js](../ooxml.js/README.md), [odf.js](../odf.js/README.md), [pdf-codec](../pdf-codec/README.md), [markdown-codec](../markdown-codec/README.md), and [document-schema.js](../document-schema.js/README.md).
 
 `documents.js` extends `ooxml.js` in two directions `ooxml.js` deliberately does not cover: full PDF support (parsing and generating, via `pdf-codec`), and a read-**and-write** manipulation API for docx/pptx content — `ooxml.js`'s own typed readers are one-way. The PDF codec is hand-written against ISO 32000-1, with no external PDF library as a dependency — see [Fidelity](#fidelity) and pdf-codec's own README for the honest trade-off (not as robust against adversarial PDFs as a 15+-year-hardened library; fully auditable and dependency-free instead). `src/mathml/` (the MathML typesetting engine) stays in this package and is hand-written too, for the same supply-chain reason. The one deliberate exception on the math side is the LaTeX parser: `src/latex/` lowers LaTeX into the schema's semantic core over a pinned exact-version [temml](https://temml.org) dependency — see [LaTeX lowering into the semantic core](#latex-lowering-into-the-semantic-core) for why a LaTeX grammar is the one component not worth hand-writing and what the pin guarantees.
 
@@ -35,15 +35,15 @@ graph TD
     odf --> cli
     pdfcodec --> cli
 
-    click schema "https://github.com/ExaDev/document-schema.js" "document-schema.js"
-    click ooxml "https://github.com/ExaDev/ooxml.js" "ooxml.js"
-    click odf "https://github.com/ExaDev/odf.js" "odf.js"
-    click pdfcodec "https://github.com/ExaDev/pdf-codec" "pdf-codec"
-    click mdcodec "https://github.com/ExaDev/markdown-codec" "markdown-codec"
-    click bytecodec "https://github.com/ExaDev/byte-codec" "byte-codec"
+    click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
+    click ooxml "https://github.com/ExaDev/documents.js/tree/main/packages/ooxml.js" "ooxml.js"
+    click odf "https://github.com/ExaDev/documents.js/tree/main/packages/odf.js" "odf.js"
+    click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
+    click mdcodec "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec" "markdown-codec"
+    click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
     click documents "https://github.com/ExaDev/documents.js" "documents.js"
-    click mcp "https://github.com/ExaDev/document-mcp" "document-mcp"
-    click cli "https://github.com/ExaDev/document-cli" "document-cli"
+    click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
+    click cli "https://github.com/ExaDev/documents.js/tree/main/packages/document-cli" "document-cli"
 
     style documents fill:#f9a825,stroke:#333,stroke-width:3px
 ```
@@ -116,7 +116,7 @@ const pdfFromXlsx = xlsxToPdf(xlsxBytes); // composes xlsxToOds -> odsToPdf inte
 const xlsxBytes2 = pdfToXlsx(pdfFromXlsx); // composes pdfToOds -> odsToXlsx internally
 
 const pdfFromMarkdown = markdownToPdf(markdownBytes);
-const markdownBytes2 = pdfToMarkdown(pdfFromMarkdown); // the lossiest conversion in the whole package -- see Fidelity
+const markdownBytes2 = pdfToMarkdown(pdfFromMarkdown); // the lossiest conversion in the whole package -- see Fidelity; it does carry page boundaries (one '<!-- page break -->' marker per page) and rank-inferred heading levels
 
 const pdfFromCsv = csvToPdf(csvBytes); // composes csvToOds -> odsToPdf internally
 const csvBytes2 = pdfToCsv(pdfFromCsv); // composes pdfToOds -> odsToCsv internally; recovers what was printed, then heuristically re-types it
@@ -127,6 +127,8 @@ const svgBytes2 = pdfToSvg(pdfFromSvg); // readPdf -> reconstructDrawing -> buil
 
 Each accepts an optional `signal` (`AbortSignal`) and either `onSubstitution` (X → PDF, called per character not representable in a standard-14 font) or `sink` (PDF → X, called per recoverable parse diagnostic). Every X → PDF conversion additionally accepts `fonts` (extra `ProvidedFont` faces) and `onFontSubstitution` (per family+weight+style that resolved to something else). Neither is needed for the common case — see [Fonts](#fonts).
 
+**Cancellation granularity, for CPU-metered runtimes** (ExaDev/documents.js#585): every conversion here is synchronous end to end, and the `signal` is honoured at page boundaries — once per page in pdf-codec's `readPdf`/`writePdf` page loops and once per page in each of this package's four reconstructors (wordprocessing/presentation/drawing/spreadsheet). An abort arriving mid-conversion therefore takes effect at the next page boundary, not instantly: a single page's content-stream interpretation, pdf-codec's document-open phase, and the per-target build/encode stage after reconstruction are not interruptible, and parse cost is roughly linear in decompressed content length — budget for the worst single page, not the page count. A shared `AbortSignal` makes a deadline enforceable at that granularity on Cloudflare Workers; it cannot convert a synchronous conversion into a resumable or streaming one (an async page-at-a-time API is a deliberate non-goal of the current surface — see pdf-codec's README for the same statement from the codec side).
+
 ### Cross-format bridges
 
 Twenty-four bridge functions across twelve pairs bypass the PDF pivot where a direct path exists. Eight same-variant direct-copy pairs (`odtToDocx`/`docxToOdt`, `odpToPptx`/`pptxToOdp`, `odsToXlsx`/`xlsxToOds`, `csvToOds`/`odsToCsv`, `csvToXlsx`/`xlsxToCsv`, `svgToOdg`/`odgToSvg`, `markdownToDocx`/`docxToMarkdown`, `markdownToOdt`/`odtToMarkdown`) compose a direct `readXContent` → `buildYPackage` pivot copy — the csv pairs are one hop to its spreadsheet siblings, so csv never needs PDF to reach ods or xlsx, and `svgToOdg`/`odgToSvg` bridge svg to its drawing sibling odg the same way. Two cross-variant semantic-transform pairs (`docxToPptx`/`pptxToDocx`, `odtToOdp`/`odpToOdt`) go through `src/convert/variant-bridges.ts`. Two PDF-composed pairs (`xlsxToMarkdown`/`markdownToXlsx`, `csvToMarkdown`/`markdownToCsv`) route through PDF internally — the lossiest conversions in the package.
@@ -159,6 +161,8 @@ const { document, diagnostics } = await converter.convert(
 
 `DocumentFormat` includes `docx`/`pptx`/`xlsx`/`odt`/`odp`/`ods`/`odg`/`svg`/`odf`/`csv`/`markdown`/`pdf` — twelve members. The port's `conversions` list is derived from `resolveCompositionPlan` plus the `odf`→`pdf` special case — 111 pairs total. `DocumentFormat` is inferred from `DocumentFormatSchema` (a real Zod schema); `DOCUMENT_FORMATS` is exported as a plain array derived from the same schema:
 
+The port also exposes `contractVersion: number`, bumped only when `DocumentConverter`'s own contract shape changes — a new field on `ConversionResult` a caller might need to branch on, or a new `ConversionOptions` field an implementation is now expected to honour — never when the `conversions` table simply grows with more supported source/target pairs (that's discoverable at runtime via `conversions` itself). It is currently `7`: the bump from `6` reflects `ConversionResult.package` changing type to the tree-form `DocumentPackage` described below, which a caller reading that field must now flatten rather than read directly.
+
 ```ts
 import { DOCUMENT_FORMATS, DocumentFormatSchema } from 'documents.js';
 
@@ -187,7 +191,7 @@ const pdfBytes = docxToPdf(docxBytes, {
 
 The tree and the flat `ContentDocument` are one format in two encodings, related by three laws (stated on [document-schema.js#20](https://github.com/ExaDev/document-schema.js/issues/20), proven over this package's real corpus by the bijection suite in `src/convert/bijection.test.ts`): (i) `flattenPackage(assemblePackage(c))` reproduces `c` exactly, up to one declared normalisation (a present-but-empty sheet `embeddedObjects` array normalises to the field absent); (ii) effective-property equality holds universally — a factored and an unfactored serialisation of one document resolve to the same properties; (iii) minting is idempotent — factoring a second time produces the identical styles table.
 
-Three flat-form signals drive the grouping, and all three are reproduced exactly on the way back: `headingLevel`, `list.level`, and — since document-schema.js 4.2.0 — the `constructStart`/`constructEnd` block pair that delimits a fidelity construct (a docx SDT, an ODF field, a tracked-change span, a bookmark, a hyperlink region, a division). `decompose` promotes each marker pair to a construct group carrying the `ConstructDescriptor` and holding the delimited region as its children, decomposed on its own; `flattenPackage` writes the pair back around that region. A construct is a semantic wrapper rather than a container, so it neither disturbs the enclosing heading/list nesting it sits inside nor resets the style chain resolving onto it — content inside a construct still inherits the ambient heading's or section's factored properties, exactly as if the construct were not there. Markers must pair up within one container's block flow: an unmatched `constructEnd`, or a `constructStart` a container never closes, throws document-schema.js's `ConstructMarkerImbalanceError` (carrying its `ConstructMarkerImbalance` payload, so the offending block index is available without parsing the message) rather than being repaired into a plausible tree. The format codecs do not emit markers yet — construct extraction per format is tracked separately on [document-schema.js#22](https://github.com/ExaDev/document-schema.js/issues/22) — but the decompose/flatten boundary itself handles them today, so a caller hand-building marker content needs no change at that boundary specifically. Reaching further than the boundary is a mixed picture, not a blanket guarantee: `buildMarkdownText` refuses a marker with the named `MarkdownConstructUnsupportedError` rather than crashing inside markdown-codec's own writer, which has no arm for either marker kind; building docx/odt bytes back from marker-carrying flat content silently drops the markers, since neither builder reads or writes them yet; and the layout engines (`convertWordprocessingToLayout`, `convertShape`) silently skip a marker block during pagination — harmless there, since a marker carries no content of its own to render.
+Three flat-form signals drive the grouping, and all three are reproduced exactly on the way back: `headingLevel`, `list.level`, and — since document-schema.js 4.2.0 — the `constructStart`/`constructEnd` block pair that delimits a fidelity construct (a docx SDT, an ODF field, a tracked-change span, a bookmark, a hyperlink region, a division). `decompose` promotes each marker pair to a construct group carrying the `ConstructDescriptor` and holding the delimited region as its children, decomposed on its own; `flattenPackage` writes the pair back around that region. A construct is a semantic wrapper rather than a container, so it neither disturbs the enclosing heading/list nesting it sits inside nor resets the style chain resolving onto it — content inside a construct still inherits the ambient heading's or section's factored properties, exactly as if the construct were not there. Markers must pair up within one container's block flow: an unmatched `constructEnd`, or a `constructStart` a container never closes, throws document-schema.js's `ConstructMarkerImbalanceError` (carrying its `ConstructMarkerImbalance` payload, so the offending block index is available without parsing the message) rather than being repaired into a plausible tree. The format codecs do not emit markers yet — construct extraction per format is tracked separately on [document-schema.js#22](https://github.com/ExaDev/document-schema.js/issues/22) — but the decompose/flatten boundary itself handles them today, so a caller hand-building marker content needs no change at that boundary specifically. Reaching further than the boundary is a mixed picture, not a blanket guarantee: `buildMarkdownText` passes markers through to markdown-codec's own bracket-resolving writer, which renders each construct it has a markdown spelling for (a footnote definition, a blockquote division, a titled image's link wrapper) and renders the rest transparently with a diagnostic — markdown-codec's own read side emits those pairs, so this package's editor and conversion round trips depend on it; building docx/odt bytes back from marker-carrying flat content silently drops the markers, since neither builder reads or writes them yet; and the layout engines (`convertWordprocessingToLayout`, `convertShape`) silently skip a marker block during pagination — harmless there, since a marker carries no content of its own to render.
 
 `assemblePackage` is the one constructor behind every construction site — decompose, then `factorStyles`, the minting pass that hoists property tuples occurring two or more times onto a group-wrapper ref plus a `styles` table entry (deterministic order; `frames`/`sourcePath`/`styleId` are per-node facts and never factor). The transform belongs to `document-schema.js`, which owns both encodings and publishes `assemblePackage`, `decompose`, `flattenPackage`, `factorStyles`, `ConstructMarkerImbalanceError`, and the `PackageChildren` type for any caller composing its own boundary — import them from there, not from this package. documents.js consumes that transform at its own boundary and re-exports none of it; the readers, builders, layout engines, and editors here keep producing and consuming the flat form, so the tree exists only where a `DocumentPackage` is constructed or consumed:
 
@@ -234,7 +238,7 @@ const docxBytesAgain = encodeDocumentPackage('docx', pkg);
 const odbPkg = decodeOdbPackage(odbBytes);
 ```
 
-`readDocumentMetadata`/`setDocumentMetadata` read or patch metadata across any `DocumentFormat`. `setDocumentMetadata` patches in place (source/target formats must match); `odf` is rejected in both directions, and `csv` is rejected in both directions too (RFC 4180 text has no metadata container) — `readDocumentMetadata('csv', ...)` answers an empty `LayoutMetadata` for the same reason. `svg` reads its root `<title>` as `metadata.title` and is rejected as a `setDocumentMetadata` source/target for the mirror-image reason: `<title>` is svg's whole metadata surface, so any other override would be silently dropped by the rebuild. `readDocumentMetadata('xlsx', ...)` is a named exception: it renders via `xlsxToPdf` and reads the PDF's metadata, because a direct read and the PDF-preview path genuinely disagree on `createdIso`/`modifiedIso`/`producer`.
+`readDocumentMetadata`/`setDocumentMetadata` read or patch metadata across any `DocumentFormat`. `setDocumentMetadata` patches in place (source/target formats must match); `odf` is rejected in both directions, and `csv` is rejected in both directions too (RFC 4180 text has no metadata container) — `readDocumentMetadata('csv', ...)` answers an empty `LayoutMetadata` for the same reason. `svg` reads its root `<title>` as `metadata.title` and is rejected as a `setDocumentMetadata` source/target for the mirror-image reason: `<title>` is svg's whole metadata surface, so any other override would be silently dropped by the rebuild. `readDocumentMetadata('xlsx', ...)` reads the workbook's own `docProps` like every other content format — `createdIso`/`modifiedIso` from `docProps/core.xml` when the file declares them, `docProps/app.xml`'s Application as `creator`, and `producer` unset (a PDF-only concept no semantic reader sets). It previously rendered a `xlsxToPdf` preview and read that PDF's metadata instead, which for a file carrying no timestamps of its own reported facts about the render rather than the workbook: timestamps stamped at the render moment and a producer naming the preview PDF's writer.
 
 ```ts
 import { readDocumentMetadata, setDocumentMetadata } from 'documents.js';
@@ -250,6 +254,14 @@ import { emuToPt } from 'documents.js/model/units';
 import { buildOdtPackage } from 'documents.js/edit/odt/content';
 ```
 
+One subpath is a declared entry point in its own right: **`documents.js/read`** (an explicit `exports` entry onto `src/convert/from-pdf.ts`, where the `pdfTo*` family lives). A consumer that only ever converts FROM pdf and imports the root barrel statically reaches every X-to-PDF renderer — and through pdf-codec's root barrel, ~2.9 MB of vendored font binaries it can never execute, which on Cloudflare Workers' free plan (3 MB gzipped for an entire Worker) is most of the budget. The read entry's module graph provably excludes them, all the way across the workspace boundary into pdf-codec's own source:
+
+```ts
+import { pdfToMarkdown } from 'documents.js/read';
+```
+
+It carries the ten `pdfTo*` conversions, `PdfToDocumentOptions`, and `readDocumentMetadata` (with `ReadDocumentMetadataOptions`) — identical functions to the root barrel's (the same forwarders, run through the composition engine's read half, and the same metadata reader dispatched through the read-only codec half `src/codecs/read.ts`), never a forked behaviour; `convertDocument` and every X-to-PDF direction stay on the root barrel. `src/read-graph.test.ts` walks the entry's static import graph, follows `pdf-codec` specifiers through that package's real `exports` map into its source, and fails the build if the write path or any font asset becomes reachable.
+
 ### Reading and building xlsx content directly
 
 Every other content format has its own standalone `readXContent`-shaped entry point (`readDocxContent`, `readPptxContent`, `readOdtContent`, `readOdpContent`, `readOdsContent`, `readOdgContent`) — xlsx is no longer the exception. `readXlsxContent`/`buildXlsxPackage` are this package's names for `ooxml.js`'s own spreadsheet `ContentDocument` read/build pair — the same one the `ods⇄xlsx` bridge and every xlsx metadata-rebuild path already use internally — re-exported here directly rather than wrapped, since `readXlsxContent` already produces the right shape on its own. (Since `ooxml.js` 4.0.0 the upstream flat builder is named `buildXlsxPackageFromContent` — the bare `buildXlsxPackage` name moved to that package's tree-form `DocumentPackage` builder — so this package re-exports the flat builder under its own long-standing `buildXlsxPackage` name and the `ContentDocument`-in/`Package`-out contract is unchanged.) csv's `readCsvContent`/`buildCsvText` are the same kind of directly-exported stage pair, one level further in: they operate on RFC 4180 text rather than a decoded package (see `src/csv/` under Architecture). svg's `readSvgContent`/`buildSvgText` are the drawing-variant counterpart of csv's pair, operating on SVG text rather than a decoded package (see `src/svg/` under Architecture).
@@ -553,11 +565,11 @@ The package is layered from generic primitives outward to the two conversion dir
 - **`src/markdown/`** — third adapter family, via `markdown-codec`. `readMarkdownContent` passes `readMarkdownContent`'s (markdown-codec's flat reader, so named since that package's 4.0.0; the bare `readMarkdown` name is now its tree-form `DocumentPackage` reader) result through the math-lowering pass (`math.ts` — markdown-codec's preserved `$$` display blocks and `\( \)` inline spans become two-layer formula blocks, with the document's symbol table seeded from its own prose). `buildMarkdownText` wraps `writeMarkdownContent`, reconstructing markdown math syntax from formula blocks carrying a presentation layer. `text.ts` is the byte↔text boundary. `MarkdownEditor` holds a mutable in-memory `ContentDocument`.
 - **`src/csv/`** — fourth adapter family, sharing the spreadsheet variant with xlsx/ods. `records.ts` is the RFC 4180 record parser/writer (one shared `quoteCsvField`, also used by the `.odb` CSV exporter); `text.ts` is the byte↔text boundary, rejecting malformed UTF-8; `read.ts` turns records into a spreadsheet `ContentDocument` (first record as verbatim string header, data cells through the same cell-typing heuristic `pdfToOds` uses); `write.ts` turns one sheet of a spreadsheet `ContentDocument` back into records via each cell's `displayText`. TSV is the same format with `{ delimiter: '\t' }` on either side.
 - **`src/svg/`** — fifth adapter family, sharing the drawing variant with odg. `text.ts` is the byte↔text boundary, rejecting malformed UTF-8; `read.ts` maps the six SVG shape primitives (rect/circle/ellipse/line/polyline/polygon/path) onto a one-page drawing `ContentDocument`, with transform lists composed as 2×3 affines and CSS lengths and the viewBox map resolved into page points; `write.ts` writes the six primitives back out, one shape element each; `path.ts` is the full SVG path-data grammar (M/L/H/V/C/S/Z plus Q/T/A and the relative forms — S/Q/T convert exactly, A is the one bounded approximation at ≤90° per cubic); `transform.ts` parses and composes the transform attribute and classifies the result by frame representability; `units.ts` resolves CSS length units and the viewBox; `paint.ts` resolves fill/stroke presentation attributes and dash styles; `diagnostics.ts` is the shared scope-limit vocabulary.
-- **`src/layout/`** — the pure conversion algorithms: `engine.ts` (wordprocessing → layout: flow, line-breaking, pagination), `slides.ts` (presentation → layout: direct placement), `sheets.ts` (spreadsheet → layout: grid, print settings, the first algorithm accepting `AbortSignal`), `drawing.ts` (drawing → layout: vector primitives + shape reuse), `reconstruct.ts` (layout → content: baseline clustering for wordprocessing/presentation, near-1:1 mapping for drawing, gridline-lattice-or-text-clustering for spreadsheet).
+- **`src/layout/`** — the pure conversion algorithms: `engine.ts` (wordprocessing → layout: flow, line-breaking, pagination), `slides.ts` (presentation → layout: direct placement), `sheets.ts` (spreadsheet → layout: grid, print settings, the first algorithm accepting `AbortSignal`), `drawing.ts` (drawing → layout: vector primitives + shape reuse), `reconstruct.ts` (layout → content: baseline clustering for wordprocessing/presentation, near-1:1 mapping for drawing, gridline-lattice-or-text-clustering for spreadsheet; plus the PDF construct surfacing — link reconciliation to `ContentRun.hyperlink` or link constructs, hidden-layer content dropped, anchor/comment and AcroForm contentControl constructs).
 - **`src/hsqldb/`** — `.odb` decoders, four tiers: `script.ts` (TEXT-script DDL/DML parser), `rowformat.ts`/`cache.ts` (CACHED binary row-store), `binary-script.ts` (BINARY/COMPRESSED whole-script). All import only `document-schema.js` — no odf.js knowledge.
 - **`src/firebird/`** — Tier 3: gbak logical-backup reader. `reader.ts` (attribute framing + RLE decompression + XDR decoding), `schema.ts`/`data.ts` (table/row walking). No ratified spec — built against Firebird's own engine source.
 - **`src/odb/`** — decoder-selection and pivot-mapping: `read.ts` routes to the right tier, `spreadsheet.ts`/`csv.ts` map to output formats. `odb/sql/` is the bounded SQL engine, `odb/formula/` is the rpt formula engine, `odb/report/` is the renderer, `odb/values.ts` is shared comparison/aggregation semantics.
-- **`src/convert/`** — the composition layer: `convert.ts` (all named functions + `convertDocument` + `resolveCompositionPlan`), `composition.ts` (the pathfinder and primitive registry), `codec.ts` (`z.codec()` pairs), `port.ts`/`local.ts` (the `DocumentConverter` port), `variant-bridges.ts` (cross-variant semantic transforms), and `from-package.ts` (`buildDocumentBytes`, which flattens once at the boundary). The tree ⇄ flat transform those construction sites call — `assemblePackage`, `decompose`, `flattenPackage`, `factorStyles` — is not implemented here: it lives in `document-schema.js`, which owns both encodings. `bijection.test.ts` is this package's own gate on it, re-running the three laws over the real corpus every reader, editor, and conversion here produces.
+- **`src/convert/`** — the composition layer: `convert.ts` (the named conversion functions and their option types), `composition.ts` (the pathfinder, the primitive registry, the bridge/fromPdf executors, and `convertDocumentFromPdf` — the read half of the engine), `composition-to-pdf.ts` (`executeToPdf`, the layout-engine registry, and the full `convertDocument` binding — the write half, split out so a read-only consumer never statically imports a renderer), `from-pdf.ts` (the `pdfTo*` family and the `documents.js/read` entry), `codec.ts` (`z.codec()` pairs), `port.ts`/`local.ts` (the `DocumentConverter` port), `variant-bridges.ts` (cross-variant semantic transforms), and `from-package.ts` (`buildDocumentBytes`, which flattens once at the boundary). The tree ⇄ flat transform those construction sites call — `assemblePackage`, `decompose`, `flattenPackage`, `factorStyles` — is not implemented here: it lives in `document-schema.js`, which owns both encodings. `bijection.test.ts` is this package's own gate on it, re-running the three laws over the real corpus every reader, editor, and conversion here produces.
 - **`src/codecs/`** — `DOCUMENT_FORMAT_CODECS`: every format's read/build capability as data, so `readDocumentMetadata`/`setDocumentMetadata`/`buildDocumentBytes` dispatch through one registry.
 - **`src/metadata/`** — cross-format metadata read/write via `DOCUMENT_FORMAT_CODECS`.
 - **`src/package-codec.ts`** — `decodeDocumentPackage`/`encodeDocumentPackage`/`decodeOdbPackage`.
@@ -587,7 +599,7 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **Live views, not flatten-and-regenerate.** Editor classes hold a reference into the real `Package`/`XmlElement` objects; saving is `encodePackage(pkg)`.
 - **Three-tier PDF-read failure policy** — throw for unprocessable files, recover-with-diagnostic for malformed-but-salvageable, degrade-with-diagnostic for unsupported features. See pdf-codec's README.
 - **Conventional commits**, enforced via commitlint + husky.
-- **Worker-isomorphic runtime.** `src/` is typechecked against a web-only environment (`lib: ["ES2024", "WebWorker"]`, no `@types/node`); `eslint` bans Node-only imports/globals; `test:workers` proves PDF-bypassing paths run in `workerd`.
+- **Worker-isomorphic runtime.** `src/` is typechecked against a web-only environment (`lib: ["ES2024", "WebWorker"]`, no `@types/node`); `eslint` bans Node-only imports/globals; `test:workers` proves both the PDF-bypassing paths and the PDF pivot itself (`pdfToMarkdown` through the read-only entry module, `markdownToPdf` through the full write path) run in `workerd`.
 
 ## Gotchas and quirks
 
@@ -666,10 +678,10 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **OMML read/write are deliberately asymmetric** — the reader covers more (`m:d`, `m:nary`, `m:acc`, `m:bar`, `m:func`, `m:sPre`) because it must read what Word wrote. `docx → odt → docx` round trips keep the mathematics but may change the OMML construct.
 - **The OMML translator covers exactly what `src/mathml/layout.ts` typesets.** A stretchy fence diverges: PDF stretches it, docx writes it at base size. `munderover` becomes nested `m:limUpp`/`m:limLow` (no operand scope in MathML).
 - **`sourcePath` traces a `LayoutItem` to its `ContentDocument` origin, but only within one read+layout pass** — not an edit-tracking mechanism. Since the frames fusion it survives as traceability only: the authoritative node↔position association is each content node's own `frames`, stamped at the moment of layout (or of reconstruction) rather than re-matched by string afterwards.
-- **`readMarkdownContent` runs markdown-codec's result through the math-lowering pass** — `markdown-codec` already produces a full `ContentDocument`, but it deliberately carries `$$` display blocks and `\( \)` inline spans through as raw LaTeX text (styled paragraphs and marker runs); the pass lowers that LaTeX into two-layer formula blocks so markdown math typesets, edits, and computes like math from any other format (see [LaTeX lowering into the semantic core](#latex-lowering-into-the-semantic-core)).
-- **Every markdown construct-mapping gap is a documented `MarkdownDiagnosticCodes` entry** (`md/invented-page-geometry`, `md/nested-emphasis-flattened`, `md/link-title-dropped`, `md/code-block-info-string-dropped`, `md/blockquote-nested-depth`, `md/list-item-block-unlisted`, `md/list-item-multi-block-flattened`, `md/image-unresolved`, `md/raw-html-preserved-as-text`/`md/raw-html-dropped`, `md/front-matter-key-unmapped`, `md/heading-level-clamped`, `md/adjacent-links-merged`, `md/code-span-as-monospace-run`, `md/paragraph-indent-dropped`, `md/list-numid-fallback`, `md/table-cell-formatting-dropped`, `md/table-cell-multi-paragraph-joined`) — never a silent approximation.
+- **`readMarkdownContent` runs markdown-codec's result through the math-lowering pass** — `markdown-codec` already produces a full `ContentDocument`, but it deliberately stops short of lowering math: a `$$` display block arrives as an embedded formula object holding only the verbatim presentation LaTeX, an inline `\( \)` span as a Cambria-Math-marked raw-LaTeX run; the pass lowers that LaTeX into two-layer formula blocks so markdown math typesets, edits, and computes like math from any other format (see [LaTeX lowering into the semantic core](#latex-lowering-into-the-semantic-core)).
+- **Every markdown construct-mapping gap is a documented `MarkdownDiagnosticCodes` entry** (`md/invented-page-geometry`, `md/nested-emphasis-flattened`, `md/link-title-dropped`, `md/blockquote-container-skipped`, `md/list-item-block-unlisted`, `md/image-unresolved`, `md/raw-html-preserved-as-text`/`md/raw-html-dropped`, `md/front-matter-key-unmapped`, `md/heading-level-clamped`, `md/adjacent-links-merged`, `md/code-span-as-monospace-run`, `md/paragraph-indent-dropped`, `md/list-numid-fallback`, `md/table-cell-formatting-dropped`, `md/table-cell-multi-paragraph-joined`) — never a silent approximation. The info-string, multi-block-item, and blockquote-depth gaps that used to be in this list are closed: a fence's language word rides `ContentParagraph.codeLanguage`, item identity rides `ContentListMembership.itemId`, and a blockquote carries a `division` construct pair.
 - **`buildMarkdownText` throws for non-`'wordprocessing'` `ContentDocument`.**
-- **`buildMarkdownText` throws `MarkdownConstructUnsupportedError` for a `constructStart`/`constructEnd` marker** — CommonMark/GFM has no spelling for a construct wrapper and, unlike an embedded formula, no plain-text stand-in either (a division's column count or a tracked-change's author has nothing defensible to render as visible text), so this is a refusal rather than a degradation. Named so a caller can branch on it and, for a `constructStart`, read the wrapped `ConstructDescriptor`'s own `kind` (`contentControl`/`field`/`anchor`/`link`/`provenance`/`division`) off `descriptorKind` without parsing the message.
+- **`buildMarkdownText` passes `constructStart`/`constructEnd` markers through to markdown-codec's own writer**, which resolves them as balanced brackets: a construct with a markdown spelling renders as that syntax (a footnote definition, a blockquote division, a titled image's link wrapper), one without renders its extent transparently under a diagnostic. A genuinely unbalanced list still throws — markdown-codec's own `MarkdownUnbalancedConstructMarkersError`, the shared definition of that check. The old `MarkdownConstructUnsupportedError` refusal is gone: markdown-codec's read side now emits marker pairs of its own (blockquotes, titled images), so a writer that refused markers would refuse this package's own editor round trips.
 - **`decodeMarkdownText` throws on malformed UTF-8** rather than producing U+FFFD.
 - **The composition engine routes every pair generically** through a declarative primitive registry and minimum-cost pathfinder. `resolveCompositionPlan` finds the minimum-cost route (same-variant bridge < cross-variant transform < via-PDF multi-hop). Named functions are thin forwarders.
 
@@ -706,7 +718,7 @@ Read as **row → column**. `✓` lossless, `~` bounded, `✗` lossy, `✗✗` s
 
 **PDF → ods** recovers what was printed, not what was entered. The printed string always survives in `displayText`; re-typed `value` is explicitly probabilistic inference.
 
-**`markdownToPdf`/`pdfToMarkdown`** is the lossiest round trip: `markdownToPdf` is faithful, but `pdfToMarkdown` stacks reconstruction lossiness PLUS markdown's coarser vocabulary (no colour, font, size, alignment). The PDF-composed markdown bridges (`xlsxToMarkdown`/`markdownToXlsx`, `csvToMarkdown`/`markdownToCsv`) stack the same two losses in both directions — hence their `✗✗` cells.
+**`markdownToPdf`/`pdfToMarkdown`** is the lossiest round trip: `markdownToPdf` is faithful, but `pdfToMarkdown` stacks reconstruction lossiness PLUS markdown's coarser vocabulary (no colour, font, size, alignment). Two structure signals do survive it (ExaDev/documents.js#584): every page boundary arrives as an exact `<!-- page break -->` marker (one per boundary — the one fact a rendered PDF states precisely), and headings are inferred from font size — each distinct size at least 2pt above the document's modal body size is a heading, ranked largest-first into `Heading1..6`, which inverts this package's own heading render sizes exactly and is a heuristic (the well-worn "largest text is the title" reading) for any other producer. Tables reach markdown as GFM pipe tables wherever the gridline-lattice gate succeeds; a table rendered without drawn gridlines (which includes every `markdownToPdf`-authored one, markdown carrying no border concept) correctly comes back as tab-separated prose rather than invented structure. The PDF-composed markdown bridges (`xlsxToMarkdown`/`markdownToXlsx`, `csvToMarkdown`/`markdownToCsv`) stack the same two losses in both directions — hence their `✗✗` cells.
 
 **The six same-variant bridge pairs** (odt⇄docx, odp⇄pptx, ods⇄xlsx, csv⇄ods, csv⇄xlsx, svg⇄odg) bypass PDF entirely — no layout engine, no reconstruction. Text, styling, tables, lists, rotated shapes survive completely. `ods⇄xlsx` has small format-boundary limits (time cells, formula dialects). Embedded formulas survive `odtToDocx` as real OOXML math. The csv pairs are bounded by what csv itself carries: toward ods/xlsx nothing the csv had is lost, while writing to csv collapses each cell to its `displayText` — formulas become their rendered values, formatting disappears, and a multi-sheet source must name the sheet it wants. The svg pair carries the six vector primitives losslessly in both directions; its one asymmetry is paint defaults — SVG's absent-fill-is-black versus a drawing frame's no-fill.
 
@@ -722,29 +734,31 @@ Read as **row → column**. `✓` lossless, `~` bounded, `✗` lossy, `✗✗` s
 
 ## Release and publishing
 
-`.github/workflows/ci.yml` runs commitlint, lint, typecheck, unit suite, and smoke test on every push/PR. On push to `main` where all pass, `release.config.ts` drives semantic-release: commit history decides the version bump, `CHANGELOG.md` and `package.json` are committed back, a GitHub Release is cut, and the package publishes to npmjs.org via OIDC trusted publishing (no `NPM_TOKEN`). Publication is detected by diffing `package.json`'s version before/after. A second job republishes under `@exadev/documents.js` to GitHub Packages; a third generates an SPDX SBOM and signs build-provenance attestations.
+Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the [monorepo root README](../../README.md#releases) for the mechanism (topological per-package `semantic-release` via `@exadev/semantic-release-workspace`, OIDC trusted npm publishing, automatic sibling dependency-range rewriting) and its [known gap](../../README.md#releases) note on GitHub Packages republishing and SBOM/provenance signing, both dropped in the migration to this monorepo and not yet restored.
 
 ## Contributing
 
-Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`, …), enforced by commitlint via a husky `commit-msg` hook — semantic-release's version bump depends on these. `pre-commit` runs `lint-staged`; `pre-push` runs the test suite. Single `main` branch, no open PR workflow established.
+Conventional Commits, enforced workspace-wide by commitlint through a root `commit-msg` hook. Work inside `packages/documents.js/`; see [CONTRIBUTING.md](../../CONTRIBUTING.md) for the shared git hooks and history conventions.
 
 ## References
 
-- [ooxml.js](https://github.com/ExaDev/ooxml.js) — docx/pptx/xlsx ⇄ JSON handling and typed reading, including `readXlsxContent` and the flat spreadsheet builder it pairs with, `buildXlsxPackageFromContent` (consumed by the `odsToXlsx`/`xlsxToOds` bridge and internal codecs, and re-exported directly from this package's own surface under the long-standing `buildXlsxPackage` name — see [Reading and building xlsx content directly](#reading-and-building-xlsx-content-directly)).
-- [document-schema.js](https://github.com/ExaDev/document-schema.js) — owns `ContentDocument`, the tree-form `DocumentPackage` and its styles-table facility, and the port contracts; shared by all sibling packages.
-- [markdown-codec](https://github.com/ExaDev/markdown-codec) — CommonMark+GFM ⇄ `ContentDocument` handling. The third format (after docx/odt) sharing the wordprocessing pivot.
-- [pdf-codec](https://github.com/ExaDev/pdf-codec) — the hand-written PDF codec (`readPdf`/`writePdf`/`pdfCodec`), the embedded STIX Two Math font, and text-measurement/font-resolution primitives.
-- [byte-codec](https://github.com/ExaDev/byte-codec) — generic byte/image utilities (ByteWriter, CRC-32, deflate/inflate, PNG/JPEG), extracted from pdf-codec.
-- [odf.js](https://github.com/ExaDev/odf.js) — ODF codec (odt/ods/odp/odg), also built on `document-schema.js`. Style interning, rotation, `svg:d` parsing, and manifest handling consumed directly.
+- [ooxml.js](../ooxml.js/README.md) — docx/pptx/xlsx ⇄ JSON handling and typed reading, including `readXlsxContent` and the flat spreadsheet builder it pairs with, `buildXlsxPackageFromContent` (consumed by the `odsToXlsx`/`xlsxToOds` bridge and internal codecs, and re-exported directly from this package's own surface under the long-standing `buildXlsxPackage` name — see [Reading and building xlsx content directly](#reading-and-building-xlsx-content-directly)).
+- [document-schema.js](../document-schema.js/README.md) — owns `ContentDocument`, the tree-form `DocumentPackage` and its styles-table facility, and the port contracts; shared by all sibling packages.
+- [markdown-codec](../markdown-codec/README.md) — CommonMark+GFM ⇄ `ContentDocument` handling. The third format (after docx/odt) sharing the wordprocessing pivot.
+- [pdf-codec](../pdf-codec/README.md) — the hand-written PDF codec (`readPdf`/`writePdf`/`pdfCodec`), the embedded STIX Two Math font, and text-measurement/font-resolution primitives.
+- [byte-codec](../byte-codec/README.md) — generic byte/image utilities (ByteWriter, CRC-32, deflate/inflate, PNG/JPEG), extracted from pdf-codec.
+- [odf.js](../odf.js/README.md) — ODF codec (odt/ods/odp/odg), also built on `document-schema.js`. Style interning, rotation, `svg:d` parsing, and manifest handling consumed directly.
 - [STIX Two Math](https://github.com/stipub/stixfonts) — the embedded math font. Vendored within pdf-codec (OFL-1.1).
 - [firebirdsql/firebird](https://github.com/FirebirdSQL/firebird) — ground truth for `src/firebird/`, since gbak backup format has no ratified spec. Read as source material only, not a build/runtime dependency.
 
 ## npm aliases
 
-This package also publishes under:
+This package also published under an alternate name from the pre-monorepo pipeline:
 
 - [js.documents](https://www.npmjs.com/package/js.documents)
 
+**Frozen since the monorepo migration** — see the [root README's release note](../../README.md#releases): the alias republish step was dropped along with GitHub Packages mirroring and SBOM/provenance signing, and nothing today keeps this name in sync with `documents.js`'s own releases. Tracked in [ExaDev/documents.js#731](https://github.com/ExaDev/documents.js/issues/731).
+
 ## License
 
 MIT

package/dist/cell-typing-CEWlywIc.d.cts

@@ -0,0 +1,22 @@
+import { ContentCellValue } from "document-schema.js";
+//#region src/layout/cell-typing.d.ts
+type CellTypeRule = 'boolean-literal' | 'iso-date' | 'named-month-date' | 'plain-number' | 'grouped-number' | 'percentage' | 'currency';
+type CellTypeDeclineReason = 'ambiguous-boolean-word' | 'ambiguous-date-order' | 'ambiguous-grouping-separator' | 'leading-zero-digits' | 'precision-loss';
+type CellTypeInferenceResult = {
+  readonly outcome: 'retyped';
+  readonly value: ContentCellValue;
+  readonly rule: CellTypeRule;
+} | {
+  readonly outcome: 'declined';
+  readonly reason: CellTypeDeclineReason;
+};
+type CellTypeInference = {
+  readonly sheetIndex: number;
+  readonly row: number;
+  readonly column: number;
+  readonly displayText: string;
+} & CellTypeInferenceResult;
+type CellTypeInferenceSink = (inference: CellTypeInference) => void;
+declare function inferCellValue(displayText: string): CellTypeInferenceResult | undefined;
+//#endregion
+export { CellTypeRule as a, CellTypeInferenceSink as i, CellTypeInference as n, inferCellValue as o, CellTypeInferenceResult as r, CellTypeDeclineReason as t };

package/dist/cell-typing-CEWlywIc.d.ts

@@ -0,0 +1,22 @@
+import { ContentCellValue } from "document-schema.js";
+//#region src/layout/cell-typing.d.ts
+type CellTypeRule = 'boolean-literal' | 'iso-date' | 'named-month-date' | 'plain-number' | 'grouped-number' | 'percentage' | 'currency';
+type CellTypeDeclineReason = 'ambiguous-boolean-word' | 'ambiguous-date-order' | 'ambiguous-grouping-separator' | 'leading-zero-digits' | 'precision-loss';
+type CellTypeInferenceResult = {
+  readonly outcome: 'retyped';
+  readonly value: ContentCellValue;
+  readonly rule: CellTypeRule;
+} | {
+  readonly outcome: 'declined';
+  readonly reason: CellTypeDeclineReason;
+};
+type CellTypeInference = {
+  readonly sheetIndex: number;
+  readonly row: number;
+  readonly column: number;
+  readonly displayText: string;
+} & CellTypeInferenceResult;
+type CellTypeInferenceSink = (inference: CellTypeInference) => void;
+declare function inferCellValue(displayText: string): CellTypeInferenceResult | undefined;
+//#endregion
+export { CellTypeRule as a, CellTypeInferenceSink as i, CellTypeInference as n, inferCellValue as o, CellTypeInferenceResult as r, CellTypeDeclineReason as t };

package/dist/codecs/read.cjs

@@ -0,0 +1,66 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_model_bytes = require("../model/bytes.cjs");
+const require_markdown_read = require("../markdown/read.cjs");
+const require_ooxml_docx_read = require("../ooxml/docx/read.cjs");
+const require_ooxml_pptx_read = require("../ooxml/pptx/read.cjs");
+const require_odf_formula_read = require("../odf/formula/read.cjs");
+const require_odf_odt_read = require("../odf/odt/read.cjs");
+const require_odf_odp_read = require("../odf/odp/read.cjs");
+const require_odf_ods_read = require("../odf/ods/read.cjs");
+const require_odf_odg_read = require("../odf/odg/read.cjs");
+const require_markdown_text = require("../markdown/text.cjs");
+const require_csv_text = require("../csv/text.cjs");
+const require_csv_read = require("../csv/read.cjs");
+const require_svg_text = require("../svg/text.cjs");
+const require_svg_read = require("../svg/read.cjs");
+const require_ports_abort = require("../ports/abort.cjs");
+const require_package_codec = require("../package-codec.cjs");
+let ooxml_js = require("ooxml.js");
+let pdf_codec_read = require("pdf-codec/read");
+//#region src/codecs/read.ts
+const CONTENT_READERS = {
+	docx: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_ooxml_docx_read.readDocxContent(require_package_codec.decodeDocumentPackage("docx", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	pptx: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_ooxml_pptx_read.readPptxContent(require_package_codec.decodeDocumentPackage("pptx", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	odt: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_odf_odt_read.readOdtContent(require_package_codec.decodeDocumentPackage("odt", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	odp: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_odf_odp_read.readOdpContent(require_package_codec.decodeDocumentPackage("odp", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	ods: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_odf_ods_read.readOdsContent(require_package_codec.decodeDocumentPackage("ods", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	odg: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_odf_odg_read.readOdgContent(require_package_codec.decodeDocumentPackage("odg", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	odf: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return require_odf_formula_read.readOdfFormulaContent(require_package_codec.decodeDocumentPackage("odf", require_model_bytes.requireArrayBufferBytes(bytes)));
+	},
+	markdown: (bytes, options) => require_markdown_read.readMarkdownContent(require_markdown_text.decodeMarkdownText(bytes), {
+		signal: options?.signal,
+		images: options?.images
+	}),
+	csv: (bytes) => require_csv_read.readCsvContent(require_csv_text.decodeCsvText(bytes)),
+	svg: (bytes) => require_svg_read.readSvgContent(require_svg_text.decodeSvgText(bytes)),
+	xlsx: (bytes, options) => {
+		require_ports_abort.throwIfAborted(options?.signal);
+		return (0, ooxml_js.readXlsxContent)(require_package_codec.decodeDocumentPackage("xlsx", require_model_bytes.requireArrayBufferBytes(bytes)));
+	}
+};
+function readDocumentLayout(bytes, options) {
+	return (0, pdf_codec_read.readPdf)(require_model_bytes.requireArrayBufferBytes(bytes), { signal: options?.signal });
+}
+//#endregion
+exports.CONTENT_READERS = CONTENT_READERS;
+exports.readDocumentLayout = readDocumentLayout;

package/dist/codecs/read.d.cts

@@ -0,0 +1,15 @@
+import { DocumentFormat } from "../convert/port.cjs";
+import { ContentDocument } from "document-schema.js";
+import { LayoutDocument } from "pdf-codec";
+import { MarkdownImageResolver } from "markdown-codec";
+//#region src/codecs/read.d.ts
+interface DocumentCodecOptions {
+  readonly signal?: AbortSignal;
+  readonly images?: MarkdownImageResolver;
+}
+type ReadContentFormat = Exclude<DocumentFormat, 'pdf'>;
+type ContentReader = (bytes: Uint8Array, options?: DocumentCodecOptions) => ContentDocument;
+declare const CONTENT_READERS: Readonly<Record<ReadContentFormat, ContentReader>>;
+declare function readDocumentLayout(bytes: Uint8Array, options?: DocumentCodecOptions): LayoutDocument;
+//#endregion
+export { CONTENT_READERS, ContentReader, DocumentCodecOptions, ReadContentFormat, readDocumentLayout };

package/dist/codecs/read.d.ts

@@ -0,0 +1,15 @@
+import { DocumentFormat } from "../convert/port.js";
+import { ContentDocument } from "document-schema.js";
+import { LayoutDocument } from "pdf-codec";
+import { MarkdownImageResolver } from "markdown-codec";
+//#region src/codecs/read.d.ts
+interface DocumentCodecOptions {
+  readonly signal?: AbortSignal;
+  readonly images?: MarkdownImageResolver;
+}
+type ReadContentFormat = Exclude<DocumentFormat, 'pdf'>;
+type ContentReader = (bytes: Uint8Array, options?: DocumentCodecOptions) => ContentDocument;
+declare const CONTENT_READERS: Readonly<Record<ReadContentFormat, ContentReader>>;
+declare function readDocumentLayout(bytes: Uint8Array, options?: DocumentCodecOptions): LayoutDocument;
+//#endregion
+export { CONTENT_READERS, ContentReader, DocumentCodecOptions, ReadContentFormat, readDocumentLayout };

package/dist/codecs/read.js

@@ -0,0 +1,64 @@
+import { requireArrayBufferBytes } from "../model/bytes.js";
+import { readMarkdownContent } from "../markdown/read.js";
+import { readDocxContent as readDocxContent$1 } from "../ooxml/docx/read.js";
+import { readPptxContent as readPptxContent$1 } from "../ooxml/pptx/read.js";
+import { readOdfFormulaContent } from "../odf/formula/read.js";
+import { readOdtContent } from "../odf/odt/read.js";
+import { readOdpContent } from "../odf/odp/read.js";
+import { readOdsContent } from "../odf/ods/read.js";
+import { readOdgContent } from "../odf/odg/read.js";
+import { decodeMarkdownText } from "../markdown/text.js";
+import { decodeCsvText } from "../csv/text.js";
+import { readCsvContent } from "../csv/read.js";
+import { decodeSvgText } from "../svg/text.js";
+import { readSvgContent } from "../svg/read.js";
+import { throwIfAborted } from "../ports/abort.js";
+import { decodeDocumentPackage } from "../package-codec.js";
+import { readXlsxContent } from "ooxml.js";
+import { readPdf } from "pdf-codec/read";
+//#region src/codecs/read.ts
+const CONTENT_READERS = {
+	docx: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readDocxContent$1(decodeDocumentPackage("docx", requireArrayBufferBytes(bytes)));
+	},
+	pptx: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readPptxContent$1(decodeDocumentPackage("pptx", requireArrayBufferBytes(bytes)));
+	},
+	odt: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readOdtContent(decodeDocumentPackage("odt", requireArrayBufferBytes(bytes)));
+	},
+	odp: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readOdpContent(decodeDocumentPackage("odp", requireArrayBufferBytes(bytes)));
+	},
+	ods: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readOdsContent(decodeDocumentPackage("ods", requireArrayBufferBytes(bytes)));
+	},
+	odg: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readOdgContent(decodeDocumentPackage("odg", requireArrayBufferBytes(bytes)));
+	},
+	odf: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readOdfFormulaContent(decodeDocumentPackage("odf", requireArrayBufferBytes(bytes)));
+	},
+	markdown: (bytes, options) => readMarkdownContent(decodeMarkdownText(bytes), {
+		signal: options?.signal,
+		images: options?.images
+	}),
+	csv: (bytes) => readCsvContent(decodeCsvText(bytes)),
+	svg: (bytes) => readSvgContent(decodeSvgText(bytes)),
+	xlsx: (bytes, options) => {
+		throwIfAborted(options?.signal);
+		return readXlsxContent(decodeDocumentPackage("xlsx", requireArrayBufferBytes(bytes)));
+	}
+};
+function readDocumentLayout(bytes, options) {
+	return readPdf(requireArrayBufferBytes(bytes), { signal: options?.signal });
+}
+//#endregion
+export { CONTENT_READERS, readDocumentLayout };

package/dist/codecs/registry.cjs

@@ -5,109 +5,63 @@ const require_edit_odt_content = require("../edit/odt/content.cjs");
 const require_edit_odp_content = require("../edit/odp/content.cjs");
 const require_edit_ods_content = require("../edit/ods/content.cjs");
 const require_edit_odg_content = require("../edit/odg/content.cjs");
-const require_markdown_read = require("../markdown/read.cjs");
 const require_markdown_write = require("../markdown/write.cjs");
-const require_ooxml_docx_read = require("../ooxml/docx/read.cjs");
-const require_ooxml_pptx_read = require("../ooxml/pptx/read.cjs");
-const require_odf_formula_read = require("../odf/formula/read.cjs");
-const require_odf_odt_read = require("../odf/odt/read.cjs");
-const require_odf_odp_read = require("../odf/odp/read.cjs");
-const require_odf_ods_read = require("../odf/ods/read.cjs");
-const require_odf_odg_read = require("../odf/odg/read.cjs");
 const require_markdown_text = require("../markdown/text.cjs");
 const require_csv_text = require("../csv/text.cjs");
-const require_csv_read = require("../csv/read.cjs");
 const require_csv_write = require("../csv/write.cjs");
 const require_svg_text = require("../svg/text.cjs");
-const require_svg_read = require("../svg/read.cjs");
 const require_svg_write = require("../svg/write.cjs");
-const require_ports_abort = require("../ports/abort.cjs");
 const require_package_codec = require("../package-codec.cjs");
+const require_codecs_read = require("./read.cjs");
 let ooxml_js = require("ooxml.js");
 let pdf_codec = require("pdf-codec");
 //#region src/codecs/registry.ts
-function isArrayBufferBacked(bytes) {
-	return bytes.buffer instanceof ArrayBuffer;
-}
-function requireArrayBufferBytes(bytes) {
-	if (!isArrayBufferBacked(bytes)) throw new TypeError("expected an ArrayBuffer-backed Uint8Array, received one backed by a SharedArrayBuffer");
-	return bytes;
-}
 const DOCUMENT_FORMAT_CODECS = {
 	docx: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return require_ooxml_docx_read.readDocxContent(require_package_codec.decodeDocumentPackage("docx", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.docx,
 		write: (content) => require_package_codec.encodeDocumentPackage("docx", require_edit_docx_content.buildDocxPackage(content))
 	} },
 	pptx: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return require_ooxml_pptx_read.readPptxContent(require_package_codec.decodeDocumentPackage("pptx", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.pptx,
 		write: (content) => require_package_codec.encodeDocumentPackage("pptx", require_edit_pptx_content.buildPptxPackage(content))
 	} },
 	odt: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return require_odf_odt_read.readOdtContent(require_package_codec.decodeDocumentPackage("odt", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.odt,
 		write: (content) => require_package_codec.encodeDocumentPackage("odt", require_edit_odt_content.buildOdtPackage(content))
 	} },
 	odp: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return require_odf_odp_read.readOdpContent(require_package_codec.decodeDocumentPackage("odp", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.odp,
 		write: (content) => require_package_codec.encodeDocumentPackage("odp", require_edit_odp_content.buildOdpPackage(content))
 	} },
 	ods: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return require_odf_ods_read.readOdsContent(require_package_codec.decodeDocumentPackage("ods", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.ods,
 		write: (content) => require_package_codec.encodeDocumentPackage("ods", require_edit_ods_content.buildOdsPackage(content))
 	} },
 	odg: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return require_odf_odg_read.readOdgContent(require_package_codec.decodeDocumentPackage("odg", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.odg,
 		write: (content) => require_package_codec.encodeDocumentPackage("odg", require_edit_odg_content.buildOdgPackage(content))
 	} },
-	odf: { content: { read: (bytes, options) => {
-		require_ports_abort.throwIfAborted(options?.signal);
-		return require_odf_formula_read.readOdfFormulaContent(require_package_codec.decodeDocumentPackage("odf", requireArrayBufferBytes(bytes)));
-	} } },
+	odf: { content: { read: require_codecs_read.CONTENT_READERS.odf } },
 	markdown: { content: {
-		read: (bytes, options) => require_markdown_read.readMarkdownContent(require_markdown_text.decodeMarkdownText(bytes), {
-			signal: options?.signal,
-			images: options?.images
-		}),
+		read: require_codecs_read.CONTENT_READERS.markdown,
 		write: (content) => require_markdown_text.encodeMarkdownText(require_markdown_write.buildMarkdownText(content))
 	} },
 	csv: { content: {
-		read: (bytes) => require_csv_read.readCsvContent(require_csv_text.decodeCsvText(bytes)),
+		read: require_codecs_read.CONTENT_READERS.csv,
 		write: (content) => require_csv_text.encodeCsvText(require_csv_write.buildCsvText(content))
 	} },
 	svg: { content: {
-		read: (bytes) => require_svg_read.readSvgContent(require_svg_text.decodeSvgText(bytes)),
+		read: require_codecs_read.CONTENT_READERS.svg,
 		write: (content) => require_svg_text.encodeSvgText(require_svg_write.buildSvgText(content))
 	} },
 	pdf: { layout: {
-		read: (bytes, options) => (0, pdf_codec.readPdf)(requireArrayBufferBytes(bytes), { signal: options?.signal }),
+		read: require_codecs_read.readDocumentLayout,
 		write: (layout, options) => (0, pdf_codec.writePdf)(layout, { signal: options?.signal })
 	} },
 	xlsx: { content: {
-		read: (bytes, options) => {
-			require_ports_abort.throwIfAborted(options?.signal);
-			return (0, ooxml_js.readXlsxContent)(require_package_codec.decodeDocumentPackage("xlsx", requireArrayBufferBytes(bytes)));
-		},
+		read: require_codecs_read.CONTENT_READERS.xlsx,
 		write: (content) => require_package_codec.encodeDocumentPackage("xlsx", (0, ooxml_js.buildXlsxPackageFromContent)(content))
 	} }
 };
 //#endregion
 exports.DOCUMENT_FORMAT_CODECS = DOCUMENT_FORMAT_CODECS;
-exports.isArrayBufferBacked = isArrayBufferBacked;
-exports.requireArrayBufferBytes = requireArrayBufferBytes;

package/dist/codecs/registry.d.cts

@@ -1,14 +1,8 @@
 import { DocumentFormat } from "../convert/port.cjs";
+import { DocumentCodecOptions } from "./read.cjs";
 import { ContentCodec } from "document-schema.js";
 import { LayoutDocument } from "pdf-codec";
-import { MarkdownImageResolver } from "markdown-codec";
 //#region src/codecs/registry.d.ts
-declare function isArrayBufferBacked(bytes: Uint8Array): bytes is Uint8Array<ArrayBuffer>;
-declare function requireArrayBufferBytes(bytes: Uint8Array): Uint8Array<ArrayBuffer>;
-interface DocumentCodecOptions {
-  readonly signal?: AbortSignal;
-  readonly images?: MarkdownImageResolver;
-}
 interface LayoutEntryCodec {
   read(bytes: Uint8Array, options?: DocumentCodecOptions): LayoutDocument;
   write(layout: LayoutDocument, options?: DocumentCodecOptions): Uint8Array;
@@ -19,4 +13,4 @@ interface DocumentFormatCodecs {
 }
 declare const DOCUMENT_FORMAT_CODECS: Readonly<Record<DocumentFormat, DocumentFormatCodecs>>;
 //#endregion
-export { DOCUMENT_FORMAT_CODECS, DocumentCodecOptions, DocumentFormatCodecs, LayoutEntryCodec, isArrayBufferBacked, requireArrayBufferBytes };
+export { DOCUMENT_FORMAT_CODECS, DocumentFormatCodecs, LayoutEntryCodec };