doc-codec 1.0.2 → 1.1.1

package/dist/table/read.cjs

@@ -0,0 +1,192 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+require("../text/special.cjs");
+const require_table_tap = require("./tap.cjs");
+//#region src/table/read.ts
+const TWIPS_PER_POINT = 20;
+function isSameColumnBoundary(left, right, toleranceTwips) {
+	return Math.abs(left - right) <= toleranceTwips;
+}
+function effectiveColumnBoundaryTolerance(definitions) {
+	let narrowestRealGapTwips;
+	for (const definition of definitions) {
+		const boundaries = definition.columnBoundariesTwips;
+		for (let index = 1; index < boundaries.length; index += 1) {
+			const left = boundaries[index - 1];
+			const right = boundaries[index];
+			if (left === void 0 || right === void 0) continue;
+			const gap = right - left;
+			if (gap > 0 && (narrowestRealGapTwips === void 0 || gap < narrowestRealGapTwips)) narrowestRealGapTwips = gap;
+		}
+	}
+	return narrowestRealGapTwips === void 0 ? TWIPS_PER_POINT : Math.min(TWIPS_PER_POINT, narrowestRealGapTwips - 1);
+}
+function assembleBlocks(entries) {
+	const blocks = [];
+	let index = 0;
+	while (index < entries.length) {
+		const entry = entries[index];
+		if (entry === void 0) break;
+		if (entry.properties.inTable !== true) {
+			blocks.push(entry.paragraph);
+			index += 1;
+			continue;
+		}
+		const { runEntries, nextIndex } = collectTableRun(entries, index);
+		const table = tryAssembleTable(runEntries);
+		blocks.push(...table !== void 0 ? [table] : runEntries.map((run) => run.paragraph));
+		index = nextIndex;
+	}
+	return blocks;
+}
+function collectTableRun(entries, start) {
+	const runEntries = [];
+	let index = start;
+	while (index < entries.length) {
+		const entry = entries[index];
+		if (entry?.properties.inTable !== true) break;
+		if (entry.properties.tableDepth !== void 0 && entry.properties.tableDepth > 1 || entry.properties.nestedTableMark === true) throw new require_errors.DocUnsupportedError("doc-codec does not support a table nested inside a table cell (table depth greater than 1)");
+		runEntries.push(entry);
+		index += 1;
+	}
+	return {
+		runEntries,
+		nextIndex: index
+	};
+}
+function tryAssembleTable(runEntries) {
+	const rawRows = [];
+	const rowDefinitions = [];
+	const rowHeights = [];
+	let cellParagraphs = [];
+	let rowCells = [];
+	for (const entry of runEntries) {
+		cellParagraphs.push(entry.paragraph);
+		if (entry.properties.tableRowEnd === true) {
+			const rowProperties = require_table_tap.applyTableSprms(entry.grpprl, {});
+			const definition = rowProperties.definition;
+			if (definition === void 0) return void 0;
+			if (rowCells.length !== definition.cells.length) return void 0;
+			rawRows.push(rowCells.map((cell, cellIndex) => {
+				const merge = definition.cells[cellIndex];
+				if (merge === void 0) throw new require_errors.DocFormatError(`internal defect: table row cell ${cellIndex} has no TAP merge entry despite the length check above`);
+				return {
+					horzMerge: merge.horzMerge,
+					vertMerge: merge.vertMerge,
+					borders: merge.borders,
+					background: merge.background,
+					blocks: cell.blocks
+				};
+			}));
+			rowDefinitions.push(definition);
+			rowHeights.push(rowProperties.heightPt);
+			rowCells = [];
+			cellParagraphs = [];
+			continue;
+		}
+		if (entry.terminator === 7) {
+			rowCells.push({ blocks: cellParagraphs });
+			cellParagraphs = [];
+		}
+	}
+	if (cellParagraphs.length > 0 || rowCells.length > 0) throw new require_errors.DocFormatError("a table's paragraphs end without a row-ending mark to close the row's last cell");
+	const toleranceTwips = effectiveColumnBoundaryTolerance(rowDefinitions);
+	const columnBoundariesTwips = canonicalColumnBoundariesTwips(rowDefinitions, toleranceTwips);
+	return {
+		kind: "table",
+		rows: buildRows(rawRows, rowDefinitions, columnBoundariesTwips, rowHeights, toleranceTwips),
+		columnWidthsPt: columnWidthsFromBoundaries(columnBoundariesTwips)
+	};
+}
+function canonicalColumnBoundariesTwips(definitions, toleranceTwips) {
+	const sorted = definitions.flatMap((definition) => definition.columnBoundariesTwips).sort((left, right) => left - right);
+	const canonical = [];
+	for (const boundary of sorted) {
+		const representative = canonical[canonical.length - 1];
+		if (representative === void 0 || !isSameColumnBoundary(representative, boundary, toleranceTwips)) canonical.push(boundary);
+	}
+	return canonical;
+}
+function gridIndexFor(canonicalBoundariesTwips, boundary, toleranceTwips) {
+	const index = canonicalBoundariesTwips.findIndex((candidate) => isSameColumnBoundary(candidate, boundary, toleranceTwips));
+	if (index === -1) throw new require_errors.DocFormatError(`internal defect: a table row's column boundary ${String(boundary)} matches no boundary on the table's own reconstructed grid, which was built from that boundary among others`);
+	return index;
+}
+function columnWidthsFromBoundaries(boundaries) {
+	const widths = [];
+	for (let index = 0; index < boundaries.length - 1; index += 1) {
+		const left = boundaries[index];
+		const right = boundaries[index + 1];
+		if (left === void 0 || right === void 0) continue;
+		widths.push((right - left) / TWIPS_PER_POINT);
+	}
+	return widths;
+}
+function logicalCellsForRow(cells, rowBoundariesTwips, canonicalBoundariesTwips, toleranceTwips) {
+	const logical = [];
+	let physicalIndex = 0;
+	while (physicalIndex < cells.length) {
+		const cell = cells[physicalIndex];
+		if (cell === void 0) break;
+		if (cell.horzMerge === 1) {
+			physicalIndex += 1;
+			continue;
+		}
+		let consumed = 1;
+		while (cells[physicalIndex + consumed]?.horzMerge === 1) consumed += 1;
+		const left = rowBoundariesTwips[physicalIndex];
+		const right = rowBoundariesTwips[physicalIndex + consumed];
+		if (left === void 0 || right === void 0) throw new require_errors.DocFormatError("a table row's own column-boundary array has fewer entries than its physical cell count requires");
+		const startGridIndex = gridIndexFor(canonicalBoundariesTwips, left, toleranceTwips);
+		const endGridIndex = gridIndexFor(canonicalBoundariesTwips, right, toleranceTwips);
+		logical.push({
+			startGridIndex,
+			colSpan: endGridIndex > startGridIndex ? endGridIndex - startGridIndex : 1,
+			vertMerge: cell.vertMerge,
+			borders: cell.borders,
+			background: cell.background,
+			blocks: cell.blocks
+		});
+		physicalIndex += consumed;
+	}
+	return logical;
+}
+function buildRows(rawRows, rowDefinitions, canonicalBoundariesTwips, rowHeights, toleranceTwips) {
+	const logicalRows = rawRows.map((row, rowIndex) => {
+		const definition = rowDefinitions[rowIndex];
+		if (definition === void 0) throw new require_errors.DocFormatError(`internal defect: table row ${rowIndex} has no TAP definition despite the earlier length check`);
+		return logicalCellsForRow(row, definition.columnBoundariesTwips, canonicalBoundariesTwips, toleranceTwips);
+	});
+	return logicalRows.map((row, rowIndex) => {
+		const cells = [];
+		for (const cell of row) {
+			const colSpan = cell.colSpan > 1 ? cell.colSpan : void 0;
+			if (cell.vertMerge === 1) {
+				cells.push({
+					blocks: [],
+					colSpan
+				});
+				continue;
+			}
+			let rowSpan = 1;
+			for (let r = rowIndex + 1; r < logicalRows.length; r += 1) {
+				if ((logicalRows[r]?.find((candidate) => candidate.startGridIndex === cell.startGridIndex))?.vertMerge !== 1) break;
+				rowSpan += 1;
+			}
+			cells.push({
+				blocks: cell.blocks,
+				colSpan,
+				rowSpan: rowSpan > 1 ? rowSpan : void 0,
+				background: cell.background,
+				borders: cell.borders
+			});
+		}
+		const heightPt = rowHeights[rowIndex];
+		return heightPt !== void 0 ? {
+			cells,
+			heightPt
+		} : { cells };
+	});
+}
+//#endregion
+exports.assembleBlocks = assembleBlocks;

package/dist/table/read.d.cts

@@ -0,0 +1,6 @@
+import { ParagraphEntry } from "../read.cjs";
+import { ContentBlock } from "document-schema.js";
+//#region src/table/read.d.ts
+declare function assembleBlocks(entries: readonly ParagraphEntry[]): ContentBlock[];
+//#endregion
+export { assembleBlocks };

package/dist/table/read.d.ts

@@ -0,0 +1,6 @@
+import { ParagraphEntry } from "../read.js";
+import { ContentBlock } from "document-schema.js";
+//#region src/table/read.d.ts
+declare function assembleBlocks(entries: readonly ParagraphEntry[]): ContentBlock[];
+//#endregion
+export { assembleBlocks };

package/dist/table/read.js

@@ -0,0 +1,191 @@
+import { DocFormatError, DocUnsupportedError } from "../errors.js";
+import "../text/special.js";
+import { applyTableSprms } from "./tap.js";
+//#region src/table/read.ts
+const TWIPS_PER_POINT = 20;
+function isSameColumnBoundary(left, right, toleranceTwips) {
+	return Math.abs(left - right) <= toleranceTwips;
+}
+function effectiveColumnBoundaryTolerance(definitions) {
+	let narrowestRealGapTwips;
+	for (const definition of definitions) {
+		const boundaries = definition.columnBoundariesTwips;
+		for (let index = 1; index < boundaries.length; index += 1) {
+			const left = boundaries[index - 1];
+			const right = boundaries[index];
+			if (left === void 0 || right === void 0) continue;
+			const gap = right - left;
+			if (gap > 0 && (narrowestRealGapTwips === void 0 || gap < narrowestRealGapTwips)) narrowestRealGapTwips = gap;
+		}
+	}
+	return narrowestRealGapTwips === void 0 ? TWIPS_PER_POINT : Math.min(TWIPS_PER_POINT, narrowestRealGapTwips - 1);
+}
+function assembleBlocks(entries) {
+	const blocks = [];
+	let index = 0;
+	while (index < entries.length) {
+		const entry = entries[index];
+		if (entry === void 0) break;
+		if (entry.properties.inTable !== true) {
+			blocks.push(entry.paragraph);
+			index += 1;
+			continue;
+		}
+		const { runEntries, nextIndex } = collectTableRun(entries, index);
+		const table = tryAssembleTable(runEntries);
+		blocks.push(...table !== void 0 ? [table] : runEntries.map((run) => run.paragraph));
+		index = nextIndex;
+	}
+	return blocks;
+}
+function collectTableRun(entries, start) {
+	const runEntries = [];
+	let index = start;
+	while (index < entries.length) {
+		const entry = entries[index];
+		if (entry?.properties.inTable !== true) break;
+		if (entry.properties.tableDepth !== void 0 && entry.properties.tableDepth > 1 || entry.properties.nestedTableMark === true) throw new DocUnsupportedError("doc-codec does not support a table nested inside a table cell (table depth greater than 1)");
+		runEntries.push(entry);
+		index += 1;
+	}
+	return {
+		runEntries,
+		nextIndex: index
+	};
+}
+function tryAssembleTable(runEntries) {
+	const rawRows = [];
+	const rowDefinitions = [];
+	const rowHeights = [];
+	let cellParagraphs = [];
+	let rowCells = [];
+	for (const entry of runEntries) {
+		cellParagraphs.push(entry.paragraph);
+		if (entry.properties.tableRowEnd === true) {
+			const rowProperties = applyTableSprms(entry.grpprl, {});
+			const definition = rowProperties.definition;
+			if (definition === void 0) return void 0;
+			if (rowCells.length !== definition.cells.length) return void 0;
+			rawRows.push(rowCells.map((cell, cellIndex) => {
+				const merge = definition.cells[cellIndex];
+				if (merge === void 0) throw new DocFormatError(`internal defect: table row cell ${cellIndex} has no TAP merge entry despite the length check above`);
+				return {
+					horzMerge: merge.horzMerge,
+					vertMerge: merge.vertMerge,
+					borders: merge.borders,
+					background: merge.background,
+					blocks: cell.blocks
+				};
+			}));
+			rowDefinitions.push(definition);
+			rowHeights.push(rowProperties.heightPt);
+			rowCells = [];
+			cellParagraphs = [];
+			continue;
+		}
+		if (entry.terminator === 7) {
+			rowCells.push({ blocks: cellParagraphs });
+			cellParagraphs = [];
+		}
+	}
+	if (cellParagraphs.length > 0 || rowCells.length > 0) throw new DocFormatError("a table's paragraphs end without a row-ending mark to close the row's last cell");
+	const toleranceTwips = effectiveColumnBoundaryTolerance(rowDefinitions);
+	const columnBoundariesTwips = canonicalColumnBoundariesTwips(rowDefinitions, toleranceTwips);
+	return {
+		kind: "table",
+		rows: buildRows(rawRows, rowDefinitions, columnBoundariesTwips, rowHeights, toleranceTwips),
+		columnWidthsPt: columnWidthsFromBoundaries(columnBoundariesTwips)
+	};
+}
+function canonicalColumnBoundariesTwips(definitions, toleranceTwips) {
+	const sorted = definitions.flatMap((definition) => definition.columnBoundariesTwips).sort((left, right) => left - right);
+	const canonical = [];
+	for (const boundary of sorted) {
+		const representative = canonical[canonical.length - 1];
+		if (representative === void 0 || !isSameColumnBoundary(representative, boundary, toleranceTwips)) canonical.push(boundary);
+	}
+	return canonical;
+}
+function gridIndexFor(canonicalBoundariesTwips, boundary, toleranceTwips) {
+	const index = canonicalBoundariesTwips.findIndex((candidate) => isSameColumnBoundary(candidate, boundary, toleranceTwips));
+	if (index === -1) throw new DocFormatError(`internal defect: a table row's column boundary ${String(boundary)} matches no boundary on the table's own reconstructed grid, which was built from that boundary among others`);
+	return index;
+}
+function columnWidthsFromBoundaries(boundaries) {
+	const widths = [];
+	for (let index = 0; index < boundaries.length - 1; index += 1) {
+		const left = boundaries[index];
+		const right = boundaries[index + 1];
+		if (left === void 0 || right === void 0) continue;
+		widths.push((right - left) / TWIPS_PER_POINT);
+	}
+	return widths;
+}
+function logicalCellsForRow(cells, rowBoundariesTwips, canonicalBoundariesTwips, toleranceTwips) {
+	const logical = [];
+	let physicalIndex = 0;
+	while (physicalIndex < cells.length) {
+		const cell = cells[physicalIndex];
+		if (cell === void 0) break;
+		if (cell.horzMerge === 1) {
+			physicalIndex += 1;
+			continue;
+		}
+		let consumed = 1;
+		while (cells[physicalIndex + consumed]?.horzMerge === 1) consumed += 1;
+		const left = rowBoundariesTwips[physicalIndex];
+		const right = rowBoundariesTwips[physicalIndex + consumed];
+		if (left === void 0 || right === void 0) throw new DocFormatError("a table row's own column-boundary array has fewer entries than its physical cell count requires");
+		const startGridIndex = gridIndexFor(canonicalBoundariesTwips, left, toleranceTwips);
+		const endGridIndex = gridIndexFor(canonicalBoundariesTwips, right, toleranceTwips);
+		logical.push({
+			startGridIndex,
+			colSpan: endGridIndex > startGridIndex ? endGridIndex - startGridIndex : 1,
+			vertMerge: cell.vertMerge,
+			borders: cell.borders,
+			background: cell.background,
+			blocks: cell.blocks
+		});
+		physicalIndex += consumed;
+	}
+	return logical;
+}
+function buildRows(rawRows, rowDefinitions, canonicalBoundariesTwips, rowHeights, toleranceTwips) {
+	const logicalRows = rawRows.map((row, rowIndex) => {
+		const definition = rowDefinitions[rowIndex];
+		if (definition === void 0) throw new DocFormatError(`internal defect: table row ${rowIndex} has no TAP definition despite the earlier length check`);
+		return logicalCellsForRow(row, definition.columnBoundariesTwips, canonicalBoundariesTwips, toleranceTwips);
+	});
+	return logicalRows.map((row, rowIndex) => {
+		const cells = [];
+		for (const cell of row) {
+			const colSpan = cell.colSpan > 1 ? cell.colSpan : void 0;
+			if (cell.vertMerge === 1) {
+				cells.push({
+					blocks: [],
+					colSpan
+				});
+				continue;
+			}
+			let rowSpan = 1;
+			for (let r = rowIndex + 1; r < logicalRows.length; r += 1) {
+				if ((logicalRows[r]?.find((candidate) => candidate.startGridIndex === cell.startGridIndex))?.vertMerge !== 1) break;
+				rowSpan += 1;
+			}
+			cells.push({
+				blocks: cell.blocks,
+				colSpan,
+				rowSpan: rowSpan > 1 ? rowSpan : void 0,
+				background: cell.background,
+				borders: cell.borders
+			});
+		}
+		const heightPt = rowHeights[rowIndex];
+		return heightPt !== void 0 ? {
+			cells,
+			heightPt
+		} : { cells };
+	});
+}
+//#endregion
+export { assembleBlocks };

package/dist/table/tap-write.cjs

@@ -0,0 +1,125 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_errors = require("../errors.cjs");
+const require_table_decoration = require("./decoration.cjs");
+//#region src/table/tap-write.ts
+/** sprmTDefTable, [MS-DOC] 2.6.3 (0xD608). */
+const SPRM_T_DEF_TABLE = 54792;
+/** sprmTDyaRowHeight (0x9407). */
+const SPRM_T_DYA_ROW_HEIGHT = 37895;
+/** sprmTDefTableShd (0xD612): a DefTableShdOperand ([MS-DOC] 2.9.53) shading cells 1-22 of the row, then sprmTDefTableShd2nd (0xD616) for 23-44 and sprmTDefTableShd3rd (0xD60C) for 45-63. Three sprms rather than one because a DefTableShdOperand's own cb is a single byte and its rgShd "MUST NOT exceed 22 elements", which is exactly why [MS-DOC] splits a row's shading across three opcodes at all. */
+const SPRM_T_DEF_TABLE_SHD = 54802;
+const SPRM_T_DEF_TABLE_SHD_2ND = 54806;
+const SPRM_T_DEF_TABLE_SHD_3RD = 54796;
+/** sprmTSetBrc (0xD62F): a TableBrcOperand ([MS-DOC] 2.9.305) restating one cell's borders on the named sides with an exact COLORREF. */
+const SPRM_T_SET_BRC = 54831;
+/** The three DefTableShdOperand sprms in cell order, each with the cell index its own rgShd starts at -- [MS-DOC] 2.6.3's own "Cells 1 - 22 ... cells 23 - 44 ... cells 45 - 63", one-based there and zero-based here. */
+const SHD_ARRAYS = [
+	{
+		opcode: SPRM_T_DEF_TABLE_SHD,
+		first: 0
+	},
+	{
+		opcode: SPRM_T_DEF_TABLE_SHD_2ND,
+		first: 22
+	},
+	{
+		opcode: SPRM_T_DEF_TABLE_SHD_3RD,
+		first: 44
+	}
+];
+/** A DefTableShdOperand's own rgShd bound, [MS-DOC] 2.9.53: "The number of elements is equal to cb / 10 and MUST NOT exceed 22." */
+const MAX_SHD_PER_ARRAY = 22;
+const TWIPS_PER_POINT = 20;
+/** A table row has "between 1 and 63 table cells" ([MS-DOC] 2.4.3), and TDefTableOperand.NumberOfColumns is itself a single byte "MUST NOT exceed 63". */
+const MAX_COLUMNS = 63;
+/** sprmPDyaBefore/After's unsigned 2-byte operand range, reused here for XAS column boundaries (also an unsigned 2-byte field in practice for the non-negative widths this writer produces). */
+const MIN_INT16 = -32768;
+const MAX_INT16 = 32767;
+/** TableBrcOperand.cb, [MS-DOC] 2.9.305: "This value MUST be 11" -- the ItcFirstLim (2), bordersToApply (1) and Brc (8) that follow it. */
+const TABLE_BRC_OPERAND_CB = 11;
+function int16(value, what) {
+	const rounded = Math.round(value);
+	if (rounded < MIN_INT16 || rounded > MAX_INT16) throw new require_errors.DocFormatError(`${what} is ${rounded}, outside the ${MIN_INT16}..${MAX_INT16} range a signed 2-byte sprm operand can hold`);
+	const unsigned = rounded < 0 ? rounded + 65536 : rounded;
+	return [unsigned & 255, unsigned >> 8 & 255];
+}
+function le16(value) {
+	return [value & 255, value >> 8 & 255];
+}
+function buildTc80(cell) {
+	return [
+		...le16((cell.vertMerge & 3) << 5),
+		0,
+		0,
+		...require_table_decoration.CELL_BORDER_SIDES.flatMap((side) => require_table_decoration.writeBrc80(cell.borders?.[side]))
+	];
+}
+/** Groups a cell's sides by the border they carry, so four identical sides become one TableBrcOperand rather than four -- bordersToApply is a bitmask of "any subset" of the edges precisely so a producer can state them together, and the row mark's grpprl has a 510-byte ceiling to stay under. Only sides whose colour the Brc80 palette cannot state exactly are grouped at all; every other side is already exact in TC80 itself. */
+function exactColorBorderGroups(borders) {
+	const groups = [];
+	for (const side of require_table_decoration.CELL_BORDER_SIDES) {
+		const border = borders?.[side];
+		if (border === void 0 || !require_table_decoration.borderNeedsExactColor(border)) continue;
+		const existing = groups.find((group) => sameBorder(group.border, border));
+		if (existing === void 0) {
+			groups.push({
+				bordersToApply: require_table_decoration.BORDERS_TO_APPLY[side],
+				border
+			});
+			continue;
+		}
+		existing.bordersToApply |= require_table_decoration.BORDERS_TO_APPLY[side];
+	}
+	return groups;
+}
+function sameBorder(left, right) {
+	return left.widthPt === right.widthPt && (left.style ?? "solid") === (right.style ?? "solid") && left.color.r === right.color.r && left.color.g === right.color.g && left.color.b === right.color.b;
+}
+/** One cell's sprmTSetBrc Prls: an ItcFirstLim naming that cell alone, the sides sharing one border, and that border's exact Brc. */
+function setBrcPrls(cell, index) {
+	const bytes = [];
+	for (const group of exactColorBorderGroups(cell.borders)) bytes.push(...le16(SPRM_T_SET_BRC), TABLE_BRC_OPERAND_CB, index, index + 1, group.bordersToApply, ...require_table_decoration.writeBrc(group.border));
+	return bytes;
+}
+/** The row's shading Prls: one DefTableShdOperand per 22-cell window that contains at least one shaded cell. A window with none is omitted entirely rather than written as an array of ShdAuto entries, since "no cells are shaded" is already the row's default -- so an undecorated table's row mark is byte-identical to what it was before shading was written at all. */
+function shadingPrls(cells) {
+	const bytes = [];
+	for (const { opcode, first } of SHD_ARRAYS) {
+		const window = cells.slice(first, first + MAX_SHD_PER_ARRAY);
+		if (window.length === 0) continue;
+		let lastShaded = -1;
+		window.forEach((cell, index) => {
+			if (cell.background !== void 0) lastShaded = index;
+		});
+		if (lastShaded === -1) continue;
+		const shd = window.slice(0, lastShaded + 1).flatMap((cell) => require_table_decoration.writeShd(cell.background));
+		bytes.push(...le16(opcode), shd.length, ...shd);
+	}
+	return bytes;
+}
+function encodeTableRowGrpprl(columnBoundariesTwips, cells, heightPt) {
+	if (columnBoundariesTwips.length !== cells.length + 1) throw new require_errors.DocFormatError(`a table row's column-boundary array must carry exactly one more entry than its cell count (got ${columnBoundariesTwips.length} boundaries for ${cells.length} cells)`);
+	if (cells.length < 1 || cells.length > MAX_COLUMNS) throw new require_errors.DocFormatError(`a table row must have between 1 and ${MAX_COLUMNS} cells, got ${cells.length}`);
+	const remainder = [
+		cells.length,
+		...columnBoundariesTwips.flatMap((boundary) => int16(boundary, "table column boundary")),
+		...cells.flatMap(buildTc80)
+	];
+	const cb = remainder.length + 1;
+	const bytes = [
+		...le16(SPRM_T_DEF_TABLE),
+		...le16(cb),
+		...remainder
+	];
+	bytes.push(...shadingPrls(cells));
+	cells.forEach((cell, index) => {
+		bytes.push(...setBrcPrls(cell, index));
+	});
+	if (heightPt !== void 0) {
+		const dyaRowHeight = Math.round(heightPt * TWIPS_PER_POINT);
+		bytes.push(...le16(SPRM_T_DYA_ROW_HEIGHT), ...int16(dyaRowHeight, "table row heightPt"));
+	}
+	return bytes;
+}
+//#endregion
+exports.encodeTableRowGrpprl = encodeTableRowGrpprl;

package/dist/table/tap-write.d.cts

@@ -0,0 +1,13 @@
+import { Color, ContentCellBorders } from "document-schema.js";
+//#region src/table/tap-write.d.ts
+interface TableCellToWrite {
+  /** VerticalMergeFlag: 0 fvmClear, 1 fvmMerge (continuation), 3 fvmRestart (first cell). */
+  readonly vertMerge: 0 | 1 | 3;
+  /** The cell's own four borders, from ContentTableCell.borders; an absent side is written as the Brc80MayBeNil no-border sentinel. */
+  readonly borders?: ContentCellBorders;
+  /** The cell's own flat background, from ContentTableCell.background. */
+  readonly background?: Color;
+}
+declare function encodeTableRowGrpprl(columnBoundariesTwips: readonly number[], cells: readonly TableCellToWrite[], heightPt: number | undefined): number[];
+//#endregion
+export { TableCellToWrite, encodeTableRowGrpprl };

package/dist/table/tap-write.d.ts

@@ -0,0 +1,13 @@
+import { Color, ContentCellBorders } from "document-schema.js";
+//#region src/table/tap-write.d.ts
+interface TableCellToWrite {
+  /** VerticalMergeFlag: 0 fvmClear, 1 fvmMerge (continuation), 3 fvmRestart (first cell). */
+  readonly vertMerge: 0 | 1 | 3;
+  /** The cell's own four borders, from ContentTableCell.borders; an absent side is written as the Brc80MayBeNil no-border sentinel. */
+  readonly borders?: ContentCellBorders;
+  /** The cell's own flat background, from ContentTableCell.background. */
+  readonly background?: Color;
+}
+declare function encodeTableRowGrpprl(columnBoundariesTwips: readonly number[], cells: readonly TableCellToWrite[], heightPt: number | undefined): number[];
+//#endregion
+export { TableCellToWrite, encodeTableRowGrpprl };

package/dist/table/tap-write.js

@@ -0,0 +1,124 @@
+import { DocFormatError } from "../errors.js";
+import { BORDERS_TO_APPLY, CELL_BORDER_SIDES, borderNeedsExactColor, writeBrc, writeBrc80, writeShd } from "./decoration.js";
+//#region src/table/tap-write.ts
+/** sprmTDefTable, [MS-DOC] 2.6.3 (0xD608). */
+const SPRM_T_DEF_TABLE = 54792;
+/** sprmTDyaRowHeight (0x9407). */
+const SPRM_T_DYA_ROW_HEIGHT = 37895;
+/** sprmTDefTableShd (0xD612): a DefTableShdOperand ([MS-DOC] 2.9.53) shading cells 1-22 of the row, then sprmTDefTableShd2nd (0xD616) for 23-44 and sprmTDefTableShd3rd (0xD60C) for 45-63. Three sprms rather than one because a DefTableShdOperand's own cb is a single byte and its rgShd "MUST NOT exceed 22 elements", which is exactly why [MS-DOC] splits a row's shading across three opcodes at all. */
+const SPRM_T_DEF_TABLE_SHD = 54802;
+const SPRM_T_DEF_TABLE_SHD_2ND = 54806;
+const SPRM_T_DEF_TABLE_SHD_3RD = 54796;
+/** sprmTSetBrc (0xD62F): a TableBrcOperand ([MS-DOC] 2.9.305) restating one cell's borders on the named sides with an exact COLORREF. */
+const SPRM_T_SET_BRC = 54831;
+/** The three DefTableShdOperand sprms in cell order, each with the cell index its own rgShd starts at -- [MS-DOC] 2.6.3's own "Cells 1 - 22 ... cells 23 - 44 ... cells 45 - 63", one-based there and zero-based here. */
+const SHD_ARRAYS = [
+	{
+		opcode: SPRM_T_DEF_TABLE_SHD,
+		first: 0
+	},
+	{
+		opcode: SPRM_T_DEF_TABLE_SHD_2ND,
+		first: 22
+	},
+	{
+		opcode: SPRM_T_DEF_TABLE_SHD_3RD,
+		first: 44
+	}
+];
+/** A DefTableShdOperand's own rgShd bound, [MS-DOC] 2.9.53: "The number of elements is equal to cb / 10 and MUST NOT exceed 22." */
+const MAX_SHD_PER_ARRAY = 22;
+const TWIPS_PER_POINT = 20;
+/** A table row has "between 1 and 63 table cells" ([MS-DOC] 2.4.3), and TDefTableOperand.NumberOfColumns is itself a single byte "MUST NOT exceed 63". */
+const MAX_COLUMNS = 63;
+/** sprmPDyaBefore/After's unsigned 2-byte operand range, reused here for XAS column boundaries (also an unsigned 2-byte field in practice for the non-negative widths this writer produces). */
+const MIN_INT16 = -32768;
+const MAX_INT16 = 32767;
+/** TableBrcOperand.cb, [MS-DOC] 2.9.305: "This value MUST be 11" -- the ItcFirstLim (2), bordersToApply (1) and Brc (8) that follow it. */
+const TABLE_BRC_OPERAND_CB = 11;
+function int16(value, what) {
+	const rounded = Math.round(value);
+	if (rounded < MIN_INT16 || rounded > MAX_INT16) throw new DocFormatError(`${what} is ${rounded}, outside the ${MIN_INT16}..${MAX_INT16} range a signed 2-byte sprm operand can hold`);
+	const unsigned = rounded < 0 ? rounded + 65536 : rounded;
+	return [unsigned & 255, unsigned >> 8 & 255];
+}
+function le16(value) {
+	return [value & 255, value >> 8 & 255];
+}
+function buildTc80(cell) {
+	return [
+		...le16((cell.vertMerge & 3) << 5),
+		0,
+		0,
+		...CELL_BORDER_SIDES.flatMap((side) => writeBrc80(cell.borders?.[side]))
+	];
+}
+/** Groups a cell's sides by the border they carry, so four identical sides become one TableBrcOperand rather than four -- bordersToApply is a bitmask of "any subset" of the edges precisely so a producer can state them together, and the row mark's grpprl has a 510-byte ceiling to stay under. Only sides whose colour the Brc80 palette cannot state exactly are grouped at all; every other side is already exact in TC80 itself. */
+function exactColorBorderGroups(borders) {
+	const groups = [];
+	for (const side of CELL_BORDER_SIDES) {
+		const border = borders?.[side];
+		if (border === void 0 || !borderNeedsExactColor(border)) continue;
+		const existing = groups.find((group) => sameBorder(group.border, border));
+		if (existing === void 0) {
+			groups.push({
+				bordersToApply: BORDERS_TO_APPLY[side],
+				border
+			});
+			continue;
+		}
+		existing.bordersToApply |= BORDERS_TO_APPLY[side];
+	}
+	return groups;
+}
+function sameBorder(left, right) {
+	return left.widthPt === right.widthPt && (left.style ?? "solid") === (right.style ?? "solid") && left.color.r === right.color.r && left.color.g === right.color.g && left.color.b === right.color.b;
+}
+/** One cell's sprmTSetBrc Prls: an ItcFirstLim naming that cell alone, the sides sharing one border, and that border's exact Brc. */
+function setBrcPrls(cell, index) {
+	const bytes = [];
+	for (const group of exactColorBorderGroups(cell.borders)) bytes.push(...le16(SPRM_T_SET_BRC), TABLE_BRC_OPERAND_CB, index, index + 1, group.bordersToApply, ...writeBrc(group.border));
+	return bytes;
+}
+/** The row's shading Prls: one DefTableShdOperand per 22-cell window that contains at least one shaded cell. A window with none is omitted entirely rather than written as an array of ShdAuto entries, since "no cells are shaded" is already the row's default -- so an undecorated table's row mark is byte-identical to what it was before shading was written at all. */
+function shadingPrls(cells) {
+	const bytes = [];
+	for (const { opcode, first } of SHD_ARRAYS) {
+		const window = cells.slice(first, first + MAX_SHD_PER_ARRAY);
+		if (window.length === 0) continue;
+		let lastShaded = -1;
+		window.forEach((cell, index) => {
+			if (cell.background !== void 0) lastShaded = index;
+		});
+		if (lastShaded === -1) continue;
+		const shd = window.slice(0, lastShaded + 1).flatMap((cell) => writeShd(cell.background));
+		bytes.push(...le16(opcode), shd.length, ...shd);
+	}
+	return bytes;
+}
+function encodeTableRowGrpprl(columnBoundariesTwips, cells, heightPt) {
+	if (columnBoundariesTwips.length !== cells.length + 1) throw new DocFormatError(`a table row's column-boundary array must carry exactly one more entry than its cell count (got ${columnBoundariesTwips.length} boundaries for ${cells.length} cells)`);
+	if (cells.length < 1 || cells.length > MAX_COLUMNS) throw new DocFormatError(`a table row must have between 1 and ${MAX_COLUMNS} cells, got ${cells.length}`);
+	const remainder = [
+		cells.length,
+		...columnBoundariesTwips.flatMap((boundary) => int16(boundary, "table column boundary")),
+		...cells.flatMap(buildTc80)
+	];
+	const cb = remainder.length + 1;
+	const bytes = [
+		...le16(SPRM_T_DEF_TABLE),
+		...le16(cb),
+		...remainder
+	];
+	bytes.push(...shadingPrls(cells));
+	cells.forEach((cell, index) => {
+		bytes.push(...setBrcPrls(cell, index));
+	});
+	if (heightPt !== void 0) {
+		const dyaRowHeight = Math.round(heightPt * TWIPS_PER_POINT);
+		bytes.push(...le16(SPRM_T_DYA_ROW_HEIGHT), ...int16(dyaRowHeight, "table row heightPt"));
+	}
+	return bytes;
+}
+//#endregion
+export { encodeTableRowGrpprl };