documents.js 1.102.2 → 2.1.0

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, 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 73 (source, target) pairs across the eight content formats and PDF, including fourteen PDF-pivot round trips, sixteen cross-format bridges (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, 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), 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 91 (source, target) pairs across the nine content formats and PDF, including eighteen PDF-pivot round trips (the seven layout-engine formats, plus xlsx and csv composing through ods), twenty-two 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, 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.
 
@@ -72,7 +72,7 @@ npm install documents.js
 
 ### The generic entry point: `convertDocument`
 
-A single function, `convertDocument`, sits behind every named conversion and reaches every pair the composition engine can route — all 73 supported (source, target) combinations. The named functions below are thin one-line forwarders to it; they remain the ergonomic layer for a caller who wants a fixed pair and autocomplete discovery, while `convertDocument` is the first-class entry point for a caller working from a runtime format pair (CLI, MCP tool, matrix enumeration).
+A single function, `convertDocument`, sits behind every named conversion and reaches every pair the composition engine can route — all 91 supported (source, target) combinations. The named functions below are thin one-line forwarders to it; they remain the ergonomic layer for a caller who wants a fixed pair and autocomplete discovery, while `convertDocument` is the first-class entry point for a caller working from a runtime format pair (CLI, MCP tool, matrix enumeration).
 
 ```ts
 import { convertDocument } from 'documents.js';
@@ -89,10 +89,10 @@ const odtBytes = convertDocument('docx', 'odt', docxBytes, { onMathDiagnostic: (
 
 ### PDF-pivot conversions
 
-The fourteen round-trip ergonomic conversions between the formats with their own layout engine and PDF (docx/pptx/odt/odp/ods/odg/markdown ⇄ PDF, all round-tripping both ways), plus `xlsxToPdf`/`pdfToXlsx` (composing the ods⇄xlsx bridge with the ods⇄pdf layout pair internally):
+The fourteen round-trip ergonomic conversions between the formats with their own layout engine and PDF (docx/pptx/odt/odp/ods/odg/markdown ⇄ PDF, all round-tripping both ways), plus `xlsxToPdf`/`pdfToXlsx` and `csvToPdf`/`pdfToCsv` (each composing its ods bridge with the ods⇄pdf layout pair internally — neither xlsx nor csv has a layout engine of its own):
 
 ```ts
-import { docxToPdf, markdownToPdf, odgToPdf, odpToPdf, odsToPdf, odtToPdf, pdfToDocx, pdfToMarkdown, pdfToOdg, pdfToOdp, pdfToOds, pdfToOdt, pdfToPptx, pdfToXlsx, pptxToPdf, xlsxToPdf } from 'documents.js';
+import { csvToPdf, docxToPdf, markdownToPdf, odgToPdf, odpToPdf, odsToPdf, odtToPdf, pdfToCsv, pdfToDocx, pdfToMarkdown, pdfToOdg, pdfToOdp, pdfToOds, pdfToOdt, pdfToPptx, pdfToXlsx, pptxToPdf, xlsxToPdf } from 'documents.js';
 
 const pdfBytes = docxToPdf(docxBytes);
 const docxBytes2 = pdfToDocx(pdfBytes);
@@ -117,13 +117,16 @@ const xlsxBytes2 = pdfToXlsx(pdfFromXlsx); // composes pdfToOds -> odsToXlsx int
 
 const pdfFromMarkdown = markdownToPdf(markdownBytes);
 const markdownBytes2 = pdfToMarkdown(pdfFromMarkdown); // the lossiest conversion in the whole package -- see Fidelity
+
+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
 ```
 
 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).
 
 ### Cross-format bridges
 
-Sixteen bridge functions across eight pairs bypass the PDF pivot entirely. Five same-variant direct-copy pairs (`odtToDocx`/`docxToOdt`, `odpToPptx`/`pptxToOdp`, `odsToXlsx`/`xlsxToOds`, `markdownToDocx`/`docxToMarkdown`, `markdownToOdt`/`odtToMarkdown`) compose a direct `readXContent` → `buildYPackage` pivot copy. Two cross-variant semantic-transform pairs (`docxToPptx`/`pptxToDocx`, `odtToOdp`/`odpToOdt`) go through `src/convert/variant-bridges.ts`. One PDF-composed pair (`xlsxToMarkdown`/`markdownToXlsx`) routes through PDF internally — the single lossiest conversion in the package.
+Twenty-two bridge functions across eleven pairs bypass the PDF pivot where a direct path exists. Seven same-variant direct-copy pairs (`odtToDocx`/`docxToOdt`, `odpToPptx`/`pptxToOdp`, `odsToXlsx`/`xlsxToOds`, `csvToOds`/`odsToCsv`, `csvToXlsx`/`xlsxToCsv`, `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. 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.
 
 ```ts
 import { odtToDocx, docxToOdt, markdownToDocx, docxToMarkdown } from 'documents.js';
@@ -135,7 +138,7 @@ const docxFromMarkdown = markdownToDocx(markdownBytes);
 const markdownBytes3 = docxToMarkdown(docxFromMarkdown); // colour, font family/size, and explicit alignment have no markdown source construct -- dropped on this hop
 ```
 
-Each takes an optional `{ signal }` — no `onSubstitution`/`sink`, since there is no font substitution or PDF-parse degradation. `odtToDocx`/`markdownToDocx`/`docxToOdt`/`docxToMarkdown` additionally take `onMathDiagnostic`, called per formula construct that degraded crossing the bridge.
+Each takes an optional `{ signal }` — no `onSubstitution`/`sink`, since there is no font substitution or PDF-parse degradation. `odtToDocx`/`markdownToDocx`/`docxToOdt`/`docxToMarkdown` additionally take `onMathDiagnostic`, called per formula construct that degraded crossing the bridge. The csv-sourced bridges (`csvToOds`, `csvToXlsx`, `csvToMarkdown`, `csvToPdf`) take `{ delimiter }` — `'\t'` parses the same format as TSV, since a delimiter is a parse option, not a different document format — and `onCellTypeInference`, the per-decision audit channel the read shares with `pdfToOds`. The csv-target bridges (`odsToCsv`, `xlsxToCsv`, `markdownToCsv`, `pdfToCsv`) take `{ delimiter, sheet }`: csv has no second sheet, so writing a multi-sheet source refuses with `CsvSheetNotSpecifiedError` naming every sheet until a caller selects one.
 
 ### The `DocumentConverter` port
 
@@ -151,18 +154,18 @@ const { document, diagnostics } = await converter.convert(
 );
 ```
 
-`DocumentFormat` includes `docx`/`pptx`/`xlsx`/`odt`/`odp`/`ods`/`odg`/`odf`/`markdown`/`pdf` — ten members. The port's `conversions` list is derived from `resolveCompositionPlan` plus the `odf`→`pdf` special case — 73 pairs total. `DocumentFormat` is inferred from `DocumentFormatSchema` (a real Zod schema); `DOCUMENT_FORMATS` is exported as a plain array derived from the same schema:
+`DocumentFormat` includes `docx`/`pptx`/`xlsx`/`odt`/`odp`/`ods`/`odg`/`odf`/`csv`/`markdown`/`pdf` — eleven members. The port's `conversions` list is derived from `resolveCompositionPlan` plus the `odf`→`pdf` special case — 91 pairs total. `DocumentFormat` is inferred from `DocumentFormatSchema` (a real Zod schema); `DOCUMENT_FORMATS` is exported as a plain array derived from the same schema:
 
 ```ts
 import { DOCUMENT_FORMATS, DocumentFormatSchema } from 'documents.js';
 
-console.log(DOCUMENT_FORMATS); // ['docx', 'pptx', 'xlsx', 'odt', 'odp', 'ods', 'odg', 'odf', 'markdown', 'pdf']
+console.log(DOCUMENT_FORMATS); // ['docx', 'pptx', 'xlsx', 'odt', 'odp', 'ods', 'odg', 'odf', 'csv', 'markdown', 'pdf']
 DocumentFormatSchema.parse(userSuppliedFormat); // throws a ZodError for anything outside that list
 ```
 
 ### 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 +173,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 +192,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';
@@ -200,7 +205,7 @@ const docxBytesAgain = buildDocumentBytes(captured, 'docx');
 
 ### Package decode/encode, metadata, and deep imports
 
-`decodeDocumentPackage`/`encodeDocumentPackage` dispatch docx/pptx/xlsx through `ooxml.js`'s OPC codec and odt/odp/ods/odg/odf through `odf.js`'s ODF codec, throwing `UnsupportedPackageFormatError` for `markdown`/`pdf`. `decodeOdbPackage` is the `.odb`-specific sibling (`.odb` is not a `DocumentFormat` member):
+`decodeDocumentPackage`/`encodeDocumentPackage` dispatch docx/pptx/xlsx through `ooxml.js`'s OPC codec and odt/odp/ods/odg/odf through `odf.js`'s ODF codec, throwing `UnsupportedPackageFormatError` for `markdown`/`csv`/`pdf` (none of the three is a package — they are plain text and bytes respectively). `decodeOdbPackage` is the `.odb`-specific sibling (`.odb` is not a `DocumentFormat` member):
 
 ```ts
 import { decodeDocumentPackage, decodeOdbPackage, encodeDocumentPackage } from 'documents.js';
@@ -210,7 +215,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. `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. `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`.
 
 ```ts
 import { readDocumentMetadata, setDocumentMetadata } from 'documents.js';
@@ -228,7 +233,7 @@ import { buildOdtPackage } from 'documents.js/edit/odt/content';
 
 ### 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 `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:
+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 `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. 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).
 
 ```ts
 import { buildXlsxPackage, decodeDocumentPackage, encodeDocumentPackage, readXlsxContent } from 'documents.js';
@@ -324,7 +329,7 @@ const layout = readPdf(pdfBytes); // -> LayoutDocument: pages of positioned text
 const bytes = writePdf(layout);
 ```
 
-The nine PDF round trips and ten PDF-bypassing bridges are also available as schema-validated [`z.codec()`](https://zod.dev) pairs (`pdfCodec`, `docxPdfCodec`, `pptxPdfCodec`, `odtPdfCodec`, `odpPdfCodec`, `odsPdfCodec`, `odgPdfCodec`, `xlsxPdfCodec`, `markdownPdfCodec`, `odtDocxCodec`, `odpPptxCodec`, `odsXlsxCodec`, `markdownDocxCodec`, `markdownOdtCodec`) — the no-options form, adding automatic two-way schema validation:
+The ten PDF round trips and fourteen PDF-bypassing bridge directions are also available as schema-validated [`z.codec()`](https://zod.dev) pairs (`pdfCodec`, `docxPdfCodec`, `pptxPdfCodec`, `odtPdfCodec`, `odpPdfCodec`, `odsPdfCodec`, `odgPdfCodec`, `xlsxPdfCodec`, `csvPdfCodec`, `markdownPdfCodec`, `odtDocxCodec`, `odpPptxCodec`, `odsXlsxCodec`, `odsCsvCodec`, `xlsxCsvCodec`, `markdownDocxCodec`, `markdownOdtCodec`) — the no-options form, adding automatic two-way schema validation. The two PDF-composed pairs have codec forms too (`xlsxMarkdownCodec`, `csvMarkdownCodec`):
 
 ```ts
 import { z } from 'zod';
@@ -502,6 +507,7 @@ The package is layered from generic primitives outward to the two conversion dir
 - **`src/ooxml/`** — thin adapters over `ooxml.js`'s own `readDocx`/`readPptx`, wrapping results into `ContentDocument`. `docx/formula.ts` is the one local reading pass (splicing OOXML math equations). `docx/extras.ts`'s `readDocxExtras` returns comments/footnotes/headers/footers/numbering.
 - **`src/odf/`** — ODF-side counterparts: `readOdtContent`/`readOdpContent`/`readOdsContent`/`readOdgContent` are thin adapters over `odf.js`. `formula/read.ts`/`formula/detect.ts` handle embedded formula detection (genuinely new work with no `odf.js`-side equivalent).
 - **`src/markdown/`** — third adapter family, via `markdown-codec`. `readMarkdownContent` passes `readMarkdown`'s result straight through (it already produces a full `ContentDocument`). `buildMarkdownText` wraps `writeMarkdown`. `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/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/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.
@@ -543,10 +549,12 @@ 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.
+- **The csv read shares `pdfToOds`'s cell-typing heuristic, with the same decision-only audit channel.** The first record is a verbatim string header (never re-typed, even when it looks like data); data cells re-type through `inferCellValue` exactly as the PDF reconstructor does — declines keep the plain string, `displayText` always carries the raw field text, and `onCellTypeInference` fires per decision, staying silent for header cells and no-candidate text. The parser drops blank records, so a record of one empty field alone cannot round-trip. Writing csv takes exactly one sheet: a multi-sheet source refuses with `CsvSheetNotSpecifiedError` naming every sheet until `{ sheet }` selects one. TSV is not a separate format — `{ delimiter: '\t' }` on either side parses or writes the same grid.
 - **`reconstructWordprocessing`/`reconstructPresentation` recover vector primitives too**, in a nested drawing document — a rule under a heading, an underline, a cell background are all recovered as vectors (intended — discarding real content because it might be incidental is ruled out). A table's gridlines are excluded from vector recovery when the lattice claims them.
 - **Recovered vectors round-trip through all four readers** — `buildDocxPackage`/`buildPptxPackage` write real DrawingML; `buildOdtPackage`/`buildOdpPackage` write real `draw:rect`/`draw:ellipse`/`draw:line`/`draw:path`. The six PDF-bypassing bridges carry vector geometry across too.
 - **Each format wraps a vector shape differently.** OOXML: pptx gets a plain `p:sp`; docx gets a `w:drawing`/`wp:anchor` with `behindDoc="1"`/`wp:wrapNone` carrying a `wps:wsp`. ODF: odp appends to `draw:page`; odt anchors in a `text:p` with `style:horizontal-rel`/`style:vertical-rel="page"` (page-absolute coordinates) and `style:run-through="background"`.
@@ -604,7 +612,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`.**
@@ -615,20 +623,21 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 
 Read as **row → column**. `✓` lossless, `~` bounded, `✗` lossy, `✗✗` severe, `→` one-way, `–` no conversion. `.odm`/`.odb` sit outside this table.
 
-| ↓ from \ to → | docx | pptx | xlsx | odt | odp | ods | odg | odf | markdown | pdf |
-| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
-| **docx** | — | ~ | – | ✓ | – | – | – | – | ✗ | ~ |
-| **pptx** | ~ | — | – | – | ✓ | – | – | – | – | ~ |
-| **xlsx** | – | – | — | – | – | ~ | – | – | ✗✗ | ~ |
-| **odt** | ✓ | – | – | — | ~ | – | – | – | ✗ | ~ |
-| **odp** | – | ✓ | – | ~ | — | – | – | – | – | ~ |
-| **ods** | – | – | ~ | – | – | — | – | – | – | ~ |
-| **odg** | – | – | – | – | – | – | — | – | – | ~ |
-| **odf** | – | – | – | – | – | – | – | — | – | → |
-| **markdown** | ~ | – | ✗✗ | ~ | – | – | – | – | — | ~ |
-| **pdf** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | – | ✗✗ | — |
-
-73 of 90 directional pairs are routable. The `ContentDocument`/`LayoutDocument` pivots are the hub, not PDF — fourteen bridges bypass PDF entirely.
+| ↓ from \ to → | docx | pptx | xlsx | odt | odp | ods | odg | odf | markdown | csv | pdf |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| **docx** | — | ~ | – | ✓ | – | – | – | – | ✗ | ✗ | ~ |
+| **pptx** | ~ | — | – | – | ✓ | – | – | – | – | ✗ | ~ |
+| **xlsx** | – | – | — | – | – | ~ | – | – | ✗✗ | ~ | ~ |
+| **odt** | ✓ | – | – | — | ~ | – | – | – | ✗ | ✗ | ~ |
+| **odp** | – | ✓ | – | ~ | — | – | – | – | – | ✗ | ~ |
+| **ods** | – | – | ~ | – | – | — | – | – | – | ~ | ~ |
+| **odg** | – | – | – | – | – | – | — | – | – | ✗ | ~ |
+| **odf** | – | – | – | – | – | – | – | — | – | – | → |
+| **markdown** | ~ | – | ✗✗ | ~ | – | – | – | – | — | ✗✗ | ~ |
+| **csv** | ✗ | ✗ | ✓ | ✗ | ✗ | ✓ | ✗ | – | ✗✗ | — | ~ |
+| **pdf** | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | ✗ | – | ✗✗ | ✗ | — |
+
+91 of 110 directional pairs are routable. The `ContentDocument`/`LayoutDocument` pivots are the hub, not PDF — eighteen 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.
 
@@ -640,9 +649,9 @@ 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).
+**`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.
 
-**The first three bridge pairs** (odt⇄docx, odp⇄pptx, ods⇄xlsx) 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 five same-variant bridge pairs** (odt⇄docx, odp⇄pptx, ods⇄xlsx, csv⇄ods, csv⇄xlsx) 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 two markdown bridge pairs** bypass PDF too, but markdown's grammar has no construct for colour/font/size/alignment — `docxToMarkdown`/`odtToMarkdown` drop them (format-boundary loss, not approximation).
 

package/dist/codecs/registry.cjs

@@ -15,6 +15,9 @@ 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_ports_abort = require("../ports/abort.cjs");
 const require_package_codec = require("../package-codec.cjs");
 let ooxml_js = require("ooxml.js");
@@ -81,6 +84,10 @@ const DOCUMENT_FORMAT_CODECS = {
 		}),
 		write: (content) => require_markdown_text.encodeMarkdownText(require_markdown_write.buildMarkdownText(content))
 	} },
+	csv: { content: {
+		read: (bytes) => require_csv_read.readCsvContent(require_csv_text.decodeCsvText(bytes)),
+		write: (content) => require_csv_text.encodeCsvText(require_csv_write.buildCsvText(content))
+	} },
 	pdf: { layout: {
 		read: (bytes, options) => (0, pdf_codec.readPdf)(requireArrayBufferBytes(bytes), { signal: options?.signal }),
 		write: (layout, options) => (0, pdf_codec.writePdf)(layout, { signal: options?.signal })

package/dist/codecs/registry.js

@@ -14,6 +14,9 @@ import { readOdpContent } from "../odf/odp/read.js";
 import { readOdsContent } from "../odf/ods/read.js";
 import { readOdgContent } from "../odf/odg/read.js";
 import { decodeMarkdownText, encodeMarkdownText } from "../markdown/text.js";
+import { decodeCsvText, encodeCsvText } from "../csv/text.js";
+import { readCsvContent } from "../csv/read.js";
+import { buildCsvText } from "../csv/write.js";
 import { throwIfAborted } from "../ports/abort.js";
 import { decodeDocumentPackage, encodeDocumentPackage } from "../package-codec.js";
 import { buildXlsxPackage, readXlsxContent } from "ooxml.js";
@@ -80,6 +83,10 @@ const DOCUMENT_FORMAT_CODECS = {
 		}),
 		write: (content) => encodeMarkdownText(buildMarkdownText(content))
 	} },
+	csv: { content: {
+		read: (bytes) => readCsvContent(decodeCsvText(bytes)),
+		write: (content) => encodeCsvText(buildCsvText(content))
+	} },
 	pdf: { layout: {
 		read: (bytes, options) => readPdf(requireArrayBufferBytes(bytes), { signal: options?.signal }),
 		write: (layout, options) => writePdf(layout, { signal: options?.signal })

package/dist/convert/capability.cjs

@@ -31,6 +31,11 @@ const FORMAT_CAPABILITIES = {
 		variant: "spreadsheet",
 		hasLayoutPath: false
 	},
+	csv: {
+		format: "csv",
+		variant: "spreadsheet",
+		hasLayoutPath: false
+	},
 	odg: {
 		format: "odg",
 		variant: "drawing",

package/dist/convert/capability.js

@@ -30,6 +30,11 @@ const FORMAT_CAPABILITIES = {
 		variant: "spreadsheet",
 		hasLayoutPath: false
 	},
+	csv: {
+		format: "csv",
+		variant: "spreadsheet",
+		hasLayoutPath: false
+	},
 	odg: {
 		format: "odg",
 		variant: "drawing",

package/dist/convert/codec.cjs

@@ -59,7 +59,25 @@ const xlsxMarkdownCodec = zod.z.codec(require_model_bytes.XlsxBytesSchema, requi
 	decode: (xlsxBytes) => require_convert_convert.xlsxToMarkdown(xlsxBytes),
 	encode: (markdownBytes) => require_convert_convert.markdownToXlsx(markdownBytes)
 });
+const csvPdfCodec = zod.z.codec(require_model_bytes.CsvBytesSchema, require_model_bytes.PdfBytesSchema, {
+	decode: (csvBytes) => require_convert_convert.csvToPdf(csvBytes),
+	encode: (pdfBytes) => require_convert_convert.pdfToCsv(pdfBytes)
+});
+const odsCsvCodec = zod.z.codec(require_model_bytes.OdsBytesSchema, require_model_bytes.CsvBytesSchema, {
+	decode: (odsBytes) => require_convert_convert.odsToCsv(odsBytes),
+	encode: (csvBytes) => require_convert_convert.csvToOds(csvBytes)
+});
+const xlsxCsvCodec = zod.z.codec(require_model_bytes.XlsxBytesSchema, require_model_bytes.CsvBytesSchema, {
+	decode: (xlsxBytes) => require_convert_convert.xlsxToCsv(xlsxBytes),
+	encode: (csvBytes) => require_convert_convert.csvToXlsx(csvBytes)
+});
+const csvMarkdownCodec = zod.z.codec(require_model_bytes.CsvBytesSchema, require_model_bytes.MarkdownBytesSchema, {
+	decode: (csvBytes) => require_convert_convert.csvToMarkdown(csvBytes),
+	encode: (markdownBytes) => require_convert_convert.markdownToCsv(markdownBytes)
+});
 //#endregion
+exports.csvMarkdownCodec = csvMarkdownCodec;
+exports.csvPdfCodec = csvPdfCodec;
 exports.docxPdfCodec = docxPdfCodec;
 exports.markdownDocxCodec = markdownDocxCodec;
 exports.markdownOdtCodec = markdownOdtCodec;
@@ -67,10 +85,12 @@ exports.markdownPdfCodec = markdownPdfCodec;
 exports.odgPdfCodec = odgPdfCodec;
 exports.odpPdfCodec = odpPdfCodec;
 exports.odpPptxCodec = odpPptxCodec;
+exports.odsCsvCodec = odsCsvCodec;
 exports.odsPdfCodec = odsPdfCodec;
 exports.odsXlsxCodec = odsXlsxCodec;
 exports.odtDocxCodec = odtDocxCodec;
 exports.odtPdfCodec = odtPdfCodec;
 exports.pptxPdfCodec = pptxPdfCodec;
+exports.xlsxCsvCodec = xlsxCsvCodec;
 exports.xlsxMarkdownCodec = xlsxMarkdownCodec;
 exports.xlsxPdfCodec = xlsxPdfCodec;

package/dist/convert/codec.d.cts

@@ -14,5 +14,9 @@ declare const odsXlsxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint
 declare const markdownDocxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
 declare const markdownOdtCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
 declare const xlsxMarkdownCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const csvPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odsCsvCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const xlsxCsvCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const csvMarkdownCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
 //#endregion
-export { docxPdfCodec, markdownDocxCodec, markdownOdtCodec, markdownPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec, xlsxMarkdownCodec, xlsxPdfCodec };
+export { csvMarkdownCodec, csvPdfCodec, docxPdfCodec, markdownDocxCodec, markdownOdtCodec, markdownPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsCsvCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec, xlsxCsvCodec, xlsxMarkdownCodec, xlsxPdfCodec };

package/dist/convert/codec.d.ts

@@ -14,5 +14,9 @@ declare const odsXlsxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint
 declare const markdownDocxCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
 declare const markdownOdtCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
 declare const xlsxMarkdownCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const csvPdfCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const odsCsvCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const xlsxCsvCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
+declare const csvMarkdownCodec: z.ZodCodec<z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>, z.ZodCustom<Uint8Array<ArrayBuffer>, Uint8Array<ArrayBuffer>>>;
 //#endregion
-export { docxPdfCodec, markdownDocxCodec, markdownOdtCodec, markdownPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec, xlsxMarkdownCodec, xlsxPdfCodec };
+export { csvMarkdownCodec, csvPdfCodec, docxPdfCodec, markdownDocxCodec, markdownOdtCodec, markdownPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsCsvCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec, xlsxCsvCodec, xlsxMarkdownCodec, xlsxPdfCodec };

package/dist/convert/codec.js

@@ -1,5 +1,5 @@
-import { DocxBytesSchema, MarkdownBytesSchema, OdgBytesSchema, OdpBytesSchema, OdsBytesSchema, OdtBytesSchema, PdfBytesSchema, PptxBytesSchema, XlsxBytesSchema } from "../model/bytes.js";
-import { docxToMarkdown, docxToOdt, docxToPdf, markdownToDocx, markdownToOdt, markdownToPdf, markdownToXlsx, odgToPdf, odpToPdf, odpToPptx, odsToPdf, odsToXlsx, odtToDocx, odtToMarkdown, odtToPdf, pdfToDocx, pdfToMarkdown, pdfToOdg, pdfToOdp, pdfToOds, pdfToOdt, pdfToPptx, pdfToXlsx, pptxToOdp, pptxToPdf, xlsxToMarkdown, xlsxToOds, xlsxToPdf } from "./convert.js";
+import { CsvBytesSchema, DocxBytesSchema, MarkdownBytesSchema, OdgBytesSchema, OdpBytesSchema, OdsBytesSchema, OdtBytesSchema, PdfBytesSchema, PptxBytesSchema, XlsxBytesSchema } from "../model/bytes.js";
+import { csvToMarkdown, csvToOds, csvToPdf, csvToXlsx, docxToMarkdown, docxToOdt, docxToPdf, markdownToCsv, markdownToDocx, markdownToOdt, markdownToPdf, markdownToXlsx, odgToPdf, odpToPdf, odpToPptx, odsToCsv, odsToPdf, odsToXlsx, odtToDocx, odtToMarkdown, odtToPdf, pdfToCsv, pdfToDocx, pdfToMarkdown, pdfToOdg, pdfToOdp, pdfToOds, pdfToOdt, pdfToPptx, pdfToXlsx, pptxToOdp, pptxToPdf, xlsxToCsv, xlsxToMarkdown, xlsxToOds, xlsxToPdf } from "./convert.js";
 import { z } from "zod";
 //#region src/convert/codec.ts
 const docxPdfCodec = z.codec(DocxBytesSchema, PdfBytesSchema, {
@@ -58,5 +58,21 @@ const xlsxMarkdownCodec = z.codec(XlsxBytesSchema, MarkdownBytesSchema, {
 	decode: (xlsxBytes) => xlsxToMarkdown(xlsxBytes),
 	encode: (markdownBytes) => markdownToXlsx(markdownBytes)
 });
+const csvPdfCodec = z.codec(CsvBytesSchema, PdfBytesSchema, {
+	decode: (csvBytes) => csvToPdf(csvBytes),
+	encode: (pdfBytes) => pdfToCsv(pdfBytes)
+});
+const odsCsvCodec = z.codec(OdsBytesSchema, CsvBytesSchema, {
+	decode: (odsBytes) => odsToCsv(odsBytes),
+	encode: (csvBytes) => csvToOds(csvBytes)
+});
+const xlsxCsvCodec = z.codec(XlsxBytesSchema, CsvBytesSchema, {
+	decode: (xlsxBytes) => xlsxToCsv(xlsxBytes),
+	encode: (csvBytes) => csvToXlsx(csvBytes)
+});
+const csvMarkdownCodec = z.codec(CsvBytesSchema, MarkdownBytesSchema, {
+	decode: (csvBytes) => csvToMarkdown(csvBytes),
+	encode: (markdownBytes) => markdownToCsv(markdownBytes)
+});
 //#endregion
-export { docxPdfCodec, markdownDocxCodec, markdownOdtCodec, markdownPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec, xlsxMarkdownCodec, xlsxPdfCodec };
+export { csvMarkdownCodec, csvPdfCodec, docxPdfCodec, markdownDocxCodec, markdownOdtCodec, markdownPdfCodec, odgPdfCodec, odpPdfCodec, odpPptxCodec, odsCsvCodec, odsPdfCodec, odsXlsxCodec, odtDocxCodec, odtPdfCodec, pptxPdfCodec, xlsxCsvCodec, xlsxMarkdownCodec, xlsxPdfCodec };

package/dist/convert/composition.cjs

@@ -16,6 +16,9 @@ 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_layout_engine = require("../layout/engine.cjs");
 const require_layout_slides = require("../layout/slides.cjs");
 const require_ports_abort = require("../ports/abort.cjs");
@@ -39,8 +42,12 @@ const CONTENT_FORMATS = [
 	"odp",
 	"ods",
 	"odg",
+	"csv",
 	"markdown"
 ];
+function isTextFormatNode(node) {
+	return !node.hasSourcePackage;
+}
 const FORMAT_NODES = {
 	docx: {
 		variant: "wordprocessing",
@@ -116,6 +123,21 @@ const FORMAT_NODES = {
 		build: (content) => require_markdown_write.buildMarkdownText(content),
 		encode: (text) => require_markdown_text.encodeMarkdownText(text),
 		hasSourcePackage: false
+	},
+	csv: {
+		variant: "spreadsheet",
+		family: "csv",
+		decode: (bytes) => require_csv_text.decodeCsvText(bytes),
+		read: (text, options) => require_csv_read.readCsvContent(text, {
+			delimiter: options?.delimiter,
+			onCellTypeInference: options?.onCellTypeInference
+		}),
+		build: (content, options) => require_csv_write.buildCsvText(content, {
+			delimiter: options?.delimiter,
+			sheet: options?.sheet
+		}),
+		encode: (text) => require_csv_text.encodeCsvText(text),
+		hasSourcePackage: false
 	}
 };
 const LAYOUT_CAPABLE = /* @__PURE__ */ new Set([
@@ -162,7 +184,7 @@ function executeBridge(source, target, bytes, options) {
 	const sourceNode = FORMAT_NODES[source];
 	const targetNode = FORMAT_NODES[target];
 	let content;
-	if (sourceNode.family === "markdown") {
+	if (isTextFormatNode(sourceNode)) {
 		const text = sourceNode.decode(bytes);
 		content = sourceNode.read(text, options);
 	} else {
@@ -182,8 +204,8 @@ function executeBridge(source, target, bytes, options) {
 		formatVersion: document_schema_js.DOCUMENT_PACKAGE_FORMAT_VERSION,
 		content: buildContent
 	});
-	if (targetNode.family === "markdown") {
-		const text = targetNode.build(buildContent);
+	if (isTextFormatNode(targetNode)) {
+		const text = targetNode.build(buildContent, options);
 		return targetNode.encode(text);
 	}
 	const pkg = targetNode.build(buildContent, options);
@@ -194,7 +216,7 @@ function executeToPdf(format, bytes, options) {
 	const node = FORMAT_NODES[format];
 	let content;
 	let fonts;
-	if (node.family === "markdown") {
+	if (isTextFormatNode(node)) {
 		require_ports_abort.throwIfAborted(options?.signal);
 		const text = node.decode(bytes);
 		const read = node.read(text, options);
@@ -230,6 +252,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 +261,7 @@ function executeToPdf(format, bytes, options) {
 				mathMetricsAt
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
@@ -247,6 +271,7 @@ function executeToPdf(format, bytes, options) {
 				mathMetricsAt
 			});
 			layout = result.document;
+			pages = result.pages;
 			formulas = result.formulas;
 			break;
 		}
@@ -257,18 +282,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,
@@ -288,14 +317,21 @@ function executeFromPdf(target, bytes, options) {
 		signal: options?.signal,
 		sink: options?.sink
 	});
-	const content = RECONSTRUCTORS[node.variant](layout, { signal: options?.signal });
+	const content = RECONSTRUCTORS[node.variant](layout, {
+		signal: options?.signal,
+		onCellTypeInference: options?.onCellTypeInference
+	});
+	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);
+	if (isTextFormatNode(node)) {
+		const text = node.build(content, options);
 		return node.encode(text);
 	}
 	const pkg = node.build(content);

package/dist/convert/composition.d.cts

@@ -1,6 +1,7 @@
 import { t as ClockPort } from "../clock-C7SUuYN0.cjs";
 import { DocumentFormat } from "./port.cjs";
 import { t as ContentVariant } from "../capability-an5gSNsu.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 { MarkdownImageResolver } from "markdown-codec";
@@ -21,9 +22,12 @@ interface UnifiedConversionOptions {
     readonly sourcePath?: string;
   }) => void;
   readonly images?: MarkdownImageResolver;
+  readonly delimiter?: string;
+  readonly sheet?: string;
+  readonly onCellTypeInference?: CellTypeInferenceSink;
   readonly clock?: ClockPort;
 }
-type ContentFormat = 'docx' | 'pptx' | 'xlsx' | 'odt' | 'odp' | 'ods' | 'odg' | 'markdown';
+type ContentFormat = 'docx' | 'pptx' | 'xlsx' | 'odt' | 'odp' | 'ods' | 'odg' | 'csv' | 'markdown';
 type LayoutVariant = Exclude<ContentVariant, 'formula'>;
 interface PackageFormatNode {
   readonly variant: LayoutVariant;
@@ -34,16 +38,16 @@ interface PackageFormatNode {
   readonly encode: (pkg: SourcePackage) => Uint8Array<ArrayBuffer>;
   readonly hasSourcePackage: true;
 }
-interface MarkdownFormatNode {
+interface TextFormatNode {
   readonly variant: LayoutVariant;
-  readonly family: 'markdown';
+  readonly family: 'markdown' | 'csv';
   readonly decode: (bytes: Uint8Array<ArrayBuffer>) => string;
   readonly read: (text: string, options?: UnifiedConversionOptions) => ContentDocument;
-  readonly build: (content: ContentDocument) => string;
+  readonly build: (content: ContentDocument, options?: UnifiedConversionOptions) => string;
   readonly encode: (text: string) => Uint8Array<ArrayBuffer>;
   readonly hasSourcePackage: false;
 }
-type FormatNode = PackageFormatNode | MarkdownFormatNode;
+type FormatNode = PackageFormatNode | TextFormatNode;
 declare const FORMAT_NODES: Readonly<Record<ContentFormat, FormatNode>>;
 type HopExecutor = 'bridge' | 'toPdf' | 'fromPdf';
 interface CompositionHop {