@rowsncolumns/rnc-engine 0.10.132

package/dist/esm/command-handlers.js

@@ -0,0 +1,404 @@
+/** Two-digit zero-pad for the ISO date/time literals below. */
+const pad2 = (n) => String(n).padStart(2, "0");
+/** The Rust merge treats an absent patch key as "leave unchanged", and JSON.stringify drops a
+ * present-but-undefined key — so a toolbar toggle-off (`{ baselineOffset: undefined }`) would
+ * reach the engine as an empty patch and silently no-op. Present-but-nullish `baselineOffset` is
+ * the UI's clear intent; translate it to the engine's explicit-clear sentinel (`"none"`, which
+ * `TextFormat::merge` collapses back to unset) before the JSON boundary. */
+const normalizeFormatPatch = (cellFormat) => {
+    if (!cellFormat || Array.isArray(cellFormat))
+        return cellFormat;
+    const tf = cellFormat.textFormat;
+    if (tf && "baselineOffset" in tf && tf.baselineOffset == null) {
+        return {
+            ...cellFormat,
+            textFormat: { ...tf, baselineOffset: "none" },
+        };
+    }
+    return cellFormat;
+};
+/** Local calendar date as ISO `YYYY-MM-DD` — locale-independent, so the engine infers it as a date. */
+const isoDate = (d) => `${d.getFullYear()}-${pad2(d.getMonth() + 1)}-${pad2(d.getDate())}`;
+/** Local wall-clock as `HH:MM:SS` — the engine infers it as a time. */
+const isoTime = (d) => `${pad2(d.getHours())}:${pad2(d.getMinutes())}:${pad2(d.getSeconds())}`;
+/**
+ * Build the {@link EngineSpreadsheetHandlers} over a single `onCommand` sink. Pure (no React) —
+ * `useEngineCore` wraps this in a `useMemo([onCommand])`.
+ */
+export function createCommandHandlers(onCommand) {
+    return {
+        // Cell values
+        onChange: (sheetId, coords, value, textFormatRuns) => onCommand({ command: "set-value", sheetId, coords, value, textFormatRuns }),
+        onChangeBatch: (sheetId, ranges, values, formatting, citations, options) => onCommand({ command: "change-batch", sheetId, ranges, values, formatting, citations, options }),
+        onDelete: (sheetId, activeCell, selections, clearType) => onCommand({ command: "delete-cells", sheetId, activeCell, selections, clearType }),
+        // `SS["onFill"]` is async (returns `Promise<void>`); the command is emitted synchronously.
+        onFill: async (sheetId, activeCell, fillSelection, selections, fillableSelections, fillType) => {
+            onCommand({ command: "fill", sheetId, activeCell, fillSelection, selections, fillableSelections, fillType });
+        },
+        // Range fill (CanvasGrid's Cmd+D / Cmd+R shortcuts, plus UP/LEFT for callers that send them).
+        // Mirrors `useOnFillRange`: from the `direction`, derive the SOURCE range to repeat — the
+        // adjacent row/column beyond the selection for a single-line selection, else the selection's own
+        // leading (DOWN/RIGHT) or trailing (UP/LEFT) line — then emit the `fill` command with the
+        // selection as the target. `fillType` stays "FillCopy" (Excel's Ctrl+D copies; series detection
+        // is reserved for fill-handle drags, which arrive via `onFill` and auto-detect in the engine).
+        // `String(direction)` avoids the grid-vs-common-types `Direction` enum identity mismatch while
+        // comparing the shared "DOWN"/"UP"/"RIGHT"/"LEFT" values.
+        onFillRange: (sheetId, activeCell, selections, direction) => {
+            const fillSelections = selections.length
+                ? selections
+                : [
+                    {
+                        range: {
+                            startRowIndex: activeCell.rowIndex,
+                            endRowIndex: activeCell.rowIndex,
+                            startColumnIndex: activeCell.columnIndex,
+                            endColumnIndex: activeCell.columnIndex,
+                        },
+                    },
+                ];
+            const firstSel = fillSelections[0];
+            const dir = String(direction);
+            if (dir === "DOWN") {
+                const isSingleRow = firstSel.range.startRowIndex === firstSel.range.endRowIndex;
+                if (isSingleRow && firstSel.range.startRowIndex <= 1)
+                    return;
+                const source = fillSelections.map((sel) => isSingleRow
+                    ? {
+                        ...sel,
+                        range: {
+                            ...sel.range,
+                            startRowIndex: sel.range.startRowIndex - 1,
+                            endRowIndex: sel.range.endRowIndex - 1,
+                        },
+                    }
+                    : {
+                        ...sel,
+                        range: { ...sel.range, endRowIndex: sel.range.startRowIndex },
+                    });
+                onCommand({
+                    command: "fill",
+                    sheetId,
+                    activeCell,
+                    fillSelection: fillSelections[0],
+                    selections: source,
+                    fillableSelections: selections,
+                    fillType: "FillCopy",
+                });
+            }
+            else if (dir === "UP") {
+                const isSingleRow = firstSel.range.startRowIndex === firstSel.range.endRowIndex;
+                const source = fillSelections.map((sel) => isSingleRow
+                    ? {
+                        ...sel,
+                        range: {
+                            ...sel.range,
+                            startRowIndex: sel.range.startRowIndex + 1,
+                            endRowIndex: sel.range.endRowIndex + 1,
+                        },
+                    }
+                    : {
+                        ...sel,
+                        range: { ...sel.range, startRowIndex: sel.range.endRowIndex },
+                    });
+                onCommand({
+                    command: "fill",
+                    sheetId,
+                    activeCell,
+                    fillSelection: fillSelections[0],
+                    selections: source,
+                    fillableSelections: fillSelections,
+                    fillType: "FillCopy",
+                });
+            }
+            else if (dir === "RIGHT") {
+                const isSingleCol = firstSel.range.startColumnIndex === firstSel.range.endColumnIndex;
+                if (isSingleCol && firstSel.range.startColumnIndex <= 1)
+                    return;
+                const source = fillSelections.map((sel) => isSingleCol
+                    ? {
+                        ...sel,
+                        range: {
+                            ...sel.range,
+                            startColumnIndex: sel.range.startColumnIndex - 1,
+                            endColumnIndex: sel.range.endColumnIndex - 1,
+                        },
+                    }
+                    : {
+                        ...sel,
+                        range: {
+                            ...sel.range,
+                            endColumnIndex: sel.range.startColumnIndex,
+                        },
+                    });
+                onCommand({
+                    command: "fill",
+                    sheetId,
+                    activeCell,
+                    fillSelection: fillSelections[0],
+                    selections: source,
+                    fillableSelections: fillSelections,
+                    fillType: "FillCopy",
+                });
+            }
+            else if (dir === "LEFT") {
+                const isSingleCol = firstSel.range.startColumnIndex === firstSel.range.endColumnIndex;
+                const source = fillSelections.map((sel) => isSingleCol
+                    ? {
+                        ...sel,
+                        range: {
+                            ...sel.range,
+                            startColumnIndex: sel.range.startColumnIndex + 1,
+                            endColumnIndex: sel.range.endColumnIndex + 1,
+                        },
+                    }
+                    : {
+                        ...sel,
+                        range: {
+                            ...sel.range,
+                            startColumnIndex: sel.range.endColumnIndex,
+                        },
+                    });
+                onCommand({
+                    command: "fill",
+                    sheetId,
+                    activeCell,
+                    fillSelection: fillSelections[0],
+                    selections: source,
+                    fillableSelections: fillSelections,
+                    fillType: "FillCopy",
+                });
+            }
+        },
+        // `SS` types `selections`/`delimiter` as optional; default to a no-op-safe shape for the command.
+        onSplitTextToColumns: (sheetId, activeCell, selections, delimiter) => onCommand({
+            command: "split-text-to-columns",
+            sheetId,
+            activeCell,
+            selections: selections ?? [],
+            delimiter: delimiter ?? "",
+        }),
+        // `SS["onRemoveDuplicates"]` is `(sheetId, activeCell, selections?)` — no `columnIndices` (the
+        // engine dedups over the selection's columns). The reference returns `RemoveDuplicatesResult`
+        // (duplicate/unique row counts) computed inline; here the dedupe runs inside the wasm engine
+        // behind the fire-and-forget `onCommand` sink and `CommitResult` carries no counts channel, so
+        // the emitter reports `undefined` — the "counts unavailable" arm the SS contract allows.
+        onRemoveDuplicates: (sheetId, activeCell, selections) => {
+            onCommand({
+                command: "remove-duplicates",
+                sheetId,
+                activeCell,
+                selections: selections ?? [],
+            });
+            return undefined;
+        },
+        onFindReplace: (ranges, find, replace, matchCase, wholeWord, useRegex) => onCommand({ command: "find-replace", ranges, find, replace, matchCase, wholeWord, useRegex }),
+        // Formatting — overloaded (`SS["onChangeFormatting"]`): a string 4th arg is the UI `(type, value)`
+        // form with `options` 6th; otherwise it's a CellFormat (the toolbar form) with `options` 5th (in
+        // the `value` slot). `options` rides the command — `{ replace: true }` is the format-painter
+        // semantics (the pattern fully replaces the target's format instead of merging onto it).
+        onChangeFormatting: (sheetId, activeCell, selections, cellFormat, value, options) => onCommand({
+            command: "change-formatting",
+            sheetId,
+            activeCell,
+            selections,
+            cellFormat: normalizeFormatPatch(typeof cellFormat === "string"
+                ? { [cellFormat]: value }
+                : cellFormat),
+            options: (typeof cellFormat === "string"
+                ? options
+                : value),
+        }),
+        onChangeBorder: (sheetId, activeCell, selections, location, color, style) => onCommand({ command: "change-border", sheetId, activeCell, selections, location, color, style }),
+        onClearFormatting: (sheetId, activeCell, selections) => onCommand({ command: "clear-formatting", sheetId, activeCell, selections }),
+        onChangeDecimals: (sheetId, activeCell, selections, type) => onCommand({ command: "change-decimals", sheetId, activeCell, selections, type }),
+        onIncreaseIndent: (sheetId, activeCell, selections) => onCommand({ command: "increase-indent", sheetId, activeCell, selections }),
+        onDecreaseIndent: (sheetId, activeCell, selections) => onCommand({ command: "decrease-indent", sheetId, activeCell, selections }),
+        onChangeIndent: (sheetId, activeCell, selections, shouldIncrease) => onCommand({ command: "change-indent", sheetId, activeCell, selections, shouldIncrease }),
+        // Insert the current date/time: the HOST stamps the clock (the literal travels in the command, so
+        // it's deterministic for undo/replay); the ENGINE infers the serial + applies the date/time format.
+        onInsertDate: (sheetId, activeCell) => onCommand({
+            command: "set-value",
+            sheetId,
+            coords: activeCell,
+            value: isoDate(new Date()),
+            textFormatRuns: undefined,
+        }),
+        onInsertTime: (sheetId, activeCell) => onCommand({
+            command: "set-value",
+            sheetId,
+            coords: activeCell,
+            value: isoTime(new Date()),
+            textFormatRuns: undefined,
+        }),
+        onInsertDateTime: (sheetId, activeCell) => {
+            const d = new Date();
+            onCommand({
+                command: "set-value",
+                sheetId,
+                coords: activeCell,
+                value: `${isoDate(d)} ${isoTime(d)}`,
+                textFormatRuns: undefined,
+            });
+        },
+        // AutoSum: the engine scans the off-window numeric run and writes `=FN(range)` into the cell.
+        onInsertAutoSum: (sheetId, activeCell, functionName) => onCommand({ command: "insert-autosum", sheetId, activeCell, functionName }),
+        onMergeCells: (sheetId, activeCell, selections, direction) => onCommand({ command: "merge-cells", sheetId, activeCell, selections, direction }),
+        onUnMergeCells: (sheetId, activeCell, selections) => onCommand({ command: "unmerge-cells", sheetId, activeCell, selections }),
+        // Rows & Columns
+        onInsertRow: (sheetId, referenceRowIndex, numRows) => onCommand({ command: "insert-row", sheetId, referenceRowIndex, numRows }),
+        onInsertColumn: (sheetId, referenceColumnIndex, numColumns) => onCommand({ command: "insert-column", sheetId, referenceColumnIndex, numColumns }),
+        onDeleteRow: (sheetId, rowIndexes) => onCommand({ command: "delete-row", sheetId, rowIndexes }),
+        onDeleteColumn: (sheetId, columnIndexes) => onCommand({ command: "delete-column", sheetId, columnIndexes }),
+        onMoveRows: (sheetId, rows, referenceRowIndex) => onCommand({ command: "move-rows", sheetId, rows, referenceRowIndex }),
+        onMoveColumns: (sheetId, columns, referenceColumnIndex) => onCommand({ command: "move-columns", sheetId, columns, referenceColumnIndex }),
+        onMoveSelection: (sheetId, from, to) => onCommand({ command: "move-range", sheetId, from: from.range, to: to.range }),
+        onHideRow: (sheetId, rowIndexes) => onCommand({ command: "hide-row", sheetId, rowIndexes }),
+        onShowRow: (sheetId, rowIndexes) => onCommand({ command: "show-row", sheetId, rowIndexes }),
+        onHideColumn: (sheetId, columnIndexes) => onCommand({ command: "hide-column", sheetId, columnIndexes }),
+        onShowColumn: (sheetId, columnIndexes) => onCommand({ command: "show-column", sheetId, columnIndexes }),
+        onGroupRows: (sheetId, rowIndexes) => onCommand({ command: "group-rows", sheetId, rowIndexes }),
+        onUngroupRows: (sheetId, rowIndexes) => onCommand({ command: "ungroup-rows", sheetId, rowIndexes }),
+        onCollapseRowGroup: (sheetId, summaryRowIndex) => onCommand({ command: "collapse-row-group", sheetId, summaryRowIndex }),
+        onExpandRowGroup: (sheetId, summaryRowIndex) => onCommand({ command: "expand-row-group", sheetId, summaryRowIndex }),
+        onGroupColumns: (sheetId, columnIndexes) => onCommand({ command: "group-columns", sheetId, columnIndexes }),
+        onUngroupColumns: (sheetId, columnIndexes) => onCommand({ command: "ungroup-columns", sheetId, columnIndexes }),
+        onCollapseColumnGroup: (sheetId, summaryColumnIndex) => onCommand({ command: "collapse-column-group", sheetId, summaryColumnIndex }),
+        onExpandColumnGroup: (sheetId, summaryColumnIndex) => onCommand({ command: "expand-column-group", sheetId, summaryColumnIndex }),
+        onSetOutlineDepth: (sheetId, axis, depth) => onCommand({ command: "set-outline-depth", sheetId, axis, depth }),
+        onResize: (sheetId, indexes, dimension, axis, autoFit) => onCommand({ command: "resize", sheetId, indexes, dimension, axis, autoFit }),
+        onAutoResize: (sheetId, indexes, axis, sizes) => onCommand({ command: "auto-resize", sheetId, indexes, axis, sizes }),
+        onFreezeRow: (sheetId, rowIndex) => onCommand({ command: "freeze-row", sheetId, rowIndex }),
+        onFreezeColumn: (sheetId, columnIndex) => onCommand({ command: "freeze-column", sheetId, columnIndex }),
+        onInsertCellsShiftDown: (sheetId, activeCell, selections) => onCommand({ command: "insert-cells-shift-down", sheetId, activeCell, selections }),
+        onInsertCellsShiftRight: (sheetId, activeCell, selections) => onCommand({ command: "insert-cells-shift-right", sheetId, activeCell, selections }),
+        onDeleteCellsShiftUp: (sheetId, activeCell, selections) => onCommand({ command: "delete-cells-shift-up", sheetId, activeCell, selections }),
+        onDeleteCellsShiftLeft: (sheetId, activeCell, selections) => onCommand({ command: "delete-cells-shift-left", sheetId, activeCell, selections }),
+        // Sheets — grid form returns the created Sheet | undefined (engine creates async → undefined).
+        onCreateNewSheet: (sheetSpec) => {
+            onCommand({ command: "create-sheet", sheetSpec });
+            return undefined;
+        },
+        onDeleteSheet: (sheetId) => onCommand({ command: "delete-sheet", sheetId }),
+        onRenameSheet: (sheetId, name, oldName) => onCommand({ command: "rename-sheet", sheetId, name, oldName }),
+        onMoveSheet: (sheetId, currentPosition, newPosition) => onCommand({ command: "move-sheet", sheetId, currentPosition, newPosition }),
+        onDuplicateSheet: (sheetId) => onCommand({ command: "duplicate-sheet", sheetId }),
+        onHideSheet: (sheetId) => onCommand({ command: "hide-sheet", sheetId }),
+        onShowSheet: (sheetId) => onCommand({ command: "show-sheet", sheetId }),
+        onChangeSheetTabColor: (sheetId, color) => onCommand({ command: "change-sheet-tab-color", sheetId, color }),
+        // Sort & Filter
+        onSortColumn: (sheetId, sortedColumnIndex, sortOrder) => onCommand({ command: "sort-column", sheetId, sortedColumnIndex, sortOrder }),
+        onSortRange: (sheetId, selections, sortOrder) => onCommand({ command: "sort-range", sheetId, selections, sortOrder }),
+        onSortTable: (sheetId, filter, dimensionIndex, sortOrder) => onCommand({ command: "sort-table", sheetId, filter, dimensionIndex, sortOrder }),
+        onFilterTable: (sheetId, filter, columnIndex, conditionType, conditionValue, visibleValues, extras) => onCommand({
+            command: "filter-table",
+            sheetId,
+            filter,
+            columnIndex,
+            conditionType,
+            conditionValue,
+            visibleValues,
+            // `undefined` keys drop out of the JSON command (carry the existing criterion forward);
+            // `null` survives as the explicit clear marker. Mirrors `createFilterSpecs` extras.
+            colorFilter: extras?.colorFilter,
+            iconFilter: extras?.iconFilter,
+        }),
+        onDeleteFilter: (sheetId, filter, columnIndex) => onCommand({ command: "delete-filter", sheetId, filter, columnIndex }),
+        onCreateBasicFilter: (sheetId, activeCell, selections, basicFilterSpec) => onCommand({ command: "create-basic-filter", sheetId, activeCell, selections, basicFilterSpec }),
+        // Tables
+        onCreateTable: (sheetId, activeCell, selections, tableSpec, theme, bandedRange) => onCommand({ command: "create-table", sheetId, activeCell, selections, tableSpec, theme, bandedRange }),
+        onRemoveTable: (tableView) => onCommand({ command: "remove-table", tableView }),
+        onUpdateTable: (sheetId, tableId, updatedTable) => onCommand({ command: "update-table", sheetId, tableId, updatedTable }),
+        onResizeTable: (sheetId, table, range) => onCommand({ command: "resize-table", sheetId, table, range }),
+        onInsertTableRow: (tableView, relativeRowIndex, rowData) => onCommand({ command: "insert-table-row", tableView, relativeRowIndex, rowData }),
+        onDeleteTableRow: (tableView, rowIndexes) => onCommand({ command: "delete-table-row", tableView, rowIndexes }),
+        onInsertTableColumn: (tableView, dimensionIndex, direction) => onCommand({ command: "insert-table-column", tableView, dimensionIndex, direction }),
+        onDeleteTableColumn: (tableView, dimensionIndex) => onCommand({ command: "delete-table-column", tableView, dimensionIndex }),
+        onMoveTableColumns: (sheetId, tableId, columns, referenceColumnIndex) => onCommand({ command: "move-table-columns", sheetId, tableId, columns, referenceColumnIndex }),
+        onChangeTableColumn: (sheetId, tableId, columnIndex, name) => onCommand({ command: "change-table-column", sheetId, tableId, columnIndex, name }),
+        onCalculatedColumn: (sheetId, tableId, columnIndex, formula, fromRowIndex) => onCommand({ command: "calculated-column", sheetId, tableId, columnIndex, formula, fromRowIndex }),
+        // Named Ranges
+        onCreateNamedRange: (sheetId, namedRange) => onCommand({ command: "create-named-range", sheetId, namedRange }),
+        onUpdateNamedRange: (sheetId, namedRange, previousNamedRange) => onCommand({ command: "update-named-range", sheetId, namedRange, previousNamedRange }),
+        onDeleteNamedRange: (namedRangeId) => onCommand({ command: "delete-named-range", namedRangeId }),
+        // Notes & special inserts
+        onUpdateNote: (sheetId, activeCell, note) => onCommand({ command: "update-note", sheetId, activeCell, note }),
+        onInsertLink: (sheetId, activeCell, selections, url, title) => onCommand({ command: "insert-link", sheetId, activeCell, selections, url, title }),
+        onRemoveLink: (sheetId, activeCell, selections) => onCommand({ command: "remove-link", sheetId, activeCell, selections }),
+        onInsertImage: (sheetId, activeCell, imageUrl, width, height, insertOverCells, embedId) => onCommand({ command: "insert-image", sheetId, activeCell, imageUrl, width, height, insertOverCells, embedId }),
+        onInsertCheckbox: (sheetId, activeCell, selections) => onCommand({ command: "insert-checkbox", sheetId, activeCell, selections }),
+        // Comments (only the host-managed thread id rides on the cell; content is the host's)
+        onInsertComment: (sheetId, rowIndex, columnIndex, commentThreadId) => onCommand({ command: "insert-comment", sheetId, rowIndex, columnIndex, commentThreadId }),
+        onRemoveComment: (sheetId, rowIndex, columnIndex) => onCommand({ command: "remove-comment", sheetId, rowIndex, columnIndex }),
+        // Citations (collection add + per-cell `citationId` link; remove-from-cell keeps the collection)
+        onCreateCitation: (sheetId, rowIndex, columnIndex, citation) => onCommand({ command: "create-citation", sheetId, rowIndex, columnIndex, citation }),
+        onUpdateCitation: (citationId, updates) => onCommand({ command: "update-citation", citationId, updates }),
+        onDeleteCitation: (citationId) => onCommand({ command: "delete-citation", citationId }),
+        onRemoveCitationFromCell: (sheetId, rowIndex, columnIndex) => onCommand({ command: "remove-citation-from-cell", sheetId, rowIndex, columnIndex }),
+        // Conditional Formatting (onCreateConditionalFormattingRule is hook-exposed — reads active sheet).
+        // These take the SAME rule-object args as `useSpreadsheetState`; the engine pulls `id` off the rule
+        // and emits the id-based command (the wire shape stays id-based; only the call surface matches SS).
+        // `previousRule` isn't needed — the engine re-derives the affected ranges from the committed rule set.
+        onUpdateConditionalFormattingRule: (updatedRule) => onCommand({
+            command: "update-conditional-format",
+            ruleId: updatedRule.id,
+            rule: updatedRule,
+        }),
+        onDeleteConditionalFormattingRule: (rule) => onCommand({ command: "delete-conditional-format", ruleId: rule.id }),
+        // Live preview: overlay the candidate rule in the engine (no persist, no undo). `null` clears it.
+        onPreviewConditionalFormattingRule: (rule) => onCommand({ command: "preview-conditional-format", rule: rule ?? null }),
+        // Data Validations — rule-object API (matches SS). The rule carries its own `ranges`; derive the
+        // target sheet + range from `ranges[0]` (the editor always supplies at least one range). `options`
+        // / `previousRule` are unused — the engine re-derives validity for every covered cell.
+        onCreateDataValidationRule: (rule) => {
+            const range = rule.ranges?.[0];
+            if (!range)
+                return;
+            onCommand({
+                command: "create-data-validation",
+                sheetId: range.sheetId,
+                range,
+                rule,
+            });
+        },
+        onUpdateDataValidationRule: (rule) => onCommand({ command: "update-data-validation", ruleId: rule.id, rule }),
+        onDeleteDataValidationRule: (rule) => onCommand({ command: "delete-data-validation", ruleId: rule.id }),
+        // Banded Ranges
+        onAddBandedRange: (sheetId, bandedRange) => onCommand({ command: "add-banded-range", sheetId, bandedRange }),
+        onRemoveBandedRange: (sheetId, bandedRange) => onCommand({ command: "remove-banded-range", sheetId, bandedRange }),
+        // Protected Ranges
+        onProtectRange: (sheetId, activeCell, selections) => onCommand({ command: "protect-range", sheetId, activeCell, selections }),
+        onUnProtectRange: (sheetId, protectedRangeId) => onCommand({ command: "unprotect-range", sheetId, protectedRangeId }),
+        onProtectSheet: (sheetId) => onCommand({ command: "protect-sheet", sheetId }),
+        onUnProtectSheet: (sheetId) => onCommand({ command: "unprotect-sheet", sheetId }),
+        // Embeds
+        onCreateEmbed: (spec) => onCommand({ command: "create-embed", spec }),
+        onUpdateEmbed: (embed) => onCommand({ command: "update-embed", embed }),
+        onMoveEmbed: (embedId, sheetId, anchorCell, offsetXPixels, offsetYPixels) => onCommand({ command: "move-embed", embedId, sheetId, anchorCell, offsetXPixels, offsetYPixels }),
+        onResizeEmbed: (embedId, sheetId, anchorCell, offsetXPixels, offsetYPixels, width, height) => onCommand({ command: "resize-embed", embedId, sheetId, anchorCell, offsetXPixels, offsetYPixels, width, height }),
+        onDeleteEmbed: (embedId) => onCommand({ command: "delete-embed", embedId }),
+        // Slicers
+        onCreateSlicer: (slicer) => onCommand({ command: "create-slicer", slicer }),
+        onUpdateSlicer: (slicer) => onCommand({ command: "update-slicer", slicer }),
+        onMoveSlicer: (slicerId, sheetId, anchorCell, offsetXPixels, offsetYPixels) => onCommand({ command: "move-slicer", slicerId, sheetId, anchorCell, offsetXPixels, offsetYPixels }),
+        onResizeSlicer: (slicerId, sheetId, anchorCell, offsetXPixels, offsetYPixels, width, height) => onCommand({ command: "resize-slicer", slicerId, sheetId, anchorCell, offsetXPixels, offsetYPixels, width, height }),
+        onDeleteSlicer: (slicerId) => onCommand({ command: "delete-slicer", slicerId }),
+        // Charts (onMoveChart / onResizeChart are hook-exposed — they read the active sheet from view state)
+        onCreateChart: (spec) => onCommand({ command: "create-chart", spec }),
+        onUpdateChart: (chart) => onCommand({ command: "update-chart", chart }),
+        onDeleteChart: (chartId) => onCommand({ command: "delete-chart", chartId }),
+        // Pivot tables
+        onCreatePivotTable: (pivotTable) => onCommand({ command: "create-pivot-table", pivotTable }),
+        onUpdatePivotTable: (pivotId, pivotTable) => onCommand({ command: "update-pivot-table", pivotId, pivotTable }),
+        onDeletePivotTable: (pivotId) => onCommand({ command: "delete-pivot-table", pivotId }),
+        onRefreshPivot: (pivotId) => onCommand({ command: "refresh-pivot", pivotId }),
+        onExpandPivotRow: (pivotId, groupKeys) => onCommand({ command: "expand-pivot-row", pivotId, groupKeys }),
+        onCollapsePivotRow: (pivotId, groupKeys) => onCommand({ command: "collapse-pivot-row", pivotId, groupKeys }),
+        onExpandPivotColumn: (pivotId, path) => onCommand({ command: "expand-pivot-column", pivotId, path }),
+        onCollapsePivotColumn: (pivotId, path) => onCommand({ command: "collapse-pivot-column", pivotId, path }),
+        onDrillDownPivot: (pivotId, filters, cell) => onCommand({ command: "drill-down-pivot", pivotId, filters, cell }),
+        // Theme / Locale
+        onChangeSpreadsheetTheme: (theme) => onCommand({ command: "change-theme", theme }),
+        // The 2nd arg (`previousLocale`) is unnecessary: the engine re-derives it from current state.
+        onChangeLocale: (locale) => onCommand({ command: "change-locale", locale }),
+    };
+}

package/dist/esm/fold.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Pure reducers that fold the engine's {@link CommitResult} channels into the minimal render state a
+ * thin "Option B" UI needs — no calc, no dependency graph, no immer. The engine is the authority; the
+ * UI just applies these deltas. {@link useEngineCore} wraps these in React state; they're kept
+ * pure (and exported) so they're unit-testable without a renderer or the wasm module.
+ */
+import type { CellData, CellFormat, SheetData } from "@rowsncolumns/common-types";
+import type { EmbeddedChart, PivotTable, Sheet } from "@rowsncolumns/spreadsheet";
+import type { CellChange, CommitResult, DimensionChange, EngineSheet, MergeChange, NoteEntry, StyleEntry, ValidationStatus, WindowCell, WindowSnapshot } from "./index";
+/** Everything a thin renderer keeps in sync from the engine. Values live in `sheetData`; styles,
+ * CF-derived styles, validity, notes, and objects live in their own maps (the same split the engine
+ * streams on). The canonical `Sheet` carries the lifecycle/dimension metadata the reducers fold into. */
+export interface EngineRenderState {
+    sheets: Sheet[];
+    sheetData: SheetData<CellData>;
+    /** `Map<"sheetId!A1", CellFormat>` — a cell's own consolidated style. */
+    cellStyles: Map<string, CellFormat>;
+    /** `Map<"sheetId!A1", CellFormat>` — render-only DERIVED formats: a formula cell's INHERITED
+     * number format (`=SUM($a,$b)` → currency), streamed by the engine and layered UNDER the user's
+     * own style in `getEffectiveFormat`. Never persisted (distinct from `cellStyles`); mirrors the JS
+     * reference's `getDerivedFormat`, but single-sourced in the engine so it survives a backend move. */
+    derivedFormats: Map<string, CellFormat>;
+    /** `Map<"sheetId!A1", note>`. */
+    notes: Map<string, string>;
+    /** Chart / pivot specs by id (the canonical EmbeddedChart / PivotTable, round-tripped by the engine). */
+    charts: Map<EmbeddedChart["chartId"], EmbeddedChart>;
+    pivotTables: Map<PivotTable["pivotId"], PivotTable>;
+}
+/** An empty render state (seed with your initial sheets). */
+export declare function emptyRenderState(sheets?: Sheet[]): EngineRenderState;
+/** Set one cell (1-indexed), creating the sparse row/column slots immutably. */
+export declare function setCell(prev: SheetData<CellData>, sheetId: number, row: number, col: number, mut: (cell: CellData) => CellData): SheetData<CellData>;
+/** 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 declare function applyChange(cell: CellData, ch: CellChange): CellData;
+/** Stream the engine's cell change-set into `sheetData`. */
+export declare function applyChanges(prev: SheetData<CellData>, changes: CellChange[]): SheetData<CellData>;
+/** 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 declare function foldStyles(prev: Map<string, CellFormat>, styles: StyleEntry[]): Map<string, CellFormat>;
+/** 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 declare function foldDataValidationResults(prev: SheetData<CellData>, vals: ValidationStatus[]): SheetData<CellData>;
+/** Fold per-cell note deltas (`note: null` = cleared). */
+export declare function foldNotes(prev: Map<string, string>, notes: NoteEntry[]): Map<string, string>;
+/** Fold id-keyed object spec deltas (charts / pivots; `null` spec = deleted). */
+export declare function foldObjects<T>(prev: Map<string | number, T>, deltas: {
+    id: string | number;
+    spec: T | null;
+}[]): Map<string | number, T>;
+/** Fold row/column metadata deltas into each sheet's `rowMetadata`/`columnMetadata`. */
+export declare function applyDimensions(prev: Sheet[], rowChanges?: DimensionChange[], columnChanges?: DimensionChange[]): Sheet[];
+/** Fold merge-region deltas into each sheet's `merges` (added appended, `removed` dropped by bounds). */
+export declare function applyMerges(prev: Sheet[], merges?: MergeChange[]): Sheet[];
+/** 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 declare function reconcileSheets(prev: Sheet[], engineSheets: EngineSheet[]): Sheet[];
+/** 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 declare function windowCellToCellData(c: WindowCell): CellData;
+/** 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 declare function windowToSheetData(prev: SheetData<CellData>, snapshot: WindowSnapshot): SheetData<CellData>;
+/** 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 declare function windowToStyles(prev: Map<string, CellFormat>, snapshot: WindowSnapshot): Map<string, CellFormat>;
+/** 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 declare function windowToDerivedFormats(prev: Map<string, CellFormat>, snapshot: WindowSnapshot): Map<string, CellFormat>;
+export declare function foldWindow(prev: EngineRenderState, snapshot: WindowSnapshot): EngineRenderState;
+/** 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 declare function foldWindows(prev: EngineRenderState, snapshots: WindowSnapshot[]): EngineRenderState;
+/** A windowed read's buffered range — 1-indexed inclusive engine coordinates. */
+export type WindowRange = {
+    sheetId: number;
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+};
+/** 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 declare function frozenBandRanges(w: WindowRange, frozenRowCount: number, frozenColumnCount: number): WindowRange[];
+/** 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 declare function foldCommitStructuralOnly(prev: EngineRenderState, commit: CommitResult): EngineRenderState;
+/** 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 declare function foldCommit(prev: EngineRenderState, commit: CommitResult): EngineRenderState;
+//# sourceMappingURL=fold.d.ts.map

package/dist/esm/fold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fold.d.ts","sourceRoot":"","sources":["../../src/fold.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,UAAU,EAEV,SAAS,EACV,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,KAAK,EACN,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,UAAU,EACV,gBAAgB,EAChB,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAC;AAGjB;;yGAEyG;AACzG,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC/B,yEAAyE;IACzE,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACpC;;;yGAGqG;IACrG,cAAc,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IAKxC,iCAAiC;IACjC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3B,yGAAyG;IACzG,MAAM,EAAE,GAAG,CAAC,aAAa,CAAC,SAAS,CAAC,EAAE,aAAa,CAAC,CAAC;IACrD,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,UAAU,CAAC,CAAC;CACrD;AAED,6DAA6D;AAC7D,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,KAAK,EAAO,GAAG,iBAAiB,CAUxE;AAED,gFAAgF;AAChF,wBAAgB,OAAO,CACrB,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,QAAQ,GAChC,SAAS,CAAC,QAAQ,CAAC,CAQrB;AAED;;;;;;0EAM0E;AAC1E,wBAAgB,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,GAAG,QAAQ,CAiCpE;AAED,4DAA4D;AAC5D,wBAAgB,YAAY,CAC1B,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,UAAU,EAAE,GACpB,SAAS,CAAC,QAAQ,CAAC,CAQrB;AAED;uFACuF;AACvF,wBAAgB,UAAU,CACxB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC7B,MAAM,EAAE,UAAU,EAAE,GACnB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CASzB;AAED;qGACqG;AACrG,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EACzB,IAAI,EAAE,gBAAgB,EAAE,GACvB,SAAS,CAAC,QAAQ,CAAC,CAUrB;AAED,0DAA0D;AAC1D,wBAAgB,SAAS,CACvB,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EACzB,KAAK,EAAE,SAAS,EAAE,GACjB,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CASrB;AAED,iFAAiF;AACjF,wBAAgB,WAAW,CAAC,CAAC,EAC3B,IAAI,EAAE,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,EAC7B,MAAM,EAAE;IAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAA;CAAE,EAAE,GAChD,GAAG,CAAC,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,CAQzB;AAED,wFAAwF;AACxF,wBAAgB,eAAe,CAC7B,IAAI,EAAE,KAAK,EAAE,EACb,UAAU,GAAE,eAAe,EAAO,EAClC,aAAa,GAAE,eAAe,EAAO,GACpC,KAAK,EAAE,CAoBT;AAED,yGAAyG;AACzG,wBAAgB,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,MAAM,GAAE,WAAW,EAAO,GAAG,KAAK,EAAE,CAwB9E;AAED;;;;;;;;;;0GAU0G;AAC1G,wBAAgB,eAAe,CAC7B,IAAI,EAAE,KAAK,EAAE,EACb,YAAY,EAAE,WAAW,EAAE,GAC1B,KAAK,EAAE,CA4CT;AAUD;;;;;;;;;4FAS4F;AAC5F,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,UAAU,GAAG,QAAQ,CAa5D;AAED;;+CAE+C;AAC/C,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,CAAC,QAAQ,CAAC,EACzB,QAAQ,EAAE,cAAc,GACvB,SAAS,CAAC,QAAQ,CAAC,CAarB;AAED;;+EAE+E;AAC/E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC7B,QAAQ,EAAE,cAAc,GACvB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAUzB;AAED;;;wDAGwD;AACxD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,EAC7B,QAAQ,EAAE,cAAc,GACvB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAUzB;AAED,wBAAgB,UAAU,CACxB,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,cAAc,GACvB,iBAAiB,CAEnB;AAsBD;;;;;;;;;;;;+BAY+B;AAC/B,wBAAgB,WAAW,CACzB,IAAI,EAAE,iBAAiB,EACvB,SAAS,EAAE,cAAc,EAAE,GAC1B,iBAAiB,CA2FnB;AAED,iFAAiF;AACjF,MAAM,MAAM,WAAW,GAAG;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAaF;;;;;;;yFAOyF;AACzF,wBAAgB,gBAAgB,CAC9B,CAAC,EAAE,WAAW,EACd,cAAc,EAAE,MAAM,EACtB,iBAAiB,EAAE,MAAM,GACxB,WAAW,EAAE,CAqCf;AAED;;;;;;wCAMwC;AACxC,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,YAAY,GACnB,iBAAiB,CA8BnB;AAED;;uCAEuC;AACvC,wBAAgB,UAAU,CACxB,IAAI,EAAE,iBAAiB,EACvB,MAAM,EAAE,YAAY,GACnB,iBAAiB,CA8BnB"}