js.documents 10.0.0 → 12.0.0

package/README.md

@@ -805,8 +805,8 @@ The package is layered from generic primitives outward to the two conversion dir
 - **`src/ppt/`** — the one legacy-binary-format adapter with a genuine wrap of its own: `ppt-codec`'s `readPptContent`/`writePptContent` operate on the flat `{ metadata, slides }` shape (mirroring `ooxml.js`'s/`odf.js`'s own upstream flat readers), not a full `'presentation'`-kind `ContentDocument` directly, so `read.ts`/`write.ts` do the envelope wrap/unwrap `src/ooxml/pptx/read.ts`/`src/odf/odp/read.ts` also do for their own formats -- minus the formula/vector-recovery passes those two run, since `ppt-codec` has no upstream equivalent to splice in. `doc` and `xls` need no equivalent module: `doc-codec`'s `readDocContent`/`writeDocContent` and `xls-codec`'s `readXlsContent`/`writeXlsContent` already read/write a real `ContentDocument` directly (the latter over `XlsContentDocument`, a plain narrowed alias), so both are called straight from `src/codecs/read.ts`/`src/codecs/registry.ts`/`src/convert/composition.ts`, exactly like `rtf-codec`'s own pair.
 - **`src/latex/`** — the LaTeX presentation → `MathExpression` lowering: `temml.ts` is the pinned-parser boundary (exact-version temml, its internal parse API guarded behind structural type guards), `lower.ts` the mechanical rules and their degradations, `symbols.ts` the glyph/command map and the prose definition scanner, `rational.ts` the exact-rational helpers, `lint.ts` the coherence lint. See [LaTeX lowering into the semantic core](#latex-lowering-into-the-semantic-core).
 - **`src/markdown/`** — third adapter family, via `markdown-codec`. `readMarkdownContent` passes `readMarkdownContent`'s (markdown-codec's flat reader, so named since that package's 4.0.0; the bare `readMarkdown` name is now its tree-form `DocumentTree` reader) result through the math-lowering pass (`math.ts` — markdown-codec's preserved `$$` display blocks and `\( \)` inline spans become two-layer formula blocks, with the document's symbol table seeded from its own prose). `buildMarkdownText` wraps `writeMarkdownContent`, reconstructing markdown math syntax from formula blocks carrying a presentation layer. `text.ts` is the byte↔text boundary. `MarkdownEditor` holds a mutable in-memory `ContentDocument`.
-- **`src/csv/`** — fourth adapter family, sharing the spreadsheet variant with xlsx/ods. `records.ts` is the RFC 4180 record parser/writer (one shared `quoteCsvField`, also used by the `.odb` CSV exporter); `text.ts` is the byte↔text boundary, rejecting malformed UTF-8; `read.ts` turns records into a spreadsheet `ContentDocument` (first record as verbatim string header, data cells through the same cell-typing heuristic `pdfToOds` uses); `write.ts` turns one sheet of a spreadsheet `ContentDocument` back into records via each cell's `displayText`. TSV is the same format with `{ delimiter: '\t' }` on either side.
-- **`src/svg/`** — fifth adapter family, sharing the drawing variant with odg. `text.ts` is the byte↔text boundary, rejecting malformed UTF-8; `read.ts` maps the six SVG shape primitives (rect/circle/ellipse/line/polyline/polygon/path) onto a one-page drawing `ContentDocument`, with transform lists composed as 2×3 affines and CSS lengths and the viewBox map resolved into page points; `write.ts` writes the six primitives back out, one shape element each; `path.ts` is the full SVG path-data grammar (M/L/H/V/C/S/Z plus Q/T/A and the relative forms — S/Q/T convert exactly, A is the one bounded approximation at ≤90° per cubic); `transform.ts` parses and composes the transform attribute and classifies the result by frame representability; `units.ts` resolves CSS length units and the viewBox; `paint.ts` resolves fill/stroke presentation attributes and dash styles; `diagnostics.ts` is the shared scope-limit vocabulary.
+- **`src/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, working the character encoding out from the bytes through [byte-codec](../byte-codec/README.md#text-decoding) rather than assuming UTF-8, so Excel's own windows-1252 export reads, and refusing bytes that are not text at all; `read.ts` turns records into a spreadsheet `ContentDocument` (first record as verbatim string header, data cells through the same cell-typing heuristic `pdfToOds` uses); `write.ts` turns one sheet of a spreadsheet `ContentDocument` back into records via each cell's `displayText`. TSV is the same format with `{ delimiter: '\t' }` on either side.
+- **`src/svg/`** — fifth adapter family, sharing the drawing variant with odg. `text.ts` is the byte↔text boundary, still rejecting anything but UTF-8 where csv and markdown now detect the encoding, because SVG is XML and XML's own encoding declaration is authoritative ([#1359](https://github.com/ExaDev/documents.js/issues/1359)); `read.ts` maps the six SVG shape primitives (rect/circle/ellipse/line/polyline/polygon/path) onto a one-page drawing `ContentDocument`, with transform lists composed as 2×3 affines and CSS lengths and the viewBox map resolved into page points; `write.ts` writes the six primitives back out, one shape element each; `path.ts` is the full SVG path-data grammar (M/L/H/V/C/S/Z plus Q/T/A and the relative forms — S/Q/T convert exactly, A is the one bounded approximation at ≤90° per cubic); `transform.ts` parses and composes the transform attribute and classifies the result by frame representability; `units.ts` resolves CSS length units and the viewBox; `paint.ts` resolves fill/stroke presentation attributes and dash styles; `diagnostics.ts` is the shared scope-limit vocabulary.
 - **`src/layout/`** — the pure conversion algorithms: `engine.ts` (wordprocessing → layout: flow, line-breaking, pagination), `slides.ts` (presentation → layout: direct placement), `sheets.ts` (spreadsheet → layout: grid, print settings, the first algorithm accepting `AbortSignal`), `drawing.ts` (drawing → layout: vector primitives + shape reuse), `reconstruct.ts` (layout → content: baseline clustering for wordprocessing/presentation, near-1:1 mapping for drawing, gridline-lattice-or-text-clustering for spreadsheet; plus the PDF construct surfacing — link reconciliation to `ContentRun.hyperlink` or link constructs, hidden-layer content dropped, anchor/comment and AcroForm contentControl constructs, and tagged-structure semantics where the file states them: heading levels from owning `H1`..`H6` elements over the font-size census, lattice-free table recovery from `/Table`/`/TR`/`/TH`/`/TD` ownership, and `division` constructs around `/Part`/`/Sect`/`/Div` extents).
 - **`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.
@@ -925,7 +925,7 @@ To run a single test file: `pnpm vitest run src/path/to/file.test.ts`.
 - **Every markdown construct-mapping gap is a documented `MarkdownDiagnosticCodes` entry** (`md/invented-page-geometry`, `md/nested-emphasis-flattened`, `md/link-title-dropped`, `md/blockquote-container-skipped`, `md/list-item-block-unlisted`, `md/image-unresolved`, `md/raw-html-preserved-as-text`/`md/raw-html-dropped`, `md/front-matter-key-unmapped`, `md/heading-level-clamped`, `md/adjacent-links-merged`, `md/code-span-as-monospace-run`, `md/paragraph-indent-dropped`, `md/list-numid-fallback`, `md/table-cell-formatting-dropped`, `md/table-cell-multi-paragraph-joined`) — never a silent approximation. The info-string, multi-block-item, and blockquote-depth gaps that used to be in this list are closed: a fence's language word rides `ContentParagraph.codeLanguage`, item identity rides `ContentListMembership.itemId`, and a blockquote carries a `division` construct pair.
 - **`buildMarkdownText` throws for non-`'wordprocessing'` `ContentDocument`.**
 - **`buildMarkdownText` passes `constructStart`/`constructEnd` markers through to markdown-codec's own writer**, which resolves them as balanced brackets: a construct with a markdown spelling renders as that syntax (a footnote definition, a blockquote division, a titled image's link wrapper), one without renders its extent transparently under a diagnostic. A genuinely unbalanced list still throws — markdown-codec's own `MarkdownUnbalancedConstructMarkersError`, the shared definition of that check. The old `MarkdownConstructUnsupportedError` refusal is gone: markdown-codec's read side now emits marker pairs of its own (blockquotes, titled images), so a writer that refused markers would refuse this package's own editor round trips.
-- **`decodeMarkdownText` throws on malformed UTF-8** rather than producing U+FFFD.
+- **`decodeMarkdownText` detects the character encoding** rather than assuming UTF-8, so a file saved in the Windows system code page or as UTF-16 reads; it throws for bytes that are not text rather than producing U+FFFD.
 - **The composition engine routes every pair generically** through a declarative primitive registry and minimum-cost pathfinder. `resolveCompositionPlan` finds the minimum-cost route (same-variant bridge < cross-variant transform < via-PDF multi-hop). Named functions are thin forwarders.
 
 ## Fidelity

package/dist/csv/text.cjs

@@ -1,22 +1,40 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let byte_codec = require("byte-codec");
 //#region src/csv/text.ts
-var CsvInvalidUtf8Error = class extends Error {
-	constructor() {
-		super("csv text must be well-formed UTF-8");
-		this.name = "CsvInvalidUtf8Error";
+/** Thrown when csv bytes cannot be decoded as text at all: they are binary, they contradict an encoding the caller declared or a byte order mark named, or they match none of the encodings byte-codec's decodeText supports. */
+var CsvUndecodableTextError = class extends Error {
+	/** Which of those three it was, carried through from byte-codec so a caller can branch on it without unwrapping `cause`. */
+	reason;
+	constructor(cause) {
+		super(`csv bytes could not be decoded as text: ${cause.message}`, { cause });
+		this.name = "CsvUndecodableTextError";
+		this.reason = cause.reason;
 	}
 };
-function decodeCsvText(bytes) {
+/**
+* Decodes csv bytes to text, working the character encoding out from the bytes.
+* @param bytes - The csv bytes.
+* @param options - An explicit `encoding` to decode under, skipping detection. Reach for it when the bytes are in an encoding detection cannot see, a mark-less UTF-16 file holding CJK text being the case that occurs.
+* @throws CsvUndecodableTextError When the bytes are not text, or match none of the supported encodings.
+* @returns The csv text.
+*/
+function decodeCsvText(bytes, options) {
 	try {
-		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-	} catch {
-		throw new CsvInvalidUtf8Error();
+		return (0, byte_codec.decodeText)(bytes, options).text;
+	} catch (error) {
+		if (error instanceof byte_codec.UndecodableTextError) throw new CsvUndecodableTextError(error);
+		throw error;
 	}
 }
+/**
+* Encodes csv text as UTF-8 bytes.
+* @param text - The csv text.
+* @returns The UTF-8 bytes, whatever encoding the text was originally decoded from.
+*/
 function encodeCsvText(text) {
 	return new TextEncoder().encode(text);
 }
 //#endregion
-exports.CsvInvalidUtf8Error = CsvInvalidUtf8Error;
+exports.CsvUndecodableTextError = CsvUndecodableTextError;
 exports.decodeCsvText = decodeCsvText;
 exports.encodeCsvText = encodeCsvText;

package/dist/csv/text.d.cts

@@ -1,8 +1,24 @@
+import { DecodeTextOptions, UndecodableTextError } from "byte-codec";
 //#region src/csv/text.d.ts
-declare class CsvInvalidUtf8Error extends Error {
-  constructor();
+/** Thrown when csv bytes cannot be decoded as text at all: they are binary, they contradict an encoding the caller declared or a byte order mark named, or they match none of the encodings byte-codec's decodeText supports. */
+declare class CsvUndecodableTextError extends Error {
+  /** Which of those three it was, carried through from byte-codec so a caller can branch on it without unwrapping `cause`. */
+  readonly reason: UndecodableTextError["reason"];
+  constructor(cause: UndecodableTextError);
 }
-declare function decodeCsvText(bytes: Uint8Array): string;
+/**
+ * Decodes csv bytes to text, working the character encoding out from the bytes.
+ * @param bytes - The csv bytes.
+ * @param options - An explicit `encoding` to decode under, skipping detection. Reach for it when the bytes are in an encoding detection cannot see, a mark-less UTF-16 file holding CJK text being the case that occurs.
+ * @throws CsvUndecodableTextError When the bytes are not text, or match none of the supported encodings.
+ * @returns The csv text.
+ */
+declare function decodeCsvText(bytes: Uint8Array, options?: DecodeTextOptions): string;
+/**
+ * Encodes csv text as UTF-8 bytes.
+ * @param text - The csv text.
+ * @returns The UTF-8 bytes, whatever encoding the text was originally decoded from.
+ */
 declare function encodeCsvText(text: string): Uint8Array<ArrayBuffer>;
 //#endregion
-export { CsvInvalidUtf8Error, decodeCsvText, encodeCsvText };
+export { CsvUndecodableTextError, decodeCsvText, encodeCsvText };

package/dist/csv/text.d.ts

@@ -1,8 +1,24 @@
+import { DecodeTextOptions, UndecodableTextError } from "byte-codec";
 //#region src/csv/text.d.ts
-declare class CsvInvalidUtf8Error extends Error {
-  constructor();
+/** Thrown when csv bytes cannot be decoded as text at all: they are binary, they contradict an encoding the caller declared or a byte order mark named, or they match none of the encodings byte-codec's decodeText supports. */
+declare class CsvUndecodableTextError extends Error {
+  /** Which of those three it was, carried through from byte-codec so a caller can branch on it without unwrapping `cause`. */
+  readonly reason: UndecodableTextError["reason"];
+  constructor(cause: UndecodableTextError);
 }
-declare function decodeCsvText(bytes: Uint8Array): string;
+/**
+ * Decodes csv bytes to text, working the character encoding out from the bytes.
+ * @param bytes - The csv bytes.
+ * @param options - An explicit `encoding` to decode under, skipping detection. Reach for it when the bytes are in an encoding detection cannot see, a mark-less UTF-16 file holding CJK text being the case that occurs.
+ * @throws CsvUndecodableTextError When the bytes are not text, or match none of the supported encodings.
+ * @returns The csv text.
+ */
+declare function decodeCsvText(bytes: Uint8Array, options?: DecodeTextOptions): string;
+/**
+ * Encodes csv text as UTF-8 bytes.
+ * @param text - The csv text.
+ * @returns The UTF-8 bytes, whatever encoding the text was originally decoded from.
+ */
 declare function encodeCsvText(text: string): Uint8Array<ArrayBuffer>;
 //#endregion
-export { CsvInvalidUtf8Error, decodeCsvText, encodeCsvText };
+export { CsvUndecodableTextError, decodeCsvText, encodeCsvText };

package/dist/csv/text.js

@@ -1,19 +1,37 @@
+import { UndecodableTextError, decodeText } from "byte-codec";
 //#region src/csv/text.ts
-var CsvInvalidUtf8Error = class extends Error {
-	constructor() {
-		super("csv text must be well-formed UTF-8");
-		this.name = "CsvInvalidUtf8Error";
+/** Thrown when csv bytes cannot be decoded as text at all: they are binary, they contradict an encoding the caller declared or a byte order mark named, or they match none of the encodings byte-codec's decodeText supports. */
+var CsvUndecodableTextError = class extends Error {
+	/** Which of those three it was, carried through from byte-codec so a caller can branch on it without unwrapping `cause`. */
+	reason;
+	constructor(cause) {
+		super(`csv bytes could not be decoded as text: ${cause.message}`, { cause });
+		this.name = "CsvUndecodableTextError";
+		this.reason = cause.reason;
 	}
 };
-function decodeCsvText(bytes) {
+/**
+* Decodes csv bytes to text, working the character encoding out from the bytes.
+* @param bytes - The csv bytes.
+* @param options - An explicit `encoding` to decode under, skipping detection. Reach for it when the bytes are in an encoding detection cannot see, a mark-less UTF-16 file holding CJK text being the case that occurs.
+* @throws CsvUndecodableTextError When the bytes are not text, or match none of the supported encodings.
+* @returns The csv text.
+*/
+function decodeCsvText(bytes, options) {
 	try {
-		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
-	} catch {
-		throw new CsvInvalidUtf8Error();
+		return decodeText(bytes, options).text;
+	} catch (error) {
+		if (error instanceof UndecodableTextError) throw new CsvUndecodableTextError(error);
+		throw error;
 	}
 }
+/**
+* Encodes csv text as UTF-8 bytes.
+* @param text - The csv text.
+* @returns The UTF-8 bytes, whatever encoding the text was originally decoded from.
+*/
 function encodeCsvText(text) {
 	return new TextEncoder().encode(text);
 }
 //#endregion
-export { CsvInvalidUtf8Error, decodeCsvText, encodeCsvText };
+export { CsvUndecodableTextError, decodeCsvText, encodeCsvText };

package/dist/edit/docx/content.cjs

@@ -210,11 +210,10 @@ function docxRowCells(positions, positionsByRow) {
 }
 function appendTable(body, block) {
 	require_edit_table_grid.assertTableObeysGridRule(block, "buildDocxPackage");
-	const columns = block.columnWidthsPt.length;
-	if (block.rows.length === 0 || columns === 0) return;
+	if (block.rows.length === 0) throw new Error("buildDocxPackage: table has no rows, and a table with no rows cannot be written in every word-processing format (ODF requires at least one table:table-row)");
 	const table = body.appendTable({
 		rows: 0,
-		columns,
+		columns: (0, document_schema_js.tableGridColumnCount)(block),
 		columnWidthsTwips: block.columnWidthsPt.map(require_model_units.ptToTwips)
 	});
 	const positionsByRow = (0, document_schema_js.walkTableGrid)(block);

package/dist/edit/docx/content.js

@@ -11,7 +11,7 @@ import { FLOW_CONTAINER_ORIGIN, drawingOfBlock, embeddedDrawingVectors } from ".
 import { formulaOfBlock, formulaPlaceholderText } from "../../model/formula.js";
 import { NUMBERING_CONTENT_TYPE, NUMBERING_PART_PATH, NUMBERING_REL_TYPE, buildNumberingRoot, declaration } from "./numbering.js";
 import { base64ToBytes } from "ooxml.js";
-import { resolveCellFillColor, tableCellColumnSpan, tableCellRowSpan, walkTableGrid } from "document-schema.js";
+import { resolveCellFillColor, tableCellColumnSpan, tableCellRowSpan, tableGridColumnCount, walkTableGrid } from "document-schema.js";
 //#region src/edit/docx/content.ts
 var ConstructMarkerState = class {
 	nextBookmarkId = 1;
@@ -209,11 +209,10 @@ function docxRowCells(positions, positionsByRow) {
 }
 function appendTable(body, block) {
 	assertTableObeysGridRule(block, "buildDocxPackage");
-	const columns = block.columnWidthsPt.length;
-	if (block.rows.length === 0 || columns === 0) return;
+	if (block.rows.length === 0) throw new Error("buildDocxPackage: table has no rows, and a table with no rows cannot be written in every word-processing format (ODF requires at least one table:table-row)");
 	const table = body.appendTable({
 		rows: 0,
-		columns,
+		columns: tableGridColumnCount(block),
 		columnWidthsTwips: block.columnWidthsPt.map(ptToTwips)
 	});
 	const positionsByRow = walkTableGrid(block);

package/dist/edit/odp/content.cjs

@@ -52,11 +52,7 @@ function appendShape(slide, shape) {
 	if (shape.blocks.length === 1 && onlyBlock?.kind === "table") {
 		const { shape: tableFrame, table } = slide.addTable({
 			frame: shape.frame,
-			table: {
-				rows: 0,
-				columns: onlyBlock.columnWidthsPt.length,
-				columnWidthsPt: onlyBlock.columnWidthsPt
-			}
+			table: require_edit_odt_content.odtTableInit(onlyBlock, "buildOdpPackage")
 		});
 		if (shape.rotationDeg !== void 0) tableFrame.rotationDeg = shape.rotationDeg;
 		require_edit_odt_content.populateOdtTable(table, onlyBlock);

package/dist/edit/odp/content.js

@@ -2,7 +2,7 @@ import { resolveMetadataTimestamps } from "../../model/metadata.js";
 import { systemClock } from "../../ports/clock.js";
 import { drawingOfBlock, embeddedDrawingVectors } from "../../model/embedded-drawing.js";
 import { formulaOfBlock, formulaPlaceholderText } from "../../model/formula.js";
-import { populateOdtTable, populateParagraph } from "../odt/content.js";
+import { odtTableInit, populateOdtTable, populateParagraph } from "../odt/content.js";
 import { createEmptyOdpPackage } from "./scaffold.js";
 import { OdpEditor } from "./editor.js";
 import { base64ToBytes } from "odf.js";
@@ -51,11 +51,7 @@ function appendShape(slide, shape) {
 	if (shape.blocks.length === 1 && onlyBlock?.kind === "table") {
 		const { shape: tableFrame, table } = slide.addTable({
 			frame: shape.frame,
-			table: {
-				rows: 0,
-				columns: onlyBlock.columnWidthsPt.length,
-				columnWidthsPt: onlyBlock.columnWidthsPt
-			}
+			table: odtTableInit(onlyBlock, "buildOdpPackage")
 		});
 		if (shape.rotationDeg !== void 0) tableFrame.rotationDeg = shape.rotationDeg;
 		populateOdtTable(table, onlyBlock);

package/dist/edit/odp/slide.d.cts

@@ -1,7 +1,7 @@
 import { t as ImageInit } from "../../image-D1z0T9Za.cjs";
 import { t as OdpShape } from "../../shape-Kmmxib5z.cjs";
 import { s as OdgVector } from "../../vector-DDP7hgvm.cjs";
-import { o as TableInit, r as OdtTable } from "../../table-CCjF09Ho.cjs";
+import { o as TableInit, r as OdtTable } from "../../table-BT3wN3Hd.cjs";
 import { Box, ContentFormula, ContentVector } from "document-schema.js";
 import { Package, XmlElement, XmlNode } from "odf.js";
 //#region src/edit/odp/slide.d.ts

package/dist/edit/odp/slide.d.ts

@@ -1,7 +1,7 @@
 import { t as ImageInit } from "../../image-D1z0T9Za.js";
 import { t as OdpShape } from "../../shape-ZAfNsCC5.js";
 import { s as OdgVector } from "../../vector-DDP7hgvm.js";
-import { o as TableInit, r as OdtTable } from "../../table-BMYJo_-F.js";
+import { o as TableInit, r as OdtTable } from "../../table-DhTy5Re7.js";
 import { Box, ContentFormula, ContentVector } from "document-schema.js";
 import { Package, XmlElement, XmlNode } from "odf.js";
 //#region src/edit/odp/slide.d.ts

package/dist/edit/odt/content.cjs

@@ -158,14 +158,23 @@ function applyCellDecoration(target, cell) {
 	if (cell.background !== void 0) target.background = (0, document_schema_js.resolveCellFillColor)(cell.background);
 	if (cell.borders !== void 0) target.borders = cell.borders;
 }
-function appendTable(body, block) {
-	const columns = block.columnWidthsPt.length;
-	if (block.rows.length === 0 || columns === 0) return;
-	populateOdtTable(body.appendTable({
+/**
+* The arguments that create the empty `table:table` a ContentTable is written into: no rows, since populateOdtTable appends one per ContentTableRow, and as many columns as the table's grid is wide.
+*
+* The grid width is what the rows and `columnWidthsPt` together state (tableGridColumnCount), so a table whose rows carry cells but which states no column widths still gets one `table:table-column` per grid column; a column with no stated width takes an equal share of the default table width, the same as any column created without one. `columnWidthsPt` is passed through untouched, so a width the table does state is always written.
+*
+* Throws when the table has no rows: ODF requires a `table:table` to hold at least one `table:table-row`, so no faithful spelling exists, and dropping the table would lose it without a trace. `entryPoint` names the caller in the message. A table that breaks the grid rule is refused by populateOdtTable before it writes anything, and a table with no rows has no grid fault to report, so the two checks never compete.
+*/
+function odtTableInit(block, entryPoint) {
+	if (block.rows.length === 0) throw new Error(`${entryPoint}: table has no rows, and ODF requires a table:table to hold at least one table:table-row`);
+	return {
 		rows: 0,
-		columns,
+		columns: (0, document_schema_js.tableGridColumnCount)(block),
 		columnWidthsPt: block.columnWidthsPt
-	}), block);
+	};
+}
+function appendTable(body, block) {
+	populateOdtTable(body.appendTable(odtTableInit(block, "buildOdtPackage")), block);
 }
 function appendCellBlock(cell, block) {
 	if (block.kind === "paragraph") populateParagraph(cell.appendParagraph(), block, { headings: "element" });
@@ -242,5 +251,6 @@ function appendEmbeddedObject(body, block) {
 }
 //#endregion
 exports.buildOdtPackage = buildOdtPackage;
+exports.odtTableInit = odtTableInit;
 exports.populateOdtTable = populateOdtTable;
 exports.populateParagraph = populateParagraph;

package/dist/edit/odt/content.d.cts

@@ -1,6 +1,6 @@
 import { t as ClockPort } from "../../clock-C7SUuYN0.cjs";
 import { t as OdtParagraph } from "../../paragraph-CRaLSzWz.cjs";
-import { r as OdtTable } from "../../table-CCjF09Ho.cjs";
+import { o as TableInit, r as OdtTable } from "../../table-BT3wN3Hd.cjs";
 import { ContentDocument, ContentParagraph, ContentTable } from "document-schema.js";
 import { Package } from "odf.js";
 //#region src/edit/odt/content.d.ts
@@ -13,5 +13,13 @@ interface PopulateParagraphOptions {
 }
 declare function populateParagraph(paragraph: OdtParagraph, block: ContentParagraph, options: PopulateParagraphOptions): void;
 declare function populateOdtTable(table: OdtTable, block: ContentTable): void;
+/**
+ * The arguments that create the empty `table:table` a ContentTable is written into: no rows, since populateOdtTable appends one per ContentTableRow, and as many columns as the table's grid is wide.
+ *
+ * The grid width is what the rows and `columnWidthsPt` together state (tableGridColumnCount), so a table whose rows carry cells but which states no column widths still gets one `table:table-column` per grid column; a column with no stated width takes an equal share of the default table width, the same as any column created without one. `columnWidthsPt` is passed through untouched, so a width the table does state is always written.
+ *
+ * Throws when the table has no rows: ODF requires a `table:table` to hold at least one `table:table-row`, so no faithful spelling exists, and dropping the table would lose it without a trace. `entryPoint` names the caller in the message. A table that breaks the grid rule is refused by populateOdtTable before it writes anything, and a table with no rows has no grid fault to report, so the two checks never compete.
+ */
+declare function odtTableInit(block: ContentTable, entryPoint: string): TableInit;
 //#endregion
-export { BuildOdtPackageOptions, PopulateParagraphOptions, buildOdtPackage, populateOdtTable, populateParagraph };
+export { BuildOdtPackageOptions, PopulateParagraphOptions, buildOdtPackage, odtTableInit, populateOdtTable, populateParagraph };

package/dist/edit/odt/content.d.ts

@@ -1,6 +1,6 @@
 import { t as ClockPort } from "../../clock-C7SUuYN0.js";
 import { t as OdtParagraph } from "../../paragraph-D4f705GG.js";
-import { r as OdtTable } from "../../table-BMYJo_-F.js";
+import { o as TableInit, r as OdtTable } from "../../table-DhTy5Re7.js";
 import { ContentDocument, ContentParagraph, ContentTable } from "document-schema.js";
 import { Package } from "odf.js";
 //#region src/edit/odt/content.d.ts
@@ -13,5 +13,13 @@ interface PopulateParagraphOptions {
 }
 declare function populateParagraph(paragraph: OdtParagraph, block: ContentParagraph, options: PopulateParagraphOptions): void;
 declare function populateOdtTable(table: OdtTable, block: ContentTable): void;
+/**
+ * The arguments that create the empty `table:table` a ContentTable is written into: no rows, since populateOdtTable appends one per ContentTableRow, and as many columns as the table's grid is wide.
+ *
+ * The grid width is what the rows and `columnWidthsPt` together state (tableGridColumnCount), so a table whose rows carry cells but which states no column widths still gets one `table:table-column` per grid column; a column with no stated width takes an equal share of the default table width, the same as any column created without one. `columnWidthsPt` is passed through untouched, so a width the table does state is always written.
+ *
+ * Throws when the table has no rows: ODF requires a `table:table` to hold at least one `table:table-row`, so no faithful spelling exists, and dropping the table would lose it without a trace. `entryPoint` names the caller in the message. A table that breaks the grid rule is refused by populateOdtTable before it writes anything, and a table with no rows has no grid fault to report, so the two checks never compete.
+ */
+declare function odtTableInit(block: ContentTable, entryPoint: string): TableInit;
 //#endregion
-export { BuildOdtPackageOptions, PopulateParagraphOptions, buildOdtPackage, populateOdtTable, populateParagraph };
+export { BuildOdtPackageOptions, PopulateParagraphOptions, buildOdtPackage, odtTableInit, populateOdtTable, populateParagraph };

package/dist/edit/odt/content.js

@@ -6,7 +6,7 @@ import { formulaOfBlock, formulaPlaceholderText } from "../../model/formula.js";
 import { headingStyleName } from "./paragraph.js";
 import { createEmptyOdtPackage } from "./scaffold.js";
 import { OdtEditor } from "./editor.js";
-import { resolveCellFillColor, tableCellColumnSpan, tableCellRowSpan, walkTableGrid } from "document-schema.js";
+import { resolveCellFillColor, tableCellColumnSpan, tableCellRowSpan, tableGridColumnCount, walkTableGrid } from "document-schema.js";
 import { base64ToBytes } from "odf.js";
 //#region src/edit/odt/content.ts
 function buildOdtPackage(content, options) {
@@ -157,14 +157,23 @@ function applyCellDecoration(target, cell) {
 	if (cell.background !== void 0) target.background = resolveCellFillColor(cell.background);
 	if (cell.borders !== void 0) target.borders = cell.borders;
 }
-function appendTable(body, block) {
-	const columns = block.columnWidthsPt.length;
-	if (block.rows.length === 0 || columns === 0) return;
-	populateOdtTable(body.appendTable({
+/**
+* The arguments that create the empty `table:table` a ContentTable is written into: no rows, since populateOdtTable appends one per ContentTableRow, and as many columns as the table's grid is wide.
+*
+* The grid width is what the rows and `columnWidthsPt` together state (tableGridColumnCount), so a table whose rows carry cells but which states no column widths still gets one `table:table-column` per grid column; a column with no stated width takes an equal share of the default table width, the same as any column created without one. `columnWidthsPt` is passed through untouched, so a width the table does state is always written.
+*
+* Throws when the table has no rows: ODF requires a `table:table` to hold at least one `table:table-row`, so no faithful spelling exists, and dropping the table would lose it without a trace. `entryPoint` names the caller in the message. A table that breaks the grid rule is refused by populateOdtTable before it writes anything, and a table with no rows has no grid fault to report, so the two checks never compete.
+*/
+function odtTableInit(block, entryPoint) {
+	if (block.rows.length === 0) throw new Error(`${entryPoint}: table has no rows, and ODF requires a table:table to hold at least one table:table-row`);
+	return {
 		rows: 0,
-		columns,
+		columns: tableGridColumnCount(block),
 		columnWidthsPt: block.columnWidthsPt
-	}), block);
+	};
+}
+function appendTable(body, block) {
+	populateOdtTable(body.appendTable(odtTableInit(block, "buildOdtPackage")), block);
 }
 function appendCellBlock(cell, block) {
 	if (block.kind === "paragraph") populateParagraph(cell.appendParagraph(), block, { headings: "element" });
@@ -240,4 +249,4 @@ function appendEmbeddedObject(body, block) {
 	body.appendFormula(formula, block.frame);
 }
 //#endregion
-export { buildOdtPackage, populateOdtTable, populateParagraph };
+export { buildOdtPackage, odtTableInit, populateOdtTable, populateParagraph };

package/dist/edit/odt/editor.d.cts

@@ -1,7 +1,7 @@
 import { t as ClockPort } from "../../clock-C7SUuYN0.cjs";
 import { n as ParagraphInit, t as OdtParagraph } from "../../paragraph-CRaLSzWz.cjs";
 import { t as OdtList } from "../../list-C_UPIZWM.cjs";
-import { o as TableInit, r as OdtTable } from "../../table-CCjF09Ho.cjs";
+import { o as TableInit, r as OdtTable } from "../../table-BT3wN3Hd.cjs";
 import { Box, ContentControlDescriptor, ContentFormula, ContentVector, DivisionDescriptor, LayoutMetadata } from "document-schema.js";
 import { Package } from "odf.js";
 //#region src/edit/odt/editor.d.ts

package/dist/edit/odt/editor.d.ts

@@ -1,7 +1,7 @@
 import { t as ClockPort } from "../../clock-C7SUuYN0.js";
 import { n as ParagraphInit, t as OdtParagraph } from "../../paragraph-D4f705GG.js";
 import { t as OdtList } from "../../list-C2GWIe6E.js";
-import { o as TableInit, r as OdtTable } from "../../table-BMYJo_-F.js";
+import { o as TableInit, r as OdtTable } from "../../table-DhTy5Re7.js";
 import { Box, ContentControlDescriptor, ContentFormula, ContentVector, DivisionDescriptor, LayoutMetadata } from "document-schema.js";
 import { Package } from "odf.js";
 //#region src/edit/odt/editor.d.ts