@rowsncolumns/rnc-engine 0.10.132

package/dist/esm/fold.js

@@ -0,0 +1,539 @@
+import { cellKey } from "./keys";
+/** An empty render state (seed with your initial sheets). */
+export function emptyRenderState(sheets = []) {
+    return {
+        sheets,
+        sheetData: {},
+        cellStyles: new Map(),
+        derivedFormats: new Map(),
+        notes: new Map(),
+        charts: new Map(),
+        pivotTables: new Map(),
+    };
+}
+/** Set one cell (1-indexed), creating the sparse row/column slots immutably. */
+export function setCell(prev, sheetId, row, col, mut) {
+    const key = String(sheetId);
+    const rows = prev[key] ? prev[key].slice() : [];
+    const existing = rows[row];
+    const values = existing?.values ? existing.values.slice() : [];
+    values[col] = mut({ ...(values[col] ?? {}) });
+    rows[row] = { ...(existing ?? {}), values };
+    return { ...prev, [key]: rows };
+}
+/** Apply one cell change. The engine streams the cell VERBATIM (`ue` input, `ev` computed value incl.
+ * `ev.ev` = errorValue, `fv` formatted, …) — JS is view-only and reconstructs nothing. We merge it
+ * over the prior cell so the RESULT fields that OTHER channels own — `dataValidationResult` and
+ * `conditionalFormattingResultById`, which never ride on the value channel — survive a value edit
+ * (the value fields are always present on `ch.cell`, so they're replaced wholesale). `cell: null`
+ * clears the value (drop `ue`/`ev`/`fv`), leaving those channel-owned result fields for the
+ * validations channel to re-emit if the cleared cell's validity flips. */
+export function applyChange(cell, ch) {
+    if (!ch.cell) {
+        const next = { ...cell };
+        delete next.ue;
+        delete next.ev;
+        delete next.fv;
+        return next;
+    }
+    const next = { ...cell, ...ch.cell };
+    // The engine OMITS cleared optional cell-content fields (it skip-serializes `None`), so a plain merge
+    // would keep a stale value when one is removed (`remove-comment`/`remove-citation-from-cell`/
+    // `remove-link`). `ch.cell` is the COMPLETE cell, so a field absent from it means it was cleared —
+    // drop it. The VALUE fields (`ue`/`ev`/`fv`) are in the list too: a cell can exist WITHOUT a value
+    // (an empty pivot-output cell tagged with `pivotId`), and a plain merge would resurrect the previous
+    // render's value into it. Pivot cell metadata (`pivotId`/`expandable`/`expanded`/`groupKeys`)
+    // follows the same rule so a re-rendered pivot row sheds stale expand chips. (CF/DV RESULT fields
+    // are channel-owned and intentionally NOT in this list.)
+    for (const k of [
+        "ue",
+        "ev",
+        "fv",
+        "citationId",
+        "commentThreadId",
+        "hyperlink",
+        "imageUrl",
+        "pivotId",
+        "expandable",
+        "expanded",
+        "groupKeys",
+    ]) {
+        if (!(k in ch.cell))
+            delete next[k];
+    }
+    return next;
+}
+/** Stream the engine's cell change-set into `sheetData`. */
+export function applyChanges(prev, changes) {
+    let next = prev;
+    for (const ch of changes) {
+        next = setCell(next, ch.sheetId, ch.rowIndex, ch.columnIndex, (cell) => applyChange(cell, ch));
+    }
+    return next;
+}
+/** Fold a style change-set into a consolidated `Map<"sheetId!A1", CellFormat>` (`format: null` =
+ * cleared → drop). Used for both own styles (`styleChanges`) and CF-derived styles. */
+export function foldStyles(prev, styles) {
+    if (!styles.length)
+        return prev;
+    const next = new Map(prev);
+    for (const s of styles) {
+        const key = cellKey(s.sheetId, s.rowIndex, s.columnIndex);
+        if (s.format)
+            next.set(key, s.format);
+        else
+            next.delete(key);
+    }
+    return next;
+}
+/** Fold data-validation results ONTO each cell's `dataValidationResult` (the same place
+ * `useSpreadsheetState` keeps it) — `false` = the value violates a rule. No separate invalid set. */
+export function foldDataValidationResults(prev, vals) {
+    if (!vals.length)
+        return prev;
+    let next = prev;
+    for (const v of vals) {
+        next = setCell(next, v.sheetId, v.rowIndex, v.columnIndex, (cell) => ({
+            ...cell,
+            dataValidationResult: v.valid,
+        }));
+    }
+    return next;
+}
+/** Fold per-cell note deltas (`note: null` = cleared). */
+export function foldNotes(prev, notes) {
+    if (!notes.length)
+        return prev;
+    const next = new Map(prev);
+    for (const n of notes) {
+        const key = cellKey(n.sheetId, n.rowIndex, n.columnIndex);
+        if (n.note == null)
+            next.delete(key);
+        else
+            next.set(key, n.note);
+    }
+    return next;
+}
+/** Fold id-keyed object spec deltas (charts / pivots; `null` spec = deleted). */
+export function foldObjects(prev, deltas) {
+    if (!deltas.length)
+        return prev;
+    const next = new Map(prev);
+    for (const d of deltas) {
+        if (d.spec == null)
+            next.delete(d.id);
+        else
+            next.set(d.id, d.spec);
+    }
+    return next;
+}
+/** Fold row/column metadata deltas into each sheet's `rowMetadata`/`columnMetadata`. */
+export function applyDimensions(prev, rowChanges = [], columnChanges = []) {
+    // A commit may omit empty structural channels (or an engine adapter may pass a partial commit), so
+    // tolerate undefined rather than crash on `.length` (the default params coerce undefined → []).
+    if (!rowChanges.length && !columnChanges.length)
+        return prev;
+    return prev.map((sheet) => {
+        const rows = rowChanges.filter((c) => c.sheetId === sheet.sheetId);
+        const cols = columnChanges.filter((c) => c.sheetId === sheet.sheetId);
+        if (!rows.length && !cols.length)
+            return sheet;
+        const next = { ...sheet };
+        for (const [changes, key] of [
+            [rows, "rowMetadata"],
+            [cols, "columnMetadata"],
+        ]) {
+            if (!changes.length)
+                continue;
+            const meta = [...(next[key] ?? [])];
+            for (const change of changes)
+                meta[change.index] = change;
+            next[key] = meta;
+        }
+        return next;
+    });
+}
+/** Fold merge-region deltas into each sheet's `merges` (added appended, `removed` dropped by bounds). */
+export function applyMerges(prev, merges = []) {
+    if (!merges.length)
+        return prev;
+    const sameRange = (a, b) => a.startRowIndex === b.startRowIndex &&
+        a.endRowIndex === b.endRowIndex &&
+        a.startColumnIndex === b.startColumnIndex &&
+        a.endColumnIndex === b.endColumnIndex;
+    return prev.map((sheet) => {
+        const mine = merges.filter((m) => m.sheetId === sheet.sheetId);
+        if (!mine.length)
+            return sheet;
+        let list = [...(sheet.merges ?? [])];
+        for (const m of mine) {
+            list = list.filter((r) => !sameRange(r, m));
+            if (!m.removed) {
+                list.push({
+                    startRowIndex: m.startRowIndex,
+                    endRowIndex: m.endRowIndex,
+                    startColumnIndex: m.startColumnIndex,
+                    endColumnIndex: m.endColumnIndex,
+                });
+            }
+        }
+        return { ...sheet, merges: list };
+    });
+}
+/** Reconcile the render-state sheet list with the engine's AUTHORITATIVE sheet set + order + titles
+ * (from {@link RncEngine.sheets}). The engine owns sheet lifecycle — it generates ids for
+ * `create-sheet`, rewrites titles on rename, reorders on move, drops on delete — so the tab list is
+ * reconciled from it rather than guessed from the command (a `create-sheet` doesn't even carry the
+ * generated id). Per-sheet DIMENSION/MERGE metadata is preserved by reusing the existing `Sheet`
+ * object for a surviving id (those facets ride the commit channels, folded by {@link foldCommit});
+ * only the identity facets (`title`/`index`/`hidden`/`tabColor`) are taken from the engine.
+ *
+ * Returns the SAME `prev` array reference when nothing changed (every id, order, title, hidden,
+ * tabColor matches and each surviving sheet object is reused) — so a pure cell edit never churns the
+ * `sheets` prop. An empty `engineSheets` (a store that doesn't expose `sheets()`) leaves `prev` as-is. */
+export function reconcileSheets(prev, engineSheets) {
+    if (!engineSheets.length)
+        return prev;
+    const byId = new Map();
+    for (const s of prev)
+        byId.set(s.sheetId, s);
+    let changed = engineSheets.length !== prev.length;
+    const next = engineSheets.map((es, i) => {
+        const existing = byId.get(es.sheetId);
+        // Identity facets from the engine; everything else (dimensions/merges/counts) from the existing
+        // sheet (or sensible defaults for a freshly-created one).
+        const merged = {
+            ...(existing ?? {}),
+            sheetId: es.sheetId,
+            title: es.title,
+            hidden: es.hidden,
+            tabColor: es.tabColor,
+            showGridLines: es.showGridLines,
+            showRowColHeaders: es.showRowColHeaders,
+            showZeros: es.showZeros,
+            zoomScale: es.zoomScale,
+            rightToLeft: es.rightToLeft,
+            defaultRowHeight: es.defaultRowHeight,
+        };
+        // Detect churn: order changed, a new sheet, or an identity/view facet changed on a survivor.
+        if (!existing ||
+            prev[i]?.sheetId !== es.sheetId ||
+            existing.title !== es.title ||
+            existing.hidden !== es.hidden ||
+            existing.tabColor !== es.tabColor ||
+            existing.showGridLines !== es.showGridLines ||
+            existing.showRowColHeaders !== es.showRowColHeaders ||
+            existing.showZeros !== es.showZeros ||
+            existing.zoomScale !== es.zoomScale ||
+            existing.rightToLeft !== es.rightToLeft ||
+            existing.defaultRowHeight !== es.defaultRowHeight) {
+            changed = true;
+            return merged;
+        }
+        // Unchanged identity + same position → reuse the existing object reference (no churn).
+        return existing;
+    });
+    return changed ? next : prev;
+}
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+// WINDOWED render state — for a sheet so large (e.g. 1,000,000 rows) that folding EVERY changed
+// cell into JS would blow up memory. Instead of `foldCommit` (which accumulates all cells forever),
+// a windowed renderer holds ONLY the current viewport's cells + styles, refreshed from the engine's
+// `readWindow` on scroll (and on each commit). The state shape is identical to `EngineRenderState`,
+// so every accessor (`getCellData`/`getEffectiveFormat`/…) works unchanged.
+// ─────────────────────────────────────────────────────────────────────────────────────────────
+/** Reconstruct a renderer-shaped {@link CellData} from a lean {@link WindowCell}. `readWindow` is a
+ * RENDER window — it carries what to paint (`formatted` text + `number` + `isFormula`), not the full
+ * cell. We surface:
+ *   • `fv` — the formatted display string (what the grid draws),
+ *   • `ev` — the effective value as a scalar (`nv` for numbers, else `sv` for text),
+ *   • `ue` — a best-effort user-entered value reconstructed from the lean fields (no formula source
+ *     here — literals carry their number/text).
+ * This LOSSY reconstruction is the FALLBACK for engines without `readWindowCommit`; the primary path
+ * (`RncEngine.readWindow` over `readWindowCommit`) carries each cell VERBATIM (`cell`), so `ue.fv`
+ * (formula source), hyperlink, note, and the full `ev` survive. See `windowToSheetData`. */
+export function windowCellToCellData(c) {
+    const isNumber = c.number != null;
+    const ev = isNumber
+        ? { nv: c.number }
+        : { sv: c.formatted };
+    // The user-entered value: a formula cell carries its SOURCE (`c.formula`, e.g. `=SUM(A1:A2)`) so the
+    // formula bar / editor shows the formula, not its result; literals carry their number/text.
+    const ue = c.formula
+        ? { fv: c.formula }
+        : isNumber
+            ? { nv: c.number }
+            : { sv: c.formatted };
+    return { ue, ev, fv: c.formatted };
+}
+/** Replace a sheet's windowed cells with the snapshot's cells (1-indexed, sparse). Everything OUTSIDE
+ * the snapshot is evicted — only the window's rows/columns are retained, so JS memory stays bounded
+ * to the viewport regardless of sheet size. */
+export function windowToSheetData(prev, snapshot) {
+    const key = String(snapshot.sheetId);
+    const rows = [];
+    for (const c of snapshot.cells) {
+        const existing = rows[c.rowIndex];
+        const values = existing?.values ?? [];
+        // Use the cell VERBATIM when the lossless read carried it (`cell`); else reconstruct from the lean
+        // fields (the fallback for engines without `readWindowCommit`).
+        values[c.columnIndex] = c.cell ?? windowCellToCellData(c);
+        rows[c.rowIndex] = { values };
+    }
+    // Replace ONLY this sheet's data (drop the previous window); other sheets are untouched.
+    return { ...prev, [key]: rows };
+}
+/** Rebuild the consolidated style map for a windowed sheet from the snapshot's `styles`. Entries for
+ * the snapshot's sheet are dropped first (eviction), then the window's are set — so a stale style
+ * outside the viewport can't linger. Styles for OTHER sheets are preserved. */
+export function windowToStyles(prev, snapshot) {
+    const sheetPrefix = `${snapshot.sheetId}!`;
+    const next = new Map();
+    // Keep other sheets' styles; evict this sheet's prior window.
+    for (const [k, v] of prev)
+        if (!k.startsWith(sheetPrefix))
+            next.set(k, v);
+    for (const s of snapshot.styles) {
+        if (!s.format)
+            continue;
+        next.set(cellKey(s.sheetId, s.rowIndex, s.columnIndex), s.format);
+    }
+    return next;
+}
+/** Fold a {@link WindowSnapshot} into render state — the windowed analog of {@link foldCommit}. Holds
+ * ONLY the snapshot's cells + styles for its sheet (evicting the prior window), leaving the sheet
+ * lifecycle/dimension metadata (`sheets`) and other sheets untouched. The single entry point a
+ * windowed UI calls on scroll and after each commit. */
+export function windowToDerivedFormats(prev, snapshot) {
+    const sheetPrefix = `${snapshot.sheetId}!`;
+    const next = new Map();
+    // Keep other sheets' derived formats; evict this sheet's prior window.
+    for (const [k, v] of prev)
+        if (!k.startsWith(sheetPrefix))
+            next.set(k, v);
+    for (const s of snapshot.derivedFormats ?? []) {
+        if (!s.format)
+            continue;
+        next.set(cellKey(s.sheetId, s.rowIndex, s.columnIndex), s.format);
+    }
+    return next;
+}
+export function foldWindow(prev, snapshot) {
+    return foldWindows(prev, [snapshot]);
+}
+/** Serialization equality for the small payload objects a windowed read rebuilds fresh every time
+ * (cells, formats). Both sides come from the same construction path, so key order is stable; a
+ * false negative only forfeits reuse, never correctness. */
+function sameJson(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+}
+/** Content equality for a rebuilt style/derived-format map against the previous one. Entry values
+ * are compared by IDENTITY — the fold reuses the previous format object whenever the content
+ * matched, so `===` here means "every entry survived reuse" (and other sheets' entries are carried
+ * over by reference). */
+function stylesEqual(next, prev) {
+    if (next.size !== prev.size)
+        return false;
+    for (const [k, v] of next)
+        if (prev.get(k) !== v)
+            return false;
+    return true;
+}
+/** Fold SEVERAL window snapshots of the SAME sheet in one pass — the viewport window plus its frozen
+ * top/left/corner bands (see {@link frozenBandRanges}). The sheet's prior cells/styles are evicted
+ * ONCE, then every snapshot's cells/styles are merged in — folding the snapshots one-by-one through
+ * {@link foldWindow} would instead evict each band as the next one lands.
+ *
+ * IDENTITY-PRESERVING: a windowed read rebuilds every cell/format as a fresh object even when its
+ * content is unchanged (the window is re-read after EVERY commit, including remote echoes and
+ * edits outside the viewport). Downstream, new identities defeat React memoization and trip the
+ * grid's renderer-identity cache invalidation — a full cold re-derive of the viewport on every
+ * commit. So the fold reuses the previous state's objects at every level where content matches:
+ * cell → row → whole sheet array → style maps → the state object itself. A fold whose window
+ * content is identical to the previous state returns `prev` unchanged, which lets React bail out
+ * of the setState entirely. */
+export function foldWindows(prev, snapshots) {
+    const first = snapshots[0];
+    if (!first)
+        return prev;
+    const key = String(first.sheetId);
+    const prevRows = prev.sheetData[key];
+    const rows = [];
+    const sheetPrefix = `${first.sheetId}!`;
+    const cellStyles = new Map();
+    const derivedFormats = new Map();
+    // Keep other sheets' styles/derived formats; evict this sheet's prior window.
+    for (const [k, v] of prev.cellStyles)
+        if (!k.startsWith(sheetPrefix))
+            cellStyles.set(k, v);
+    for (const [k, v] of prev.derivedFormats)
+        if (!k.startsWith(sheetPrefix))
+            derivedFormats.set(k, v);
+    for (const snapshot of snapshots) {
+        for (const c of snapshot.cells) {
+            const values = rows[c.rowIndex]?.values ?? [];
+            // Use the cell VERBATIM when the lossless read carried it (`cell`); else reconstruct from the
+            // lean fields (the fallback for engines without `readWindowCommit`).
+            const built = c.cell ?? windowCellToCellData(c);
+            const prevCell = prevRows?.[c.rowIndex]?.values?.[c.columnIndex];
+            values[c.columnIndex] =
+                prevCell != null && sameJson(prevCell, built) ? prevCell : built;
+            rows[c.rowIndex] = { values };
+        }
+        for (const s of snapshot.styles) {
+            if (!s.format)
+                continue;
+            const k = cellKey(s.sheetId, s.rowIndex, s.columnIndex);
+            const prevFmt = prev.cellStyles.get(k);
+            cellStyles.set(k, prevFmt != null && sameJson(prevFmt, s.format) ? prevFmt : s.format);
+        }
+        for (const s of snapshot.derivedFormats ?? []) {
+            if (!s.format)
+                continue;
+            const k = cellKey(s.sheetId, s.rowIndex, s.columnIndex);
+            const prevFmt = prev.derivedFormats.get(k);
+            derivedFormats.set(k, prevFmt != null && sameJson(prevFmt, s.format) ? prevFmt : s.format);
+        }
+    }
+    // Row-level reuse: a row whose every cell survived per-cell reuse takes the previous row object;
+    // if EVERY row (including holes) matches, the whole sheet array keeps its identity.
+    let rowsAllReused = prevRows != null && rows.length === prevRows.length;
+    for (let i = 0; i < rows.length; i++) {
+        const row = rows[i];
+        const prevRow = prevRows?.[i];
+        if (row == null) {
+            // A hole (no cells in this row's window) only matches a hole.
+            if (prevRow != null)
+                rowsAllReused = false;
+            continue;
+        }
+        const values = row.values ?? [];
+        const prevValues = prevRow?.values;
+        let same = prevValues != null && prevValues.length === values.length;
+        if (same)
+            for (let j = 0; j < values.length; j++)
+                if (values[j] !== prevValues[j]) {
+                    same = false;
+                    break;
+                }
+        if (same)
+            rows[i] = prevRow;
+        else
+            rowsAllReused = false;
+    }
+    const nextRows = rowsAllReused && prevRows != null ? prevRows : rows;
+    const nextCellStyles = stylesEqual(cellStyles, prev.cellStyles)
+        ? prev.cellStyles
+        : cellStyles;
+    const nextDerivedFormats = stylesEqual(derivedFormats, prev.derivedFormats)
+        ? prev.derivedFormats
+        : derivedFormats;
+    if (nextRows === prevRows &&
+        nextCellStyles === prev.cellStyles &&
+        nextDerivedFormats === prev.derivedFormats)
+        return prev;
+    return {
+        ...prev,
+        sheetData: nextRows === prevRows
+            ? prev.sheetData
+            : { ...prev.sheetData, [key]: nextRows },
+        cellStyles: nextCellStyles,
+        derivedFormats: nextDerivedFormats,
+    };
+}
+/** Hard caps on the frozen-band spans a windowed read will load. Frozen panes occupy screen space, so
+ * only ~a screenful of frozen rows/columns can ever be visible — but the frozen COUNTS are unbounded
+ * (freeze "up to current row" deep in a million-row sheet stores that row as the count). Without a cap,
+ * one band read becomes `rows 1..count × window cols` — millions of `CellData` entries accumulated into
+ * a single `HashMap` inside the wasm store, whose resize overflows wasm32's 2 GiB allocation-layout
+ * limit and traps with hashbrown's "Hash table capacity overflow" panic, poisoning the shared engine.
+ * These caps bound the band read; frozen cells beyond them are off-screen and render blank only in the
+ * (already unusable) case of a frozen span taller/wider than the screen. */
+const MAX_FROZEN_BAND_ROWS = 512;
+const MAX_FROZEN_BAND_COLS = 128;
+/** The frozen-pane bands a windowed read must ALWAYS include alongside the viewport window: the top
+ * band (frozen rows × the window's columns), the left band (the window's rows × frozen columns), and
+ * the top-left corner (frozen rows × frozen columns). Frozen panes stay on screen at every scroll
+ * position, so their cells must never be evicted by the window fold — without these bands, scrolling
+ * past the frozen rows/columns blanks them. Bands already covered by the window (its edge sits at
+ * row/column 1) are omitted; a window starting INSIDE the frozen span only needs the uncovered part.
+ * Band spans are clamped to {@link MAX_FROZEN_BAND_ROWS}/{@link MAX_FROZEN_BAND_COLS}, and non-finite
+ * or fractional counts (a corrupted doc plane) are floored — `NaN` disables the band. */
+export function frozenBandRanges(w, frozenRowCount, frozenColumnCount) {
+    const topRows = Math.min(Math.floor(frozenRowCount), MAX_FROZEN_BAND_ROWS, w.startRow - 1);
+    const leftCols = Math.min(Math.floor(frozenColumnCount), MAX_FROZEN_BAND_COLS, w.startCol - 1);
+    const bands = [];
+    if (topRows > 0)
+        bands.push({
+            sheetId: w.sheetId,
+            startRow: 1,
+            startCol: w.startCol,
+            endRow: topRows,
+            endCol: w.endCol,
+        });
+    if (leftCols > 0)
+        bands.push({
+            sheetId: w.sheetId,
+            startRow: w.startRow,
+            startCol: 1,
+            endRow: w.endRow,
+            endCol: leftCols,
+        });
+    if (topRows > 0 && leftCols > 0)
+        bands.push({
+            sheetId: w.sheetId,
+            startRow: 1,
+            startCol: 1,
+            endRow: topRows,
+            endCol: leftCols,
+        });
+    return bands;
+}
+/** Fold a {@link WindowSnapshot} companion {@link CommitResult}, keeping the channels a windowed
+ * sheet can't re-read from the window: structural metadata (dimensions / merges) AND the whole-document
+ * object channels (charts / pivots). In windowed mode a commit's CELL changes are intentionally NOT
+ * accumulated (the window is re-read instead); but row/column metadata + merges, and charts + pivots,
+ * are not part of the window read (and `documentFacets` excludes charts), so they must fold here or a
+ * windowed sheet silently drops them — e.g. charts/pivots an xlsx import adds. Cells/styles are left
+ * for {@link foldWindow} to refresh. */
+export function foldCommitStructuralOnly(prev, commit) {
+    const sheets = applyMerges(applyDimensions(prev.sheets, commit.rowChanges, commit.columnChanges), commit.merges);
+    // `foldObjects` returns `prev` unchanged on an empty delta, so an edit-only commit stays churn-free.
+    const charts = foldObjects(prev.charts, commit.chartChanges.map((c) => ({ id: c.chartId, spec: c.chart })));
+    const pivotTables = foldObjects(prev.pivotTables, commit.pivotChanges.map((p) => ({ id: p.pivotId, spec: p.pivotTable })));
+    // Notes are a SIDE map (`getNote`), not cell data — the window re-read never delivers them, so
+    // unlike values/styles they must fold here too. Without this, an `update-note` on a windowed doc
+    // (and the notes carried by a reload/reproject snapshot or a remote commit) never reached
+    // `state.notes`: the note persisted in the doc but rendered nowhere — no corner indicator, no
+    // tooltip, and the note editor reopened empty. `foldNotes` returns `prev.notes` on an empty
+    // delta, keeping the churn-free contract.
+    const notes = foldNotes(prev.notes, commit.noteChanges ?? []);
+    if (sheets === prev.sheets &&
+        charts === prev.charts &&
+        pivotTables === prev.pivotTables &&
+        notes === prev.notes) {
+        return prev;
+    }
+    return { ...prev, sheets, charts, pivotTables, notes };
+}
+/** Fold a whole {@link CommitResult} into the render state — the single entry point a thin UI calls
+ * for every engine change-set (edit, undo/redo, load). Returns a new state (referentially changed
+ * only where a channel had deltas). */
+export function foldCommit(prev, commit) {
+    let sheets = applyDimensions(prev.sheets, commit.rowChanges, commit.columnChanges);
+    sheets = applyMerges(sheets, commit.merges);
+    // Values first, then the data-validation RESULT lands on each affected cell (not a side map).
+    let sheetData = applyChanges(prev.sheetData, commit.changes);
+    sheetData = foldDataValidationResults(sheetData, commit.validations);
+    return {
+        sheets,
+        sheetData,
+        cellStyles: foldStyles(prev.cellStyles, commit.styleChanges),
+        // Render-only inherited formats (`=SUM($a,$b)` → currency). Empty/absent when no formula cell
+        // changed (the engine skip-serializes it), so default to `[]`.
+        derivedFormats: foldStyles(prev.derivedFormats, commit.derivedFormatChanges ?? []),
+        notes: foldNotes(prev.notes, commit.noteChanges),
+        charts: foldObjects(prev.charts, commit.chartChanges.map((c) => ({ id: c.chartId, spec: c.chart }))),
+        pivotTables: foldObjects(prev.pivotTables, commit.pivotChanges.map((p) => ({ id: p.pivotId, spec: p.pivotTable }))),
+    };
+}