@lotics/xlsx 0.1.0

package/src/workbook_model.ts

@@ -0,0 +1,911 @@
+import type {
+  ParsedSpreadsheet,
+  ParsedSheet,
+  ParsedRow,
+  ParsedCell,
+  ParsedColumn,
+  CellStyle,
+  CellContent,
+  RichTextPart,
+  ParsedImage,
+  FreezePane,
+  MergedCellRange,
+  PageSetup,
+  PrintTitles,
+  HeaderFooter,
+} from "./types";
+import type { ParsedConditionalFormat } from "./excel_cf_types";
+import type {
+  ParsedChart,
+  ParsedTable,
+  ParsedDrawing,
+  ParsedSparklineGroup,
+  AutoFilterRange,
+  ParsedDataValidation,
+} from "./ooxml_chart_types";
+import { formatNumFmt } from "./excel_numfmt";
+import { colLettersToNum, refToRowCol, rowColToRef, packRef, unpackRef } from "./excel_utils";
+import { allBorders } from "./style_helpers";
+import { PivotTableModel } from "./pivot_model";
+
+// =============================================================================
+// Cell value type
+// =============================================================================
+
+export type CellValue = string | number | boolean | null;
+export type { CellStyle } from "./types";
+
+// =============================================================================
+// CellMap — int-keyed cell storage with a Map-compatible API
+// =============================================================================
+//
+// `SheetModel.cells` looks like a `Map<string, CellModel>` to its callers
+// but internally stores entries keyed by an integer packed from (row, col).
+// V8's Map operations are measurably faster on numeric keys than on strings,
+// and iteration avoids string hashing entirely.
+//
+// The wrapper exposes the same API surface as the standard Map (get, set,
+// has, delete, size, keys, values, entries, forEach, Symbol.iterator) so
+// existing call sites continue to work unchanged. Iteration unpacks the
+// int key back to an A1 ref on demand.
+
+export class CellMap implements Iterable<[string, CellModel]> {
+  private store = new Map<number, CellModel>();
+
+  get size(): number {
+    return this.store.size;
+  }
+
+  get(ref: string): CellModel | undefined {
+    return this.store.get(packRef(ref));
+  }
+
+  set(ref: string, cell: CellModel): this {
+    const key = packRef(ref);
+    if (key < 0) return this;
+    this.store.set(key, cell);
+    return this;
+  }
+
+  has(ref: string): boolean {
+    return this.store.has(packRef(ref));
+  }
+
+  delete(ref: string): boolean {
+    return this.store.delete(packRef(ref));
+  }
+
+  clear(): void {
+    this.store.clear();
+  }
+
+  *keys(): IterableIterator<string> {
+    for (const k of this.store.keys()) yield unpackRef(k);
+  }
+
+  values(): IterableIterator<CellModel> {
+    return this.store.values();
+  }
+
+  *entries(): IterableIterator<[string, CellModel]> {
+    for (const [k, v] of this.store) yield [unpackRef(k), v];
+  }
+
+  forEach(callback: (value: CellModel, key: string, map: CellMap) => void): void {
+    for (const [k, v] of this.store) callback(v, unpackRef(k), this);
+  }
+
+  [Symbol.iterator](): IterableIterator<[string, CellModel]> {
+    return this.entries();
+  }
+
+  /**
+   * Direct packed-int access escape hatch for hot loops in the command
+   * layer (row/col insert/delete) that already work in (row, col) space
+   * and want to avoid the redundant unpack→repack round trip.
+   */
+  packedEntries(): IterableIterator<[number, CellModel]> {
+    return this.store.entries();
+  }
+
+  /** Direct packed-key set, for the same hot loops. */
+  setPacked(packed: number, cell: CellModel): void {
+    this.store.set(packed, cell);
+  }
+
+  /** Direct packed-key delete. */
+  deletePacked(packed: number): boolean {
+    return this.store.delete(packed);
+  }
+}
+
+// =============================================================================
+// CellModel — mutable cell data
+// =============================================================================
+
+export interface CellModel {
+  value: CellValue;
+  displayValue: string;
+  formula?: string;
+  styleIndex: number;
+  richText?: RichTextPart[];
+  error?: string;
+  numFmtCode: string;
+  content: CellContent;
+  isArrayFormula?: boolean;
+  arrayRange?: string;
+  /**
+   * Original cellXfs index from `xl/styles.xml` at load time. When the writer
+   * detects no style mutations occurred (`workbook.styles.dirty === false`),
+   * it uses this index to passthrough the original styles part.
+   */
+  originalXfIndex?: number;
+}
+
+// =============================================================================
+// Change events — fired on any mutation
+// =============================================================================
+
+export type ChangeEvent =
+  | { type: "cell_value"; sheet: number; ref: string; oldValue: CellValue; newValue: CellValue }
+  | { type: "cell_style"; sheet: number; ref: string; oldStyle: number; newStyle: number }
+  | { type: "rows_inserted"; sheet: number; at: number; count: number }
+  | { type: "rows_deleted"; sheet: number; at: number; count: number }
+  | { type: "cols_inserted"; sheet: number; at: number; count: number }
+  | { type: "cols_deleted"; sheet: number; at: number; count: number }
+  | { type: "merge"; sheet: number; ref: string }
+  | { type: "unmerge"; sheet: number; ref: string }
+  | { type: "sheet_added"; index: number }
+  | { type: "sheet_deleted"; index: number }
+  | { type: "sheet_renamed"; index: number; oldName: string; newName: string };
+
+// =============================================================================
+// StyleRegistry — deduplicated CellStyle storage
+// =============================================================================
+
+export class StyleRegistry {
+  private styles: CellStyle[] = [{}]; // Index 0 = empty/default style
+  private keyMap = new Map<string, number>();
+  /**
+   * Becomes true the first time a style not present in the original
+   * `xl/styles.xml` is interned. The writer uses this to skip rebuilding
+   * the styles part when no consumer has changed any style.
+   */
+  dirty = false;
+  /**
+   * Set of numFmtCodes recorded by `registerNumFmt()` at load time. New
+   * numFmtCodes encountered after `markClean()` flip `dirty` to true so
+   * the styles part gets regenerated to include the new code.
+   */
+  private knownNumFmts = new Set<string>(["General", ""]);
+
+  constructor() {
+    this.keyMap.set(styleKey({}), 0);
+  }
+
+  /** Get style by index. Returns empty style for invalid indices. */
+  get(index: number): CellStyle {
+    return this.styles[index] ?? {};
+  }
+
+  /** Number of registered styles. */
+  get size(): number {
+    return this.styles.length;
+  }
+
+  /** Find or create a style entry. Returns the index. */
+  intern(style: CellStyle): number {
+    const key = styleKey(style);
+    const existing = this.keyMap.get(key);
+    if (existing !== undefined) return existing;
+
+    const index = this.styles.length;
+    this.styles.push({ ...style });
+    this.keyMap.set(key, index);
+    this.dirty = true;
+    return index;
+  }
+
+  /** Create a new style by merging a partial override onto an existing style. Returns the index. */
+  merge(baseIndex: number, override: Partial<CellStyle>): number {
+    const base = this.get(baseIndex);
+    const merged: CellStyle = { ...base, ...override };
+    return this.intern(merged);
+  }
+
+  /** Record a numFmtCode in use. Flips `dirty` if the code was unknown. */
+  registerNumFmt(code: string | undefined): void {
+    if (!code || this.knownNumFmts.has(code)) return;
+    this.knownNumFmts.add(code);
+    this.dirty = true;
+  }
+
+  /**
+   * Reset the `dirty` flag and snapshot the current numFmt set as the
+   * baseline. Called once after loading from a parsed workbook so that
+   * subsequent mutations are detectable.
+   */
+  markClean(): void {
+    this.dirty = false;
+  }
+}
+
+/**
+ * Produce a stable canonical key for a CellStyle to support deduplication.
+ *
+ * Implemented as an explicit fixed-order field walk rather than
+ * `JSON.stringify` so the hot path (placeholder engine, bulk format ops)
+ * avoids reflection and string allocation cost. Empty styles produce `""`.
+ *
+ * Two equal `CellStyle` shapes always produce the same key; two unequal
+ * shapes always produce different keys.
+ */
+function styleKey(style: CellStyle): string {
+  const parts: string[] = [];
+  if (style.fontBold) parts.push("fb");
+  if (style.fontItalic) parts.push("fi");
+  if (style.fontStrike) parts.push("fs");
+  if (style.fontColor !== undefined) parts.push(`fc:${style.fontColor}`);
+  if (style.fontSize !== undefined) parts.push(`fz:${style.fontSize}`);
+  if (style.fontName !== undefined) parts.push(`fn:${style.fontName}`);
+  if (style.fontUnderline !== undefined) parts.push(`fu:${style.fontUnderline}`);
+  if (style.fontVertAlign !== undefined) parts.push(`fv:${style.fontVertAlign}`);
+  if (style.backgroundColor !== undefined) parts.push(`bg:${style.backgroundColor}`);
+  if (style.backgroundGradient !== undefined) parts.push(`bgr:${style.backgroundGradient}`);
+  if (style.backgroundPattern !== undefined) parts.push(`bp:${style.backgroundPattern}`);
+  if (style.patternType !== undefined) parts.push(`pt:${style.patternType}`);
+  if (style.gradientData !== undefined) parts.push(`gd:${JSON.stringify(style.gradientData)}`);
+  if (style.horizontalAlign !== undefined) parts.push(`ha:${style.horizontalAlign}`);
+  if (style.verticalAlign !== undefined) parts.push(`va:${style.verticalAlign}`);
+  if (style.wrapText) parts.push("wt");
+  if (style.shrinkToFit) parts.push("stf");
+  if (style.indent !== undefined) parts.push(`in:${style.indent}`);
+  if (style.textRotation !== undefined) parts.push(`tr:${style.textRotation}`);
+  if (style.readingOrder !== undefined) parts.push(`ro:${style.readingOrder}`);
+  if (style.borderTop) parts.push(`bt:${style.borderTop.width}|${style.borderTop.style}|${style.borderTop.color ?? ""}`);
+  if (style.borderRight) parts.push(`br:${style.borderRight.width}|${style.borderRight.style}|${style.borderRight.color ?? ""}`);
+  if (style.borderBottom) parts.push(`bb:${style.borderBottom.width}|${style.borderBottom.style}|${style.borderBottom.color ?? ""}`);
+  if (style.borderLeft) parts.push(`bl:${style.borderLeft.width}|${style.borderLeft.style}|${style.borderLeft.color ?? ""}`);
+  if (style.borderDiagonal) parts.push(`bd:${style.borderDiagonal.width}|${style.borderDiagonal.style}|${style.borderDiagonal.color ?? ""}`);
+  if (style.diagonalUp) parts.push("du");
+  if (style.diagonalDown) parts.push("dd");
+  return parts.join("|");
+}
+
+// =============================================================================
+// SheetModel — mutable sheet with sparse cell storage
+// =============================================================================
+
+export class SheetModel {
+  name: string;
+  styles?: StyleRegistry;
+  cells = new CellMap();
+  colWidths = new Map<number, number>();
+  rowHeights = new Map<number, number>();
+  defaultColWidth = 10;
+  defaultRowHeight = 15;
+  mergedCells: string[] = [];
+  freeze?: { row: number; col: number };
+  hiddenRows = new Set<number>();
+  hiddenCols = new Set<number>();
+  rowOutlineLevels = new Map<number, number>();
+  colOutlineLevels = new Map<number, number>();
+  conditionalFormats: ParsedConditionalFormat[] = [];
+  images: ParsedImage[] = [];
+  charts: ParsedChart[] = [];
+  tables: ParsedTable[] = [];
+  drawings: ParsedDrawing[] = [];
+  dataValidations: ParsedDataValidation[] = [];
+  sparklineGroups: ParsedSparklineGroup[] = [];
+  pivotTables: PivotTableModel[] = [];
+  autoFilter?: AutoFilterRange;
+  rowPageBreaks: number[] = [];
+  colPageBreaks: number[] = [];
+  hyperlinks = new Map<string, string>();
+  view: {
+    showGridLines: boolean;
+    showHeaders: boolean;
+    zoomScale: number;
+    rightToLeft: boolean;
+    tabColor?: string;
+  } = {
+    showGridLines: true,
+    showHeaders: true,
+    zoomScale: 100,
+    rightToLeft: false,
+  };
+  pageSetup?: PageSetup;
+  printTitles?: PrintTitles;
+  headerFooter?: HeaderFooter;
+
+  constructor(name: string, styles?: StyleRegistry) {
+    this.name = name;
+    this.styles = styles;
+  }
+
+  /**
+   * Freeze the rows/cols above and to the left of `topLeftRef`.
+   * `setFreeze("B2")` freezes row 1 and column A; data area starts at B2.
+   * Pass `null` or omit to clear the freeze.
+   */
+  setFreeze(topLeftRef: string | null): void {
+    if (topLeftRef === null) {
+      this.freeze = undefined;
+      return;
+    }
+    const rc = refToRowCol(topLeftRef);
+    if (!rc) throw new Error(`Invalid cell reference: ${topLeftRef}`);
+    this.freeze = { row: rc.row - 1, col: rc.col - 1 };
+  }
+
+  /** Get cell, returning undefined for empty cells. */
+  getCell(ref: string): CellModel | undefined {
+    return this.cells.get(ref);
+  }
+
+  /**
+   * Set cell value with optional inline style. Interns style via the
+   * StyleRegistry when available. When `style` is supplied and matches the
+   * existing cell's style (or is identical to a previously interned style),
+   * the cell's `originalXfIndex` is preserved so that the writer can use
+   * styles-passthrough mode if no other mutation has dirtied the registry.
+   */
+  set(
+    ref: string,
+    value: CellValue,
+    style?: CellStyle,
+    numFmt?: string,
+    formula?: string,
+  ): CellModel {
+    const existing = this.cells.get(ref);
+    const styleIndex = style && this.styles ? this.styles.intern(style) : (existing?.styleIndex ?? 0);
+    const numFmtCode = numFmt ?? existing?.numFmtCode ?? "General";
+    if (this.styles) this.styles.registerNumFmt(numFmtCode);
+    const displayValue = computeDisplayValue(value, numFmtCode);
+    const content = buildContentFromValue(displayValue, this.hyperlinks.get(ref));
+    const cell: CellModel = {
+      value,
+      displayValue,
+      formula,
+      styleIndex,
+      numFmtCode,
+      content,
+    };
+    if (existing && existing.styleIndex === styleIndex && existing.numFmtCode === numFmtCode && existing.originalXfIndex !== undefined) {
+      cell.originalXfIndex = existing.originalXfIndex;
+    }
+    this.cells.set(ref, cell);
+    return cell;
+  }
+
+  /**
+   * Fast path: set a cell with an already-interned style index, skipping
+   * both the `JSON.stringify` styleKey hash AND the eager `displayValue`/
+   * `content` materialization that `set()` performs.
+   *
+   * Optimized for hot loops like the Excel template placeholder engine
+   * where every cell of every expanded row reuses the same template style
+   * and the resulting workbook will be exported (not canvas-rendered) — the
+   * xlsx writer reads `cell.value` directly, so the formatted display value
+   * is never needed.
+   *
+   * If a consumer later needs `displayValue` for one of these cells, call
+   * `materializeDisplayValue(cell)` to compute and memoize it.
+   *
+   * Pass `originalXfIndex` to enable styles-passthrough mode for cells
+   * copied from a parsed template.
+   */
+  setWithStyleIndex(
+    ref: string,
+    value: CellValue,
+    styleIndex: number,
+    numFmtCode: string = "General",
+    formula?: string,
+    originalXfIndex?: number,
+  ): CellModel {
+    if (this.styles) this.styles.registerNumFmt(numFmtCode);
+    const cell: CellModel = {
+      value,
+      displayValue: "",
+      formula,
+      styleIndex,
+      numFmtCode,
+      content: { type: "plain", text: "" },
+    };
+    if (originalXfIndex !== undefined) cell.originalXfIndex = originalXfIndex;
+    this.cells.set(ref, cell);
+    return cell;
+  }
+
+  /** Delete cell (make empty). Returns true if cell existed. */
+  deleteCell(ref: string): boolean {
+    return this.cells.delete(ref);
+  }
+
+  /** Add a merged cell range. Optionally set the top-left cell value and style. */
+  merge(range: string, value?: CellValue, style?: CellStyle): void {
+    this.mergedCells.push(range);
+    if (value !== undefined) {
+      const topLeft = range.split(":")[0];
+      this.set(topLeft, value, style);
+    }
+  }
+
+  /** Set column width by letter ("A") or zero-based index (0). */
+  setColumnWidth(col: string | number, width: number): void {
+    const idx = typeof col === "string" ? colLettersToNum(col) : col;
+    this.colWidths.set(idx, width);
+  }
+
+  /** Set row height. Row is 1-based. */
+  setRowHeight(row: number, height: number): void {
+    this.rowHeights.set(row, height);
+  }
+
+  /** Write a row of header cells: bold, centered, bordered, with background color. */
+  headerRow(row: number, labels: string[], options?: { background?: string }): void {
+    const bg = options?.background ?? "#D9E1F2";
+    const style: CellStyle = {
+      fontBold: true,
+      horizontalAlign: "center",
+      backgroundColor: bg,
+      ...allBorders(),
+    };
+    labels.forEach((label, i) => {
+      const ref = rowColToRef(row, i + 1);
+      this.set(ref, label, style);
+    });
+  }
+
+  /** Compute the bounding box of all non-empty cells. */
+  getUsedRange(): { minRow: number; maxRow: number; minCol: number; maxCol: number } {
+    let minRow = Infinity;
+    let maxRow = 0;
+    let minCol = Infinity;
+    let maxCol = 0;
+
+    for (const ref of this.cells.keys()) {
+      const rc = refToRowCol(ref);
+      if (!rc) continue;
+      if (rc.row < minRow) minRow = rc.row;
+      if (rc.row > maxRow) maxRow = rc.row;
+      if (rc.col < minCol) minCol = rc.col;
+      if (rc.col > maxCol) maxCol = rc.col;
+    }
+
+    if (maxRow === 0) return { minRow: 1, maxRow: 1, minCol: 1, maxCol: 1 };
+    return { minRow, maxRow, minCol, maxCol };
+  }
+}
+
+// =============================================================================
+// WorkbookModel — mutable workbook root
+// =============================================================================
+
+export class WorkbookModel {
+  sheets: SheetModel[];
+  activeSheetIndex: number;
+  styles: StyleRegistry;
+  date1904: boolean;
+  namedRanges = new Map<string, string>();
+  /**
+   * Excel's `calcPr.fullCalcOnLoad` flag. When true, callers that render
+   * cells (frontend canvas, PDF converters) must recompute all formulas
+   * via `FormulaEngine.evaluateAll()` before trusting cached values.
+   * Excel honors this automatically; we have to opt in explicitly.
+   */
+  fullCalcOnLoad: boolean;
+  /**
+   * Primary onChange callback. Kept as a writable property for back-compat with
+   * existing code that does `wb.onChange = (e) => ...`. New consumers should
+   * prefer `subscribe()` so multiple listeners can coexist.
+   */
+  onChange: ((event: ChangeEvent) => void) | undefined;
+  private subscribers: Set<(event: ChangeEvent) => void> = new Set();
+
+  constructor(opts: {
+    sheets: SheetModel[];
+    activeSheetIndex: number;
+    styles: StyleRegistry;
+    date1904?: boolean;
+    fullCalcOnLoad?: boolean;
+  }) {
+    this.sheets = opts.sheets;
+    this.activeSheetIndex = opts.activeSheetIndex;
+    this.styles = opts.styles;
+    this.date1904 = opts.date1904 ?? false;
+    this.fullCalcOnLoad = opts.fullCalcOnLoad ?? false;
+  }
+
+  /** Register an additional change listener. Returns an unsubscribe callback. */
+  subscribe(listener: (event: ChangeEvent) => void): () => void {
+    this.subscribers.add(listener);
+    return () => {
+      this.subscribers.delete(listener);
+    };
+  }
+
+  /** Emit a change event to the primary listener and every subscriber. */
+  emit(event: ChangeEvent): void {
+    this.onChange?.(event);
+    for (const sub of this.subscribers) sub(event);
+  }
+
+  /** Produce an immutable ParsedSpreadsheet snapshot for read-only consumers. */
+  toSnapshot(): ParsedSpreadsheet {
+    return {
+      sheets: this.sheets.map((sheet) => sheetToSnapshot(sheet, this.styles)),
+      activeSheetIndex: this.activeSheetIndex,
+    };
+  }
+}
+
+// =============================================================================
+// Snapshot conversion: SheetModel → ParsedSheet
+// =============================================================================
+
+function sheetToSnapshot(sheet: SheetModel, styles: StyleRegistry): ParsedSheet {
+  const { maxRow, maxCol } = sheet.getUsedRange();
+
+  // Group cells by row
+  const rowMap = new Map<number, ParsedCell[]>();
+  for (const [ref, cell] of sheet.cells) {
+    const rc = refToRowCol(ref);
+    if (!rc) continue;
+    let arr = rowMap.get(rc.row);
+    if (!arr) {
+      arr = [];
+      rowMap.set(rc.row, arr);
+    }
+    const style = styles.get(cell.styleIndex);
+    const hyperlink = sheet.hyperlinks.get(ref);
+    const content = hyperlink
+      ? { type: "hyperlink" as const, text: cell.displayValue !== "" ? cell.displayValue : hyperlink, url: hyperlink }
+      : cell.richText
+        ? { type: "rich_text" as const, parts: cell.richText }
+        : cell.content;
+
+    const parsedCell: ParsedCell = {
+      column: rc.col,
+      value: cell.displayValue,
+      rawValue: typeof cell.value === "number" ? cell.value : undefined,
+      content,
+      style,
+    };
+    if (cell.error) parsedCell.error = cell.error;
+    if (cell.formula) parsedCell.formula = cell.formula;
+    if (cell.isArrayFormula) parsedCell.isArrayFormula = true;
+    if (cell.arrayRange) parsedCell.arrayRange = cell.arrayRange;
+    arr.push(parsedCell);
+  }
+
+  // Build sorted rows (include hidden rows with hidden flag, matching column behavior)
+  const rows: ParsedRow[] = [];
+  const sortedRowNums = Array.from(rowMap.keys()).sort((a, b) => a - b);
+  for (const rowNum of sortedRowNums) {
+    const cells = rowMap.get(rowNum)!;
+    cells.sort((a, b) => a.column - b.column);
+    rows.push({
+      index: rowNum,
+      height: sheet.rowHeights.get(rowNum) ?? sheet.defaultRowHeight,
+      cells,
+      hidden: sheet.hiddenRows.has(rowNum),
+    });
+  }
+
+  // Build columns
+  const columns: ParsedColumn[] = [];
+  for (let c = 1; c <= maxCol; c++) {
+    columns.push({
+      index: c,
+      width: sheet.colWidths.get(c) ?? sheet.defaultColWidth,
+      hidden: sheet.hiddenCols.has(c),
+    });
+  }
+
+  // Build merged cells
+  const mergedCells: MergedCellRange[] = sheet.mergedCells.map((ref) => {
+    const match = ref.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/);
+    if (!match) return { startRow: 1, startCol: 1, endRow: 1, endCol: 1 };
+    return {
+      startCol: colLettersToNum(match[1]),
+      startRow: parseInt(match[2], 10),
+      endCol: colLettersToNum(match[3]),
+      endRow: parseInt(match[4], 10),
+    };
+  });
+
+  // Build freeze pane
+  let freezePane: FreezePane | undefined;
+  if (sheet.freeze) {
+    freezePane = { frozenRows: sheet.freeze.row, frozenCols: sheet.freeze.col };
+  }
+
+  return {
+    name: sheet.name,
+    columns,
+    rows,
+    mergedCells,
+    totalRowCount: maxRow,
+    truncated: false,
+    defaultRowHeight: sheet.defaultRowHeight,
+    defaultColWidth: sheet.defaultColWidth,
+    showGridLines: sheet.view.showGridLines,
+    freezePane,
+    conditionalFormats: sheet.conditionalFormats,
+    images: sheet.images,
+    rowOutlineLevels: sheet.rowOutlineLevels,
+    colOutlineLevels: sheet.colOutlineLevels,
+    charts: sheet.charts,
+    tables: sheet.tables,
+    drawings: sheet.drawings,
+    dataValidations: sheet.dataValidations.length > 0 ? sheet.dataValidations : undefined,
+    sparklineGroups: sheet.sparklineGroups.length > 0 ? sheet.sparklineGroups : undefined,
+    autoFilter: sheet.autoFilter,
+    rowPageBreaks: sheet.rowPageBreaks.length > 0 ? sheet.rowPageBreaks : undefined,
+    colPageBreaks: sheet.colPageBreaks.length > 0 ? sheet.colPageBreaks : undefined,
+    pageSetup: sheet.pageSetup,
+    printTitles: sheet.printTitles,
+    headerFooter: sheet.headerFooter,
+  };
+}
+
+
+// =============================================================================
+// Factory: ParsedSpreadsheet → WorkbookModel
+// =============================================================================
+
+export function loadWorkbookFromSnapshot(
+  parsed: ParsedSpreadsheet,
+  date1904 = false,
+): WorkbookModel {
+  const styles = new StyleRegistry();
+  const sheets: SheetModel[] = [];
+
+  for (const ps of parsed.sheets) {
+    const sheet = loadSheetFromParsed(ps, styles);
+    sheets.push(sheet);
+  }
+
+  const wb = new WorkbookModel({
+    sheets,
+    activeSheetIndex: parsed.activeSheetIndex,
+    styles,
+    date1904,
+    fullCalcOnLoad: parsed.fullCalcOnLoad,
+  });
+  if (parsed.namedRanges) {
+    wb.namedRanges = new Map(parsed.namedRanges);
+  }
+
+  // Build pivot table models. Caches live at workbook scope; tables live on
+  // the sheet they were placed on. Pivots without a resolvable cache are
+  // dropped — Excel would mark them as needing refresh, but in our model
+  // there's nothing meaningful to render so we skip them.
+  if (parsed.pivotCaches && parsed.pivotCaches.size > 0) {
+    for (let i = 0; i < parsed.sheets.length; i++) {
+      const ps = parsed.sheets[i];
+      if (!ps.pivotTables || ps.pivotTables.length === 0) continue;
+      const sheet = wb.sheets[i];
+      for (const config of ps.pivotTables) {
+        const cache = parsed.pivotCaches.get(config.cacheId);
+        if (!cache) continue;
+        const model = new PivotTableModel(config, cache);
+        // First-pass recompute so initial render shows current numbers.
+        model.recompute(wb);
+        sheet.pivotTables.push(model);
+      }
+    }
+  }
+
+  // Snapshot the post-load state as the clean baseline. Subsequent mutations
+  // (intern, registerNumFmt) will flip dirty back to true.
+  styles.markClean();
+  return wb;
+}
+
+function loadSheetFromParsed(ps: ParsedSheet, styles: StyleRegistry): SheetModel {
+  const sheet = new SheetModel(ps.name, styles);
+
+  // Metadata
+  sheet.defaultRowHeight = ps.defaultRowHeight;
+  sheet.defaultColWidth = ps.defaultColWidth;
+  sheet.view.showGridLines = ps.showGridLines;
+  sheet.conditionalFormats = [...ps.conditionalFormats];
+  sheet.images = [...ps.images];
+  sheet.charts = ps.charts ? [...ps.charts] : [];
+  sheet.tables = ps.tables ? [...ps.tables] : [];
+  sheet.drawings = ps.drawings ? [...ps.drawings] : [];
+  sheet.dataValidations = ps.dataValidations ? [...ps.dataValidations] : [];
+  sheet.sparklineGroups = ps.sparklineGroups ? [...ps.sparklineGroups] : [];
+  if (ps.autoFilter) sheet.autoFilter = ps.autoFilter;
+  sheet.rowPageBreaks = ps.rowPageBreaks ? [...ps.rowPageBreaks] : [];
+  sheet.colPageBreaks = ps.colPageBreaks ? [...ps.colPageBreaks] : [];
+  sheet.rowOutlineLevels = new Map(ps.rowOutlineLevels);
+  sheet.colOutlineLevels = new Map(ps.colOutlineLevels);
+  if (ps.pageSetup) sheet.pageSetup = ps.pageSetup;
+  if (ps.printTitles) sheet.printTitles = ps.printTitles;
+  if (ps.headerFooter) sheet.headerFooter = ps.headerFooter;
+
+  // Freeze pane
+  if (ps.freezePane) {
+    sheet.freeze = { row: ps.freezePane.frozenRows, col: ps.freezePane.frozenCols };
+  }
+
+  // Columns
+  for (const col of ps.columns) {
+    if (col.width !== ps.defaultColWidth) {
+      sheet.colWidths.set(col.index, col.width);
+    }
+    if (col.hidden) {
+      sheet.hiddenCols.add(col.index);
+    }
+  }
+
+  // Merged cells
+  sheet.mergedCells = ps.mergedCells.map((mc) => {
+    const startRef = rowColToRef(mc.startRow, mc.startCol);
+    const endRef = rowColToRef(mc.endRow, mc.endCol);
+    return `${startRef}:${endRef}`;
+  });
+
+  // Rows and cells
+  for (const row of ps.rows) {
+    if (row.height !== ps.defaultRowHeight) {
+      sheet.rowHeights.set(row.index, row.height);
+    }
+    if (row.hidden) {
+      sheet.hiddenRows.add(row.index);
+    }
+
+    for (const cell of row.cells) {
+      const ref = rowColToRef(row.index, cell.column);
+      const styleIndex = styles.intern(cell.style);
+      styles.registerNumFmt(cell.numFmtCode);
+
+      // Use typed value from parser when available (lossless round-trip),
+      // fall back to inferring from display value for programmatically-built cells
+      const rawValue = cell.typedValue !== undefined ? cell.typedValue : inferRawValue(cell.value, cell.content);
+
+      const model: CellModel = {
+        value: rawValue,
+        displayValue: cell.value,
+        styleIndex,
+        numFmtCode: cell.numFmtCode ?? "General",
+        content: cell.content,
+      };
+      if (cell.error) model.error = cell.error;
+      if (cell.formula) model.formula = cell.formula;
+      if (cell.isArrayFormula) model.isArrayFormula = true;
+      if (cell.arrayRange) model.arrayRange = cell.arrayRange;
+      if (cell.originalXfIndex !== undefined) model.originalXfIndex = cell.originalXfIndex;
+      if (cell.content.type === "rich_text") {
+        model.richText = cell.content.parts;
+      }
+      if (cell.content.type === "hyperlink") {
+        sheet.hyperlinks.set(ref, cell.content.url);
+      }
+
+      sheet.cells.set(ref, model);
+    }
+  }
+
+  // Apply auto-filter initial state — hide rows that don't match filter criteria
+  if (sheet.autoFilter && sheet.autoFilter.columns.length > 0) {
+    applyAutoFilterHiddenRows(sheet);
+  }
+
+  return sheet;
+}
+
+/** Hide rows that don't match the auto-filter criteria. */
+function applyAutoFilterHiddenRows(sheet: SheetModel): void {
+  const af = sheet.autoFilter;
+  if (!af) return;
+
+  const refMatch = af.ref.match(/^([A-Z]+)(\d+):([A-Z]+)(\d+)$/);
+  if (!refMatch) return;
+
+  const startCol = colLettersToNum(refMatch[1]);
+  const headerRow = parseInt(refMatch[2], 10);
+  const endRow = parseInt(refMatch[4], 10);
+
+  // Only process columns that have active filters
+  const activeFilters = af.columns.filter(
+    (col) => (col.filterValues && col.filterValues.length > 0) || col.customFilter,
+  );
+  if (activeFilters.length === 0) return;
+
+  // Check each data row (skip header)
+  for (let r = headerRow + 1; r <= endRow; r++) {
+    let visible = true;
+    for (const filterCol of activeFilters) {
+      const col = startCol + filterCol.colIndex;
+      const cell = sheet.getCell(rowColToRef(r, col));
+      const cellText = cell?.displayValue ?? "";
+
+      if (filterCol.filterValues && filterCol.filterValues.length > 0) {
+        // Value filter: cell must match one of the allowed values
+        if (!filterCol.filterValues.includes(cellText)) {
+          visible = false;
+          break;
+        }
+      } else if (filterCol.customFilter) {
+        // Custom filter (e.g., greaterThan, lessThan)
+        const num = parseFloat(cellText);
+        const threshold = parseFloat(filterCol.customFilter.value);
+        if (!isNaN(num) && !isNaN(threshold)) {
+          if (!matchesCustomFilter(num, filterCol.customFilter.operator, threshold)) {
+            visible = false;
+            break;
+          }
+        }
+      }
+    }
+
+    if (!visible) {
+      sheet.hiddenRows.add(r);
+    }
+  }
+}
+
+function matchesCustomFilter(value: number, operator: string, threshold: number): boolean {
+  switch (operator) {
+    case "greaterThan": return value > threshold;
+    case "greaterThanOrEqual": return value >= threshold;
+    case "lessThan": return value < threshold;
+    case "lessThanOrEqual": return value <= threshold;
+    case "equal": return value === threshold;
+    case "notEqual": return value !== threshold;
+    default: return true;
+  }
+}
+
+/** Infer the raw CellValue from the display string and content type. */
+function inferRawValue(displayValue: string, content: CellContent): CellValue {
+  if (!displayValue) return null;
+  if (displayValue === "TRUE") return true;
+  if (displayValue === "FALSE") return false;
+
+  // Try to parse as number
+  const num = Number(displayValue);
+  if (!isNaN(num) && displayValue.trim() !== "") return num;
+
+  // String value
+  if (content.type === "hyperlink") return content.text;
+  if (content.type === "rich_text") {
+    return content.parts.map((p) => p.text).join("");
+  }
+  return displayValue;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function computeDisplayValue(value: CellValue, numFmtCode: string): string {
+  if (value === null) return "";
+  if (typeof value === "boolean") return value ? "TRUE" : "FALSE";
+  if (typeof value === "string") return value;
+  return formatNumFmt(value, numFmtCode).text;
+}
+
+function buildContentFromValue(displayValue: string, hyperlink?: string): CellContent {
+  if (hyperlink) {
+    return { type: "hyperlink", text: displayValue !== "" ? displayValue : hyperlink, url: hyperlink };
+  }
+  return { type: "plain", text: displayValue };
+}
+
+/**
+ * Backfill `displayValue` and `content` on a cell created via the
+ * `setWithStyleIndex` fast path. Idempotent — safe to call repeatedly.
+ * Returns the (possibly newly computed) display value.
+ */
+export function materializeDisplayValue(cell: CellModel, hyperlink?: string): string {
+  if (cell.displayValue === "" && cell.value !== null && cell.value !== "") {
+    cell.displayValue = computeDisplayValue(cell.value, cell.numFmtCode);
+    cell.content = buildContentFromValue(cell.displayValue, hyperlink);
+  }
+  return cell.displayValue;
+}