documents.js 2.3.3 → 3.0.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![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)
 
-> 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 `ContentDocument`/`LayoutDocument` model, with PDF 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](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).
 
 `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.
 
@@ -168,22 +168,35 @@ DocumentFormatSchema.parse(userSuppliedFormat); // throws a ZodError for anythin
 
 ### Intermediate `DocumentPackage`, JSON, and bytes
 
-Every conversion function accepts an `onDocument` callback receiving the intermediate `DocumentPackage` — the fused unified tree of document-schema.js 3: `content` (whose own nodes carry `frames`, the rendered page positions the layout pass stamped onto them, in PDF user-space) plus `pages` (each rendered page's size, indexed to match every `frames[].pageIndex`). The port surfaces the same value as `package` on `ConversionResult`. For PDF-bypassing bridges, `pkg.pages` is always `undefined` and no node carries frames — no layout pass ran.
+Every conversion function accepts an `onDocument` callback receiving the intermediate `DocumentPackage` — since document-schema.js 4, the single hierarchical tree: `children` carry the decomposed group tree (one group per container — a section, slide, sheet, or draw page — with heading and list paragraphs anchoring nested groups inside their container's flow), and the content nodes embedded in that tree carry `frames`, the rendered page positions the layout pass stamped onto them, in PDF user-space. `pages` (each rendered page's size, indexed to match every `frames[].pageIndex`) and the minted `styles` table ride the root. The port surfaces the same value as `package` on `ConversionResult`. For PDF-bypassing bridges, `pkg.pages` is always `undefined` and no node carries frames — no layout pass ran.
 
 ```ts
-import { docxToPdf } from 'documents.js';
+import { docxToPdf, flattenPackage } from 'documents.js';
 
 const pdfBytes = docxToPdf(docxBytes, {
   onDocument: (pkg) => {
-    console.log(pkg.content.kind); // 'wordprocessing'
+    console.log(pkg.kind); // 'wordprocessing' -- the document kind rides the tree's root
     console.log(pkg.pages?.length); // populated for every X-to-PDF/PDF-to-X conversion
-    const block = pkg.content.kind === 'wordprocessing' ? pkg.content.sections[0]?.blocks[0] : undefined;
+    const content = flattenPackage(pkg); // the flat ContentDocument, fully materialised
+    const block = content.kind === 'wordprocessing' ? content.sections[0]?.blocks[0] : undefined;
     console.log(block?.kind === 'paragraph' ? block.runs[0]?.frames : 'no paragraph'); // that run's rendered placements
   },
 });
 ```
 
-`documentPackageWithSchema`/`documentFromJson` turn a `DocumentPackage` into self-describing JSON and back (re-exported from `document-schema.js`):
+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.
+
+`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). `decompose`, `flattenPackage`, and `factorStyles` are all exported for a caller composing its own boundary; the readers and builders keep producing and consuming the flat form, so the tree exists only at the package boundary:
+
+```ts
+import { assemblePackage, decompose, factorStyles, flattenPackage } from 'documents.js';
+
+const tree = assemblePackage(content, pages); // decompose + mint: the tree a conversion reports
+const flat = flattenPackage(tree); // the exact flat ContentDocument back, refs materialised
+const again = factorStyles(tree); // re-mint: identical table and tree (law iii)
+```
+
+`documentPackageWithSchema`/`documentFromJson` turn a `DocumentPackage` into self-describing JSON and back (re-exported from `document-schema.js`); the version-pinned `$schema` URI the dumper stamps is the package's version — the hand-kept `formatVersion` integer is gone:
 
 ```ts
 import { documentFromJson, documentPackageWithSchema } from 'documents.js';
@@ -192,10 +205,10 @@ const tagged = documentPackageWithSchema(pkg);
 writeFileSync('converted.doc.json', JSON.stringify(tagged, null, 2));
 
 const { kind, value } = documentFromJson(JSON.parse(readFileSync('converted.doc.json', 'utf8')));
-// kind: 'DocumentPackage' (here) | 'ContentDocument' | 'LayoutDocument'
+// kind: 'DocumentPackage' (here) | 'ContentDocument'
 ```
 
-`buildDocumentBytes` rebuilds any `DocumentFormat`'s bytes from a `DocumentPackage` — `'pdf'` rebuilds the pdf-codec view from the package's own frames+pages (`layoutDocumentFromPackage`, a mechanical inverse walking the content tree and emitting `LayoutItem`s from each node's recorded placements; throwing if the package carries no `pages`), `'odf'` has no builder and throws, everything else rebuilds from the `ContentDocument` half. `layoutDocumentFromPackage` is exported too, for a caller wanting the rebuilt `LayoutDocument` without writing bytes. Two honest limits on the pdf rebuild, both structural properties of what a package records: a run's frames carry positions, not the wrap decisions that distributed its text across them, so a wrapped run re-renders once, whole, at its first recorded placement; and no font registry or positioned formula survives a bare package (a formula block's frame records where it sat while its glyphs render as nothing):
+`buildDocumentBytes` rebuilds any `DocumentFormat`'s bytes from a tree-form `DocumentPackage` — it flattens once at the boundary and hands the flat form to the builders, whose signatures never changed. `'pdf'` rebuilds the pdf-codec view from the package's own frames+pages (`layoutDocumentFromPackage`, a mechanical inverse walking the flattened content and emitting `LayoutItem`s from each node's recorded placements; throwing if the package carries no `pages`), `'odf'` has no builder and throws, everything else rebuilds from the flattened `ContentDocument`. `layoutDocumentFromPackage` is exported too, for a caller wanting the rebuilt `LayoutDocument` without writing bytes. Two honest limits on the pdf rebuild, both structural properties of what a package records: a run's frames carry positions, not the wrap decisions that distributed its text across them, so a wrapped run re-renders once, whole, at its first recorded placement; and no font registry or positioned formula survives a bare package (a formula block's frame records where it sat while its glyphs render as nothing):
 
 ```ts
 import { buildDocumentBytes, docxToPdf } from 'documents.js';
@@ -522,7 +535,7 @@ const { family, bold, italic } = describeFontFace(fontBytes, 'BrandSans-Regular.
 
 The package is layered from generic primitives outward to the two conversion directions:
 
-- **`src/model/`** — thin additions on top of `document-schema.js`, which owns the two pivot models (`LayoutDocument`, `ContentDocument`) imported, not defined here. Local: `bytes.ts` (magic-byte schemas), `units.ts` (EMU/twip/point conversions), `geometry.ts`/`color.ts`/`style.ts` (thin re-exports plus PDF-specific `flipY`), `paint-order.ts` (merges drawing page `shapes`/`vectors` by `paintOrder`), `formula.ts` (helpers around `ContentFormula`), `embedded-drawing.ts` (packages recovered vectors as a `ContentEmbeddedObjectBlock`).
+- **`src/model/`** — thin additions on top of `document-schema.js`, which owns the content model (`ContentDocument`, and since 4.0.0 the tree-form `DocumentPackage` vocabulary) imported, not defined here; the `LayoutDocument` item family is pdf-codec's own since the schema-4 demotion. Local: `bytes.ts` (magic-byte schemas), `units.ts` (EMU/twip/point conversions), `geometry.ts`/`color.ts`/`style.ts` (thin re-exports plus PDF-specific `flipY`), `paint-order.ts` (merges drawing page `shapes`/`vectors` by `paintOrder`), `formula.ts` (helpers around `ContentFormula`), `embedded-drawing.ts` (packages recovered vectors as a `ContentEmbeddedObjectBlock`).
 - **`pdf-codec`** (external) — the hand-written PDF codec, plus generic byte/image primitives (now in `byte-codec`). See that package's own README.
 - **`src/ports/`** — injectable ports: `throwIfAborted` (signal check at long-loop boundaries) and `ClockPort`/`systemClock`/`fixedClock` (injectable "now" for deterministic output — exported but not yet consumed by any conversion path).
 - **`src/xml/`** and **`src/opc/`** — parent-aware XML query/mutation and OPC package mechanics over `ooxml.js`'s `Package`/`XmlNode`. `src/xml/odf-text.ts` holds `encodeOdfText`/`decodeOdfText` — see the ODF text gotcha below.
@@ -541,7 +554,7 @@ The package is layered from generic primitives outward to the two conversion dir
 - **`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), `from-package.ts` (`buildDocumentBytes`).
+- **`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 the package boundary itself — `decompose.ts`/`flatten.ts` (the lossless tree ⇄ flat pair), `factor-styles.ts` (`assemblePackage` and the styles minting pass), `canonicalise.ts` (the shared canonical-key recipe) — plus `from-package.ts` (`buildDocumentBytes`, which flattens once at the boundary).
 - **`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`.
@@ -578,8 +591,8 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **`ooxml.js`'s typed readers are the basis for conversion** — `readDocxContent`/`readPptxContent` are thin wrappers, not independent walks. They are deliberately not re-exported (exposing both would invite using the wrong one). `readDocx`'s `comments`/`footnotes`/`headers`/`footers`/`numbering` are exposed via `readDocxExtras`. `readPptx` has no extras reader yet. xlsx is the one exception: `ooxml.js`'s `readXlsxContent`/`buildXlsxPackage` already read/write a spreadsheet `ContentDocument` directly (unlike `readDocx`/`readPptx`, which `readDocxContent`/`readPptxContent` wrap), so they're re-exported as-is rather than given a documents.js-local wrapper of their own — `readXlsx`, the separate lossy cell-values-only view, stays unexported for the same reason `readDocx`/`readPptx` do.
 - **ODF text content is not a plain string.** ODF represents runs of spaces as `<text:s>`, tabs as `<text:tab/>`, line breaks as `<text:line-break/>` — all elements, not text nodes. Every ODF text getter MUST call `decodeOdfText`, never `textContent()` — which silently drops them (no error, just shorter text).
 - **docx⇄PDF and pptx⇄PDF are explicitly not round-trip-lossless** — see [Fidelity](#fidelity). The cross-format bridge pairs are a genuinely different case.
-- **A `DocumentPackage` from `onDocument`/`ConversionResult.package` is a snapshot, not a live view** — mutating `content` after the layout pass leaves its nodes' `frames` stale; nothing detects or rejects that, and the schema keeps `content`'s populated `frames` and `pages` in sync with nothing.
-- **`frames` are stamped in place onto the caller's own content tree** — `convertXToLayout` mutates its `ContentDocument` argument (each node's placements are appended to its own `frames` array, one frame per rendered placement: per wrapped fragment on a run, the cell box on a cell, the emitted item's box on an image/vector/shape) and returns `pages` alongside the internal `LayoutDocument`. A run wrapped across three lines carries three frames; a repeat-row spreadsheet cell carries one per page it re-renders on. Reconstructors attach frames from the exact items each reconstructed node was clustered from, so every PDF-to-X conversion's content carries genuine positions too.
+- **A `DocumentPackage` from `onDocument`/`ConversionResult.package` is a snapshot, not a live view** — mutating the tree's content nodes after the layout pass leaves their `frames` stale; nothing detects or rejects that, and the schema keeps the tree's populated `frames` and `pages` in sync with nothing.
+- **`frames` are stamped in place onto the caller's own content tree** — `convertXToLayout` mutates its `ContentDocument` argument (each node's placements are appended to its own `frames` array, one frame per rendered placement: per wrapped fragment on a run, the cell box on a cell, the emitted item's box on an image/vector/shape) and returns `pages` alongside the internal `LayoutDocument`. A run wrapped across three lines carries three frames; a repeat-row spreadsheet cell carries one per page it re-renders on. Reconstructors attach frames from the exact items each reconstructed node was clustered from, so every PDF-to-X conversion's content carries genuine positions too. The tree an `onDocument` callback receives embeds those same framed node objects (decompose wraps, it never copies — only a styles-minted paragraph or run is a copy), so the positions are identical in both encodings by construction.
 - **ODF text getters must call `decodeOdfText`.** See the dedicated gotcha above.
 - **`readPdf` recovers rect/ellipse/line as their own `LayoutRect`/`LayoutEllipse`/`LayoutLine` kinds** via pdf-codec's shape-pattern detection — an axis-aligned closed four-corner subpath is a rect, four kappa-ratio cubics at cardinal points is an ellipse, an open single straight stroke is a line. A false positive changes kind, never geometry. Off-axis rotations, freeform curves, and multi-subpath figures narrow to `LayoutPath`.
 - **`pdfToOds` re-types cells heuristically — this is probabilistic, not a fidelity guarantee.** A rendered PDF never carries a cell's typed value, only the printed string. Re-typing fires only where the string has exactly one defensible reading: the decimal must be exactly representable as a JS number; separators must be unambiguous (`"1,234"` is declined — competing European reading is 1.234); leading zeros decline (`"007"`); dates must self-state their component roles (ISO or named month accepted; `"01/02/2024"` declined). `TRUE`/`FALSE` re-type as booleans; `Yes`/`No` are declined. `displayText` always carries the rendered string verbatim. `onCellTypeInference` reports every decision. A formula is never claimed.
@@ -674,7 +687,7 @@ Read as **row → column**. `✓` lossless, `~` bounded, `✗` lossy, `✗✗` s
 | **csv** | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✗ | ✗ | – | ✗✗ | — | ~ |
 | **pdf** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | – | ✗✗ | ✗ | — |
 
-111 of 132 directional pairs are routable. The `ContentDocument`/`LayoutDocument` pivots are the hub, not PDF — twenty bridges bypass PDF entirely.
+111 of 132 directional pairs are routable. The shared `ContentDocument` model is the hub, not PDF — twenty bridges bypass PDF entirely.
 
 **X → PDF** is a genuine layout render: positioned text, images, tables, lists, vector primitives, styled through the full cascade. It is a faithful visual approximation, not pixel-identical — closeness depends on font availability.
 
@@ -713,7 +726,7 @@ Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`, …), enforced by comm
 ## References
 
 - [ooxml.js](https://github.com/ExaDev/ooxml.js) — docx/pptx/xlsx ⇄ JSON handling and typed reading, including `readXlsxContent`/`buildXlsxPackage` (consumed by the `odsToXlsx`/`xlsxToOds` bridge and internal codecs, and re-exported directly from this package's own surface — 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`/`LayoutDocument` and the port contracts; shared by all sibling packages.
+- [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.

package/dist/codecs/registry.d.cts

@@ -1,5 +1,6 @@
 import { DocumentFormat } from "../convert/port.cjs";
-import { ContentCodec, LayoutCodec } from "document-schema.js";
+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>;
@@ -8,10 +9,14 @@ interface DocumentCodecOptions {
   readonly signal?: AbortSignal;
   readonly images?: MarkdownImageResolver;
 }
+interface LayoutEntryCodec {
+  read(bytes: Uint8Array, options?: DocumentCodecOptions): LayoutDocument;
+  write(layout: LayoutDocument, options?: DocumentCodecOptions): Uint8Array;
+}
 interface DocumentFormatCodecs {
   readonly content?: ContentCodec<DocumentCodecOptions>;
-  readonly layout?: LayoutCodec<DocumentCodecOptions>;
+  readonly layout?: LayoutEntryCodec;
 }
 declare const DOCUMENT_FORMAT_CODECS: Readonly<Record<DocumentFormat, DocumentFormatCodecs>>;
 //#endregion
-export { DOCUMENT_FORMAT_CODECS, DocumentCodecOptions, DocumentFormatCodecs, isArrayBufferBacked, requireArrayBufferBytes };
+export { DOCUMENT_FORMAT_CODECS, DocumentCodecOptions, DocumentFormatCodecs, LayoutEntryCodec, isArrayBufferBacked, requireArrayBufferBytes };

package/dist/codecs/registry.d.ts

@@ -1,5 +1,6 @@
 import { DocumentFormat } from "../convert/port.js";
-import { ContentCodec, LayoutCodec } from "document-schema.js";
+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>;
@@ -8,10 +9,14 @@ interface DocumentCodecOptions {
   readonly signal?: AbortSignal;
   readonly images?: MarkdownImageResolver;
 }
+interface LayoutEntryCodec {
+  read(bytes: Uint8Array, options?: DocumentCodecOptions): LayoutDocument;
+  write(layout: LayoutDocument, options?: DocumentCodecOptions): Uint8Array;
+}
 interface DocumentFormatCodecs {
   readonly content?: ContentCodec<DocumentCodecOptions>;
-  readonly layout?: LayoutCodec<DocumentCodecOptions>;
+  readonly layout?: LayoutEntryCodec;
 }
 declare const DOCUMENT_FORMAT_CODECS: Readonly<Record<DocumentFormat, DocumentFormatCodecs>>;
 //#endregion
-export { DOCUMENT_FORMAT_CODECS, DocumentCodecOptions, DocumentFormatCodecs, isArrayBufferBacked, requireArrayBufferBytes };
+export { DOCUMENT_FORMAT_CODECS, DocumentCodecOptions, DocumentFormatCodecs, LayoutEntryCodec, isArrayBufferBacked, requireArrayBufferBytes };

package/dist/convert/canonicalise.cjs

@@ -0,0 +1,20 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/convert/canonicalise.ts
+function canonicalise(value) {
+	if (Array.isArray(value)) return value.map(canonicalise);
+	if (isRecord(value)) {
+		const sorted = {};
+		for (const key of Object.keys(value).sort()) sorted[key] = canonicalise(value[key]);
+		return sorted;
+	}
+	return value;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalKey(value) {
+	return JSON.stringify(canonicalise(value));
+}
+//#endregion
+exports.canonicalKey = canonicalKey;
+exports.canonicalise = canonicalise;

package/dist/convert/canonicalise.d.cts

@@ -0,0 +1,5 @@
+//#region src/convert/canonicalise.d.ts
+declare function canonicalise(value: unknown): unknown;
+declare function canonicalKey(value: unknown): string;
+//#endregion
+export { canonicalKey, canonicalise };

package/dist/convert/canonicalise.d.ts

@@ -0,0 +1,5 @@
+//#region src/convert/canonicalise.d.ts
+declare function canonicalise(value: unknown): unknown;
+declare function canonicalKey(value: unknown): string;
+//#endregion
+export { canonicalKey, canonicalise };

package/dist/convert/canonicalise.js

@@ -0,0 +1,18 @@
+//#region src/convert/canonicalise.ts
+function canonicalise(value) {
+	if (Array.isArray(value)) return value.map(canonicalise);
+	if (isRecord(value)) {
+		const sorted = {};
+		for (const key of Object.keys(value).sort()) sorted[key] = canonicalise(value[key]);
+		return sorted;
+	}
+	return value;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function canonicalKey(value) {
+	return JSON.stringify(canonicalise(value));
+}
+//#endregion
+export { canonicalKey, canonicalise };

package/dist/convert/composition.cjs

@@ -28,13 +28,14 @@ const require_ports_abort = require("../ports/abort.cjs");
 const require_layout_sheets = require("../layout/sheets.cjs");
 const require_layout_drawing = require("../layout/drawing.cjs");
 const require_layout_reconstruct = require("../layout/reconstruct.cjs");
+const require_convert_factor_styles = require("./factor-styles.cjs");
 const require_convert_variant_bridges = require("./variant-bridges.cjs");
 const require_convert_capability = require("./capability.cjs");
 let ooxml_js = require("ooxml.js");
-let document_schema_js = require("document-schema.js");
+require("document-schema.js");
+let pdf_codec = require("pdf-codec");
 let odf_js = require("odf.js");
 require("markdown-codec");
-let pdf_codec = require("pdf-codec");
 //#region src/convert/composition.ts
 const mathMetricsAt = (sizePt) => (0, pdf_codec.loadMathFont)().metricsAt(sizePt);
 const CONTENT_FORMATS = [
@@ -217,16 +218,16 @@ function executeBridge(source, target, bytes, options) {
 		buildContent = transform(content);
 	}
 	require_ports_abort.throwIfAborted(options?.signal);
-	options?.onDocument?.({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content: buildContent
-	});
+	let out;
 	if (isTextFormatNode(targetNode)) {
 		const text = targetNode.build(buildContent, options);
-		return targetNode.encode(text);
+		out = targetNode.encode(text);
+	} else {
+		const pkg = targetNode.build(buildContent, options);
+		out = targetNode.encode(pkg);
 	}
-	const pkg = targetNode.build(buildContent, options);
-	return targetNode.encode(pkg);
+	options?.onDocument?.(require_convert_factor_styles.assemblePackage(buildContent));
+	return out;
 }
 function executeToPdf(format, bytes, options) {
 	if (!LAYOUT_CAPABLE.has(format)) throw new Error(`executeToPdf: '${format}' has no layout engine of its own`);
@@ -311,22 +312,23 @@ function executeToPdf(format, bytes, options) {
 		}
 		default: throw new Error(`executeToPdf: cannot lay out a '${content.kind}' document`);
 	}
-	options?.onDocument?.({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content,
-		pages: [...pages]
-	});
-	if (formulas === void 0) return (0, pdf_codec.writePdf)(layout, {
-		signal: options?.signal,
-		onSubstitution: options?.onSubstitution,
-		fonts
-	});
-	return (0, pdf_codec.writePdf)(layout, {
+	if (formulas === void 0) {
+		const out = (0, pdf_codec.writePdf)(layout, {
+			signal: options?.signal,
+			onSubstitution: options?.onSubstitution,
+			fonts
+		});
+		options?.onDocument?.(require_convert_factor_styles.assemblePackage(content, pages));
+		return out;
+	}
+	const out = (0, pdf_codec.writePdf)(layout, {
 		signal: options?.signal,
 		onSubstitution: options?.onSubstitution,
 		formulas,
 		fonts
 	});
+	options?.onDocument?.(require_convert_factor_styles.assemblePackage(content, pages));
+	return out;
 }
 function executeFromPdf(target, bytes, options) {
 	const node = FORMAT_NODES[target];
@@ -342,17 +344,16 @@ function executeFromPdf(target, bytes, options) {
 		widthPt: page.widthPt,
 		heightPt: page.heightPt
 	}));
-	options?.onDocument?.({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content,
-		pages
-	});
+	let out;
 	if (isTextFormatNode(node)) {
 		const text = node.build(content, options);
-		return node.encode(text);
+		out = node.encode(text);
+	} else {
+		const pkg = node.build(content);
+		out = node.encode(pkg);
 	}
-	const pkg = node.build(content);
-	return node.encode(pkg);
+	options?.onDocument?.(require_convert_factor_styles.assemblePackage(content, pages));
+	return out;
 }
 function buildCompositionGraph() {
 	const adj = /* @__PURE__ */ new Map();

package/dist/convert/composition.d.cts

@@ -5,9 +5,9 @@ import { SvgDiagnosticSink } from "../svg/diagnostics.cjs";
 import { CellTypeInferenceSink } from "../layout/cell-typing.cjs";
 import { t as OmmlDiagnostic } from "../shared-DLZ3IQUl.cjs";
 import { ContentDocument, DocumentPackage, FontSubstitution, ProvidedFont } from "document-schema.js";
+import { PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
 import { MarkdownImageResolver } from "markdown-codec";
 import { Package } from "ooxml.js";
-import { PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
 //#region src/convert/composition.d.ts
 type SourcePackage = Package;
 interface UnifiedConversionOptions {

package/dist/convert/composition.d.ts

@@ -6,8 +6,8 @@ import { CellTypeInferenceSink } from "../layout/cell-typing.js";
 import { t as OmmlDiagnostic } from "../shared-DUOzjwcL.js";
 import { Package } from "ooxml.js";
 import { ContentDocument, DocumentPackage, FontSubstitution, ProvidedFont } from "document-schema.js";
-import { MarkdownImageResolver } from "markdown-codec";
 import { PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
+import { MarkdownImageResolver } from "markdown-codec";
 //#region src/convert/composition.d.ts
 type SourcePackage = Package;
 interface UnifiedConversionOptions {

package/dist/convert/composition.js

@@ -27,13 +27,14 @@ import { throwIfAborted } from "../ports/abort.js";
 import { convertSpreadsheetToLayout } from "../layout/sheets.js";
 import { convertDrawingToLayout } from "../layout/drawing.js";
 import { reconstructDrawing, reconstructPresentation, reconstructSpreadsheet, reconstructWordprocessing } from "../layout/reconstruct.js";
+import { assemblePackage } from "./factor-styles.js";
 import { drawingToPresentation, presentationToDrawing, presentationToWordprocessing, wordprocessingToPresentation } from "./variant-bridges.js";
 import { UnsupportedConversionError } from "./capability.js";
 import { buildXlsxPackage, decodePackage, encodePackage, readXlsxContent } from "ooxml.js";
-import { DOCUMENT_PACKAGE_FORMAT_VERSION } from "document-schema.js";
+import "document-schema.js";
+import { createFontMeasurer, createFontRegistry, loadMathFont, readPdf, writePdf } from "pdf-codec";
 import { decodePackage as decodePackage$1, encodePackage as encodePackage$1 } from "odf.js";
 import "markdown-codec";
-import { createFontMeasurer, createFontRegistry, loadMathFont, readPdf, writePdf } from "pdf-codec";
 //#region src/convert/composition.ts
 const mathMetricsAt = (sizePt) => loadMathFont().metricsAt(sizePt);
 const CONTENT_FORMATS = [
@@ -216,16 +217,16 @@ function executeBridge(source, target, bytes, options) {
 		buildContent = transform(content);
 	}
 	throwIfAborted(options?.signal);
-	options?.onDocument?.({
-		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content: buildContent
-	});
+	let out;
 	if (isTextFormatNode(targetNode)) {
 		const text = targetNode.build(buildContent, options);
-		return targetNode.encode(text);
+		out = targetNode.encode(text);
+	} else {
+		const pkg = targetNode.build(buildContent, options);
+		out = targetNode.encode(pkg);
 	}
-	const pkg = targetNode.build(buildContent, options);
-	return targetNode.encode(pkg);
+	options?.onDocument?.(assemblePackage(buildContent));
+	return out;
 }
 function executeToPdf(format, bytes, options) {
 	if (!LAYOUT_CAPABLE.has(format)) throw new Error(`executeToPdf: '${format}' has no layout engine of its own`);
@@ -310,22 +311,23 @@ function executeToPdf(format, bytes, options) {
 		}
 		default: throw new Error(`executeToPdf: cannot lay out a '${content.kind}' document`);
 	}
-	options?.onDocument?.({
-		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content,
-		pages: [...pages]
-	});
-	if (formulas === void 0) return writePdf(layout, {
-		signal: options?.signal,
-		onSubstitution: options?.onSubstitution,
-		fonts
-	});
-	return writePdf(layout, {
+	if (formulas === void 0) {
+		const out = writePdf(layout, {
+			signal: options?.signal,
+			onSubstitution: options?.onSubstitution,
+			fonts
+		});
+		options?.onDocument?.(assemblePackage(content, pages));
+		return out;
+	}
+	const out = writePdf(layout, {
 		signal: options?.signal,
 		onSubstitution: options?.onSubstitution,
 		formulas,
 		fonts
 	});
+	options?.onDocument?.(assemblePackage(content, pages));
+	return out;
 }
 function executeFromPdf(target, bytes, options) {
 	const node = FORMAT_NODES[target];
@@ -341,17 +343,16 @@ function executeFromPdf(target, bytes, options) {
 		widthPt: page.widthPt,
 		heightPt: page.heightPt
 	}));
-	options?.onDocument?.({
-		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content,
-		pages
-	});
+	let out;
 	if (isTextFormatNode(node)) {
 		const text = node.build(content, options);
-		return node.encode(text);
+		out = node.encode(text);
+	} else {
+		const pkg = node.build(content);
+		out = node.encode(pkg);
 	}
-	const pkg = node.build(content);
-	return node.encode(pkg);
+	options?.onDocument?.(assemblePackage(content, pages));
+	return out;
 }
 function buildCompositionGraph() {
 	const adj = /* @__PURE__ */ new Map();

package/dist/convert/convert.cjs

@@ -12,11 +12,12 @@ const require_ports_abort = require("../ports/abort.cjs");
 const require_odb_csv = require("../odb/csv.cjs");
 const require_odb_read = require("../odb/read.cjs");
 const require_odb_spreadsheet = require("../odb/spreadsheet.cjs");
+const require_convert_factor_styles = require("./factor-styles.cjs");
 const require_convert_composition = require("./composition.cjs");
 let ooxml_js = require("ooxml.js");
 let document_schema_js = require("document-schema.js");
-let odf_js = require("odf.js");
 let pdf_codec = require("pdf-codec");
+let odf_js = require("odf.js");
 //#region src/convert/convert.ts
 const mathMetricsAt = (sizePt) => (0, pdf_codec.loadMathFont)().metricsAt(sizePt);
 function docxToPdf(bytes, options) {
@@ -70,7 +71,7 @@ function odfToPdf(bytes, options) {
 		heightPt: box.heightPt
 	}, document_schema_js.PAGE_SIZE_A4.heightPt);
 	const layout = {
-		formatVersion: document_schema_js.LAYOUT_FORMAT_VERSION,
+		formatVersion: pdf_codec.LAYOUT_FORMAT_VERSION,
 		metadata: content.metadata,
 		pages: [{
 			widthPt: document_schema_js.PAGE_SIZE_A4.widthPt,
@@ -79,16 +80,8 @@ function odfToPdf(bytes, options) {
 		}],
 		images: {}
 	};
-	options?.onDocument?.({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content,
-		pages: [{
-			widthPt: document_schema_js.PAGE_SIZE_A4.widthPt,
-			heightPt: document_schema_js.PAGE_SIZE_A4.heightPt
-		}]
-	});
 	require_ports_abort.throwIfAborted(options?.signal);
-	return (0, pdf_codec.writePdf)(layout, {
+	const out = (0, pdf_codec.writePdf)(layout, {
 		signal: options?.signal,
 		formulas: [{
 			pageIndex: 0,
@@ -97,6 +90,11 @@ function odfToPdf(bytes, options) {
 			box
 		}]
 	});
+	options?.onDocument?.(require_convert_factor_styles.assemblePackage(content, [{
+		widthPt: document_schema_js.PAGE_SIZE_A4.widthPt,
+		heightPt: document_schema_js.PAGE_SIZE_A4.heightPt
+	}]));
+	return out;
 }
 function pdfToDocx(bytes, options) {
 	return require_convert_composition.convertDocument("pdf", "docx", bytes, options);
@@ -280,7 +278,6 @@ function odmToPdf(bytes, options) {
 	require_ports_abort.throwIfAborted(options?.signal);
 	const content = {
 		kind: "wordprocessing",
-		formatVersion: document_schema_js.CONTENT_FORMAT_VERSION,
 		metadata: require_model_metadata.resolveMetadataTimestamps((0, odf_js.readOdfMetadata)(pkg), options?.clock),
 		sections: combinedSections
 	};
@@ -307,10 +304,7 @@ function odbToXlsx(bytes, options) {
 	require_ports_abort.throwIfAborted(options?.signal);
 	const content = require_odb_spreadsheet.odbTablesToSpreadsheetDocument(tables);
 	const out = (0, ooxml_js.encodePackage)((0, ooxml_js.buildXlsxPackage)(content));
-	options?.onDocument?.({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content
-	});
+	options?.onDocument?.(require_convert_factor_styles.assemblePackage(content));
 	return out;
 }
 function odbToCsv(bytes, options) {
@@ -319,10 +313,7 @@ function odbToCsv(bytes, options) {
 	const tables = require_odb_read.readOdbTables(pkg, { timeZone: options?.timeZone });
 	require_ports_abort.throwIfAborted(options?.signal);
 	const csv = require_odb_csv.buildOdbTableCsv(tables, options?.table);
-	if (options?.onDocument !== void 0) options.onDocument({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content: require_odb_spreadsheet.odbTablesToSpreadsheetDocument(tables)
-	});
+	if (options?.onDocument !== void 0) options.onDocument(require_convert_factor_styles.assemblePackage(require_odb_spreadsheet.odbTablesToSpreadsheetDocument(tables)));
 	return csv;
 }
 function odbReportToDocx(content, options) {
@@ -344,17 +335,14 @@ function odbReportToPdf(content, options) {
 		measurer: (0, pdf_codec.createFontMeasurer)(fonts),
 		mathMetricsAt
 	});
-	options?.onDocument?.({
-		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
-		content,
-		pages: [...pages]
-	});
-	return (0, pdf_codec.writePdf)(layout, {
+	const out = (0, pdf_codec.writePdf)(layout, {
 		signal: options?.signal,
 		onSubstitution: options?.onSubstitution,
 		formulas,
 		fonts
 	});
+	options?.onDocument?.(require_convert_factor_styles.assemblePackage(content, pages));
+	return out;
 }
 //#endregion
 exports.OdmUnresolvedSectionError = OdmUnresolvedSectionError;

package/dist/convert/convert.d.cts

@@ -5,8 +5,8 @@ import { t as OmmlDiagnostic } from "../shared-DLZ3IQUl.cjs";
 import { HsqldbDecodeOptions } from "../hsqldb/rowformat.cjs";
 import { DocumentFontRegistryOptions } from "../fonts/registry.cjs";
 import { ContentDocument, ContentSection, DocumentPackage } from "document-schema.js";
-import { MarkdownImageResolver } from "markdown-codec";
 import { PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
+import { MarkdownImageResolver } from "markdown-codec";
 import { OdmSection, Package } from "odf.js";
 //#region src/convert/convert.d.ts
 interface DocumentToPdfOptions extends DocumentFontRegistryOptions {

package/dist/convert/convert.d.ts

@@ -5,9 +5,9 @@ import { t as OmmlDiagnostic } from "../shared-DUOzjwcL.js";
 import { HsqldbDecodeOptions } from "../hsqldb/rowformat.js";
 import { DocumentFontRegistryOptions } from "../fonts/registry.js";
 import { ContentDocument, ContentSection, DocumentPackage } from "document-schema.js";
+import { PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
 import { OdmSection, Package } from "odf.js";
 import { MarkdownImageResolver } from "markdown-codec";
-import { PdfDiagnosticSink, WinAnsiSubstitution } from "pdf-codec";
 //#region src/convert/convert.d.ts
 interface DocumentToPdfOptions extends DocumentFontRegistryOptions {
   readonly signal?: AbortSignal;