documents.js 1.102.2 → 2.0.0

package/README.md

@@ -162,7 +162,7 @@ DocumentFormatSchema.parse(userSuppliedFormat); // throws a ZodError for anythin
 
 ### Intermediate `DocumentPackage`, JSON, and bytes
 
-Every conversion function accepts an `onDocument` callback receiving the intermediate `DocumentPackage` (content + layout). The port surfaces the same value as `package` on `ConversionResult`. For PDF-bypassing bridges, `pkg.layout` is always `undefined`.
+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.
 
 ```ts
 import { docxToPdf } from 'documents.js';
@@ -170,7 +170,9 @@ import { docxToPdf } from 'documents.js';
 const pdfBytes = docxToPdf(docxBytes, {
   onDocument: (pkg) => {
     console.log(pkg.content.kind); // 'wordprocessing'
-    console.log(pkg.layout?.pages.length); // populated for every X-to-PDF/PDF-to-X conversion
+    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;
+    console.log(block?.kind === 'paragraph' ? block.runs[0]?.frames : 'no paragraph'); // that run's rendered placements
   },
 });
 ```
@@ -187,7 +189,7 @@ const { kind, value } = documentFromJson(JSON.parse(readFileSync('converted.doc.
 // kind: 'DocumentPackage' (here) | 'ContentDocument' | 'LayoutDocument'
 ```
 
-`buildDocumentBytes` rebuilds any `DocumentFormat`'s bytes from a `DocumentPackage` — `'pdf'` writes the `LayoutDocument` half directly (throwing if the package carries none), `'odf'` has no builder and throws, everything else rebuilds from the `ContentDocument` half:
+`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):
 
 ```ts
 import { buildDocumentBytes, docxToPdf } from 'documents.js';
@@ -543,7 +545,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` afterwards leaves `layout` stale; nothing detects or rejects that.
+- **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.
 - **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.
@@ -604,7 +607,7 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **A formula that cannot typeset degrades to its plain-text stand-in, never to nothing.** `buildDocxPackage` writes real OMML; `buildOdtPackage` writes real embedded formula sub-documents. The markdown writer is the only stand-in-only path. `odmToPdf` carries formulas through as ordinary blocks.
 - **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.
+- **`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` passes `readMarkdown`'s result straight through** — `markdown-codec` already produces a full `ContentDocument`.
 - **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.
 - **`buildMarkdownText` throws for non-`'wordprocessing'` `ContentDocument`.**

package/dist/convert/composition.cjs

@@ -230,6 +230,7 @@ function executeToPdf(format, bytes, options) {
 	}
 	const measurer = (0, pdf_codec.createFontMeasurer)(fonts);
 	let layout;
+	let pages;
 	let formulas;
 	switch (content.kind) {
 		case "wordprocessing": {
@@ -238,6 +239,7 @@ function executeToPdf(format, bytes, options) {
 				mathMetricsAt
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
@@ -247,6 +249,7 @@ function executeToPdf(format, bytes, options) {
 				mathMetricsAt
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
@@ -257,18 +260,22 @@ function executeToPdf(format, bytes, options) {
 				signal: options?.signal
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
-		case "drawing":
-			layout = LAYOUT_ENGINES.drawing(content, { measurer });
+		case "drawing": {
+			const result = LAYOUT_ENGINES.drawing(content, { measurer });
+			layout = result.document;
+			pages = result.pages;
 			break;
+		}
 		default: throw new Error(`executeToPdf: cannot lay out a '${content.kind}' document`);
 	}
 	options?.onDocument?.({
 		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages: [...pages]
 	});
 	if (formulas === void 0) return (0, pdf_codec.writePdf)(layout, {
 		signal: options?.signal,
@@ -289,10 +296,14 @@ function executeFromPdf(target, bytes, options) {
 		sink: options?.sink
 	});
 	const content = RECONSTRUCTORS[node.variant](layout, { signal: options?.signal });
+	const pages = layout.pages.map((page) => ({
+		widthPt: page.widthPt,
+		heightPt: page.heightPt
+	}));
 	options?.onDocument?.({
 		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages
 	});
 	if (node.family === "markdown") {
 		const text = node.build(content);

package/dist/convert/composition.js

@@ -229,6 +229,7 @@ function executeToPdf(format, bytes, options) {
 	}
 	const measurer = createFontMeasurer(fonts);
 	let layout;
+	let pages;
 	let formulas;
 	switch (content.kind) {
 		case "wordprocessing": {
@@ -237,6 +238,7 @@ function executeToPdf(format, bytes, options) {
 				mathMetricsAt
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
@@ -246,6 +248,7 @@ function executeToPdf(format, bytes, options) {
 				mathMetricsAt
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
@@ -256,18 +259,22 @@ function executeToPdf(format, bytes, options) {
 				signal: options?.signal
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
-		case "drawing":
-			layout = LAYOUT_ENGINES.drawing(content, { measurer });
+		case "drawing": {
+			const result = LAYOUT_ENGINES.drawing(content, { measurer });
+			layout = result.document;
+			pages = result.pages;
 			break;
+		}
 		default: throw new Error(`executeToPdf: cannot lay out a '${content.kind}' document`);
 	}
 	options?.onDocument?.({
 		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages: [...pages]
 	});
 	if (formulas === void 0) return writePdf(layout, {
 		signal: options?.signal,
@@ -288,10 +295,14 @@ function executeFromPdf(target, bytes, options) {
 		sink: options?.sink
 	});
 	const content = RECONSTRUCTORS[node.variant](layout, { signal: options?.signal });
+	const pages = layout.pages.map((page) => ({
+		widthPt: page.widthPt,
+		heightPt: page.heightPt
+	}));
 	options?.onDocument?.({
 		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages
 	});
 	if (node.family === "markdown") {
 		const text = node.build(content);

package/dist/convert/convert.cjs

@@ -76,7 +76,10 @@ function odfToPdf(bytes, options) {
 	options?.onDocument?.({
 		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		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, {
@@ -291,14 +294,14 @@ function odbReportToPdf(content, options) {
 		fonts: options?.fonts,
 		onSubstitution: options?.onFontSubstitution
 	});
-	const { document: layout, formulas } = require_layout_engine.convertWordprocessingToLayout(content, {
+	const { document: layout, formulas, pages } = require_layout_engine.convertWordprocessingToLayout(content, {
 		measurer: (0, pdf_codec.createFontMeasurer)(fonts),
 		mathMetricsAt
 	});
 	options?.onDocument?.({
 		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages: [...pages]
 	});
 	return (0, pdf_codec.writePdf)(layout, {
 		signal: options?.signal,

package/dist/convert/convert.js

@@ -75,7 +75,10 @@ function odfToPdf(bytes, options) {
 	options?.onDocument?.({
 		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages: [{
+			widthPt: PAGE_SIZE_A4.widthPt,
+			heightPt: PAGE_SIZE_A4.heightPt
+		}]
 	});
 	throwIfAborted(options?.signal);
 	return writePdf(layout, {
@@ -290,14 +293,14 @@ function odbReportToPdf(content, options) {
 		fonts: options?.fonts,
 		onSubstitution: options?.onFontSubstitution
 	});
-	const { document: layout, formulas } = convertWordprocessingToLayout(content, {
+	const { document: layout, formulas, pages } = convertWordprocessingToLayout(content, {
 		measurer: createFontMeasurer(fonts),
 		mathMetricsAt
 	});
 	options?.onDocument?.({
 		formatVersion: DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content,
-		layout
+		pages: [...pages]
 	});
 	return writePdf(layout, {
 		signal: options?.signal,

package/dist/convert/from-package.cjs

@@ -1,16 +1,193 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_model_geometry = require("../model/geometry.cjs");
+const require_layout_shared = require("../layout/shared.cjs");
+require("../layout/sheets.cjs");
+const require_layout_drawing = require("../layout/drawing.cjs");
 const require_codecs_registry = require("../codecs/registry.cjs");
+let document_schema_js = require("document-schema.js");
 let pdf_codec = require("pdf-codec");
 //#region src/convert/from-package.ts
 function buildDocumentBytes(pkg, target) {
 	if (target === "pdf") {
-		if (pkg.layout === void 0) throw new Error("this DocumentPackage has no layout -- only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries one; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
-		return (0, pdf_codec.writePdf)(pkg.layout);
+		if (pkg.pages === void 0) throw new Error("this DocumentPackage has no pages -- only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries them; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
+		return (0, pdf_codec.writePdf)(layoutDocumentFromPackage(pkg));
 	}
 	if (target === "odf") throw new Error("'odf' (a standalone formula document) cannot be built from a DocumentPackage -- there is no ContentDocument-to-odf builder");
 	const content = require_codecs_registry.DOCUMENT_FORMAT_CODECS[target].content;
 	if (!content?.write) throw new Error(`DocumentFormat '${target}' has no content.write codec in DOCUMENT_FORMAT_CODECS, and is not 'pdf'/'odf' -- this is an internal invariant violation, not a caller error`);
 	return require_codecs_registry.requireArrayBufferBytes(content.write(pkg.content));
 }
+function pageOfFrame(state, frame) {
+	return state.pages[frame.pageIndex];
+}
+function emitRun(state, run) {
+	const frame = run.frames?.[0];
+	if (frame === void 0) return;
+	const page = pageOfFrame(state, frame);
+	if (page === void 0) return;
+	const font = require_layout_shared.runFont(run);
+	const sizePt = run.sizePt ?? 18;
+	const textItem = {
+		kind: "text",
+		text: run.text,
+		xPt: frame.xPt,
+		yPt: frame.yPt,
+		font,
+		sizePt,
+		color: run.color ?? document_schema_js.COLOR_BLACK,
+		underline: run.underline
+	};
+	page.items.push(textItem);
+	if (run.hyperlink !== void 0) {
+		const link = {
+			kind: "link",
+			uri: run.hyperlink,
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt
+		};
+		page.items.push(link);
+	}
+}
+function emitParagraph(state, paragraph) {
+	for (const run of paragraph.runs) emitRun(state, run);
+}
+function emitImageBlock(state, block, frames) {
+	for (const frame of frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		const image = {
+			kind: "image",
+			imageId: require_layout_shared.registerImage(block, state.images),
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt
+		};
+		page.items.push(image);
+	}
+}
+function emitTableCell(state, cell) {
+	for (const frame of cell.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		if (cell.background !== void 0) page.items.push({
+			kind: "rect",
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt,
+			fill: cell.background
+		});
+		if (cell.borders !== void 0) {
+			const frameYDown = require_model_geometry.flipY({
+				xPt: frame.xPt,
+				yPt: frame.yPt,
+				widthPt: frame.widthPt,
+				heightPt: frame.heightPt
+			}, page.heightPt);
+			require_layout_shared.pushCellBorderLines(cell.borders, frameYDown, page.heightPt, cell.sourcePath, page.items);
+		}
+	}
+	for (const block of cell.blocks) if (block.kind === "paragraph") emitParagraph(state, block);
+	else if (block.kind === "image") emitImageBlock(state, block, block.frames);
+	else if (block.kind === "table") emitTable(state, block);
+}
+function emitTable(state, table) {
+	for (const row of table.rows) for (const cell of row.cells) emitTableCell(state, cell);
+}
+function emitVector(state, vector) {
+	for (const frame of vector.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		const items = page.items;
+		require_layout_drawing.convertVector(vector, page.heightPt, items);
+	}
+}
+function emitSheetCell(state, cell) {
+	if ((cell.runs ?? []).some((run) => (run.frames?.length ?? 0) > 0)) for (const run of cell.runs ?? []) emitRun(state, run);
+	else for (const frame of cell.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		page.items.push({
+			kind: "text",
+			text: cell.displayText,
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			font: document_schema_js.DEFAULT_LAYOUT_FONT,
+			sizePt: 10,
+			color: document_schema_js.COLOR_BLACK
+		});
+	}
+	for (const frame of cell.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		if (cell.background !== void 0) page.items.push({
+			kind: "rect",
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt,
+			fill: cell.background
+		});
+		if (cell.borders !== void 0) {
+			const frameYDown = require_model_geometry.flipY({
+				xPt: frame.xPt,
+				yPt: frame.yPt,
+				widthPt: frame.widthPt,
+				heightPt: frame.heightPt
+			}, page.heightPt);
+			require_layout_shared.pushCellBorderLines(cell.borders, frameYDown, page.heightPt, cell.sourcePath, page.items);
+		}
+	}
+}
+function emitSheet(state, sheet) {
+	for (const cell of sheet.cells) emitSheetCell(state, cell);
+	for (const image of sheet.images) for (const frame of image.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		const layoutImage = {
+			kind: "image",
+			imageId: require_layout_shared.registerImage(image, state.images),
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt
+		};
+		page.items.push(layoutImage);
+	}
+}
+function emitBlocks(state, blocks) {
+	for (const block of blocks) if (block.kind === "paragraph") emitParagraph(state, block);
+	else if (block.kind === "image") emitImageBlock(state, block, block.frames);
+	else if (block.kind === "table") emitTable(state, block);
+}
+function layoutDocumentFromPackage(pkg) {
+	const pages = (pkg.pages ?? []).map((page) => ({
+		widthPt: page.widthPt,
+		heightPt: page.heightPt,
+		items: []
+	}));
+	const state = {
+		pages,
+		images: {}
+	};
+	const content = pkg.content;
+	if (content.kind === "wordprocessing") for (const section of content.sections) emitBlocks(state, section.blocks);
+	else if (content.kind === "presentation") for (const slide of content.slides) for (const shape of slide.shapes) emitBlocks(state, shape.blocks);
+	else if (content.kind === "spreadsheet") for (const sheet of content.sheets) emitSheet(state, sheet);
+	else if (content.kind === "drawing") for (const drawPage of content.pages) {
+		for (const vector of drawPage.vectors) emitVector(state, vector);
+		for (const shape of drawPage.shapes) emitBlocks(state, shape.blocks);
+	}
+	return {
+		formatVersion: document_schema_js.LAYOUT_FORMAT_VERSION,
+		metadata: content.metadata,
+		pages,
+		images: state.images
+	};
+}
 //#endregion
 exports.buildDocumentBytes = buildDocumentBytes;
+exports.layoutDocumentFromPackage = layoutDocumentFromPackage;

package/dist/convert/from-package.d.cts

@@ -1,6 +1,7 @@
 import { DocumentFormat } from "./port.cjs";
-import { DocumentPackage } from "document-schema.js";
+import { DocumentPackage, LayoutDocument } from "document-schema.js";
 //#region src/convert/from-package.d.ts
 declare function buildDocumentBytes(pkg: DocumentPackage, target: DocumentFormat): Uint8Array<ArrayBuffer>;
+declare function layoutDocumentFromPackage(pkg: DocumentPackage): LayoutDocument;
 //#endregion
-export { buildDocumentBytes };
+export { buildDocumentBytes, layoutDocumentFromPackage };

package/dist/convert/from-package.d.ts

@@ -1,6 +1,7 @@
 import { DocumentFormat } from "./port.js";
-import { DocumentPackage } from "document-schema.js";
+import { DocumentPackage, LayoutDocument } from "document-schema.js";
 //#region src/convert/from-package.d.ts
 declare function buildDocumentBytes(pkg: DocumentPackage, target: DocumentFormat): Uint8Array<ArrayBuffer>;
+declare function layoutDocumentFromPackage(pkg: DocumentPackage): LayoutDocument;
 //#endregion
-export { buildDocumentBytes };
+export { buildDocumentBytes, layoutDocumentFromPackage };

package/dist/convert/from-package.js

@@ -1,15 +1,191 @@
+import { flipY } from "../model/geometry.js";
+import { pushCellBorderLines, registerImage, runFont } from "../layout/shared.js";
+import "../layout/sheets.js";
+import { convertVector } from "../layout/drawing.js";
 import { DOCUMENT_FORMAT_CODECS, requireArrayBufferBytes } from "../codecs/registry.js";
+import { COLOR_BLACK, DEFAULT_LAYOUT_FONT, LAYOUT_FORMAT_VERSION } from "document-schema.js";
 import { writePdf } from "pdf-codec";
 //#region src/convert/from-package.ts
 function buildDocumentBytes(pkg, target) {
 	if (target === "pdf") {
-		if (pkg.layout === void 0) throw new Error("this DocumentPackage has no layout -- only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries one; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
-		return writePdf(pkg.layout);
+		if (pkg.pages === void 0) throw new Error("this DocumentPackage has no pages -- only a package dumped from a <format>-to-pdf or pdf-to-<format> conversion carries them; a bridge conversion's own dump (e.g. odt-to-docx) never does, so 'pdf' is not a reachable target from it");
+		return writePdf(layoutDocumentFromPackage(pkg));
 	}
 	if (target === "odf") throw new Error("'odf' (a standalone formula document) cannot be built from a DocumentPackage -- there is no ContentDocument-to-odf builder");
 	const content = DOCUMENT_FORMAT_CODECS[target].content;
 	if (!content?.write) throw new Error(`DocumentFormat '${target}' has no content.write codec in DOCUMENT_FORMAT_CODECS, and is not 'pdf'/'odf' -- this is an internal invariant violation, not a caller error`);
 	return requireArrayBufferBytes(content.write(pkg.content));
 }
+function pageOfFrame(state, frame) {
+	return state.pages[frame.pageIndex];
+}
+function emitRun(state, run) {
+	const frame = run.frames?.[0];
+	if (frame === void 0) return;
+	const page = pageOfFrame(state, frame);
+	if (page === void 0) return;
+	const font = runFont(run);
+	const sizePt = run.sizePt ?? 18;
+	const textItem = {
+		kind: "text",
+		text: run.text,
+		xPt: frame.xPt,
+		yPt: frame.yPt,
+		font,
+		sizePt,
+		color: run.color ?? COLOR_BLACK,
+		underline: run.underline
+	};
+	page.items.push(textItem);
+	if (run.hyperlink !== void 0) {
+		const link = {
+			kind: "link",
+			uri: run.hyperlink,
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt
+		};
+		page.items.push(link);
+	}
+}
+function emitParagraph(state, paragraph) {
+	for (const run of paragraph.runs) emitRun(state, run);
+}
+function emitImageBlock(state, block, frames) {
+	for (const frame of frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		const image = {
+			kind: "image",
+			imageId: registerImage(block, state.images),
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt
+		};
+		page.items.push(image);
+	}
+}
+function emitTableCell(state, cell) {
+	for (const frame of cell.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		if (cell.background !== void 0) page.items.push({
+			kind: "rect",
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt,
+			fill: cell.background
+		});
+		if (cell.borders !== void 0) {
+			const frameYDown = flipY({
+				xPt: frame.xPt,
+				yPt: frame.yPt,
+				widthPt: frame.widthPt,
+				heightPt: frame.heightPt
+			}, page.heightPt);
+			pushCellBorderLines(cell.borders, frameYDown, page.heightPt, cell.sourcePath, page.items);
+		}
+	}
+	for (const block of cell.blocks) if (block.kind === "paragraph") emitParagraph(state, block);
+	else if (block.kind === "image") emitImageBlock(state, block, block.frames);
+	else if (block.kind === "table") emitTable(state, block);
+}
+function emitTable(state, table) {
+	for (const row of table.rows) for (const cell of row.cells) emitTableCell(state, cell);
+}
+function emitVector(state, vector) {
+	for (const frame of vector.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		const items = page.items;
+		convertVector(vector, page.heightPt, items);
+	}
+}
+function emitSheetCell(state, cell) {
+	if ((cell.runs ?? []).some((run) => (run.frames?.length ?? 0) > 0)) for (const run of cell.runs ?? []) emitRun(state, run);
+	else for (const frame of cell.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		page.items.push({
+			kind: "text",
+			text: cell.displayText,
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			font: DEFAULT_LAYOUT_FONT,
+			sizePt: 10,
+			color: COLOR_BLACK
+		});
+	}
+	for (const frame of cell.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		if (cell.background !== void 0) page.items.push({
+			kind: "rect",
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt,
+			fill: cell.background
+		});
+		if (cell.borders !== void 0) {
+			const frameYDown = flipY({
+				xPt: frame.xPt,
+				yPt: frame.yPt,
+				widthPt: frame.widthPt,
+				heightPt: frame.heightPt
+			}, page.heightPt);
+			pushCellBorderLines(cell.borders, frameYDown, page.heightPt, cell.sourcePath, page.items);
+		}
+	}
+}
+function emitSheet(state, sheet) {
+	for (const cell of sheet.cells) emitSheetCell(state, cell);
+	for (const image of sheet.images) for (const frame of image.frames ?? []) {
+		const page = pageOfFrame(state, frame);
+		if (page === void 0) continue;
+		const layoutImage = {
+			kind: "image",
+			imageId: registerImage(image, state.images),
+			xPt: frame.xPt,
+			yPt: frame.yPt,
+			widthPt: frame.widthPt,
+			heightPt: frame.heightPt
+		};
+		page.items.push(layoutImage);
+	}
+}
+function emitBlocks(state, blocks) {
+	for (const block of blocks) if (block.kind === "paragraph") emitParagraph(state, block);
+	else if (block.kind === "image") emitImageBlock(state, block, block.frames);
+	else if (block.kind === "table") emitTable(state, block);
+}
+function layoutDocumentFromPackage(pkg) {
+	const pages = (pkg.pages ?? []).map((page) => ({
+		widthPt: page.widthPt,
+		heightPt: page.heightPt,
+		items: []
+	}));
+	const state = {
+		pages,
+		images: {}
+	};
+	const content = pkg.content;
+	if (content.kind === "wordprocessing") for (const section of content.sections) emitBlocks(state, section.blocks);
+	else if (content.kind === "presentation") for (const slide of content.slides) for (const shape of slide.shapes) emitBlocks(state, shape.blocks);
+	else if (content.kind === "spreadsheet") for (const sheet of content.sheets) emitSheet(state, sheet);
+	else if (content.kind === "drawing") for (const drawPage of content.pages) {
+		for (const vector of drawPage.vectors) emitVector(state, vector);
+		for (const shape of drawPage.shapes) emitBlocks(state, shape.blocks);
+	}
+	return {
+		formatVersion: LAYOUT_FORMAT_VERSION,
+		metadata: content.metadata,
+		pages,
+		images: state.images
+	};
+}
 //#endregion
-export { buildDocumentBytes };
+export { buildDocumentBytes, layoutDocumentFromPackage };

package/dist/index.cjs

@@ -800,6 +800,7 @@ Object.defineProperty(exports, "isXmlNode", {
 		return ooxml_js.isXmlNode;
 	}
 });
+exports.layoutDocumentFromPackage = require_convert_from_package.layoutDocumentFromPackage;
 Object.defineProperty(exports, "layoutDocumentWithSchema", {
 	enumerable: true,
 	get: function() {