doc-codec 1.1.2 → 2.1.0

package/dist/table/write.js

@@ -1,5 +1,6 @@
 import { DocFormatError, DocUnsupportedError } from "../errors.js";
 import "../text/special.js";
+import { fitsAloneOnPapxPage } from "../prop/fkp-write.js";
 import { encodeTableRowGrpprl } from "./tap-write.js";
 //#region src/table/write.ts
 /** sprmPFInTable (0x2416): a Bool8, "MUST be 1 any time the table depth is greater than zero". */
@@ -47,7 +48,64 @@ function columnBoundariesTwips(columnWidthsPt) {
 	}
 	return boundaries;
 }
-function flattenRow(cells, columnCount, boundaries, active) {
+/** A deep copy of `active` -- a fresh Map holding a fresh object per entry, never the same ActiveVerticalMerge instances. flattenTable's own per-row budget check (see its own note below) has to try flattening a row's lost-boundary split as a dry run before committing to it, and placeCell mutates `covered.remaining` on the object a Map entry already holds -- a shallow copy would let that dry run's own mutation bleed into the real, committed state for every row after it. */
+function cloneActive(active) {
+	return new Map(Array.from(active, ([column, merge]) => [column, { ...merge }]));
+}
+/** Where one logical cell lands on the row's own grid, before any lost-boundary splitting: its span in grid columns, and whether it is a vertical-merge continuation of a cell above. `active`'s own cross-row state must evolve identically wherever this runs, since recoverableBoundaries and flattenRow each walk every row with their own fresh map and have to land on the same columns for the second pass's splitting decisions to mean anything. */
+function placeCell(cell, column, active) {
+	const covered = active.get(column);
+	if (cell.blocks.length === 0 && covered !== void 0 && covered.remaining > 0) {
+		covered.remaining -= 1;
+		return {
+			span: covered.span,
+			isContinuation: true
+		};
+	}
+	const span = cell.colSpan ?? 1;
+	const rowSpan = cell.rowSpan ?? 1;
+	if (rowSpan > 1) active.set(column, {
+		span,
+		remaining: rowSpan - 1
+	});
+	return {
+		span,
+		isContinuation: false
+	};
+}
+function recoverableBoundaries(rows) {
+	const stated = /* @__PURE__ */ new Set();
+	const active = /* @__PURE__ */ new Map();
+	for (const row of rows) {
+		let column = 0;
+		for (const cell of row.cells) {
+			const { span } = placeCell(cell, column, active);
+			column += span;
+			stated.add(column);
+		}
+	}
+	return stated;
+}
+function distributeLostBoundaries(lostBoundaries, rowCount) {
+	const perRow = Array.from({ length: rowCount }, () => /* @__PURE__ */ new Set());
+	lostBoundaries.forEach((boundary, index) => {
+		const bucket = perRow[index % rowCount];
+		if (bucket === void 0) throw new DocFormatError("internal defect: distributeLostBoundaries built fewer row buckets than the row count it was given");
+		bucket.add(boundary);
+	});
+	return perRow;
+}
+function splitAtLostBoundaries(column, span, lostBoundaries) {
+	const subSpans = [];
+	let start = column;
+	for (let position = column + 1; position < column + span; position += 1) if (lostBoundaries.has(position)) {
+		subSpans.push(position - start);
+		start = position;
+	}
+	subSpans.push(column + span - start);
+	return subSpans;
+}
+function flattenRow(cells, columnCount, boundaries, active, lostBoundaries) {
 	const paragraphs = [];
 	const cellsToWrite = [];
 	const firstBoundary = boundaries[0];
@@ -55,36 +113,31 @@ function flattenRow(cells, columnCount, boundaries, active) {
 	const rowBoundariesTwips = [firstBoundary];
 	let column = 0;
 	for (const cell of cells) {
-		const covered = active.get(column);
-		const isContinuation = cell.blocks.length === 0 && covered !== void 0 && covered.remaining > 0;
-		let span;
-		let vertMerge;
-		let blocks;
-		if (isContinuation) {
-			covered.remaining -= 1;
-			span = covered.span;
-			vertMerge = 1;
-			blocks = [];
-		} else {
-			span = cell.colSpan ?? 1;
-			const rowSpan = cell.rowSpan ?? 1;
-			vertMerge = rowSpan > 1 ? 3 : 0;
-			if (rowSpan > 1) active.set(column, {
-				span,
-				remaining: rowSpan - 1
+		const startColumn = column;
+		const { span, isContinuation } = placeCell(cell, startColumn, active);
+		const rowSpan = cell.rowSpan ?? 1;
+		const vertMerge = isContinuation ? 1 : rowSpan > 1 ? 3 : 0;
+		const blocks = isContinuation ? [] : cell.blocks;
+		const subSpans = splitAtLostBoundaries(startColumn, span, lostBoundaries);
+		subSpans.forEach((subSpan, subIndex) => {
+			paragraphs.push(...cellParagraphs(subIndex === 0 ? blocks : []));
+			cellsToWrite.push(subIndex === 0 ? isContinuation ? {
+				vertMerge,
+				horzMerge: subSpans.length > 1 ? 2 : 0
+			} : {
+				vertMerge,
+				horzMerge: subSpans.length > 1 ? 2 : 0,
+				borders: cell.borders,
+				background: cell.background
+			} : {
+				vertMerge,
+				horzMerge: 1
 			});
-			blocks = cell.blocks;
-		}
-		paragraphs.push(...cellParagraphs(blocks));
-		cellsToWrite.push(isContinuation ? { vertMerge } : {
-			vertMerge,
-			borders: cell.borders,
-			background: cell.background
+			column += subSpan;
+			const rightBoundary = boundaries[column];
+			if (rightBoundary === void 0) throw new DocFormatError(`a table cell's own colSpan runs past the table's ${columnCount}-column grid`);
+			rowBoundariesTwips.push(rightBoundary);
 		});
-		column += span;
-		const rightBoundary = boundaries[column];
-		if (rightBoundary === void 0) throw new DocFormatError(`a table cell's own colSpan runs past the table's ${columnCount}-column grid`);
-		rowBoundariesTwips.push(rightBoundary);
 	}
 	if (column !== columnCount) throw new DocFormatError(`a table row's own cells cover ${column} columns (via colSpan), but the table declares ${columnCount} in columnWidthsPt`);
 	return {
@@ -93,27 +146,51 @@ function flattenRow(cells, columnCount, boundaries, active) {
 		rowBoundariesTwips
 	};
 }
-function flattenTable(table) {
+function rowMarkParagraph(rowBoundariesTwips, cellsToWrite, heightPt) {
+	return {
+		runs: [],
+		properties: {},
+		extraGrpprl: rowMarkExtraGrpprl(rowBoundariesTwips, cellsToWrite, heightPt),
+		terminator: 7
+	};
+}
+function rowSplitFits(row, columnCount, boundaries, active, candidateBoundaries, heightPt) {
+	const trial = flattenRow(row.cells, columnCount, boundaries, cloneActive(active), candidateBoundaries);
+	if (trial.cellsToWrite.length > 63) return false;
+	const trialGrpprl = rowMarkExtraGrpprl(trial.rowBoundariesTwips, trial.cellsToWrite, heightPt);
+	return fitsAloneOnPapxPage(trialGrpprl);
+}
+function flattenTable(table, blockIndex, onWarning) {
 	const columnCount = table.columnWidthsPt.length;
 	if (columnCount === 0 || table.rows.length === 0) throw new DocFormatError("a table must have at least one column and one row to write");
 	const boundaries = columnBoundariesTwips(table.columnWidthsPt);
+	const stated = recoverableBoundaries(table.rows);
+	const lostBoundaries = [];
+	for (let index = 1; index < columnCount; index += 1) if (!stated.has(index)) lostBoundaries.push(index);
+	const lostBoundariesByRow = distributeLostBoundaries(lostBoundaries, table.rows.length);
 	const active = /* @__PURE__ */ new Map();
 	const output = [];
-	for (const row of table.rows) {
-		const { paragraphs, cellsToWrite, rowBoundariesTwips } = flattenRow(row.cells, columnCount, boundaries, active);
+	table.rows.forEach((row, rowIndex) => {
+		const rowLostBoundaries = lostBoundariesByRow[rowIndex];
+		if (rowLostBoundaries === void 0) throw new DocFormatError("internal defect: distributeLostBoundaries returned fewer buckets than the table has rows");
+		let rowLostBoundariesToApply = rowLostBoundaries;
+		if (rowLostBoundaries.size > 0 && !rowSplitFits(row, columnCount, boundaries, active, rowLostBoundaries, row.heightPt)) {
+			const ordered = Array.from(rowLostBoundaries);
+			let kept = ordered;
+			while (kept.length > 0 && !rowSplitFits(row, columnCount, boundaries, active, new Set(kept), row.heightPt)) kept = kept.slice(0, -1);
+			rowLostBoundariesToApply = new Set(kept);
+			const droppedCount = ordered.length - kept.length;
+			onWarning?.(kept.length === 0 ? `doc-codec: table at block ${blockIndex}, row ${rowIndex} could not state ${rowLostBoundaries.size === 1 ? "its assigned lost column boundary" : `any of its ${rowLostBoundaries.size} assigned lost column boundaries`} without exceeding a PapxInFkp record's own byte budget or the format's own 63-cell-per-row ceiling; attempting to write it unsplit instead, which narrows columnWidthsPt on read for this table exactly as this writer's own pre-#992 behaviour did -- if this row's own unsplit encoding also overflows this same budget, writeDocContent can still throw its usual DocFormatError further down this same pipeline, after any remaining rows have reported their own warnings` : `doc-codec: table at block ${blockIndex}, row ${rowIndex} could only state ${kept.length} of its ${ordered.length} assigned lost column boundaries without exceeding a PapxInFkp record's own byte budget or the format's own 63-cell-per-row ceiling; dropping the other ${droppedCount} (narrowing columnWidthsPt on read for those boundaries alone)`);
+		}
+		const { paragraphs, cellsToWrite, rowBoundariesTwips } = flattenRow(row.cells, columnCount, boundaries, active, rowLostBoundariesToApply);
 		output.push(...paragraphs);
-		output.push({
-			runs: [],
-			properties: {},
-			extraGrpprl: rowMarkExtraGrpprl(rowBoundariesTwips, cellsToWrite, row.heightPt),
-			terminator: 7
-		});
-	}
+		output.push(rowMarkParagraph(rowBoundariesTwips, cellsToWrite, row.heightPt));
+	});
 	return output;
 }
-function flattenSectionBlocks(blocks) {
+function flattenSectionBlocks(blocks, onWarning) {
 	const output = [];
-	for (const block of blocks) {
+	blocks.forEach((block, blockIndex) => {
 		if (block.kind === "paragraph") {
 			output.push({
 				runs: block.runs,
@@ -121,14 +198,14 @@ function flattenSectionBlocks(blocks) {
 				extraGrpprl: [],
 				terminator: 13
 			});
-			continue;
+			return;
 		}
 		if (block.kind === "table") {
-			output.push(...flattenTable(block));
-			continue;
+			output.push(...flattenTable(block, blockIndex, onWarning));
+			return;
 		}
 		throw new DocUnsupportedError(`doc-codec's writer does not yet support '${block.kind}' blocks (see README's scope note)`);
-	}
+	});
 	return output;
 }
 //#endregion

package/dist/write-C_vJizAM.d.cts

@@ -0,0 +1,15 @@
+import { ContentBlock, ContentParagraph, ContentRun } from "document-schema.js";
+//#region src/table/write.d.ts
+/** Reports a non-fatal write-time degradation -- this package's own analogue of byte-codec's/pdf-codec's `onWarning`, adopted here rather than a new shape of its own so a caller already handling one already handles the other. */
+type WriteWarning = (message: string) => void;
+interface WriteParagraph {
+  readonly runs: readonly ContentRun[];
+  readonly properties: Pick<ContentParagraph, "alignment" | "indentLeftPt" | "indentFirstLinePt" | "spacingBeforePt" | "spacingAfterPt" | "lineSpacing" | "pageBreakBefore">;
+  /** Extra grpprl bytes appended after encodeParagraphGrpprl's own output -- sprmPFInTable on every table paragraph, plus sprmPFTtp and the row's own TAP on a row's trailing mark. */
+  readonly extraGrpprl: readonly number[];
+  /** The character terminating this paragraph in the text stream: PARAGRAPH_MARK normally, CELL_MARK for a table cell or row mark. */
+  readonly terminator: number;
+}
+declare function flattenSectionBlocks(blocks: readonly ContentBlock[], onWarning?: WriteWarning): WriteParagraph[];
+//#endregion
+export { WriteWarning as n, flattenSectionBlocks as r, WriteParagraph as t };

package/dist/write-C_vJizAM.d.ts

@@ -0,0 +1,15 @@
+import { ContentBlock, ContentParagraph, ContentRun } from "document-schema.js";
+//#region src/table/write.d.ts
+/** Reports a non-fatal write-time degradation -- this package's own analogue of byte-codec's/pdf-codec's `onWarning`, adopted here rather than a new shape of its own so a caller already handling one already handles the other. */
+type WriteWarning = (message: string) => void;
+interface WriteParagraph {
+  readonly runs: readonly ContentRun[];
+  readonly properties: Pick<ContentParagraph, "alignment" | "indentLeftPt" | "indentFirstLinePt" | "spacingBeforePt" | "spacingAfterPt" | "lineSpacing" | "pageBreakBefore">;
+  /** Extra grpprl bytes appended after encodeParagraphGrpprl's own output -- sprmPFInTable on every table paragraph, plus sprmPFTtp and the row's own TAP on a row's trailing mark. */
+  readonly extraGrpprl: readonly number[];
+  /** The character terminating this paragraph in the text stream: PARAGRAPH_MARK normally, CELL_MARK for a table cell or row mark. */
+  readonly terminator: number;
+}
+declare function flattenSectionBlocks(blocks: readonly ContentBlock[], onWarning?: WriteWarning): WriteParagraph[];
+//#endregion
+export { WriteWarning as n, flattenSectionBlocks as r, WriteParagraph as t };

package/dist/write.cjs

@@ -19,12 +19,12 @@ let archive_codec = require("archive-codec");
 const TEXT_FC = 1024;
 /** This writer only ever emits 16-bit (uncompressed) text -- see text/piece-table-write.ts. */
 const BYTES_PER_CHARACTER = 2;
-function writeDocContent(document) {
+function writeDocContent(document, options = {}) {
 	if (document.kind !== "wordprocessing") throw new require_errors.DocUnsupportedError(`doc-codec writes wordprocessing documents only; got a '${document.kind}' document`);
 	if (document.sections.length !== 1) throw new require_errors.DocUnsupportedError(`doc-codec's reader never distinguishes more than one section within a document (see README's "Section properties" scope note): writeDocContent refuses ${document.sections.length} sections rather than silently merging their content into what would read back as one`);
 	const [section] = document.sections;
 	if (section === void 0) throw new require_errors.DocFormatError("a wordprocessing document must carry a section");
-	const writeParagraphs = require_table_write.flattenSectionBlocks(section.blocks);
+	const writeParagraphs = require_table_write.flattenSectionBlocks(section.blocks, options.onWarning);
 	if (writeParagraphs[writeParagraphs.length - 1]?.terminator !== 13) writeParagraphs.push({
 		runs: [],
 		properties: {},

package/dist/write.d.cts

@@ -1,5 +1,10 @@
+import { n as WriteWarning } from "./write-C_vJizAM.cjs";
 import { ContentDocument } from "document-schema.js";
 //#region src/write.d.ts
-declare function writeDocContent(document: ContentDocument): Uint8Array<ArrayBuffer>;
+interface WriteDocContentOptions {
+  /** Reports a non-fatal write-time degradation -- today, only table/write.ts's own per-row lost-boundary-budget fallback (ExaDev/documents.js#1013), the same `onWarning` shape byte-codec's PNG decoder and pdf-codec already use for a recoverable, non-fatal defect. Not a guarantee the write itself goes on to succeed: when a row's own assigned lost boundaries can't be trimmed down to a split that fits at all, this still fires once -- reporting that the row's boundaries could not be stated and that its fully-unsplit encoding is being attempted instead -- before writeDocContent can discover, further down the same pipeline, that even that unsplit encoding overflows the row's own byte budget and throws its usual DocFormatError; the warning describes what this fallback could not recover, not a promise that a hard failure won't immediately follow it. It is never called in place of a genuine refusal this writer makes outright (an unsupported block kind, more than one section, and so on) -- those always throw DocFormatError/DocUnsupportedError directly, with no warning first. */
+  readonly onWarning?: WriteWarning;
+}
+declare function writeDocContent(document: ContentDocument, options?: WriteDocContentOptions): Uint8Array<ArrayBuffer>;
 //#endregion
-export { writeDocContent };
+export { WriteDocContentOptions, writeDocContent };

package/dist/write.d.ts

@@ -1,5 +1,10 @@
+import { n as WriteWarning } from "./write-C_vJizAM.js";
 import { ContentDocument } from "document-schema.js";
 //#region src/write.d.ts
-declare function writeDocContent(document: ContentDocument): Uint8Array<ArrayBuffer>;
+interface WriteDocContentOptions {
+  /** Reports a non-fatal write-time degradation -- today, only table/write.ts's own per-row lost-boundary-budget fallback (ExaDev/documents.js#1013), the same `onWarning` shape byte-codec's PNG decoder and pdf-codec already use for a recoverable, non-fatal defect. Not a guarantee the write itself goes on to succeed: when a row's own assigned lost boundaries can't be trimmed down to a split that fits at all, this still fires once -- reporting that the row's boundaries could not be stated and that its fully-unsplit encoding is being attempted instead -- before writeDocContent can discover, further down the same pipeline, that even that unsplit encoding overflows the row's own byte budget and throws its usual DocFormatError; the warning describes what this fallback could not recover, not a promise that a hard failure won't immediately follow it. It is never called in place of a genuine refusal this writer makes outright (an unsupported block kind, more than one section, and so on) -- those always throw DocFormatError/DocUnsupportedError directly, with no warning first. */
+  readonly onWarning?: WriteWarning;
+}
+declare function writeDocContent(document: ContentDocument, options?: WriteDocContentOptions): Uint8Array<ArrayBuffer>;
 //#endregion
-export { writeDocContent };
+export { WriteDocContentOptions, writeDocContent };

package/dist/write.js

@@ -18,12 +18,12 @@ import { hasSummaryInformationFields, writeCompoundFile, writeSummaryInformation
 const TEXT_FC = 1024;
 /** This writer only ever emits 16-bit (uncompressed) text -- see text/piece-table-write.ts. */
 const BYTES_PER_CHARACTER = 2;
-function writeDocContent(document) {
+function writeDocContent(document, options = {}) {
 	if (document.kind !== "wordprocessing") throw new DocUnsupportedError(`doc-codec writes wordprocessing documents only; got a '${document.kind}' document`);
 	if (document.sections.length !== 1) throw new DocUnsupportedError(`doc-codec's reader never distinguishes more than one section within a document (see README's "Section properties" scope note): writeDocContent refuses ${document.sections.length} sections rather than silently merging their content into what would read back as one`);
 	const [section] = document.sections;
 	if (section === void 0) throw new DocFormatError("a wordprocessing document must carry a section");
-	const writeParagraphs = flattenSectionBlocks(section.blocks);
+	const writeParagraphs = flattenSectionBlocks(section.blocks, options.onWarning);
 	if (writeParagraphs[writeParagraphs.length - 1]?.terminator !== 13) writeParagraphs.push({
 		runs: [],
 		properties: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doc-codec",
-  "version": "1.1.2",
+  "version": "2.1.0",
   "description": "A hand-written reader for the Word Binary File Format ([MS-DOC], .doc) against the shared document-schema.js content pivot: FIB parsing, piece-table text reconstruction, and CHPX/PAPX formatting exceptions.",
   "type": "module",
   "repository": {
@@ -58,6 +58,8 @@
     "test": "turbo run _test",
     "_test": "vitest run --project unit",
     "_test:coverage": "vitest run --project unit --coverage",
+    "test:mutation": "turbo run _test:mutation",
+    "_test:mutation": "stryker run stryker.config.mjs",
     "test:watch": "vitest --project unit",
     "test:workers": "turbo run _test:workers",
     "_test:workers": "vitest run --config vitest.workers.config.ts",
@@ -76,15 +78,19 @@
   "license": "MIT",
   "packageManager": "pnpm@11.6.0",
   "dependencies": {
-    "archive-codec": "^1.4.2",
-    "document-schema.js": "^5.6.0"
+    "archive-codec": "^1.5.0",
+    "document-schema.js": "^6.1.0"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.5",
     "@cloudflare/vitest-pool-workers": "^0.20.1",
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/typescript-checker": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
     "@types/node": "^26.1.2",
     "eslint": "^10.8.0",
     "husky": "^9.1.7",
+    "jiti": "2.7.0",
     "publint": "^0.3.21",
     "tsdown": "^0.22.13",
     "turbo": "^2.10.8",