@beyondwork/docx-react-component 1.0.0

package/test/formats/xlsx/model/workbook.test.ts

@@ -0,0 +1,669 @@
+/**
+ * Tests for the canonical workbook model.
+ *
+ * Covers:
+ * - workbook creation and metadata
+ * - sheet registry (add, remove, rename, move, get by name)
+ * - sparse cell storage (set, get, delete, extent)
+ * - all cell value kinds (blank, text, number, boolean, error, formula)
+ * - shared string table
+ * - merge range operations
+ * - style references
+ */
+
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+  makeBlankCell,
+  makeBooleanCell,
+  makeErrorCell,
+  makeFormulaCell,
+  makeNumberCell,
+  makeTextCell,
+  cellKey,
+  parseCellKey,
+} from "../../../../src/formats/xlsx/model/cell.ts";
+import type { CellValue } from "../../../../src/formats/xlsx/model/cell.ts";
+
+import {
+  addMerge,
+  createSheet,
+  findMergesContaining,
+  getCell,
+  getSheetExtent,
+  iterateCellAddresses,
+  removeMerge,
+  setCell,
+} from "../../../../src/formats/xlsx/model/sheet.ts";
+
+import {
+  createEmptyStyleRegistry,
+  getXfRecord,
+  isDateFormatHeuristic,
+} from "../../../../src/formats/xlsx/model/styles.ts";
+import type { XfRecord } from "../../../../src/formats/xlsx/model/styles.ts";
+
+import {
+  WORKBOOK_SCHEMA_VERSION,
+  addSheet,
+  appendSharedString,
+  createWorkbook,
+  getSheet,
+  getSheetByName,
+  listSheets,
+  moveSheet,
+  removeSheet,
+  renameSheet,
+  resolveSharedString,
+  workbookToJson,
+  workbookFromJson,
+} from "../../../../src/formats/xlsx/model/workbook.ts";
+
+// ---------------------------------------------------------------------------
+// Proof bundle accumulator
+// ---------------------------------------------------------------------------
+
+const PROOF_DIR = ".tmp/wave-25-xlsx-proof";
+const PROOF_PATH = `${PROOF_DIR}/model-tests.json`;
+
+interface TestResult {
+  id: string;
+  description: string;
+  passed: boolean;
+  detail?: string;
+}
+
+const results: TestResult[] = [];
+
+function record(id: string, description: string, passed: boolean, detail?: string): void {
+  results.push({ id, description, passed, detail });
+}
+
+// ---------------------------------------------------------------------------
+// Cell value helpers
+// ---------------------------------------------------------------------------
+
+test("cell.ts: cellKey and parseCellKey are inverses", () => {
+  const key = cellKey(3, 7);
+  assert.equal(key, "3:7");
+  const addr = parseCellKey(key);
+  assert.deepEqual(addr, { row: 3, col: 7 });
+  record("cell-key-roundtrip", "cellKey / parseCellKey roundtrip", true);
+});
+
+test("cell.ts: parseCellKey throws on invalid input", () => {
+  assert.throws(() => parseCellKey("invalid"), /Invalid cell key/);
+  record("cell-key-invalid", "parseCellKey throws on bad input", true);
+});
+
+test("cell.ts: makeBlankCell produces correct kind", () => {
+  const cell = makeBlankCell();
+  assert.equal(cell.kind, "blank");
+  assert.equal(cell.styleRef, undefined);
+  record("blank-cell", "makeBlankCell produces blank kind", true);
+});
+
+test("cell.ts: makeBlankCell with styleRef", () => {
+  const cell = makeBlankCell({ xfIndex: 2 });
+  assert.equal(cell.kind, "blank");
+  assert.deepEqual(cell.styleRef, { xfIndex: 2 });
+  record("blank-cell-style", "makeBlankCell with styleRef", true);
+});
+
+test("cell.ts: makeTextCell produces correct value", () => {
+  const cell = makeTextCell("Hello", false);
+  assert.equal(cell.kind, "text");
+  assert.equal(cell.value, "Hello");
+  assert.equal(cell.fromSharedString, false);
+  record("text-cell", "makeTextCell produces text kind", true);
+});
+
+test("cell.ts: makeTextCell with fromSharedString flag", () => {
+  const cell = makeTextCell("World", true, { xfIndex: 1 });
+  assert.equal(cell.fromSharedString, true);
+  assert.deepEqual(cell.styleRef, { xfIndex: 1 });
+  record("text-cell-shared", "makeTextCell fromSharedString flag", true);
+});
+
+test("cell.ts: makeNumberCell produces correct value", () => {
+  const cell = makeNumberCell(42.5);
+  assert.equal(cell.kind, "number");
+  assert.equal(cell.value, 42.5);
+  record("number-cell", "makeNumberCell value", true);
+});
+
+test("cell.ts: makeBooleanCell produces correct value", () => {
+  const t = makeBooleanCell(true);
+  const f = makeBooleanCell(false);
+  assert.equal(t.kind, "boolean");
+  assert.equal(t.value, true);
+  assert.equal(f.value, false);
+  record("boolean-cell", "makeBooleanCell true/false", true);
+});
+
+test("cell.ts: makeErrorCell produces correct error code", () => {
+  const cell = makeErrorCell("#DIV/0!");
+  assert.equal(cell.kind, "error");
+  assert.equal(cell.errorCode, "#DIV/0!");
+  record("error-cell", "makeErrorCell error code", true);
+});
+
+test("cell.ts: makeFormulaCell with cached value", () => {
+  const cell = makeFormulaCell("SUM(A1:A10)", { type: "number", value: 123 });
+  assert.equal(cell.kind, "formula");
+  assert.equal(cell.formula, "SUM(A1:A10)");
+  assert.deepEqual(cell.cachedValue, { type: "number", value: 123 });
+  record("formula-cell-cached", "makeFormulaCell with cached value", true);
+});
+
+test("cell.ts: makeFormulaCell without cached value", () => {
+  const cell = makeFormulaCell("A1+B1");
+  assert.equal(cell.cachedValue, undefined);
+  record("formula-cell-no-cache", "makeFormulaCell without cached value", true);
+});
+
+// ---------------------------------------------------------------------------
+// Sheet operations
+// ---------------------------------------------------------------------------
+
+test("sheet.ts: createSheet creates empty sheet", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  assert.equal(sheet.sheetId, "s1");
+  assert.equal(sheet.name, "Sheet1");
+  assert.equal(sheet.orderIndex, 0);
+  assert.equal(sheet.hidden, false);
+  assert.equal(sheet.cells.size, 0);
+  assert.equal(sheet.rowProps.size, 0);
+  assert.equal(sheet.colProps.size, 0);
+  assert.deepEqual(sheet.merges, []);
+  record("sheet-create", "createSheet produces empty sheet", true);
+});
+
+test("sheet.ts: setCell and getCell round-trip", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  const cell = makeNumberCell(99);
+  setCell(sheet, 0, 0, cell);
+  const retrieved = getCell(sheet, 0, 0);
+  assert.deepEqual(retrieved, cell);
+  record("cell-set-get", "setCell / getCell round-trip", true);
+});
+
+test("sheet.ts: getCell returns undefined for absent cell", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  assert.equal(getCell(sheet, 5, 5), undefined);
+  record("cell-get-absent", "getCell returns undefined for absent cell", true);
+});
+
+test("sheet.ts: setCell with undefined removes cell", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  setCell(sheet, 2, 3, makeTextCell("x", false));
+  setCell(sheet, 2, 3, undefined);
+  assert.equal(getCell(sheet, 2, 3), undefined);
+  assert.equal(sheet.cells.size, 0);
+  record("cell-delete", "setCell with undefined removes cell", true);
+});
+
+test("sheet.ts: getSheetExtent returns null for empty sheet", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  assert.equal(getSheetExtent(sheet), null);
+  record("extent-empty", "getSheetExtent null for empty sheet", true);
+});
+
+test("sheet.ts: getSheetExtent computes correct bounds", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  setCell(sheet, 0, 0, makeTextCell("A1", false));
+  setCell(sheet, 3, 5, makeTextCell("F4", false));
+  setCell(sheet, 1, 2, makeNumberCell(7));
+  const extent = getSheetExtent(sheet);
+  assert.deepEqual(extent, { minRow: 0, maxRow: 3, minCol: 0, maxCol: 5 });
+  record("extent-bounds", "getSheetExtent computes correct bounds", true);
+});
+
+test("sheet.ts: iterateCellAddresses yields all occupied cells", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  setCell(sheet, 0, 0, makeTextCell("a", false));
+  setCell(sheet, 1, 1, makeNumberCell(1));
+  setCell(sheet, 2, 2, makeBooleanCell(true));
+  const addresses = [...iterateCellAddresses(sheet)];
+  assert.equal(addresses.length, 3);
+  record("iterate-addresses", "iterateCellAddresses yields correct count", true);
+});
+
+// ---------------------------------------------------------------------------
+// Merge operations
+// ---------------------------------------------------------------------------
+
+test("sheet.ts: addMerge stores a merge range", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  addMerge(sheet, { startRow: 0, startCol: 0, endRow: 2, endCol: 3 });
+  assert.equal(sheet.merges.length, 1);
+  assert.deepEqual(sheet.merges[0], { startRow: 0, startCol: 0, endRow: 2, endCol: 3 });
+  record("merge-add", "addMerge stores merge range", true);
+});
+
+test("sheet.ts: removeMerge removes exact range", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  const merge = { startRow: 1, startCol: 1, endRow: 3, endCol: 3 };
+  addMerge(sheet, merge);
+  addMerge(sheet, { startRow: 5, startCol: 0, endRow: 6, endCol: 1 });
+  const removed = removeMerge(sheet, merge);
+  assert.equal(removed, true);
+  assert.equal(sheet.merges.length, 1);
+  record("merge-remove", "removeMerge removes exact merge", true);
+});
+
+test("sheet.ts: removeMerge returns false when range not found", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  const removed = removeMerge(sheet, { startRow: 0, startCol: 0, endRow: 1, endCol: 1 });
+  assert.equal(removed, false);
+  record("merge-remove-absent", "removeMerge returns false for absent merge", true);
+});
+
+test("sheet.ts: findMergesContaining returns overlapping merges", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  addMerge(sheet, { startRow: 0, startCol: 0, endRow: 2, endCol: 2 });
+  addMerge(sheet, { startRow: 5, startCol: 5, endRow: 7, endCol: 7 });
+  assert.equal(findMergesContaining(sheet, 1, 1).length, 1);
+  assert.equal(findMergesContaining(sheet, 6, 6).length, 1);
+  assert.equal(findMergesContaining(sheet, 3, 3).length, 0);
+  record("merge-find", "findMergesContaining returns correct merges", true);
+});
+
+test("sheet.ts: cell at top-left of merge is included in merge", () => {
+  const sheet = createSheet("s1", "Sheet1", 0);
+  addMerge(sheet, { startRow: 2, startCol: 3, endRow: 4, endCol: 5 });
+  assert.equal(findMergesContaining(sheet, 2, 3).length, 1);
+  assert.equal(findMergesContaining(sheet, 4, 5).length, 1);
+  assert.equal(findMergesContaining(sheet, 5, 5).length, 0);
+  record("merge-boundary", "merge boundary cells correctly included/excluded", true);
+});
+
+// ---------------------------------------------------------------------------
+// Workbook registry
+// ---------------------------------------------------------------------------
+
+test("workbook.ts: createWorkbook produces correct initial state", () => {
+  const wb = createWorkbook();
+  assert.equal(wb.schemaVersion, WORKBOOK_SCHEMA_VERSION);
+  assert.equal(wb.metadata.date1904, false);
+  assert.equal(wb.sheets.size, 0);
+  assert.deepEqual(wb.sheetOrder, []);
+  assert.deepEqual(wb.sharedStrings.strings, []);
+  assert.deepEqual(wb.namedItems, []);
+  record("workbook-create", "createWorkbook initial state", true);
+});
+
+test("workbook.ts: createWorkbook accepts metadata overrides", () => {
+  const wb = createWorkbook({ title: "Budget 2026", date1904: true });
+  assert.equal(wb.metadata.title, "Budget 2026");
+  assert.equal(wb.metadata.date1904, true);
+  record("workbook-metadata", "createWorkbook metadata override", true);
+});
+
+test("workbook.ts: addSheet adds sheet and registers in order", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Sheet1");
+  addSheet(wb, "s2", "Sheet2");
+  assert.equal(wb.sheets.size, 2);
+  assert.deepEqual(wb.sheetOrder, ["s1", "s2"]);
+  record("sheet-add", "addSheet registers sheets in order", true);
+});
+
+test("workbook.ts: addSheet assigns correct orderIndex", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Sheet1");
+  addSheet(wb, "s2", "Sheet2");
+  assert.equal(wb.sheets.get("s1")?.orderIndex, 0);
+  assert.equal(wb.sheets.get("s2")?.orderIndex, 1);
+  record("sheet-order-index", "addSheet assigns correct orderIndex", true);
+});
+
+test("workbook.ts: addSheet throws on duplicate id", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Sheet1");
+  assert.throws(() => addSheet(wb, "s1", "Sheet1-dup"), /already exists/);
+  record("sheet-dup-id", "addSheet throws on duplicate id", true);
+});
+
+test("workbook.ts: addSheet at specific index inserts correctly", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Sheet1");
+  addSheet(wb, "s2", "Sheet2");
+  addSheet(wb, "s3", "Sheet3", 1); // insert before Sheet2
+  assert.deepEqual(wb.sheetOrder, ["s1", "s3", "s2"]);
+  assert.equal(wb.sheets.get("s3")?.orderIndex, 1);
+  assert.equal(wb.sheets.get("s2")?.orderIndex, 2);
+  record("sheet-insert", "addSheet at index inserts correctly", true);
+});
+
+test("workbook.ts: removeSheet removes sheet from registry", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Sheet1");
+  addSheet(wb, "s2", "Sheet2");
+  const removed = removeSheet(wb, "s1");
+  assert.equal(removed?.sheetId, "s1");
+  assert.equal(wb.sheets.size, 1);
+  assert.deepEqual(wb.sheetOrder, ["s2"]);
+  assert.equal(wb.sheets.get("s2")?.orderIndex, 0);
+  record("sheet-remove", "removeSheet removes sheet and reindexes", true);
+});
+
+test("workbook.ts: removeSheet returns undefined for unknown id", () => {
+  const wb = createWorkbook();
+  const removed = removeSheet(wb, "nonexistent");
+  assert.equal(removed, undefined);
+  record("sheet-remove-absent", "removeSheet returns undefined for unknown id", true);
+});
+
+test("workbook.ts: getSheet returns correct sheet", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Sheet1");
+  const sheet = getSheet(wb, "s1");
+  assert.equal(sheet?.sheetId, "s1");
+  record("sheet-get", "getSheet returns correct sheet", true);
+});
+
+test("workbook.ts: getSheetByName finds sheet by display name", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "Budget");
+  addSheet(wb, "s2", "Summary");
+  assert.equal(getSheetByName(wb, "Budget")?.sheetId, "s1");
+  assert.equal(getSheetByName(wb, "Summary")?.sheetId, "s2");
+  assert.equal(getSheetByName(wb, "Missing"), undefined);
+  record("sheet-get-by-name", "getSheetByName finds sheet", true);
+});
+
+test("workbook.ts: listSheets returns sheets in tab order", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "First");
+  addSheet(wb, "s2", "Second");
+  addSheet(wb, "s3", "Third");
+  const sheets = listSheets(wb);
+  assert.equal(sheets.length, 3);
+  assert.equal(sheets[0].name, "First");
+  assert.equal(sheets[1].name, "Second");
+  assert.equal(sheets[2].name, "Third");
+  record("sheet-list", "listSheets returns sheets in tab order", true);
+});
+
+test("workbook.ts: renameSheet updates display name", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "OldName");
+  renameSheet(wb, "s1", "NewName");
+  assert.equal(wb.sheets.get("s1")?.name, "NewName");
+  record("sheet-rename", "renameSheet updates display name", true);
+});
+
+test("workbook.ts: renameSheet throws for unknown id", () => {
+  const wb = createWorkbook();
+  assert.throws(() => renameSheet(wb, "nonexistent", "X"), /not found/);
+  record("sheet-rename-absent", "renameSheet throws for unknown id", true);
+});
+
+test("workbook.ts: moveSheet reorders sheets", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "First");
+  addSheet(wb, "s2", "Second");
+  addSheet(wb, "s3", "Third");
+  moveSheet(wb, "s1", 2);
+  assert.deepEqual(wb.sheetOrder, ["s2", "s3", "s1"]);
+  assert.equal(wb.sheets.get("s1")?.orderIndex, 2);
+  assert.equal(wb.sheets.get("s2")?.orderIndex, 0);
+  record("sheet-move", "moveSheet reorders sheets correctly", true);
+});
+
+test("workbook.ts: moveSheet no-op when already at target", () => {
+  const wb = createWorkbook();
+  addSheet(wb, "s1", "First");
+  addSheet(wb, "s2", "Second");
+  moveSheet(wb, "s1", 0); // already at 0
+  assert.deepEqual(wb.sheetOrder, ["s1", "s2"]);
+  record("sheet-move-noop", "moveSheet is no-op when already at target", true);
+});
+
+// ---------------------------------------------------------------------------
+// Shared string table
+// ---------------------------------------------------------------------------
+
+test("workbook.ts: appendSharedString adds strings in order", () => {
+  const wb = createWorkbook();
+  const idx0 = appendSharedString(wb, "Alpha");
+  const idx1 = appendSharedString(wb, "Beta");
+  assert.equal(idx0, 0);
+  assert.equal(idx1, 1);
+  assert.deepEqual(wb.sharedStrings.strings, ["Alpha", "Beta"]);
+  record("shared-strings-append", "appendSharedString appends in order", true);
+});
+
+test("workbook.ts: resolveSharedString returns correct string", () => {
+  const wb = createWorkbook();
+  appendSharedString(wb, "Hello");
+  appendSharedString(wb, "World");
+  assert.equal(resolveSharedString(wb, 0), "Hello");
+  assert.equal(resolveSharedString(wb, 1), "World");
+  assert.equal(resolveSharedString(wb, 99), undefined);
+  record("shared-strings-resolve", "resolveSharedString returns correct string", true);
+});
+
+// ---------------------------------------------------------------------------
+// Style registry
+// ---------------------------------------------------------------------------
+
+test("styles.ts: createEmptyStyleRegistry is empty", () => {
+  const reg = createEmptyStyleRegistry();
+  assert.equal(reg.cellFormats.length, 0);
+  assert.equal(reg.numFormats.size, 0);
+  assert.equal(reg.cellFormatCount, 0);
+  record("styles-empty", "createEmptyStyleRegistry is empty", true);
+});
+
+test("styles.ts: getXfRecord returns undefined for missing index", () => {
+  const reg = createEmptyStyleRegistry();
+  assert.equal(getXfRecord(reg, 0), undefined);
+  record("styles-xf-missing", "getXfRecord returns undefined for missing index", true);
+});
+
+test("styles.ts: getXfRecord returns stored xf record", () => {
+  const reg = createEmptyStyleRegistry();
+  const xf: XfRecord = {
+    xfIndex: 0,
+    fontId: 0,
+    fillId: 0,
+    borderId: 0,
+    numFmtId: 0,
+    rawAttributes: { applyFont: "1" },
+  };
+  reg.cellFormats.push(xf);
+  reg.cellFormatCount = 1;
+  assert.deepEqual(getXfRecord(reg, 0), xf);
+  record("styles-xf-stored", "getXfRecord returns stored xf record", true);
+});
+
+test("styles.ts: isDateFormatHeuristic recognizes built-in date numFmtId", () => {
+  const reg = createEmptyStyleRegistry();
+  const xf: XfRecord = {
+    xfIndex: 0,
+    fontId: 0,
+    fillId: 0,
+    borderId: 0,
+    numFmtId: 14, // built-in short date
+    rawAttributes: {},
+  };
+  reg.cellFormats.push(xf);
+  assert.equal(isDateFormatHeuristic(reg, 0), true);
+  record("styles-date-builtin", "isDateFormatHeuristic recognizes built-in date", true);
+});
+
+test("styles.ts: isDateFormatHeuristic returns false for general numFmtId 0", () => {
+  const reg = createEmptyStyleRegistry();
+  const xf: XfRecord = {
+    xfIndex: 0,
+    fontId: 0,
+    fillId: 0,
+    borderId: 0,
+    numFmtId: 0,
+    rawAttributes: {},
+  };
+  reg.cellFormats.push(xf);
+  assert.equal(isDateFormatHeuristic(reg, 0), false);
+  record("styles-date-general", "isDateFormatHeuristic false for numFmtId 0", true);
+});
+
+// ---------------------------------------------------------------------------
+// Integration scenario: populate a sheet with multiple cell types
+// ---------------------------------------------------------------------------
+
+test("integration: build a small workbook with multiple sheets and cell types", () => {
+  const wb = createWorkbook({ title: "Test Workbook" });
+
+  // Add two sheets
+  const s1 = addSheet(wb, "sheet1", "Data");
+  const s2 = addSheet(wb, "sheet2", "Summary");
+
+  // Populate sheet 1 with various cell types
+  setCell(s1, 0, 0, makeTextCell("Name", false));
+  setCell(s1, 0, 1, makeTextCell("Value", false));
+  setCell(s1, 1, 0, makeTextCell("Alpha", false));
+  setCell(s1, 1, 1, makeNumberCell(100));
+  setCell(s1, 2, 0, makeTextCell("Beta", false));
+  setCell(s1, 2, 1, makeFormulaCell("B2*2", { type: "number", value: 200 }));
+  setCell(s1, 3, 0, makeBooleanCell(true));
+  setCell(s1, 3, 1, makeErrorCell("#N/A"));
+
+  // Add a merge in sheet 1
+  addMerge(s1, { startRow: 4, startCol: 0, endRow: 4, endCol: 3 });
+
+  // Populate summary sheet with a shared-string reference
+  appendSharedString(wb, "Total");
+  setCell(s2, 0, 0, makeTextCell("Total", true, { xfIndex: 0 }));
+  setCell(s2, 0, 1, makeFormulaCell("Data!B2+Data!B3", { type: "number", value: 300 }));
+
+  // Assertions
+  assert.equal(wb.sheets.size, 2);
+  assert.equal(s1.cells.size, 8);
+  assert.equal(s1.merges.length, 1);
+  assert.equal(getCell(s1, 1, 1)?.kind, "number");
+  assert.equal((getCell(s1, 2, 1) as { kind: string; formula: string })?.formula, "B2*2");
+  assert.equal(getCell(s1, 3, 0)?.kind, "boolean");
+  assert.equal(getCell(s1, 3, 1)?.kind, "error");
+  assert.equal(getCell(s2, 0, 0)?.kind, "text");
+  assert.equal(resolveSharedString(wb, 0), "Total");
+
+  const extent = getSheetExtent(s1);
+  assert.equal(extent?.maxRow, 3);
+  assert.equal(extent?.maxCol, 1);
+
+  record("integration-scenario", "full workbook integration scenario", true);
+});
+
+// ---------------------------------------------------------------------------
+// Formula reference tokens (architecture requirement for safe remapping)
+// ---------------------------------------------------------------------------
+
+test("cell.ts: makeFormulaCell stores referenceTokens", () => {
+  const cell = makeFormulaCell("SUM(A1:A10)+B2", undefined, undefined, ["A1:A10", "B2"]);
+  assert.equal(cell.kind, "formula");
+  assert.deepEqual(cell.referenceTokens, ["A1:A10", "B2"]);
+  record("formula-ref-tokens", "makeFormulaCell stores referenceTokens", true);
+});
+
+test("cell.ts: makeFormulaCell defaults referenceTokens to empty array", () => {
+  const cell = makeFormulaCell("TODAY()");
+  assert.deepEqual(cell.referenceTokens, []);
+  record("formula-ref-tokens-default", "makeFormulaCell defaults referenceTokens to []", true);
+});
+
+test("cell.ts: makeFormulaCell with cached value preserves referenceTokens", () => {
+  const cell = makeFormulaCell(
+    "A1+B1",
+    { type: "number", value: 42 },
+    { xfIndex: 0 },
+    ["A1", "B1"],
+  );
+  assert.deepEqual(cell.referenceTokens, ["A1", "B1"]);
+  assert.deepEqual(cell.cachedValue, { type: "number", value: 42 });
+  assert.deepEqual(cell.styleRef, { xfIndex: 0 });
+  record("formula-ref-tokens-with-cached", "referenceTokens coexists with cachedValue and styleRef", true);
+});
+
+// ---------------------------------------------------------------------------
+// Workbook serialization round-trip (Map → JSON → Map)
+// ---------------------------------------------------------------------------
+
+test("workbook.ts: workbookToJson produces JSON-serializable output", () => {
+  const wb = createWorkbook({ title: "Serialize Test" });
+  const s = addSheet(wb, "s1", "Sheet1");
+  setCell(s, 0, 0, makeTextCell("Hello", false));
+  setCell(s, 1, 0, makeNumberCell(99));
+  addMerge(s, { startRow: 0, startCol: 0, endRow: 0, endCol: 2 });
+  appendSharedString(wb, "shared");
+
+  const plain = workbookToJson(wb);
+  // Should round-trip through JSON without throwing
+  const json = JSON.stringify(plain);
+  assert.ok(json.length > 0, "JSON output is non-empty");
+  assert.ok(!json.includes("[object Map]"), "No un-serialized Map in output");
+  record("workbook-to-json", "workbookToJson produces JSON-serializable plain object", true);
+});
+
+test("workbook.ts: workbookFromJson restores workbook faithfully", () => {
+  const wb = createWorkbook({ title: "Round Trip" });
+  const s = addSheet(wb, "s1", "Data");
+  setCell(s, 0, 0, makeTextCell("Alpha", true));
+  setCell(s, 1, 1, makeNumberCell(3.14));
+  addMerge(s, { startRow: 2, startCol: 0, endRow: 2, endCol: 1 });
+  appendSharedString(wb, "Alpha");
+
+  const serialized = workbookToJson(wb);
+  const restored = workbookFromJson(serialized);
+
+  assert.equal(restored.schemaVersion, WORKBOOK_SCHEMA_VERSION);
+  assert.equal(restored.metadata.title, "Round Trip");
+  assert.equal(restored.sheets.size, 1);
+  assert.deepEqual(restored.sheetOrder, ["s1"]);
+  assert.equal(restored.sharedStrings.strings[0], "Alpha");
+
+  const rs = restored.sheets.get("s1");
+  assert.ok(rs, "sheet s1 present after restore");
+  assert.equal(rs!.cells.size, 2);
+  assert.equal(rs!.merges.length, 1);
+  const cell = getCell(rs!, 0, 0);
+  assert.equal(cell?.kind, "text");
+  assert.equal((cell as { value: string }).value, "Alpha");
+  record("workbook-round-trip", "workbookToJson/workbookFromJson round-trip is faithful", true);
+});
+
+test("workbook.ts: workbookFromJson throws on schema version mismatch", () => {
+  const wb = createWorkbook();
+  const plain = workbookToJson(wb);
+  // Corrupt the schema version
+  const corrupted = { ...plain, schemaVersion: "workbook/0" as typeof WORKBOOK_SCHEMA_VERSION };
+  assert.throws(() => workbookFromJson(corrupted), /Unsupported workbook schema version/);
+  record("workbook-schema-mismatch", "workbookFromJson throws on schema version mismatch", true);
+});
+
+// ---------------------------------------------------------------------------
+// Write proof bundle (deferred to process exit so all test records are captured)
+// ---------------------------------------------------------------------------
+
+process.on("exit", () => {
+  const passed = results.filter((r) => r.passed).length;
+  const failed = results.filter((r) => !r.passed).length;
+
+  const proofBundle = {
+    reportVersion: "wave-25-model/1",
+    component: "xlsx-canonical-workbook-model",
+    generatedAt: new Date().toISOString(),
+    summary: {
+      total: results.length,
+      passed,
+      failed,
+    },
+    tests: results,
+  };
+
+  mkdirSync(PROOF_DIR, { recursive: true });
+  writeFileSync(PROOF_PATH, JSON.stringify(proofBundle, null, 2), "utf8");
+});