@rowsncolumns/rnc-engine 0.10.132

package/dist/esm/use-engine-core.js

@@ -0,0 +1,2279 @@
+// Lightweight dependency-graph NODE classes (data holders — NOT the JS calculator) used to shape the
+// real `getPrecedents`/`getDependents` results, which the engine now backs with actual graph data.
+import { CellNode, CellRangeNode, isCellCoordinate, isCellNode, makeKey, } from "@rowsncolumns/dag";
+import { DEFAULT_ACTIVE_CELL, DEFAULT_ARRAY, defaultSpreadsheetTheme, getInitialActiveSheetId, ICON_SET_COLORS, ICON_SET_GLYPHS, useFonts, } from "@rowsncolumns/spreadsheet";
+import { CellXfsRegistry, generateDataFromClipboard, isStyleReference, pickFormula, pickValue, SharedStringRegistry, transpose, useOnCopy, useOnTraceDependentsPrecedents, } from "@rowsncolumns/spreadsheet-state";
+import { getCellUserEnteredFormat, getCellUserEnteredValue, getExtendedValueBool, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, normalizeExternalUrl, } from "@rowsncolumns/utils";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { createCommandHandlers, } from "./command-handlers";
+import { emptyRenderState, foldCommit, foldCommitStructuralOnly, foldWindow, foldWindows, frozenBandRanges, reconcileSheets, } from "./fold";
+import { RncEngine, } from "./index";
+import { cellKey, parseCellKey } from "./keys";
+import { rescopeRulesAfterMove } from "./move-rescope";
+/** Extra rows/columns to read on EACH side of the visible range so a small scroll reveals already-
+ * loaded cells (no flash) before the next `readWindow`. Tuned for a typical viewport; the window
+ * size stays O(viewport), not O(sheet), so JS memory is bounded regardless of a 1M-row sheet. */
+const WINDOW_BUFFER_ROWS = 50;
+const WINDOW_BUFFER_COLS = 5;
+/** How close (in rows/cols) the visible range may get to the LOADED window's edge before we re-read.
+ * `onViewPortChange` fires on every scroll tick, but the loaded window already extends a full buffer
+ * past the viewport — so while the visible range stays inside that buffer (minus this margin), the
+ * cells are already in state and scrolling is pure paint: NO synchronous `readWindow`, no `foldWindow`,
+ * no re-render. We only re-read once the viewport scrolls within this margin of an edge (prefetching
+ * the next slice while buffer still covers the gap). Must be < the buffer, or every tick re-reads.
+ * This is what keeps windowed scrolling smooth — without it each scroll tick blocked on a wasm read. */
+const WINDOW_REFRESH_MARGIN_ROWS = 16;
+const WINDOW_REFRESH_MARGIN_COLS = 2;
+/** Windowed read that always keeps the frozen panes loaded: the buffered viewport window PLUS the
+ * sheet's frozen top/left/corner bands (see {@link frozenBandRanges}). Frozen rows/columns stay on
+ * screen at every scroll position, but the window fold evicts everything outside what's read here —
+ * so without the bands, scrolling past the frozen span blanks the frozen cells. Fold the result with
+ * `foldWindows` (one eviction, all snapshots merged).
+ *
+ * `pinnedCell` (the sheet's active cell) gets the same residency guarantee as the frozen bands: the
+ * formula bar keeps displaying the ACTIVE cell's user-entered value while the user scrolls it out of
+ * the viewport, but every accessor answering that read (`getUserEnteredValue`, `getTextFormatRuns`,
+ * `getCellFormat`, …) resolves through the windowed `getCellData` — so an evicted active cell blanked
+ * the formula bar on scroll. A 1×1 range piggybacking on a read that's already crossing into wasm is
+ * free; skipped when the cell is inside the window or a frozen band. */
+function readWindowWithFrozenBands(engine, w, frozenRowCount, frozenColumnCount, pinnedCell) {
+    const ranges = [w, ...frozenBandRanges(w, frozenRowCount, frozenColumnCount)];
+    if (pinnedCell) {
+        const { rowIndex, columnIndex } = pinnedCell;
+        const covered = ranges.some((r) => rowIndex >= r.startRow &&
+            rowIndex <= r.endRow &&
+            columnIndex >= r.startCol &&
+            columnIndex <= r.endCol);
+        if (!covered && rowIndex >= 1 && columnIndex >= 1) {
+            ranges.push({
+                sheetId: w.sheetId,
+                startRow: rowIndex,
+                startCol: columnIndex,
+                endRow: rowIndex,
+                endCol: columnIndex,
+            });
+        }
+    }
+    return ranges.map((r) => engine.readWindow(r.sheetId, r.startRow, r.startCol, r.endRow, r.endCol));
+}
+/** Display text for a cell whose custom-function eval is in flight — the same transient
+ * placeholder the JS engine's `SheetCell` shows (`LOADING_VALUE`). */
+const LOADING_FORMATTED_VALUE = "Loading...";
+// A paint-format target spanning at least this many rows/cols is a header-click
+// full-column/row selection, not an intentional drag — bound it to the data extent.
+const UNBOUNDED_PAINT_SPAN = 10_000;
+/** The engine marks a host-call cell awaiting its answer — and every cell SHADOWED by it, i.e.
+ * whose value derives from it directly, through a chain, or through a range (see rnc-store
+ * `refresh_pending_shadow`) — with an error named `#PENDING!`, instead of letting dependents
+ * compute off 0/empty; the host's `set-effective-value` answer settles the whole set. It is a
+ * WAIT state, not a failure: the accessors present it as LOADING ({@link LOADING_FORMATTED_VALUE}
+ * text, no error indicator / popover). Sentinel-driven, so collab PEERS of the evaluating client
+ * render loading too. */
+const isPendingEvalError = (ev) => {
+    const err = ev?.ev;
+    return !!err && (err.name === "#PENDING!" || err.message === "#PENDING!");
+};
+/** The Invalid marker presented for a cell whose engine data-validation verdict is `false`.
+ * One shared object (stable identity across reads); message mirrors `SheetCell.validate()`. */
+const DATA_VALIDATION_INVALID_ERROR = {
+    type: "Invalid",
+    message: "This cell's contents violate its validation rule",
+};
+/** A {@link CellData} for a previewed value. The stream hands us display strings (the host's values,
+ * or a formula restated when evaluation is off), so a numeric-looking string is presented as a number
+ * — that's what right-alignment and any consumer reading `ev.nv` expect. Nothing here is evaluated:
+ * a preview never runs the formula engine, because it never commits. */
+function previewCellData(text) {
+    if (text == null)
+        return { ue: {}, ev: {}, fv: "" };
+    const trimmed = text.trim();
+    const asNumber = trimmed !== "" && !trimmed.startsWith("=") ? Number(trimmed) : Number.NaN;
+    if (!Number.isNaN(asNumber)) {
+        return { ue: { nv: asNumber }, ev: { nv: asNumber }, fv: text };
+    }
+    return { ue: { sv: text }, ev: { sv: text }, fv: text };
+}
+/** Seed for the parsed facets before the first commit (stable reference). */
+const EMPTY_FACETS = {
+    conditionalFormats: [],
+    dataValidations: [],
+    namedRanges: [],
+    tables: [],
+    embeds: [],
+    slicers: [],
+    bandedRanges: [],
+    protectedRanges: [],
+    basicFilters: [],
+    citations: [],
+};
+/** True when 1-indexed cell (row,col) falls inside a `SheetRange` on the given sheet. */
+function rangeContains(range, sheetId, row, col) {
+    return (range.sheetId === sheetId &&
+        row >= (range.startRowIndex ?? 0) &&
+        row <= (range.endRowIndex ?? -1) &&
+        col >= (range.startColumnIndex ?? 0) &&
+        col <= (range.endColumnIndex ?? -1));
+}
+// ── Drop-in parity stubs for the rest of `useSpreadsheetState`'s surface ──
+// These keys exist so the hook is STRUCTURALLY a `useSpreadsheetState` (any consumer that destructures
+// them type-checks), but in Option B they're INERT: the engine owns calc + the dependency graph +
+// undo/redo (so the JS immer-patch history is vestigial — see `undo`/`redo`, which delegate to it), and
+// import / dialogs / clipboard / citations are the host app's concern. Typed via `SS[K]` so signatures
+// stay exact; module-level so the references are stable (one identity, no re-render churn, no deps).
+const EMPTY_COLORS = {};
+// Calc + dependency graph — the engine computes everything; nothing to schedule, evaluate, or trace in JS.
+const addFormulaToGraph = () => { };
+const enqueueCalculation = () => { };
+const enqueueGraphOperation = () => { };
+const updateDependencyGraph = () => { };
+const clearEvaluatedCellsCache = () => { };
+// `calculateNow` and `onRequestCalculate` are REAL methods (defined in the hook — recalculate
+// command / engine scratch-eval respectively); see the hook body.
+// `getDependencyGraph` (a whole-graph JSON dump) stays a thin stub — niche debug/export, low value.
+// `getPrecedents`/`getDependents` are REAL, implemented in the hook over the engine's graph (below);
+// `onTracePrecedents`/`onTraceDependents`/`onRemoveArrows`/`arrows` are REAL too — the reference's
+// trace hook composed over those engine-backed queries (see the hook body).
+const getDependencyGraph = () => "[]";
+// `onViewPortChange` is REAL here (it drives windowed reads), so it's NOT a module-level stub — it's
+// implemented in the hook with the `ViewportRange` shape CanvasGrid reports, and is a no-op in the
+// default (non-windowed) path. See the hook body + the `EngineSpreadsheet` declaration.
+const evaluateConditionalFormatting = () => { };
+const evaluateConditionalFormattingForViewport = () => { };
+// The Rust engine re-derives CF/DV results for changed cells inside every
+// commit (`apply_cf_into_changes`), so the JS-side explicit re-derivation is
+// inherently unnecessary here.
+const reevaluateDerivationsForCells = () => { };
+const evaluateDataValidations = () => { };
+const evaluateDataValidationsForViewport = () => { };
+// Undo/redo — owned by the engine (`undo`/`redo`). These JS immer-patch history hooks are inert.
+const applyPatch = () => { };
+const generateStatePatches = () => Promise.resolve({});
+const createHistory = () => () => { };
+// `onClearHistory` is REAL (implemented in the hook — clears the engine's undo/redo stacks).
+// `getFormattingFromRange` / `getFormulasFromRange` / `getUserEnteredValuesFromRange` are REAL,
+// implemented in the hook over the folded state (see below). `getSheetProperties` stays a no-op (the
+// grid reads sheet props via the dedicated accessors).
+const getSheetProperties = () => undefined;
+// A rejected promise (`Promise<never>` → assignable anywhere) for the async ops the HOST owns in
+// Option B — import / paste / file-drop. Honest signal if a drop-in caller ever invokes one.
+const hostOwned = (op) => Promise.reject(new Error(`${op} is host-owned in the engine-backed hook`));
+// Import — a separate host-driven ingestion path, not the live render surface.
+const importExcelFile = () => hostOwned("importExcelFile");
+const importCSVFile = () => hostOwned("importCSVFile");
+const importCSVFileLegacy = () => hostOwned("importCSVFileLegacy");
+// `onUpdateSheet`, `onRequestAddRows`, `onDeleteDataValidationRules`, `onClearHistory`, and
+// `onChangeBatchStream` are REAL (implemented in the hook below — they emit commands / extend the
+// grid / stream chunked batches / clear engine history). The one that remains inert:
+//   • `onChangeCellXfs` — a React `setState` for Excel's cellXfs (style-index) registry; the engine
+//     stores `CellFormat` directly on cells, so there's no xfs registry to mutate — no engine analog.
+const onChangeCellXfs = undefined;
+/** Which axes a range reader omits for a `HIDDEN_DIMENSION_STRATEGY`. All four variants are honored:
+ * rows only, columns only, both, or neither (`SHOW_ALL` — and `null`/`undefined`, which the chart
+ * callers use to mean "show all"). */
+function hiddenStrategyAxes(strategy) {
+    return {
+        skipRows: strategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" ||
+            strategy === "SKIP_HIDDEN_ROWS",
+        skipCols: strategy === "SKIP_HIDDEN_ROWS_AND_COLUMNS" ||
+            strategy === "SKIP_HIDDEN_COLUMNS",
+    };
+}
+/** 1-based column number for an A1 column label (`"A"` → 1, `"AA"` → 27). Inverse of
+ * {@link columnLabel}. */
+function columnNumber(label) {
+    let n = 0;
+    for (let i = 0; i < label.length; i++)
+        n = n * 26 + (label.toUpperCase().charCodeAt(i) - 64);
+    return n;
+}
+/** An A1 cell/range reference (`B3`, `$B$3`, `B3:C5`) — the part of an internal link after `!`. */
+const A1_RANGE_RE = /^\$?([A-Za-z]{1,3})\$?(\d+)(?::\$?([A-Za-z]{1,3})\$?(\d+))?$/;
+/** Parse an internal-link `location` (`'My Sheet'!A1:B5`, `Sheet1!B3`, `A1`) into its sheet-name
+ * part and 1-based range. `range` is undefined when the reference isn't A1-shaped (e.g. a named
+ * range) — the caller can still act on `sheetName`. */
+function parseInternalLocation(location) {
+    const bang = location.indexOf("!");
+    const sheetName = bang >= 0
+        ? location.slice(0, bang).replace(/^'|'$/g, "").replace(/''/g, "'")
+        : undefined;
+    const ref = (bang >= 0 ? location.slice(bang + 1) : location).trim();
+    const m = A1_RANGE_RE.exec(ref);
+    if (!m)
+        return { sheetName };
+    const startColumn = columnNumber(m[1]);
+    const startRow = Number(m[2]);
+    const endColumn = m[3] ? columnNumber(m[3]) : startColumn;
+    const endRow = m[4] ? Number(m[4]) : startRow;
+    return {
+        sheetName,
+        range: {
+            startRowIndex: Math.min(startRow, endRow),
+            endRowIndex: Math.max(startRow, endRow),
+            startColumnIndex: Math.min(startColumn, endColumn),
+            endColumnIndex: Math.max(startColumn, endColumn),
+        },
+    };
+}
+// `useEngineCore` is the engine-only surface (data / calc / commands / accessors) — NOT a standalone
+// drop-in for `useSpreadsheetState`. The chrome (dialogs + host intents) lives in `useSpreadsheetUI`;
+// the drop-in parity lock is asserted on their composition, `useSpreadsheetEngine`.
+/** **Option B, pure core:** the Rust→WASM data store + calc + commands, with no UI/chrome. The
+ * composed {@link useSpreadsheetEngine} layers {@link useSpreadsheetUI} (dialogs) on top — most apps
+ * want that. Use `useEngineCore` directly only when you bring your own chrome. */
+export function useEngineCore(options) {
+    const engineRef = useRef(null);
+    // Host custom-function implementations by name (JS bodies the engine calls back via `customEvals`).
+    const customFnsRef = useRef(new Map());
+    // Per-cell eval generation + in-flight AbortController. A `customCancels` entry (or a NEWER eval
+    // of the same cell) bumps the generation and aborts the controller: the impl's signal fires (so
+    // fetches/poll loops actually stop) and its late answer finds a newer generation on resolution
+    // and is dropped — a stale result must never materialize at a vacated coordinate.
+    const evalGenRef = useRef(new Map());
+    const evalAbortRef = useRef(new Map());
+    const abortEval = useCallback((key) => {
+        const gens = evalGenRef.current;
+        gens.set(key, (gens.get(key) ?? 0) + 1);
+        const controller = evalAbortRef.current.get(key);
+        if (controller) {
+            evalAbortRef.current.delete(key);
+            controller.abort();
+        }
+    }, []);
+    // Latest-ref for the host's cancel observer (identity may change every render).
+    const onCustomEvalCancelRef = useRef(options.onCustomEvalCancel);
+    onCustomEvalCancelRef.current = options.onCustomEvalCancel;
+    // Latest-refs for the streaming batch-write observers (identities may change every render).
+    const onStreamStartRef = useRef(options.onStreamStart);
+    onStreamStartRef.current = options.onStreamStart;
+    const onStreamProgressRef = useRef(options.onStreamProgress);
+    onStreamProgressRef.current = options.onStreamProgress;
+    const onStreamEndRef = useRef(options.onStreamEnd);
+    onStreamEndRef.current = options.onStreamEnd;
+    const [ready, setReady] = useState(false);
+    const [state, setState] = useState(() => emptyRenderState(options.sheets));
+    // Windowed mode (default off). When on, render state holds only the current viewport's cells/styles
+    // (see the `windowed` option). `windowedRef` is read inside the engine subscriber (stable closure);
+    // `windowRef` holds the currently-loaded buffered range so a commit can re-read THAT window.
+    const windowedRef = useRef(options.windowed ?? false);
+    const windowRef = useRef(null);
+    // The last viewport CanvasGrid reported (via `onViewPortChange`) — the row/column span the user is
+    // actually looking at. Reused to seed the window on a sheet switch so the WHOLE visible grid loads:
+    // switching sheets keeps the scroll position and therefore does NOT re-fire `onViewPortChange`, so a
+    // tiny top-left placeholder would leave everything past the first few columns unfetched until a
+    // manual scroll. Null until the first viewport report.
+    const lastViewportRef = useRef(null);
+    // Live refs for the windowed frozen-band reads (read inside stable callbacks + the mount effect).
+    // The host getter is authoritative (a collab host answers from its doc plane); the hook's own folded
+    // per-sheet counts are the fallback. Latest-ref pattern: reassigned every render.
+    const getWindowFrozenCountsRef = useRef(options.getWindowFrozenCounts);
+    getWindowFrozenCountsRef.current = options.getWindowFrozenCounts;
+    const stateSheetsRef = useRef(options.sheets);
+    stateSheetsRef.current = state.sheets;
+    // One windowed read = the buffered window + the sheet's frozen bands + the sheet's active cell
+    // (pinned so the formula bar's active-cell read survives scrolling it out of the window — see
+    // `readWindowWithFrozenBands`). Frozen counts come from the host's getter when provided (see
+    // `getWindowFrozenCounts`), else the hook's folded sheet metadata. The active cell defaults to A1
+    // exactly like the published view state does (`viewOfSheet`), so a never-clicked sheet still pins
+    // the cell the formula bar is showing. `activeCellBySheetIdRef` is declared below; the closure only
+    // runs after mount, when it's initialized.
+    const readWindowedSnapshots = useCallback((engine, w) => {
+        const host = getWindowFrozenCountsRef.current?.(w.sheetId);
+        const sheet = stateSheetsRef.current.find((s) => s.sheetId === w.sheetId);
+        return readWindowWithFrozenBands(engine, w, host?.frozenRowCount ?? sheet?.frozenRowCount ?? 0, host?.frozenColumnCount ?? sheet?.frozenColumnCount ?? 0, activeCellBySheetIdRef.current[w.sheetId] ?? DEFAULT_ACTIVE_CELL);
+    }, []);
+    // Engine data extents `[sheetId, rowCount, colCount][]` → the grid's scroll extent in windowed mode
+    // (so it scrolls the full sheet while JS holds only the window). Empty until the engine reports them.
+    const [extents, setExtents] = useState([]);
+    // Document-level facets (CF rules, tables, named/protected ranges, embeds, slicers, banded ranges,
+    // basic filters, DV rules) — read in one shot from the engine after each commit. Stored as the RAW
+    // JSON string so a pure cell edit (facets unchanged) keeps the SAME string ⇒ same parsed object ⇒
+    // stable facet props ⇒ no needless CanvasGrid re-render. Parsed lazily in `facets` below.
+    const [facetsJson, setFacetsJson] = useState("{}");
+    const [hist, setHist] = useState({ canUndo: false, canRedo: false });
+    // View state — pure UI, never engine-owned. Cursor + selections are stored BY SHEET (mirroring the
+    // JS engine's `useSheetState`), so every sheet remembers its own active cell/selections and a sheet
+    // switch restores them. The maps are mirrored into refs SYNCHRONOUSLY at every mutation site (like
+    // `viewRef`) so stable callbacks read the live value, not a stale closure.
+    // Initial active sheet: the first VISIBLE titled sheet (the JS engine's `getInitialActiveSheetId`),
+    // falling back to the first seed (seeds may omit `title`, which that helper filters out) — then 1.
+    const [activeSheetId, setActiveSheetId] = useState(() => getInitialActiveSheetId(options.sheets) ?? options.sheets[0]?.sheetId ?? 1);
+    const [activeCellBySheetId, setActiveCellBySheetId] = useState({});
+    const [selectionsBySheetId, setSelectionsBySheetId] = useState({});
+    const activeCellBySheetIdRef = useRef(activeCellBySheetId);
+    const selectionsBySheetIdRef = useRef(selectionsBySheetId);
+    // The ACTIVE sheet's entries — the shared defaults keep identities stable for unvisited sheets.
+    const activeCell = activeCellBySheetId[activeSheetId] ?? DEFAULT_ACTIVE_CELL;
+    const selections = selectionsBySheetId[activeSheetId] ?? DEFAULT_ARRAY;
+    /** The remembered view for `sheetId` (cursor + selections it was left with, or the defaults). */
+    const viewOfSheet = useCallback((sheetId) => ({
+        activeSheetId: sheetId,
+        activeCell: activeCellBySheetIdRef.current[sheetId] ?? DEFAULT_ACTIVE_CELL,
+        selections: selectionsBySheetIdRef.current[sheetId] ?? DEFAULT_ARRAY,
+    }), []);
+    // Format painter: the captured 2-D pattern of source formats (empty = inactive). Applied to a target
+    // via a `change-formatting` command with `options.replace` (mirrors `usePaintFormat`).
+    const [paintFormats, setPaintFormats] = useState([]);
+    // The last SINGLE formatting command (a paint-array `change-formatting` is excluded — not a
+    // repeatable single action), replayed onto the current target by `onRepeatFormatting`. Recorded in
+    // `onCommand` so toolbar formatting (which goes straight through the pure handlers) is captured too.
+    const lastFormattingRef = useRef(null);
+    // Load default fonts
+    useFonts();
+    // The engine owns the DOCUMENT undo/redo; the hook keeps a PARALLEL view-state stack (cursor /
+    // selection / active sheet) so undo also restores where the user was — kept in lockstep with the
+    // engine via its undo-stack DEPTH. `viewRef` mirrors the current view for reading inside callbacks
+    // (avoids stale closures); the stacks hold the view as it was BEFORE each recorded edit.
+    const viewRef = useRef({
+        activeSheetId: getInitialActiveSheetId(options.sheets) ?? options.sheets[0]?.sheetId ?? 1,
+        activeCell: DEFAULT_ACTIVE_CELL,
+        selections: DEFAULT_ARRAY,
+    });
+    const viewUndo = useRef([]);
+    const viewRedo = useRef([]);
+    const lastUndoDepth = useRef(0);
+    // Post-hydration active-sheet re-derivation state (see the `onChanges` subscriber): the seed ids
+    // the mount-time derivation saw, whether the one-shot re-derivation already ran, and whether the
+    // user/host explicitly picked a sheet (which always wins over the re-derivation).
+    const seedSheetIdsRef = useRef(new Set(options.sheets.map((s) => s.sheetId)));
+    const activeSheetRederivedRef = useRef(false);
+    const userPickedSheetRef = useRef(false);
+    const applyView = useCallback((v) => {
+        viewRef.current = v;
+        const cells = {
+            ...activeCellBySheetIdRef.current,
+            [v.activeSheetId]: v.activeCell,
+        };
+        const sels = {
+            ...selectionsBySheetIdRef.current,
+            [v.activeSheetId]: v.selections,
+        };
+        activeCellBySheetIdRef.current = cells;
+        selectionsBySheetIdRef.current = sels;
+        setActiveSheetId(v.activeSheetId);
+        setActiveCellBySheetId(cells);
+        setSelectionsBySheetId(sels);
+    }, []);
+    // The initial sheets/document are creation-time inputs; capture them so the effect runs once and
+    // doesn't tear the engine down on every render.
+    const initial = useRef(options);
+    useEffect(() => {
+        let alive = true;
+        let unsubscribe = () => { };
+        void RncEngine.create(initial.current.sheets.map((s) => ({
+            sheetId: s.sheetId,
+            title: String(s.title ?? s.sheetId),
+        })), {
+            engine: initial.current.createEngine?.(),
+            gridRows: initial.current.gridRows,
+            gridCols: initial.current.gridCols,
+        }).then((engine) => {
+            if (!alive) {
+                engine.free();
+                return;
+            }
+            engineRef.current = engine;
+            // Tell the engine we render windowed BEFORE any commit (load below included), so it strips the
+            // per-cell channels we'd only discard — the windowed fold re-reads visible cells from the window.
+            // No-op on engines without `setWindowed`; the fold still ignores those channels either way.
+            engine.setWindowed(windowedRef.current);
+            // Seed option-provided custom functions so a LOADED `=NAME(…)` cell resolves on the first recalc
+            // (registration must precede load — see `customFunctions` on the options). Both the engine and the
+            // resolve loop below read these from `customFnsRef`.
+            if (initial.current.customFunctions)
+                for (const [name, impl] of Object.entries(initial.current.customFunctions))
+                    customFnsRef.current.set(name, impl);
+            // Re-register any custom functions declared before the engine finished initializing.
+            for (const name of customFnsRef.current.keys())
+                engine.registerCustomFunction(name);
+            // Refresh the engine's data extents into state (windowed mode sizes the grid scroll to these).
+            const refreshExtents = () => {
+                const next = engine.sheetExtents();
+                setExtents((prev) => 
+                // Keep the prior identity when unchanged so the grid's row/col count props stay stable.
+                JSON.stringify(prev) === JSON.stringify(next) ? prev : next);
+            };
+            // Read the currently-loaded window (plus the sheet's frozen bands) from the engine and fold ONLY
+            // that into render state (evicting cells outside it). No-op until a viewport has been reported
+            // (or the initial window set).
+            const refreshWindow = () => {
+                const w = windowRef.current;
+                if (!w)
+                    return;
+                const snaps = readWindowedSnapshots(engine, w);
+                setState((prev) => foldWindows(prev, snaps));
+            };
+            unsubscribe = engine.onChanges((commit) => {
+                // Reconcile the tab list with the engine's authoritative sheet set/order/titles after every
+                // commit — so create / rename / delete / reorder / hide / color update the tabs (and a new
+                // sheet renders). The engine owns lifecycle (it generates `create-sheet` ids), so this can't
+                // be derived from the command. `reconcileSheets` preserves each surviving sheet's
+                // dimension/merge metadata and returns the SAME array when nothing changed (no churn).
+                const engineSheets = engine.sheets();
+                if (windowedRef.current) {
+                    // Windowed: do NOT accumulate the commit's cell changes (that's the 1M-row blowup). Fold only
+                    // the structural channels (dimensions / merges), then re-read the CURRENT window so in-view
+                    // edits + recomputed dependents update. Out-of-view changes need no folding.
+                    setState((prev) => {
+                        const folded = foldCommitStructuralOnly(prev, commit);
+                        const sheets = reconcileSheets(folded.sheets, engineSheets);
+                        return sheets === folded.sheets ? folded : { ...folded, sheets };
+                    });
+                    refreshWindow();
+                    refreshExtents();
+                }
+                else {
+                    setState((prev) => {
+                        const folded = foldCommit(prev, commit);
+                        const sheets = reconcileSheets(folded.sheets, engineSheets);
+                        return sheets === folded.sheets ? folded : { ...folded, sheets };
+                    });
+                }
+                // If the active sheet was deleted (it's gone from the engine's set), fall back to the first
+                // remaining sheet so the renderer keeps a valid active sheet. Done inline (not via
+                // `onChangeActiveSheet`, defined later) since this subscriber closes over `[]`; the live active
+                // id is read from `viewRef`. A windowed window pointing at the gone sheet is re-seeded on the
+                // next scroll/commit, so no extra handling is needed here.
+                if (engineSheets.length &&
+                    !engineSheets.some((s) => s.sheetId === viewRef.current.activeSheetId)) {
+                    const firstId = engineSheets[0].sheetId;
+                    viewRef.current = viewOfSheet(firstId);
+                    setActiveSheetId(firstId);
+                }
+                // ONE-SHOT post-hydration re-derivation of the initial active sheet. Collab hosts seed the
+                // engine with a placeholder sheet list (e.g. `[{sheetId: 1, title: 'Sheet1'}]`) before the
+                // Y.Doc syncs, so the mount-time `getInitialActiveSheetId` ran against the SEED — a doc whose
+                // data lives on other sheets (agent-built workbooks: tool-created sheets get fresh ids while
+                // the empty seed survives, listed last) would open on the blank seed sheet every time. The
+                // first commit whose authoritative sheet set goes beyond the seed re-runs the derivation —
+                // skipped once the user (or host) has explicitly picked a sheet.
+                if (!activeSheetRederivedRef.current &&
+                    engineSheets.length &&
+                    engineSheets.some((s) => !seedSheetIdsRef.current.has(s.sheetId))) {
+                    activeSheetRederivedRef.current = true;
+                    if (!userPickedSheetRef.current) {
+                        const derivedId = getInitialActiveSheetId(engineSheets) ?? engineSheets[0].sheetId;
+                        if (derivedId !== viewRef.current.activeSheetId) {
+                            viewRef.current = viewOfSheet(derivedId);
+                            setActiveSheetId(derivedId);
+                        }
+                    }
+                }
+                // Re-read facets and keep the prior string identity if unchanged (the common case).
+                const nextFacets = engine.documentFacetsJson();
+                setFacetsJson((prev) => (prev === nextFacets ? prev : nextFacets));
+                setHist({ canUndo: engine.canUndo(), canRedo: engine.canRedo() });
+                // Resolve host custom-function requests: run the registered JS impl with the engine's RESOLVED
+                // args + the calling cell, then push the result (incl. `structuredValue`) back via
+                // `set-effective-value`. Everything is deferred to a microtask, so we never re-enter the engine
+                // during its own commit. While the impl is in flight the cell carries the engine's `#PENDING!`
+                // sentinel, which the accessors present as "Loading..." (see `isPendingEvalError`); the answer
+                // (or the error below) clears it.
+                // Cancelled host calls: their cell no longer holds the formula (cleared / overwritten /
+                // undone / removed with its row or column). Bump the cell's eval generation so any
+                // in-flight impl's late answer is dropped, then surface the batch to the host so it can
+                // abort external work the call started (e.g. a backend `=AOP` run).
+                if (commit.customCancels?.length) {
+                    for (const c of commit.customCancels) {
+                        abortEval(cellKey(c.sheetId, c.rowIndex, c.columnIndex));
+                    }
+                    onCustomEvalCancelRef.current?.(commit.customCancels);
+                }
+                for (const req of commit.customEvals) {
+                    const impl = customFnsRef.current.get(req.name);
+                    if (!impl)
+                        continue;
+                    const coords = {
+                        rowIndex: req.rowIndex,
+                        columnIndex: req.columnIndex,
+                    };
+                    const key = cellKey(req.sheetId, req.rowIndex, req.columnIndex);
+                    // A newer eval supersedes any in-flight one for the same cell (a precedent changed
+                    // mid-flight): abort it so its work stops AND its slower answer can't land after ours.
+                    abortEval(key);
+                    const generation = evalGenRef.current.get(key) ?? 0;
+                    const controller = new AbortController();
+                    evalAbortRef.current.set(key, controller);
+                    const push = (effectiveValue) => {
+                        // The cell's call was cancelled/superseded after this request — drop the stale answer.
+                        if ((evalGenRef.current.get(key) ?? 0) !== generation)
+                            return;
+                        evalAbortRef.current.delete(key);
+                        engine.applyCommand({
+                            command: "set-effective-value",
+                            sheetId: req.sheetId,
+                            coords,
+                            effectiveValue,
+                        });
+                    };
+                    void Promise.resolve().then(() => {
+                        const result = impl(req.args, {
+                            sheetId: req.sheetId,
+                            rowIndex: req.rowIndex,
+                            columnIndex: req.columnIndex,
+                            signal: controller.signal,
+                        });
+                        if (result instanceof Promise) {
+                            return result
+                                .then((ev) => {
+                                if (ev)
+                                    push(ev);
+                            })
+                                // A rejected impl must still clear the engine's #PENDING! sentinel — land an error
+                                // value (the async analog of a sync throw) instead of leaving the cell loading forever.
+                                .catch(() => push({
+                                ev: {
+                                    type: "Error",
+                                    name: "#ERROR!",
+                                    message: "Custom function failed",
+                                },
+                            }));
+                        }
+                        if (result)
+                            push(result);
+                    });
+                }
+            });
+            if (initial.current.initialDocument)
+                engine.load(initial.current.initialDocument);
+            // Push the host's starting locale so the first render is already localized (re-derives + streams
+            // every formatted cell). en-US is the engine default, so only a non-default locale needs this.
+            if (initial.current.locale && initial.current.locale !== "en-US")
+                engine.applyCommand({
+                    command: "change-locale",
+                    locale: initial.current.locale,
+                });
+            // Windowed mode: seed an initial top-left window (so the grid has something to paint before the
+            // first scroll event) and read the engine's extents. The load above already ran with `windowRef`
+            // null (so its commit folded only structurally — no 1M-cell accumulation); we now read the window.
+            if (windowedRef.current) {
+                const firstSheet = initial.current.sheets[0]?.sheetId;
+                if (firstSheet != null) {
+                    windowRef.current = {
+                        sheetId: firstSheet,
+                        startRow: 1,
+                        startCol: 1,
+                        endRow: 1 + WINDOW_BUFFER_ROWS,
+                        endCol: 1 + WINDOW_BUFFER_COLS,
+                    };
+                    const w = windowRef.current;
+                    const snap = engine.readWindow(w.sheetId, w.startRow, w.startCol, w.endRow, w.endCol);
+                    setState((prev) => foldWindow(prev, snap));
+                }
+                refreshExtents();
+            }
+            setReady(true);
+        });
+        return () => {
+            alive = false;
+            unsubscribe();
+            // Stop every in-flight custom-function eval — the engine is going away with the answers.
+            for (const controller of evalAbortRef.current.values()) {
+                controller.abort();
+            }
+            evalAbortRef.current.clear();
+            engineRef.current?.free();
+            engineRef.current = null;
+        };
+    }, []);
+    // Cells painted by a PREVIEW batch stream: rendered, never committed. `onChangeBatchStream`'s
+    // contract (and the legacy JS engine's) is local-render-only — the chunks show what is coming and
+    // the host persists once, after the stream completes, through a single history-on `onChangeBatch`.
+    // Committing per chunk instead would write partial results to the document, broadcast every frame
+    // to collab peers, and turn one user action into N undo entries.
+    const [streamPreview, setStreamPreview] = useState(null);
+    const streamPreviewRef = useRef(null);
+    const publishStreamPreview = useCallback(() => {
+        const next = streamPreviewRef.current;
+        setStreamPreview(next && next.size ? new Map(next) : null);
+    }, []);
+    const clearStreamPreview = useCallback(() => {
+        if (!streamPreviewRef.current?.size)
+            return;
+        streamPreviewRef.current = null;
+        setStreamPreview(null);
+    }, []);
+    const retireStreamPreviewForCommand = useCallback((command) => {
+        const preview = streamPreviewRef.current;
+        if (!preview?.size)
+            return;
+        const cmd = command;
+        if (cmd.command === "change-theme")
+            return;
+        const ranges = cmd.ranges ?? (cmd.range ? [cmd.range] : null);
+        if (!ranges?.length || cmd.sheetId == null) {
+            streamPreviewRef.current = null;
+            setStreamPreview(null);
+            return;
+        }
+        let removed = false;
+        for (const key of Array.from(preview.keys())) {
+            const parsed = parseCellKey(key);
+            if (!parsed || parsed.sheetId !== cmd.sheetId)
+                continue;
+            const covered = ranges.some((r) => parsed.rowIndex >= r.startRowIndex &&
+                parsed.rowIndex <= r.endRowIndex &&
+                parsed.columnIndex >= r.startColumnIndex &&
+                parsed.columnIndex <= r.endColumnIndex);
+            if (covered) {
+                preview.delete(key);
+                removed = true;
+            }
+        }
+        if (!removed)
+            return;
+        streamPreviewRef.current = preview.size ? preview : null;
+        setStreamPreview(preview.size ? new Map(preview) : null);
+    }, []);
+    // The committed `fv` a preview is standing on. Read through a ref so the streaming callback
+    // (created once) always sees fresh values.
+    const sheetDataRef = useRef(state.sheetData);
+    sheetDataRef.current = state.sheetData;
+    const committedFvAt = useCallback((sheetId, rowIndex, columnIndex) => sheetDataRef.current?.[sheetId]?.[rowIndex]?.values?.[columnIndex]?.fv ??
+        undefined, []);
+    const onCommand = useCallback((command) => {
+        const engine = engineRef.current;
+        if (!engine)
+            return;
+        // The host's apply (or any other local write) is the authority — retire the preview for the cells
+        // it covers in this same render, so the committed value replaces the previewed one with no blank
+        // frame in between.
+        retireStreamPreviewForCommand(command);
+        // Remember the last SINGLE formatting action so `onRepeatFormatting` can replay it onto a new
+        // target (a 2-D paint-format array is not a repeatable single action, so it's excluded).
+        if ((command.command === "change-formatting" &&
+            !Array.isArray(command.cellFormat)) ||
+            command.command === "change-border") {
+            lastFormattingRef.current = command;
+        }
+        // Snapshot the view BEFORE applying — that's where undo should return the user.
+        const before = viewRef.current;
+        engine.applyCommand(command);
+        // Only record a view snapshot if the command actually pushed a document undo entry (skips
+        // no-op-inverse commands like change-theme), keeping the two stacks aligned.
+        if (engine.undoDepth() > lastUndoDepth.current) {
+            viewUndo.current.push(before);
+            viewRedo.current = [];
+        }
+        lastUndoDepth.current = engine.undoDepth();
+        // The engine's move-range relocates cells but never re-scopes range-scoped CF/DV rules —
+        // carry the touched rules to the destination right after the move (Excel/Sheets behavior).
+        if (command.command === "move-range") {
+            for (const followUp of rescopeRulesAfterMove(engine.documentFacets(), command.sheetId, command.from, command.to)) {
+                onCommand(followUp);
+            }
+        }
+    }, [retireStreamPreviewForCommand]);
+    // "Calculate Now" (F9): force a full recalculation so volatile functions (NOW/TODAY/RAND/…) refresh.
+    // The engine re-evaluates + streams the changed cells through the normal commit (folded like any edit);
+    // it mutates no document state, so it isn't undoable. The reference's `options` (reset-graph /
+    // disable-eval) are moot here — the engine has no deferred-calc queue or graph-only mode to gate.
+    const calculateNow = useCallback(() => {
+        onCommand({ command: "recalculate" });
+        return Promise.resolve();
+    }, [onCommand]);
+    // Live formula preview — the cell editor's `onRequestCalculate`. Scratch-evaluates the
+    // in-progress formula through the engine: read-only, nothing installed or committed, no dirty
+    // marks. Error results suppress the preview (mirroring the reference wrapper's `FormulaError`
+    // handling) — which also covers a host custom-function call (`=AOP(...)`): it is not a
+    // formualizer function, so it evaluates to `#NAME?` and, critically, never enqueues a
+    // `customEvals` request — typing an =AOP formula can't fire an agent run from the preview.
+    const onRequestCalculate = useCallback(async (value, sheetId, rowIndex, columnIndex, _options) => {
+        const formula = typeof value === "string" ? value.trim() : "";
+        if (!formula.startsWith("="))
+            return undefined;
+        const ev = engineRef.current?.evalFormula(sheetId, rowIndex, columnIndex, formula);
+        if (!ev)
+            return undefined;
+        // The preview contract is stringly (the reference returns display text / a result array).
+        const nv = ev.nv ?? ev.numberValue;
+        if (nv != null)
+            return String(nv);
+        const sv = ev.sv ?? ev.stringValue;
+        if (sv != null)
+            return sv;
+        const bv = ev.bv ?? ev.boolValue;
+        if (bv != null)
+            return bv ? "TRUE" : "FALSE";
+        return undefined;
+    }, []);
+    // "Filter by color" swatches for the FilterBox — computed engine-side in ONE column scan
+    // (the JS per-row `getEffectiveFormat` scan is disabled on windowed hosts). Icon entries come
+    // back as (iconSet, iconId); the glyph + painted color resolve through the same tables the CF
+    // renderer uses, so the picker shows exactly what the grid draws.
+    const getFilterColors = useCallback((sheetId, columnIndex, range) => {
+        const res = engineRef.current?.filterColors(sheetId, columnIndex, range.startRowIndex, range.endRowIndex);
+        if (!res)
+            return undefined;
+        const icons = res.icons.map(({ iconSet, iconId }) => ({
+            iconSet,
+            iconId,
+            glyph: ICON_SET_GLYPHS[iconSet]?.[iconId] ?? "",
+            color: ICON_SET_COLORS[iconSet]?.[iconId],
+        }));
+        return {
+            availableCellColors: res.cellColors.length ? res.cellColors : undefined,
+            availableFontColors: res.fontColors.length ? res.fontColors : undefined,
+            availableIcons: icons.length ? icons : undefined,
+        };
+    }, []);
+    // Host-push of a computed effective value (custom-formula / structured result) — the Option-B
+    // `setEffectiveValue`. The engine stores it (incl. `structuredValue`), feeds the scalar to
+    // dependents, and protects it from recalc until the cell is edited.
+    const setEffectiveValue = useCallback((sheetId, coords, effectiveValue) => onCommand({
+        command: "set-effective-value",
+        sheetId,
+        coords,
+        effectiveValue,
+    }), [onCommand]);
+    // Register a host (JS) custom function. The engine recognizes `=NAME(…)` (no `#NAME?`, deps tracked)
+    // and streams a `customEvals` request the subscriber answers by running `impl` (see the effect).
+    const registerCustomFunction = useCallback((name, impl) => {
+        customFnsRef.current.set(name, impl);
+        engineRef.current?.registerCustomFunction(name);
+    }, []);
+    // Undo AND redo of an edit both return the cursor to the EDIT location — mirroring the reference's
+    // `{ activeCell: { undo: coords, redo: coords } }`. So when an entry crosses between the undo/redo
+    // stacks we move the SAME stored view, NOT the live cursor (pushing the live cursor would make redo
+    // jump to wherever you happened to be when you pressed undo, e.g. B2 instead of the edited A1).
+    const undo = useCallback(() => {
+        const engine = engineRef.current;
+        if (!engine)
+            return;
+        const prevDepth = engine.undoDepth();
+        engine.undo();
+        if (engine.undoDepth() < prevDepth) {
+            const restore = viewUndo.current.pop();
+            if (restore) {
+                viewRedo.current.push(restore);
+                applyView(restore);
+            }
+        }
+        lastUndoDepth.current = engine.undoDepth();
+    }, [applyView]);
+    const redo = useCallback(() => {
+        const engine = engineRef.current;
+        if (!engine)
+            return;
+        const prevRedoDepth = engine.redoDepth();
+        engine.redo();
+        if (engine.redoDepth() < prevRedoDepth) {
+            const restore = viewRedo.current.pop();
+            if (restore) {
+                viewUndo.current.push(restore);
+                applyView(restore);
+            }
+        }
+        lastUndoDepth.current = engine.undoDepth();
+    }, [applyView]);
+    const load = useCallback((document) => {
+        engineRef.current?.load(document);
+    }, []);
+    /**
+     * Import an `.xlsx` workbook through the native Rust engine, REPLACING the current document (sheets,
+     * cell data, facets, history) — not merging into it. Render state is cleared first so nothing from
+     * the previous workbook lingers; the engine fresh-loads and its commit re-populates state via the
+     * onChanges subscriber (non-windowed folds the full commit onto the empty state + reconciles tabs;
+     * windowed re-reads the first imported sheet's window). Returns false if the backend can't import.
+     */
+    const importXlsx = useCallback((bytes) => {
+        const engine = engineRef.current;
+        if (!engine?.importXlsx)
+            return false;
+        // The engine REPLACES its document and returns the full commit WITHOUT notifying subscribers — we
+        // drive the render reset here. The commit's merges/row-col metadata fold only onto sheets that
+        // already exist in the base, so we seed the base from the engine's post-import sheet set first
+        // (otherwise reconcileSheets would rebuild bare sheets and drop merges/dimensions).
+        const commit = engine.importXlsx(bytes);
+        if (!commit)
+            return false;
+        const engineSheets = engine.sheets?.() ?? [];
+        const seedSheets = engineSheets.map((es) => ({
+            sheetId: es.sheetId,
+            title: es.title,
+            hidden: es.hidden,
+            tabColor: es.tabColor,
+            defaultRowHeight: es.defaultRowHeight,
+        }));
+        const firstId = engineSheets[0]?.sheetId ?? viewRef.current.activeSheetId;
+        windowRef.current = windowedRef.current
+            ? {
+                sheetId: firstId,
+                startRow: 1,
+                startCol: 1,
+                endRow: 1 + WINDOW_BUFFER_ROWS,
+                endCol: 1 + WINDOW_BUFFER_COLS,
+            }
+            : null;
+        // `importXlsx`'s return is engine-specific: the in-process rnc-engine returns a full `CommitResult`
+        // we fold directly, but the yrs-store engine loads its document into the CRDT and returns only a
+        // lightweight summary (`[{sheetId,name}]`). Folding that non-commit crashed the render
+        // (`changes is not iterable`). Detect a foldable commit; otherwise read the document back from the
+        // engine via `readWindow` (the universal path both engines support).
+        const foldableCommit = typeof commit === "object" &&
+            commit !== null &&
+            Array.isArray(commit.changes);
+        const extents = engine.sheetExtents?.() ?? [];
+        setState(() => {
+            let next = emptyRenderState(seedSheets);
+            if (windowedRef.current) {
+                // Windowed: fold only structural channels (cells come from the viewport read below).
+                if (foldableCommit)
+                    next = foldCommitStructuralOnly(next, commit);
+                if (windowRef.current) {
+                    const w = windowRef.current;
+                    next = foldWindow(next, engine.readWindow(w.sheetId, w.startRow, w.startCol, w.endRow, w.endCol));
+                }
+            }
+            else if (foldableCommit) {
+                // Non-windowed + a real commit (rnc-engine): fold every imported cell + style in one pass.
+                next = foldCommit(next, commit);
+            }
+            else {
+                // Non-windowed + a non-commit return (yrs-store summary): read each sheet's full extent from
+                // the engine to populate cells/styles/formulas (the doc already lives in the engine's CRDT).
+                for (const es of engineSheets) {
+                    const extent = extents.find((e) => e[0] === es.sheetId);
+                    const maxRow = extent?.[1] ?? 0;
+                    const maxCol = extent?.[2] ?? 0;
+                    if (maxRow >= 1 && maxCol >= 1) {
+                        next = foldWindow(next, engine.readWindow(es.sheetId, 1, 1, maxRow, maxCol));
+                    }
+                }
+            }
+            const sheets = reconcileSheets(next.sheets, engineSheets);
+            return sheets === next.sheets ? next : { ...next, sheets };
+        });
+        // Re-read the engine's authoritative facets / extents / history after the replace.
+        setExtents(engine.sheetExtents?.() ?? []);
+        const nextFacets = engine.documentFacetsJson();
+        setFacetsJson((prev) => (prev === nextFacets ? prev : nextFacets));
+        setHist({ canUndo: engine.canUndo(), canRedo: engine.canRedo() });
+        // The document was REPLACED: the old workbook's per-sheet cursors are meaningless on the new one
+        // (imported sheet ids typically collide with the old ids), and the view undo/redo stacks pair with
+        // engine history that no longer exists. Reset all of it; the import opens at the first sheet's A1.
+        activeCellBySheetIdRef.current = {};
+        selectionsBySheetIdRef.current = {};
+        setActiveCellBySheetId({});
+        setSelectionsBySheetId({});
+        viewUndo.current = [];
+        viewRedo.current = [];
+        lastUndoDepth.current = engine.undoDepth();
+        viewRef.current = {
+            activeSheetId: firstId,
+            activeCell: DEFAULT_ACTIVE_CELL,
+            selections: DEFAULT_ARRAY,
+        };
+        setActiveSheetId(firstId);
+        return true;
+    }, []);
+    // WINDOWED reads. Wire to CanvasGrid's `onViewPortChange`: read the visible range (+ a buffer) from
+    // the engine and replace the in-JS window (evicting cells outside it, so memory stays O(viewport)).
+    // A no-op in the default mode (every cell is already folded). Reads the active sheet from `viewRef`
+    // (live, no stale closure) so it stays a stable callback.
+    const onViewPortChange = useCallback((viewport) => {
+        if (!windowedRef.current)
+            return;
+        const engine = engineRef.current;
+        if (!engine)
+            return;
+        // Remember the visible span so a sheet switch (which doesn't re-fire this) can re-seed to it.
+        lastViewportRef.current = viewport;
+        const sheetId = viewRef.current.activeSheetId;
+        // Skip the re-read while the visible range is still comfortably INSIDE the loaded window. The window
+        // already extends a full buffer past the prior viewport, so scrolling within it needs no engine read
+        // (the cells are in state) — doing one on every tick is what made windowed scrolling jitter. We only
+        // re-read when the viewport gets within the refresh margin of an edge we could still scroll past (a
+        // window edge sitting at 1 / `Math.max` clamp can't extend further, so it never forces a re-read).
+        const loaded = windowRef.current;
+        if (loaded &&
+            loaded.sheetId === sheetId &&
+            (loaded.startRow <= 1 ||
+                viewport.rowStartIndex >=
+                    loaded.startRow + WINDOW_REFRESH_MARGIN_ROWS) &&
+            viewport.rowStopIndex <= loaded.endRow - WINDOW_REFRESH_MARGIN_ROWS &&
+            (loaded.startCol <= 1 ||
+                viewport.columnStartIndex >=
+                    loaded.startCol + WINDOW_REFRESH_MARGIN_COLS) &&
+            viewport.columnStopIndex <= loaded.endCol - WINDOW_REFRESH_MARGIN_COLS) {
+            return;
+        }
+        // CanvasGrid reports 0-indexed buffered bounds; the engine window is 1-indexed inclusive. Clamp the
+        // low edge to 1 and pad both edges by the buffer so a small scroll reveals already-loaded cells.
+        const startRow = Math.max(1, viewport.rowStartIndex - WINDOW_BUFFER_ROWS);
+        const startCol = Math.max(1, viewport.columnStartIndex - WINDOW_BUFFER_COLS);
+        const endRow = Math.max(startRow, viewport.rowStopIndex + WINDOW_BUFFER_ROWS);
+        const endCol = Math.max(startCol, viewport.columnStopIndex + WINDOW_BUFFER_COLS);
+        const w = { sheetId, startRow, startCol, endRow, endCol };
+        windowRef.current = w;
+        const snaps = readWindowedSnapshots(engine, w);
+        setState((prev) => foldWindows(prev, snaps));
+    }, [readWindowedSnapshots]);
+    const onChangeActiveSheet = useCallback((sheetId) => {
+        // An explicit pick (user tab click, host navigation) permanently disables the post-hydration
+        // initial-active-sheet re-derivation — never yank the user off a sheet they chose.
+        userPickedSheetRef.current = true;
+        // Restore the target sheet's remembered cursor/selections (per-sheet view state, like the JS
+        // engine's `useSheetState`) so callbacks reading `viewRef` see the restored view immediately.
+        viewRef.current = viewOfSheet(sheetId);
+        setActiveSheetId(sheetId);
+        // Windowed: re-seed the window on the newly-active sheet (the old window pointed at the prior
+        // sheet). Switching sheets keeps the scroll position, so CanvasGrid does NOT re-fire
+        // `onViewPortChange` — re-seed to the SAME span the user is currently viewing (the last reported
+        // viewport) so the whole visible grid loads, not just a top-left A–F placeholder. Fall back to the
+        // top-left default only before the first viewport report.
+        if (windowedRef.current && engineRef.current) {
+            const vp = lastViewportRef.current;
+            const w = vp
+                ? {
+                    sheetId,
+                    startRow: Math.max(1, vp.rowStartIndex - WINDOW_BUFFER_ROWS),
+                    startCol: Math.max(1, vp.columnStartIndex - WINDOW_BUFFER_COLS),
+                    endRow: Math.max(1, vp.rowStopIndex) + WINDOW_BUFFER_ROWS,
+                    endCol: Math.max(1, vp.columnStopIndex) + WINDOW_BUFFER_COLS,
+                }
+                : {
+                    sheetId,
+                    startRow: 1,
+                    startCol: 1,
+                    endRow: 1 + WINDOW_BUFFER_ROWS,
+                    endCol: 1 + WINDOW_BUFFER_COLS,
+                };
+            windowRef.current = w;
+            const snaps = readWindowedSnapshots(engineRef.current, w);
+            setState((prev) => foldWindows(prev, snaps));
+        }
+    }, [readWindowedSnapshots]);
+    const onChangeActiveCell = useCallback((sheetId, c) => {
+        const next = { ...activeCellBySheetIdRef.current, [sheetId]: c };
+        activeCellBySheetIdRef.current = next;
+        if (sheetId === viewRef.current.activeSheetId)
+            viewRef.current = { ...viewRef.current, activeCell: c };
+        setActiveCellBySheetId(next);
+    }, []);
+    const onChangeSelections = useCallback((sheetId, sel) => {
+        const next = { ...selectionsBySheetIdRef.current, [sheetId]: sel };
+        selectionsBySheetIdRef.current = next;
+        if (sheetId === viewRef.current.activeSheetId)
+            viewRef.current = { ...viewRef.current, selections: sel };
+        setSelectionsBySheetId(next);
+    }, []);
+    const { sheetData, cellStyles, derivedFormats, notes } = state;
+    const getCellData = useCallback((sheetId, rowIndex, columnIndex) => {
+        const committed = sheetData?.[sheetId]?.[rowIndex]?.values?.[columnIndex] ?? undefined;
+        // A previewing stream shadows the committed cell — until the real value lands, which is any
+        // change to what was committed when the preview was painted (`basis`). That covers a local
+        // apply, a backend tool's authoritative write, and a collab peer's edit alike.
+        const preview = streamPreview?.get(cellKey(sheetId, rowIndex, columnIndex));
+        if (preview && committed?.fv === preview.basis)
+            return preview.data;
+        return committed;
+    }, [sheetData, streamPreview]);
+    // Stable-identity cache for the user⊕derived merge: a 2-level `WeakMap<userFmt, WeakMap<derivedFmt,
+    // merged>>`, so the SAME merged object is returned across renders unless an input actually changes.
+    // Mirrors `use-sheet-properties`'s `getEffectiveFormat`, keeping the grid from re-rendering on
+    // identity churn. GC-friendly: keyed on the format objects themselves (no manual eviction).
+    const mergedFormatCache = useRef(new WeakMap());
+    const getEffectiveFormat = useCallback((sheetId, rowIndex, columnIndex) => {
+        const key = cellKey(sheetId, rowIndex, columnIndex);
+        // The cell's OWN consolidated style. Conditional formatting is NOT layered here — CanvasGrid
+        // computes it from the rules (`useConditionalFormatting`); CF overlays don't ride on the format.
+        const own = cellStyles.get(key);
+        // A previewing stream's formatting wins over the committed style, so the preview shows what the
+        // apply will look like — under the same "until the real value lands" rule `getCellData` uses.
+        const previewEntry = streamPreview?.get(key);
+        if (previewEntry?.format &&
+            (sheetData?.[sheetId]?.[rowIndex]?.values?.[columnIndex]?.fv ??
+                undefined) === previewEntry.basis)
+            return own ? { ...own, ...previewEntry.format } : previewEntry.format;
+        // The engine-derived inherited format (`=SUM($a,$b)` → currency), layered UNDER the user's own
+        // style — exactly as the JS reference's `getDerivedFormat`. The engine suppresses it whenever the
+        // cell has its own number format, so the user's choice always wins on conflict.
+        const derived = derivedFormats.get(key);
+        if (!derived)
+            return own;
+        if (!own)
+            return derived;
+        let inner = mergedFormatCache.current.get(own);
+        if (!inner) {
+            inner = new WeakMap();
+            mergedFormatCache.current.set(own, inner);
+        }
+        let merged = inner.get(derived);
+        if (!merged) {
+            merged = { ...derived, ...own };
+            inner.set(derived, merged);
+        }
+        return merged;
+    }, [cellStyles, derivedFormats, streamPreview, sheetData]);
+    const getNote = useCallback((sheetId, rowIndex, columnIndex) => notes.get(cellKey(sheetId, rowIndex, columnIndex)), [notes]);
+    const getFormattedValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cell = getCellData(sheetId, rowIndex, columnIndex);
+        // A host-call cell awaiting its answer displays the loading placeholder, not the engine's
+        // `#PENDING!` sentinel text (the JS engine's transient `fv = "Loading..."` analog).
+        if (isPendingEvalError(cell?.ev))
+            return LOADING_FORMATTED_VALUE;
+        // A structured result's display text lives in the payload, NOT the engine-derived `fv`
+        // (which is empty for a structured-only effective value). Mirrors useSheetProperties'
+        // `getFormattedValue` structured branch, so chips (=AOP queued/running/answered states,
+        // hyperlink results) report the text they display — without this, consumers keyed on the
+        // formatted value treat the cell as EMPTY (e.g. a long neighbour's text overflows over a
+        // queued =AOP chip).
+        const structured = cell?.ev?.structuredValue;
+        if (structured) {
+            switch (structured.kind) {
+                case "hyperlink":
+                    return (structured.title ??
+                        structured.url);
+                case "image":
+                    return "";
+                default:
+                    return (structured.formattedValue ??
+                        cell?.fv ??
+                        undefined);
+            }
+        }
+        // Excel display parity: a user-entered lone text-prefix apostrophe (`'`)
+        // renders as a blank cell — the `'` stays visible only in the formula
+        // bar / editor (`ue`). Guarding the read side also heals documents whose
+        // persisted `fv` was stamped before this rule existed.
+        if (cell?.ue?.sv === "'") {
+            return "";
+        }
+        return cell?.fv ?? undefined;
+    }, [getCellData]);
+    // The cell's effective value as a SCALAR (bool ?? number ?? string) — the shape `<CanvasGrid>` and
+    // chart series want. Mirrors useSheetProperties' `getEffectiveValue`. Errors → undefined.
+    const getEffectiveValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const ev = getCellData(sheetId, rowIndex, columnIndex)?.ev;
+        if (!ev)
+            return undefined;
+        return ev.bv ?? ev.nv ?? ev.sv ?? undefined;
+    }, [getCellData]);
+    // The cell's effective value as the full extended-value OBJECT (`{nv,sv,bv,…}`) — the
+    // useSheetProperties `getEffectiveExtendedValue` (api / backwards-compat consumers).
+    // The `#PENDING!` sentinel is stripped: CanvasGrid derives its red error corner-marker from
+    // THIS accessor (`getExtendedValueError(getEffectiveExtendedValue(...))`, not the hook's
+    // `getErrorValue`), so leaking the pending eval error paints every in-flight async formula —
+    // and its dependents — as errored. A pending ev carries no scalar value, so omitting the
+    // error facet loses nothing for the other consumers.
+    // Cache the ev synthesized for an invalid cell (keyed on the folded cell object, which is
+    // replaced whenever its value or verdict changes) so repeated reads keep a stable identity.
+    const invalidEvCache = useRef(new WeakMap());
+    const getEffectiveExtendedValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cell = getCellData(sheetId, rowIndex, columnIndex);
+        const ev = cell?.ev;
+        if (ev && isPendingEvalError(ev)) {
+            const { ev: _pendingError, ...rest } = ev;
+            return rest;
+        }
+        // The engine's data-validation verdict rides `dataValidationResult` (`false` = violates its
+        // rule), not `ev.ev` — bridge it into the error facet so the grid draws the same Invalid
+        // corner + popover the JS host stamps via `SheetCell.validate()`.
+        if (cell && cell.dataValidationResult === false && !ev?.ev) {
+            let merged = invalidEvCache.current.get(cell);
+            if (!merged) {
+                merged = { ...(ev ?? {}), ev: DATA_VALIDATION_INVALID_ERROR };
+                invalidEvCache.current.set(cell, merged);
+            }
+            return merged;
+        }
+        return ev;
+    }, [getCellData]);
+    const getUserEnteredValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const ue = getCellData(sheetId, rowIndex, columnIndex)?.ue;
+        if (!ue)
+            return undefined;
+        if (ue.fv != null)
+            return ue.fv; // a formula (`=SUM(...)`)
+        if (ue.nv != null)
+            return String(ue.nv);
+        if (ue.bv != null)
+            return ue.bv ? "TRUE" : "FALSE";
+        return ue.sv ?? undefined;
+    }, [getCellData]);
+    const getHyperlink = useCallback((sheetId, rowIndex, columnIndex) => getCellData(sheetId, rowIndex, columnIndex)?.hyperlink, [getCellData]);
+    // ── Additional cell accessors (mirror useSheetProperties / useSpreadsheetState, typed via SS) ──
+    // Rich-text runs ride on the cell (`textFormatRuns`, emitted by the engine from the imported
+    // rich shared string). Surface them so the grid renders mixed in-cell formatting.
+    const getTextFormatRuns = useCallback((sheetId, rowIndex, columnIndex) => getCellData(sheetId, rowIndex, columnIndex)?.textFormatRuns, [getCellData]);
+    const getUserEnteredExtendedValue = useCallback((sheetId, rowIndex, columnIndex) => getCellData(sheetId, rowIndex, columnIndex)?.ue, [getCellData]);
+    const getUserEnteredFormat = useCallback((sheetId, rowIndex, columnIndex) => cellStyles.get(cellKey(sheetId, rowIndex, columnIndex)), [cellStyles]);
+    const getErrorValue = useCallback((sheetId, rowIndex, columnIndex) => {
+        const cell = getCellData(sheetId, rowIndex, columnIndex);
+        const ev = cell?.ev;
+        // The `#PENDING!` sentinel is a WAIT state, not a failure — presenting it through the error
+        // channel would draw the red corner + error popover on every in-flight async formula. The
+        // cell displays "Loading..." via `getFormattedValue` instead.
+        if (isPendingEvalError(ev))
+            return undefined;
+        if (ev?.ev)
+            return ev.ev;
+        // The engine's data-validation verdict rides `dataValidationResult` (`false` = violates its
+        // rule), NOT `ev.ev` — bridge it here, matching `getEffectiveExtendedValue`, so both error
+        // channels agree with the Invalid marker the JS host stamps via `SheetCell.validate()`.
+        if (cell?.dataValidationResult === false) {
+            return DATA_VALIDATION_INVALID_ERROR;
+        }
+        return undefined;
+    }, [getCellData]);
+    // Mentions ride on the cell's rich-text runs — the mention-typed entries of `textFormatRuns`
+    // (the reference filters its shared-strings runs the same way).
+    const getMentionsFromCell = useCallback((sheetId, rowIndex, columnIndex) => getTextFormatRuns(sheetId, rowIndex, columnIndex)?.filter((run) => run.nodeType === "mention"), [getTextFormatRuns]);
+    const { sheets } = state;
+    // Memoized sheet lookups — the `useSheetProperties` pattern (`sheetMetaDataById` /
+    // `sheetPropertiesById`): build maps ONCE per sheet-list change so every accessor is O(1), instead
+    // of an O(n) `sheets.find()` on each call (which the grid fires per visible cell, per render).
+    const { sheetById, sheetIndexById, sheetIdByName } = useMemo(() => {
+        const byId = new Map();
+        const indexById = new Map();
+        const idByName = new Map();
+        sheets.forEach((s, i) => {
+            byId.set(s.sheetId, s);
+            indexById.set(s.sheetId, i);
+            if (s.title != null)
+                idByName.set(String(s.title), s.sheetId);
+        });
+        return {
+            sheetById: byId,
+            sheetIndexById: indexById,
+            sheetIdByName: idByName,
+        };
+    }, [sheets]);
+    // Engine data extent per sheet `sheetId → {rows, cols}` (windowed mode). The grid's scroll extent
+    // takes the MAX of the seeded sheet count and the engine's data extent — so the sheet scrolls past
+    // the loaded window (the whole point) without ever shrinking below the declared grid size.
+    const extentById = useMemo(() => {
+        const m = new Map();
+        for (const [sheetId, rows, cols] of extents)
+            m.set(sheetId, { rows, cols });
+        return m;
+    }, [extents]);
+    const dimMeta = useCallback((sheetId, axis, index) => {
+        const meta = sheetById.get(sheetId)?.[axis];
+        return meta?.[index];
+    }, [sheetById]);
+    const getRowHeight = useCallback((sheetId, rowIndex) => dimMeta(sheetId, "rowMetadata", rowIndex)?.size, [dimMeta]);
+    const getColumnWidth = useCallback((sheetId, columnIndex) => dimMeta(sheetId, "columnMetadata", columnIndex)?.size, [dimMeta]);
+    const isHiddenRow = useCallback((sheetId, rowIndex) => {
+        const m = dimMeta(sheetId, "rowMetadata", rowIndex);
+        return Boolean(m?.hiddenByUser || m?.hiddenByFilter || m?.hiddenByGroup);
+    }, [dimMeta]);
+    const isHiddenColumn = useCallback((sheetId, columnIndex) => {
+        const m = dimMeta(sheetId, "columnMetadata", columnIndex);
+        return Boolean(m?.hiddenByUser || m?.hiddenByFilter || m?.hiddenByGroup);
+    }, [dimMeta]);
+    // Return types mirror CanvasGridProps exactly (string / number, not `… | undefined`) so the hook is
+    // a cast-free drop-in. A missing sheet falls back to the grid defaults.
+    const getSheetName = useCallback((sheetId) => sheetById.get(sheetId)?.title ?? "", [sheetById]);
+    const getSheetCount = useCallback(() => sheets.length, [sheets]);
+    const getSheetIndex = useCallback((sheetId) => sheetIndexById.get(sheetId) ?? -1, [sheetIndexById]);
+    const getSheetId = useCallback((title) => sheetIdByName.get(title), [sheetIdByName]);
+    // The sheet's grid extent. In windowed mode it's the MAX of the seeded count and the engine's data
+    // extent, so the grid scrolls the full sheet even though JS holds only the window.
+    const getSheetRowCount = useCallback((sheetId) => Math.max(sheetById.get(sheetId)?.rowCount ?? 1000, extentById.get(sheetId)?.rows ?? 0), [sheetById, extentById]);
+    const getSheetColumnCount = useCallback((sheetId) => Math.max(sheetById.get(sheetId)?.columnCount ?? 26, extentById.get(sheetId)?.cols ?? 0), [sheetById, extentById]);
+    // Rows that actually carry data (the grid uses this to bound auto-fill / navigation). `sheetId` is
+    // optional to match the grid's `getDataRowCount?(sheetId?: number)`. In windowed mode the folded
+    // `sheetData` is only the viewport, so fall back to the engine's data extent (the true data height).
+    const getDataRowCount = useCallback((sheetId) => {
+        if (windowedRef.current && sheetId != null) {
+            const ext = extentById.get(sheetId)?.rows;
+            if (ext != null)
+                return ext;
+        }
+        return sheetData[String(sheetId)]?.length;
+    }, [sheetData, extentById]);
+    const getDataColumnCount = useCallback((sheetId) => {
+        const rows = sheetData[String(sheetId)];
+        let max = 0;
+        for (const row of rows ?? [])
+            max = Math.max(max, row?.values?.length ?? 0);
+        return max;
+    }, [sheetData]);
+    const getNonEmptyRowCount = useCallback((sheetId) => sheetData[String(sheetId)]?.length, [sheetData]);
+    const getNonEmptyColumnCount = useCallback((sheetId, rowIndex) => {
+        const rows = sheetData[String(sheetId)];
+        return rows?.[rowIndex]?.values?.length;
+    }, [sheetData]);
+    // ── Range reads (charts / pivots) ──
+    // CRITICAL: a chart/pivot source range can extend FAR past the rendered window, so these read the
+    // FULL document from the engine via `readWindow` (which accepts any rectangle) — NOT the hook's
+    // folded `sheetData`, which only holds the visible viewport. `readWindow` is a synchronous in-process
+    // WASM call today, so these stay sync (the chart/pivot consumer contract requires sync). They will
+    // need to become async only when the engine moves off the main thread (Web Worker) or behind a
+    // remote data source — at which point those consumers' contracts change too (queue-until-loaded).
+    // The `sheetData` dep is the reactivity signal: a new fold ⇒ new accessor identity ⇒ charts re-read.
+    /** Off-window search: row-major coordinates of every cell on `sheetId` matching `query`. Backed by
+     * the engine (`RncEngine.findAll`), so it finds matches OUTSIDE the loaded viewport — which the JS
+     * `useSearch` (it only sees loaded cells) cannot. Wire this as `useSearch`'s `findMatches` so search,
+     * next/prev, counter, and highlighting all work over the full windowed document. */
+    const findAll = useCallback((sheetId, query, options) => engineRef.current?.findAll(sheetId, query, options) ?? [], []);
+    const getSeriesValuesFromRange = useCallback((sheetRange, hiddenDimensionStrategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const engine = engineRef.current;
+        if (!engine)
+            return [];
+        const { sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex, } = sheetRange;
+        const snap = engine.readWindow(sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex);
+        // `readWindow` returns only the non-empty cells, sparsely — index them, then walk the full range
+        // in row-major order so absent cells surface as `undefined` (matching the reference accessor).
+        const byKey = new Map();
+        for (const c of snap.cells)
+            byKey.set(`${c.rowIndex},${c.columnIndex}`, c.number ?? (c.formatted || undefined));
+        const values = [];
+        const { skipRows, skipCols } = hiddenStrategyAxes(hiddenDimensionStrategy);
+        for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+            for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                if ((skipRows && isHiddenRow(sheetId, rowIndex)) ||
+                    (skipCols && isHiddenColumn(sheetId, columnIndex)))
+                    continue;
+                values.push(byKey.get(`${rowIndex},${columnIndex}`));
+            }
+        }
+        return values;
+    }, 
+    // `sheetData` is an intentional reactivity signal: the body reads the engine (not the fold), so a
+    // new fold ⇒ new accessor identity ⇒ chart consumers re-read. See the block comment above.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sheetData, isHiddenRow, isHiddenColumn]);
+    const getColumnarDataFromRange = useCallback((sheetRange) => {
+        const columnar = {};
+        const engine = engineRef.current;
+        if (!engine)
+            return columnar;
+        const { sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex, } = sheetRange;
+        const snap = engine.readWindow(sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex);
+        const byKey = new Map();
+        for (const c of snap.cells)
+            byKey.set(`${c.rowIndex},${c.columnIndex}`, c);
+        // First row = the column headers; each column below it becomes `columnar[header]`.
+        for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+            const header = byKey.get(`${startRowIndex},${columnIndex}`)?.formatted;
+            if (header == null)
+                continue;
+            const col = [];
+            for (let rowIndex = startRowIndex + 1; rowIndex <= endRowIndex; rowIndex++) {
+                const cell = byKey.get(`${rowIndex},${columnIndex}`);
+                col.push(cell ? cell.number ?? cell.formatted : "");
+            }
+            columnar[header] = col;
+        }
+        return columnar;
+    }, 
+    // `sheetData` is an intentional reactivity signal (see getSeriesValuesFromRange).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sheetData]);
+    // The FORMATTED display values of a range, in row-major order — chart DOMAIN (axis labels). Same
+    // engine-sourced (off-window-safe) walk as getSeriesValuesFromRange, but uses `cell.formatted`.
+    const getDomainValuesFromRange = useCallback((sheetRange, hiddenDimensionStrategy = "SKIP_HIDDEN_ROWS_AND_COLUMNS") => {
+        const engine = engineRef.current;
+        if (!engine)
+            return [];
+        const { sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex, } = sheetRange;
+        const snap = engine.readWindow(sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex);
+        const byKey = new Map();
+        for (const c of snap.cells)
+            byKey.set(`${c.rowIndex},${c.columnIndex}`, c.formatted || undefined);
+        const values = [];
+        const { skipRows, skipCols } = hiddenStrategyAxes(hiddenDimensionStrategy);
+        for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+            for (let columnIndex = startColumnIndex; columnIndex <= endColumnIndex; columnIndex++) {
+                if ((skipRows && isHiddenRow(sheetId, rowIndex)) ||
+                    (skipCols && isHiddenColumn(sheetId, columnIndex)))
+                    continue;
+                values.push(byKey.get(`${rowIndex},${columnIndex}`));
+            }
+        }
+        return values;
+    }, 
+    // `sheetData` is an intentional reactivity signal (see getSeriesValuesFromRange).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sheetData, isHiddenRow, isHiddenColumn]);
+    // Range readers — a row-major walk over the folded cells, surfacing per cell the user-entered value,
+    // the formula source, or the effective format. `useSpreadsheetState` exposes these off its JS
+    // calculator; here they reuse the engine-backed accessors. The `HIDDEN_DIMENSION_STRATEGY` picks
+    // which hidden axes are omitted (rows, columns, both — or none for `SHOW_ALL`).
+    const getUserEnteredValuesFromRange = useCallback((sheetRange, strategy) => {
+        const { sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex, } = sheetRange;
+        const { skipRows, skipCols } = hiddenStrategyAxes(strategy);
+        const out = [];
+        for (let r = startRowIndex; r <= endRowIndex; r++)
+            for (let c = startColumnIndex; c <= endColumnIndex; c++) {
+                if ((skipRows && isHiddenRow(sheetId, r)) ||
+                    (skipCols && isHiddenColumn(sheetId, c)))
+                    continue;
+                out.push(getUserEnteredValue(sheetId, r, c));
+            }
+        return out;
+    }, [getUserEnteredValue, isHiddenRow, isHiddenColumn]);
+    const getFormulasFromRange = useCallback((sheetRange, strategy) => {
+        const { sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex, } = sheetRange;
+        const { skipRows, skipCols } = hiddenStrategyAxes(strategy);
+        const out = [];
+        for (let r = startRowIndex; r <= endRowIndex; r++)
+            for (let c = startColumnIndex; c <= endColumnIndex; c++) {
+                if ((skipRows && isHiddenRow(sheetId, r)) ||
+                    (skipCols && isHiddenColumn(sheetId, c)))
+                    continue;
+                // The formula source (`=…`) only; a literal cell contributes `undefined`.
+                out.push(getCellData(sheetId, r, c)?.ue?.fv ?? undefined);
+            }
+        return out;
+    }, [getCellData, isHiddenRow, isHiddenColumn]);
+    const getFormattingFromRange = useCallback((sheetRange, strategy) => {
+        const { sheetId, startRowIndex, startColumnIndex, endRowIndex, endColumnIndex, } = sheetRange;
+        const { skipRows, skipCols } = hiddenStrategyAxes(strategy);
+        const out = [];
+        for (let r = startRowIndex; r <= endRowIndex; r++)
+            for (let c = startColumnIndex; c <= endColumnIndex; c++) {
+                if ((skipRows && isHiddenRow(sheetId, r)) ||
+                    (skipCols && isHiddenColumn(sheetId, c)))
+                    continue;
+                out.push(getEffectiveFormat(sheetId, r, c));
+            }
+        return out;
+    }, [getEffectiveFormat, isHiddenRow, isHiddenColumn]);
+    // Dependency queries — backed by the engine's REAL graph (it parses each formula with the grammar it
+    // evaluates). Returned as `@rowsncolumns/dag` nodes so they're drop-in for the reference's trace
+    // tooling: the source node's `inputKeys` carry its DIRECT precedents, and each dependent carries its
+    // OWN refs as `inputKeys` — the exact shape `useOnTraceDependentsPrecedents` walks to build arrows.
+    // A range SOURCE unions the per-cell results (deduped by node key), bounded to the engine's data
+    // extent so a full-column selection doesn't walk a million empty cells.
+    const sourceCellsOf = useCallback((engine, source) => {
+        if (isCellCoordinate(source))
+            return [source];
+        // The engine's data extent (authoritative, current even in non-windowed mode where the hook's
+        // extent state isn't refreshed per commit); the folded state extent is the fallback.
+        const engineExtent = engine
+            .sheetExtents()
+            .find((e) => e[0] === source.sheetId);
+        const extent = engineExtent
+            ? { rows: engineExtent[1], cols: engineExtent[2] }
+            : extentById.get(source.sheetId);
+        const endRow = Math.min(source.endRowIndex, Math.max(extent?.rows ?? 0, source.startRowIndex));
+        const endCol = Math.min(source.endColumnIndex, Math.max(extent?.cols ?? 0, source.startColumnIndex));
+        const cells = [];
+        for (let r = source.startRowIndex; r <= endRow; r++)
+            for (let c = source.startColumnIndex; c <= endCol; c++)
+                cells.push({ sheetId: source.sheetId, rowIndex: r, columnIndex: c });
+        return cells;
+    }, [extentById]);
+    const getPrecedents = useCallback((source, includeSource) => {
+        const engine = engineRef.current;
+        if (!engine)
+            return [];
+        const sourceKey = makeKey(source);
+        const byKey = new Map();
+        for (const cell of sourceCellsOf(engine, source)) {
+            const { cells, ranges } = engine.precedents(cell.sheetId, cell.rowIndex, cell.columnIndex);
+            for (const c of cells) {
+                const k = makeKey(c);
+                if (k !== sourceKey && !byKey.has(k))
+                    byKey.set(k, new CellNode(k, c));
+            }
+            for (const r of ranges) {
+                const k = makeKey(r);
+                if (k !== sourceKey && !byKey.has(k))
+                    byKey.set(k, new CellRangeNode(k, r));
+            }
+        }
+        const nodes = [...byKey.values()];
+        if (!includeSource)
+            return nodes;
+        if (isCellCoordinate(source)) {
+            const sourceNode = new CellNode(sourceKey, source);
+            for (const n of nodes)
+                sourceNode.inputKeys.add(n);
+            return [sourceNode, ...nodes];
+        }
+        const sourceNode = new CellRangeNode(sourceKey, source);
+        for (const n of nodes)
+            if (isCellNode(n))
+                sourceNode.inputKeys.add(n);
+        return [sourceNode, ...nodes];
+    }, 
+    // `sheetData` is an intentional reactivity signal (see getSeriesValuesFromRange).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sheetData, sourceCellsOf]);
+    const getDependents = useCallback((source, includeSource) => {
+        const engine = engineRef.current;
+        if (!engine)
+            return [];
+        const sourceKey = makeKey(source);
+        const byKey = new Map();
+        for (const cell of sourceCellsOf(engine, source)) {
+            for (const d of engine.dependents(cell.sheetId, cell.rowIndex, cell.columnIndex)) {
+                const k = makeKey(d);
+                if (k !== sourceKey && !byKey.has(k))
+                    byKey.set(k, new CellNode(k, d));
+            }
+        }
+        for (const node of byKey.values()) {
+            const { cells, ranges } = engine.precedents(node.position.sheetId, node.position.rowIndex, node.position.columnIndex);
+            for (const c of cells)
+                node.inputKeys.add(new CellNode(makeKey(c), c));
+            for (const r of ranges)
+                node.inputKeys.add(new CellRangeNode(makeKey(r), r));
+        }
+        const nodes = [...byKey.values()];
+        // The source node only rides along for a CELL source — the reference's return type
+        // (`(CellNode | StaticNode)[]`) has no range-node arm.
+        return includeSource && isCellCoordinate(source)
+            ? [new CellNode(sourceKey, source), ...nodes]
+            : nodes;
+    }, 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [sheetData, sourceCellsOf]);
+    // Trace precedents/dependents arrows — the REFERENCE hook (state + `<Arrow/>` node construction)
+    // composed over the engine-backed queries above. Arrows are rebuilt per trace call and cleared by
+    // `onRemoveArrows`, exactly like the JS engine.
+    const { arrows, onRemoveArrows, onTraceDependents, onTracePrecedents } = useOnTraceDependentsPrecedents({ getDependents, getPrecedents });
+    // A sheet-property update → ONE `update-sheet` command carrying the partial spec; the engine applies
+    // the provided fields (title + view metadata). Returns undefined: the engine streams the result, so
+    // callers don't need the updated Sheet back synchronously (the `S | undefined` signature allows it).
+    const onUpdateSheet = useCallback((sheetId, sheetSpec) => {
+        onCommand({ command: "update-sheet", sheetId, sheetSpec });
+        return undefined;
+    }, [onCommand]);
+    // "Add N more rows" (the grid footer): extend the sheet's grid size — the reference's `rowCount`
+    // bump through `onUpdateSheet`. The grid's scroll extent derives from the render-state sheet
+    // (`MAX(rowCount, data extent)`), so the bump lands on the render state; the engine grows cell
+    // storage on demand and has no explicit row capacity to update.
+    const onRequestAddRows = useCallback((sheetId, additionalRowCount) => {
+        setState((prev) => ({
+            ...prev,
+            sheets: prev.sheets.map((s) => s.sheetId === sheetId
+                ? { ...s, rowCount: (s.rowCount ?? 1000) + additionalRowCount }
+                : s),
+        }));
+        return undefined;
+    }, []);
+    // Delete data-validation rules — one `delete-data-validation` command per rule.
+    const onDeleteDataValidationRules = useCallback((rules) => {
+        for (const rule of rules)
+            onCommand({ command: "delete-data-validation", ruleId: rule.id });
+    }, [onCommand]);
+    // Clear the engine's undo/redo history (the document is unchanged) + reset the toolbar flags.
+    const onClearHistory = useCallback(() => {
+        engineRef.current?.clearHistory();
+        setHist({ canUndo: false, canRedo: false });
+    }, []);
+    // Streaming batch writes — the AI/agent write path, with the reference hook's exact public
+    // contract: an async iterable of CUMULATIVE row-major chunks (each chunk restates the range's rows
+    // so far; `rows[0]` maps to `range.startRowIndex`), `onStreamStart` / `onStreamProgress` (last
+    // non-empty cell) / `onStreamEnd` lifecycle callbacks, and the `disableDelta` /
+    // `disableEvaluation` / `isAborted` options. Each chunk is applied as ONE `change-batch` command —
+    // NOT the engine's NDJSON `streamBegin`/`streamWrite`/`streamEnd`, which is a load-time hydration
+    // (raw `StreamRecord` lines, one recompute at the very end, no per-chunk visibility). Command-per-
+    // chunk gives progressive rendering through the normal commit → fold pipeline, engine-evaluated
+    // formulas, and the engine's own row-height refit for wrap/text-format styles.
+    //
+    // Divergences from the reference internals (same observable contract):
+    //   • A cell the chunk doesn't own a value for but still touches (style-only `cell_styles`, or a
+    //     formula skipped under `disableEvaluation`) RESTATES its current user-entered value in the
+    //     grid — `change-batch` is an atomic rectangle write, and a `null` entry would clear the cell
+    //     the reference preserves. The restate is read from the engine (off-window-safe).
+    //   • Delta mode (`disableDelta: false`) governs PROGRESS reporting (each cell is announced once);
+    //     the write always restates the chunk's full rows — the input is cumulative, so the rewrite is
+    //     idempotent and the final document is identical.
+    const onChangeBatchStream = useCallback((sheetId, range, stream, streamOptions) => {
+        const streamId = `stream_${Date.now()}_${Math.random()
+            .toString(36)
+            .substring(2, 9)}`;
+        onStreamStartRef.current?.(streamId);
+        const disableDeltaUpdates = streamOptions?.disableDelta ?? true;
+        const disableEvaluation = streamOptions?.disableEvaluation;
+        // Opt-in commit-per-chunk, for a caller that genuinely wants each chunk persisted as it
+        // arrives (and accepts N undo entries). The default is the documented preview contract.
+        const commitChunks = streamOptions
+            ?.commitChunks === true;
+        // Per-row column cursor (delta mode) — progress fires only for cells not yet announced.
+        const rowCursorByIndex = new Map();
+        return (async () => {
+            try {
+                for await (const rows of stream) {
+                    if (!Array.isArray(rows) || !rows.length)
+                        continue;
+                    if (streamOptions?.isAborted?.())
+                        return;
+                    const engine = engineRef.current;
+                    if (!engine)
+                        return;
+                    const rowCount = Math.min(rows.length, range.endRowIndex - range.startRowIndex + 1);
+                    if (rowCount <= 0)
+                        continue;
+                    // Existing user-entered values for restated cells, read lazily ONCE per chunk from the
+                    // engine. Prefers the lossless `cell.ue`; lean-window engines fall back to the formula
+                    // source / raw number.
+                    let existingUe = null;
+                    const restatedUeAt = (rowIndex, columnIndex) => {
+                        if (!existingUe) {
+                            existingUe = new Map();
+                            let maxLen = 0;
+                            for (let i = 0; i < rowCount; i++) {
+                                const len = Array.isArray(rows[i]) ? rows[i].length : 0;
+                                if (len > maxLen)
+                                    maxLen = len;
+                            }
+                            const endCol = Math.min(range.startColumnIndex + Math.max(maxLen, 1) - 1, range.endColumnIndex);
+                            const win = engine.readWindow(sheetId, range.startRowIndex, range.startColumnIndex, range.startRowIndex + rowCount - 1, endCol);
+                            for (const cell of win.cells) {
+                                const ue = cell.cell?.ue;
+                                const s = ue?.fv ??
+                                    (ue?.nv != null
+                                        ? String(ue.nv)
+                                        : ue?.bv != null
+                                            ? ue.bv
+                                                ? "TRUE"
+                                                : "FALSE"
+                                            : (ue?.sv ??
+                                                cell.formula ??
+                                                (cell.number != null
+                                                    ? String(cell.number)
+                                                    : cell.formatted || null)));
+                                if (s != null)
+                                    existingUe.set(`${cell.rowIndex},${cell.columnIndex}`, s);
+                            }
+                        }
+                        return existingUe.get(`${rowIndex},${columnIndex}`) ?? null;
+                    };
+                    const values = [];
+                    const formatting = [];
+                    let hasFormatting = false;
+                    let hasCells = false;
+                    let maxWrittenCols = 0;
+                    for (let i = 0; i < rowCount; i++) {
+                        const row = rows[i];
+                        const rowValues = [];
+                        const rowFormats = [];
+                        values.push(rowValues);
+                        formatting.push(rowFormats);
+                        if (!Array.isArray(row) || !row.length)
+                            continue;
+                        const absRow = range.startRowIndex + i;
+                        const colCount = Math.min(row.length, range.endColumnIndex - range.startColumnIndex + 1);
+                        const cursor = disableDeltaUpdates
+                            ? 0
+                            : (rowCursorByIndex.get(i) ?? 0);
+                        let lastNonEmptyIndex = -1;
+                        for (let j = 0; j < colCount; j++) {
+                            const cellInput = row[j];
+                            const absCol = range.startColumnIndex + j;
+                            const formula = cellInput?.formula;
+                            const hasFormula = formula != null && formula !== "";
+                            const hasValue = cellInput?.value != null && cellInput.value !== "";
+                            if (j >= cursor &&
+                                (hasFormula || hasValue || cellInput?.cell_styles != null)) {
+                                lastNonEmptyIndex = Math.max(lastNonEmptyIndex, j);
+                                onStreamProgressRef.current?.(streamId, sheetId, {
+                                    rowIndex: absRow,
+                                    columnIndex: absCol,
+                                });
+                            }
+                            if (hasFormula && !disableEvaluation) {
+                                const trimmed = String(formula).trim();
+                                rowValues.push(trimmed
+                                    ? trimmed.startsWith("=")
+                                        ? trimmed
+                                        : `=${trimmed}`
+                                    : null);
+                            }
+                            else if (hasFormula) {
+                                rowValues.push(restatedUeAt(absRow, absCol));
+                            }
+                            else if (cellInput?.value != null) {
+                                rowValues.push(String(cellInput.value));
+                            }
+                            else if (cellInput?.cell_styles != null) {
+                                rowValues.push(restatedUeAt(absRow, absCol));
+                            }
+                            else {
+                                rowValues.push(null);
+                            }
+                            const styles = cellInput?.cell_styles ?? null;
+                            rowFormats.push(styles);
+                            if (styles)
+                                hasFormatting = true;
+                        }
+                        hasCells = hasCells || colCount > 0;
+                        if (colCount > maxWrittenCols)
+                            maxWrittenCols = colCount;
+                        if (!disableDeltaUpdates && lastNonEmptyIndex >= cursor)
+                            rowCursorByIndex.set(i, lastNonEmptyIndex + 1);
+                    }
+                    if (streamOptions?.isAborted?.())
+                        return;
+                    if (!hasCells)
+                        continue;
+                    if (commitChunks) {
+                        onCommand({
+                            command: "change-batch",
+                            sheetId,
+                            ranges: [
+                                {
+                                    startRowIndex: range.startRowIndex,
+                                    endRowIndex: range.startRowIndex + rowCount - 1,
+                                    startColumnIndex: range.startColumnIndex,
+                                    endColumnIndex: range.startColumnIndex + Math.max(maxWrittenCols, 1) - 1,
+                                },
+                            ],
+                            values,
+                            formatting: hasFormatting ? formatting : undefined,
+                        });
+                        continue;
+                    }
+                    // Preview: paint the chunk locally, commit nothing. `null` entries are cells this chunk
+                    // doesn't own — leave the committed cell showing through rather than shadowing it blank.
+                    const preview = streamPreviewRef.current ?? new Map();
+                    for (let i = 0; i < values.length; i++) {
+                        const absRow = range.startRowIndex + i;
+                        const rowValues = values[i] ?? [];
+                        const rowFormats = formatting[i] ?? [];
+                        for (let j = 0; j < rowValues.length; j++) {
+                            const text = rowValues[j];
+                            const format = rowFormats[j] ?? null;
+                            if (text == null && !format)
+                                continue;
+                            const column = range.startColumnIndex + j;
+                            preview.set(cellKey(sheetId, absRow, column), {
+                                data: previewCellData(text),
+                                format,
+                                basis: committedFvAt(sheetId, absRow, column),
+                            });
+                        }
+                    }
+                    streamPreviewRef.current = preview;
+                    publishStreamPreview();
+                }
+            }
+            catch (error) {
+                if (!commitChunks)
+                    clearStreamPreview();
+                throw error;
+            }
+            finally {
+                // An aborted preview is discarded here. A COMPLETED preview deliberately survives: the
+                // host persists next, and the applying write retires it in that same render. Clearing on
+                // end instead would blank the cells until the apply landed.
+                if (!commitChunks && streamOptions?.isAborted?.())
+                    clearStreamPreview();
+                onStreamEndRef.current?.(streamId);
+            }
+        })();
+    }, [
+        onCommand,
+        clearStreamPreview,
+        publishStreamPreview,
+        committedFvAt,
+    ]);
+    // Derived dimensions of the active sheet (folded metadata + seeded counts) — O(1) via the map. In
+    // windowed mode the grid's scroll extent is MAX(seeded, engine data extent) so it scrolls the full
+    // sheet (`getSheetRowCount`/`getSheetColumnCount` apply the same max).
+    const activeSheet = sheetById.get(activeSheetId);
+    const activeExtent = extentById.get(activeSheetId);
+    const rowCount = Math.max(activeSheet?.rowCount ?? 1000, activeExtent?.rows ?? 0);
+    const columnCount = Math.max(activeSheet?.columnCount ?? 26, activeExtent?.cols ?? 0);
+    const frozenRowCount = activeSheet?.frozenRowCount ?? 0;
+    const frozenColumnCount = activeSheet?.frozenColumnCount ?? 0;
+    // Memoize the array facets on the active sheet — the `?? []` fallback would otherwise mint a fresh
+    // empty array each render and churn the return memo's deps. `activeSheet` is a stable Map reference
+    // while `sheets`/`activeSheetId` are unchanged.
+    const rowMetadata = useMemo(() => activeSheet?.rowMetadata ?? [], [activeSheet]);
+    const columnMetadata = useMemo(() => activeSheet?.columnMetadata ?? [], [activeSheet]);
+    const merges = useMemo(() => activeSheet?.merges ?? [], [activeSheet]);
+    // The full command-emitting handler surface — every `on*` is a thin shim turning UI-shaped args
+    // into a `commands.ts` command (the engine owns ALL execution). Built once: `onCommand` is a stable
+    // empty-dep useCallback. The pure factory + its spec (command-handlers.ts) guarantee the
+    // handler→command mapping; nothing here touches the document directly.
+    const handlers = useMemo(() => createCommandHandlers(onCommand), [onCommand]);
+    // Grid-shaped handlers that need view state (the active sheet). Kept as STABLE useCallbacks here (not
+    // in the pure factory) so `<CanvasGrid>` props don't churn every render — they read `viewRef.current`
+    // (the live active sheet) instead of closing over `activeSheetId`, so identity never changes. The
+    // grid omits sheetId from chart move/resize (charts live on the active sheet) and passes just the rule
+    // to create-conditional-format.
+    const onMoveChart = useCallback((chartId, anchorCell, offsetXPixels, offsetYPixels) => onCommand({
+        command: "move-chart",
+        chartId,
+        sheetId: viewRef.current.activeSheetId,
+        anchorCell,
+        offsetXPixels,
+        offsetYPixels,
+    }), [onCommand]);
+    const onResizeChart = useCallback((chartId, anchorCell, offsetXPixels, offsetYPixels, width, height) => onCommand({
+        command: "resize-chart",
+        chartId,
+        sheetId: viewRef.current.activeSheetId,
+        anchorCell,
+        offsetXPixels,
+        offsetYPixels,
+        width,
+        height,
+    }), [onCommand]);
+    const onCreateConditionalFormattingRule = useCallback((rule) => onCommand({
+        command: "create-conditional-format",
+        sheetId: viewRef.current.activeSheetId,
+        rule,
+    }), [onCommand]);
+    // Repeat the last formatting action on the current target — re-emit the recorded command (captured in
+    // `onCommand`) with the new sheet/cell/selection swapped in. Mirrors `onRepeatFormatting`.
+    const onRepeatFormatting = useCallback((sheetId, activeCell, selections) => {
+        const last = lastFormattingRef.current;
+        if (last)
+            onCommand({ ...last, sheetId, activeCell, selections });
+    }, [onCommand]);
+    // ── Format painter (mirrors `usePaintFormat`): capture a 2-D format pattern, then replay it over a
+    // target with `replace` (the engine tiles the pattern). `isPaintFormatActive` is derived below. ──
+    const captureFormats = useCallback((sheetId, range) => {
+        const grid = [];
+        for (let r = range.startRowIndex; r <= range.endRowIndex; r++) {
+            const row = [];
+            for (let c = range.startColumnIndex; c <= range.endColumnIndex; c++) {
+                row.push(getEffectiveFormat(sheetId, r, c));
+            }
+            grid.push(row);
+        }
+        return grid;
+    }, [getEffectiveFormat]);
+    const onSavePaintFormat = useCallback((sheetId, activeCell, selections) => {
+        const range = selections?.[0]?.range ?? {
+            startRowIndex: activeCell.rowIndex,
+            endRowIndex: activeCell.rowIndex,
+            startColumnIndex: activeCell.columnIndex,
+            endColumnIndex: activeCell.columnIndex,
+        };
+        setPaintFormats(captureFormats(sheetId, range));
+    }, [captureFormats]);
+    const onApplyPaintFormat = useCallback((sheetId, activeCell, selections) => {
+        if (!paintFormats.length)
+            return;
+        const rowSpan = paintFormats.length - 1;
+        const colSpan = (paintFormats[0]?.length ?? 1) - 1;
+        // The pattern tiles across the full dragged target (Excel painter semantics —
+        // the store's change-formatting applier repeats the grid modulo its size).
+        // Only header-click full-column/row targets are bounded — to the sheet's data
+        // extent, never below one full pattern — so we never enumerate ~1M cells.
+        const extent = engineRef.current
+            ?.sheetExtents?.()
+            .find(([id]) => id === sheetId);
+        const clampEnd = (start, end, span, dataEnd) => {
+            if (end - start >= UNBOUNDED_PAINT_SPAN)
+                return Math.min(end, Math.max(start + span, dataEnd));
+            return end;
+        };
+        const target = selections && selections.length
+            ? selections.map((sel) => ({
+                ...sel,
+                range: {
+                    ...sel.range,
+                    endRowIndex: clampEnd(sel.range.startRowIndex, sel.range.endRowIndex, rowSpan, extent?.[1] ?? 0),
+                    endColumnIndex: clampEnd(sel.range.startColumnIndex, sel.range.endColumnIndex, colSpan, extent?.[2] ?? 0),
+                },
+            }))
+            : [
+                {
+                    range: {
+                        startRowIndex: activeCell.rowIndex,
+                        endRowIndex: activeCell.rowIndex + rowSpan,
+                        startColumnIndex: activeCell.columnIndex,
+                        endColumnIndex: activeCell.columnIndex + colSpan,
+                    },
+                },
+            ];
+        onCommand({
+            command: "change-formatting",
+            sheetId,
+            activeCell,
+            selections: target,
+            cellFormat: paintFormats,
+            options: { replace: true },
+        });
+        setPaintFormats([]); // single-use, like the JS reference
+    }, [paintFormats, onCommand]);
+    // Selection interceptor (parity with `useSpreadsheetState`'s `onChangeSelectionsInterceptor`): a
+    // FINISHED grid selection while the painter is armed applies the captured pattern to the target
+    // instead of updating the view selection. An empty selection list (a plain cell click) makes
+    // `onApplyPaintFormat` derive the target from the active cell + the pattern's span.
+    const onChangeSelectionsInterceptor = useCallback((sheetId, sel, finishedSelection) => {
+        if (paintFormats.length && finishedSelection) {
+            onApplyPaintFormat(sheetId, viewRef.current.activeCell, sel);
+            return;
+        }
+        onChangeSelections(sheetId, sel);
+    }, [paintFormats, onApplyPaintFormat, onChangeSelections]);
+    const paintFormat = useCallback((sourceSheetRange, targetSheetRange) => {
+        onCommand({
+            command: "change-formatting",
+            sheetId: targetSheetRange.sheetId,
+            activeCell: {
+                rowIndex: targetSheetRange.startRowIndex,
+                columnIndex: targetSheetRange.startColumnIndex,
+            },
+            selections: [{ range: targetSheetRange }],
+            cellFormat: captureFormats(sourceSheetRange.sheetId, sourceSheetRange),
+            options: { replace: true },
+        });
+    }, [captureFormats, onCommand]);
+    // Following a hyperlink: external URLs open a new tab (the only browser-safe action here); an
+    // internal reference (`Sheet1!A1:B5`) NAVIGATES — switch to the target sheet, then move the cursor
+    // + selection to the parsed range (the reference's `navigateToSheetRange`; the grid's own
+    // active-cell tracking scrolls it into view).
+    const onSelectLink = useCallback((sheetId, _activeCell, hyperlink) => {
+        if (!hyperlink)
+            return;
+        const open = (url) => {
+            if (typeof window !== "undefined")
+                window.open(normalizeExternalUrl(url), "_blank", "noopener");
+        };
+        if (typeof hyperlink === "string")
+            return open(hyperlink);
+        if (hyperlink.kind === "external")
+            return open(hyperlink.url);
+        if (hyperlink.kind === "internal" && hyperlink.location) {
+            const { sheetName, range } = parseInternalLocation(hyperlink.location);
+            // A bare `A1` targets the cell's own sheet; an unknown sheet name is a dead link — no-op.
+            const target = sheetName ? getSheetId(sheetName) : sheetId;
+            if (target == null)
+                return;
+            if (target !== viewRef.current.activeSheetId)
+                onChangeActiveSheet(target);
+            if (range) {
+                onChangeActiveCell(target, {
+                    rowIndex: range.startRowIndex,
+                    columnIndex: range.startColumnIndex,
+                });
+                onChangeSelections(target, [{ range }]);
+            }
+        }
+    }, [getSheetId, onChangeActiveSheet, onChangeActiveCell, onChangeSelections]);
+    // Cycle the active sheet (Ctrl+PageUp/PageDown in the grid) — pure view, no engine command.
+    const onSelectNextSheet = useCallback((sheetId) => {
+        const i = sheets.findIndex((s) => s.sheetId === sheetId);
+        const next = sheets[(i + 1) % (sheets.length || 1)];
+        if (next)
+            onChangeActiveSheet(next.sheetId);
+    }, [sheets, onChangeActiveSheet]);
+    const onSelectPreviousSheet = useCallback((sheetId) => {
+        const i = sheets.findIndex((s) => s.sheetId === sheetId);
+        const prev = sheets[(i - 1 + sheets.length) % (sheets.length || 1)];
+        if (prev)
+            onChangeActiveSheet(prev.sheetId);
+    }, [sheets, onChangeActiveSheet]);
+    // ── Document facets (engine-owned; parsed once per facet change) ──
+    // Parse the raw facets string lazily; identity changes ONLY when the string did (see `facetsJson`).
+    const facets = useMemo(() => facetsJson === "{}"
+        ? EMPTY_FACETS
+        : JSON.parse(facetsJson), [facetsJson]);
+    // Whole-document facets pass straight through (stable while `facets` is stable).
+    const conditionalFormats = facets.conditionalFormats;
+    const tables = facets.tables;
+    const namedRanges = facets.namedRanges;
+    const protectedRanges = facets.protectedRanges;
+    const embeds = facets.embeds;
+    const slicers = facets.slicers;
+    // Citations (workbook-level collection; a cell links to one via `citationId`). The grid renders the
+    // overlay from this list — the engine owns it (unlike `useSpreadsheetState`, where it's an app prop).
+    const citations = facets.citations;
+    // Banded ranges + the basic filter are per-active-sheet (the grid draws only the active sheet's).
+    // Standalone banded ranges (alternating colors) ride the engine's "banded" facet; a TABLE's visual
+    // style is materialized on its facet entry as `bandedRange` (never as per-cell format), so derive
+    // those here exactly like `useSpreadsheetState` — this single array is what the grid paints and the
+    // copy path serializes table styling from.
+    const bandedRanges = useMemo(() => {
+        const tableBands = (tables ?? [])
+            .filter((t) => t.sheetId === activeSheetId && t.bandedRange != null)
+            .map((t) => ({
+            bandedRangeId: `${t.id}-${t.theme}`,
+            range: { ...t.range, sheetId: activeSheetId },
+            ...t.bandedRange,
+        }));
+        return [
+            ...facets.bandedRanges.filter((b) => b.range?.sheetId === activeSheetId),
+            ...tableBands,
+        ];
+    }, [facets, tables, activeSheetId]);
+    const basicFilter = useMemo(() => facets.basicFilters.find((f) => f.sheetId === activeSheetId)?.filter, [facets, activeSheetId]);
+    // Body rows the engine hid for the active sheet (basic filter OR a table-column filter), as compact
+    // [start,end] 1-based inclusive ranges. CanvasGrid derives `visibleRowRanges` from these — the
+    // channel that makes a table/basic filter actually hide rows (and scales to 1M without per-row meta).
+    const hostHiddenRowRanges = useMemo(() => (facets.hiddenRowRanges?.[String(activeSheetId)] ?? []), [facets, activeSheetId]);
+    // The cell's data-validation rule — resolved by RANGE MEMBERSHIP (the engine stores rules with their
+    // ranges, not an id/rule on the cell as `useSpreadsheetState` does), returning the canonical rule shape.
+    const getDataValidation = useCallback((sheetId, rowIndex, columnIndex) => {
+        const entry = facets.dataValidations.find((dv) => dv.ranges.some((r) => rangeContains(r, sheetId, rowIndex, columnIndex)));
+        // `displayStyle` must ride along: the grid's `showValidationDropdownArrow` hides the
+        // in-cell arrow for `"plain"` (imported OOXML `showDropDown="1"` — suppress-dropdown).
+        return entry?.condition
+            ? {
+                condition: entry.condition,
+                displayStyle: entry.displayStyle,
+                allowBlank: entry.allowBlank,
+            }
+            : undefined;
+    }, [facets]);
+    // ── Parity stubs that close over hook state (the rest are module-level) ──
+    // Empty registries — the engine owns styles + shared strings; JS keeps no cellXfs/SST table.
+    const cellXfsRegistry = useMemo(() => new CellXfsRegistry(), []);
+    const sharedStringRegistry = useMemo(() => new SharedStringRegistry(), []);
+    // ── Clipboard ──
+    // Copy/cut WRITE the clipboard (the rich `application/json` + html/csv/plain) straight from the
+    // engine's read accessors — a pure read, so it's identical to `useSpreadsheetState` and safe in
+    // Option B (no document mutation). Cut writes the same clipboard; the source delete happens at paste.
+    // Option B keeps styles in a SEPARATE `cellStyles` map, so `getCellData` returns value-only cells
+    // (no `uf`). `useOnCopy` serializes the rich `application/json` clipboard straight from this cell data
+    // and writes the effective format ONLY into the HTML representation — so the JSON cell carries no
+    // format and paste lands values-only (the bug: bold/number-format/etc. silently dropped on copy↔paste).
+    // Inject the cell's effective format as an inline `uf` here so it round-trips: `generateDataFromClipboard`
+    // passes a non-`StyleReference` `uf` through untouched, and `onPaste` forwards it as the paste command's
+    // per-cell `format`, which the engine applies via `set_style`.
+    const getCellDataForCopy = useCallback((sheetId, rowIndex, columnIndex) => {
+        const data = getCellData(sheetId, rowIndex, columnIndex);
+        const uf = getEffectiveFormat(sheetId, rowIndex, columnIndex);
+        if (!uf)
+            return data;
+        return { ...(data ?? {}), uf };
+    }, [getCellData, getEffectiveFormat]);
+    // `theme` makes `useOnCopy` emit inline styles into the text/html payload (fills, text colors,
+    // borders — including the table/banded styling resolved from `bandedRanges` above), so pasting
+    // into Excel/Word preserves what the grid renders.
+    const onCopy = useOnCopy({
+        theme: options.theme ?? defaultSpreadsheetTheme,
+        merges,
+        tables,
+        bandedRanges,
+        getEffectiveFormat,
+        getFormattedValue,
+        getColumnWidth: (sheetId, columnIndex) => getColumnWidth(sheetId, columnIndex) ?? 100,
+        getRowHeight: (sheetId, rowIndex) => getRowHeight(sheetId, rowIndex) ?? 20,
+        isColumnHidden: isHiddenColumn,
+        isHiddenRow,
+        getCellData: getCellDataForCopy,
+    });
+    // Paste resolves the BOUNDED clipboard UI-side (parse only) then hands the engine a `paste` command:
+    // the engine places the rectangle and relocates relative formula refs by (target − source), and on a
+    // cut clears the source. Formatting IS carried: `generateDataFromClipboard` resolves the clipboard's
+    // cellXfs style-refs to an inline `CellFormat` on each parsed cell, which we forward per cell below;
+    // the engine applies it via `set_style` (streams on `styleChanges`). Only a still-unresolved
+    // `StyleReference` (no matching cellXfs entry) is skipped, since a bare ref can't cross to the engine.
+    const onPaste = useCallback(async (e, sourceSheetId, destinationSheetId, copiedSelections, pasteActiveCell, pasteSelections, _finalSelections, isCutOperation) => {
+        const parsed = await generateDataFromClipboard(e, pasteActiveCell, destinationSheetId, getSheetName(destinationSheetId), true, initial.current.locale);
+        let results = parsed?.results ?? [];
+        if (!results.length)
+            return;
+        // Paste Special. The grid stashes the mode under a synthetic `pasteSpecialType` clipboard key
+        // (same as `useSpreadsheetState`). Transpose/Value/Formula transform the parsed cells UI-side
+        // (the engine can't "resolve a formula to its value"); Formatting rides a `format_only` flag the
+        // engine honors (apply each cell's format, leave destination values intact).
+        const pasteSpecialType = e?.clipboardData?.getData("pasteSpecialType");
+        if (pasteSpecialType === "Transposed") {
+            results = transpose(results);
+        }
+        else if (pasteSpecialType === "Value") {
+            results = pickValue(results, destinationSheetId, initial.current.locale);
+        }
+        else if (pasteSpecialType === "Formula") {
+            results = pickFormula(results, destinationSheetId, initial.current.locale);
+        }
+        const formatOnly = pasteSpecialType === "Formatting";
+        // Destination top-left = the paste selection's start (else the active cell).
+        const to = pasteSelections?.[pasteSelections.length - 1]?.range;
+        const target = to
+            ? { rowIndex: to.startRowIndex, columnIndex: to.startColumnIndex }
+            : pasteActiveCell;
+        // The copied range top-left, kept for the cut source-clear below.
+        const from = copiedSelections?.[0]?.range;
+        // `generateDataFromClipboard` has ALREADY re-anchored each relative formula ref to its destination
+        // (its `moveFormula(sourceCell → destinationCell)` pass overwrites the cell's `fv`), so the formula
+        // text in `cells` is destination-shifted on arrival. The engine's paste then shifts relative refs by
+        // (target − source); passing the real copy origin as `source` would apply that shift a SECOND time and
+        // DOUBLE the offset (`=A1` from B1 pasted to B2 → `=A3` instead of `=A2`). Pin `source` to `target` so
+        // the engine's shift is a zero-delta no-op and the already-correct formula is preserved.
+        const source = target;
+        const cells = results.map((row) => row.map((cell) => {
+            if (!cell)
+                return null;
+            const ue = getCellUserEnteredValue(cell);
+            const num = getExtendedValueNumber(ue);
+            const bool = getExtendedValueBool(ue);
+            // Formula text wins, else the literal as a string (`String(0)`/`"FALSE"` survive).
+            const value = getExtendedValueFormula(ue) ??
+                getExtendedValueString(ue) ??
+                (num != null
+                    ? String(num)
+                    : bool != null
+                        ? bool
+                            ? "TRUE"
+                            : "FALSE"
+                        : null);
+            // Carry the copied cell's format. A `StyleReference` can't cross to the engine (it owns
+            // styles inline), so skip refs — engine-copied cells already have an inline `CellFormat`.
+            const fmt = getCellUserEnteredFormat(cell);
+            const format = fmt && !isStyleReference(fmt) ? fmt : undefined;
+            // Carry the copied cell's hyperlink so a pasted link stays clickable (Excel/Sheets
+            // parity). The engine stores the target as a plain string; resolve `HyperlinkValue`
+            // to its external URL / internal location here.
+            const hl = cell.hyperlink;
+            const hyperlink = typeof hl === "string"
+                ? hl
+                : hl == null
+                    ? undefined
+                    : hl.kind === "external"
+                        ? hl.url
+                        : hl.location;
+            return { value, format, hyperlink };
+        }));
+        onCommand({
+            command: "paste",
+            sheetId: destinationSheetId,
+            target,
+            source,
+            cells,
+            cut: isCutOperation && from && sourceSheetId != null
+                ? { sheetId: sourceSheetId, range: from }
+                : null,
+            formatOnly,
+        });
+    }, [getSheetName, getCellData, onCommand]);
+    return useMemo(() => ({
+        ...state,
+        ...handlers,
+        ready,
+        engine: engineRef.current,
+        canUndo: hist.canUndo,
+        canRedo: hist.canRedo,
+        onCommand,
+        undo,
+        redo,
+        onUndo: undo,
+        onRedo: redo,
+        onMoveChart,
+        onResizeChart,
+        onCreateConditionalFormattingRule,
+        // Repeat last formatting (the action itself is recorded in `onCommand`).
+        onRepeatFormatting,
+        // Format painter + hyperlink follow + the citation overlay (engine-owned).
+        onSavePaintFormat,
+        onApplyPaintFormat,
+        paintFormat,
+        isPaintFormatActive: paintFormats.length > 0,
+        onSelectLink,
+        citations,
+        load,
+        importXlsx,
+        setEffectiveValue,
+        registerCustomFunction,
+        activeSheetId,
+        activeCell,
+        selections,
+        activeCellBySheetId,
+        selectionsBySheetId,
+        onChangeActiveSheet,
+        onChangeActiveCell,
+        onChangeSelections: onChangeSelectionsInterceptor,
+        rowCount,
+        columnCount,
+        frozenRowCount,
+        frozenColumnCount,
+        rowMetadata,
+        columnMetadata,
+        merges,
+        getCellData,
+        getFormattedValue,
+        getUserEnteredValue,
+        getEffectiveValue,
+        getEffectiveExtendedValue,
+        getEffectiveFormat,
+        getHyperlink,
+        getNote,
+        getRowHeight,
+        getColumnWidth,
+        isHiddenRow,
+        isHiddenColumn,
+        getSheetName,
+        getSheetId,
+        getSheetCount,
+        getSheetIndex,
+        getSheetRowCount,
+        getSheetColumnCount,
+        getDataRowCount,
+        findAll,
+        getSeriesValuesFromRange,
+        getDomainValuesFromRange,
+        getColumnarDataFromRange,
+        getTextFormatRuns,
+        getUserEnteredExtendedValue,
+        getUserEnteredFormat,
+        getErrorValue,
+        getMentionsFromCell,
+        getDataColumnCount,
+        getNonEmptyRowCount,
+        getNonEmptyColumnCount,
+        onSelectNextSheet,
+        onSelectPreviousSheet,
+        // Sheet-view toggles + zoom come from the ACTIVE sheet's imported `<sheetView>` (reconciled
+        // onto each Sheet), defaulting to Excel's on/100% when the file didn't specify.
+        showGridLines: state.sheets.find((s) => s.sheetId === activeSheetId)?.showGridLines ??
+            true,
+        showRowColHeaders: state.sheets.find((s) => s.sheetId === activeSheetId)
+            ?.showRowColHeaders ?? true,
+        zoomScale: state.sheets.find((s) => s.sheetId === activeSheetId)?.zoomScale ?? 1,
+        // Undefined when the file didn't specify — CanvasGrid falls back to its own default.
+        defaultRowHeight: state.sheets.find((s) => s.sheetId === activeSheetId)
+            ?.defaultRowHeight ?? undefined,
+        isDarkMode: false,
+        bandedRanges,
+        basicFilter,
+        hostHiddenRowRanges,
+        arrows,
+        conditionalFormats,
+        tables,
+        namedRanges,
+        protectedRanges,
+        embeds,
+        slicers,
+        getDataValidation,
+        // ── Drop-in parity stubs (inert in Option B — see EngineSpreadsheetParityStubs) ──
+        cellXfsRegistry,
+        sharedStringRegistry,
+        spreadsheetColors: EMPTY_COLORS,
+        isImportingExcelfile: false,
+        onChangeCellXfs,
+        addFormulaToGraph,
+        enqueueCalculation,
+        enqueueGraphOperation,
+        updateDependencyGraph,
+        clearEvaluatedCellsCache,
+        calculateNow,
+        onRequestCalculate,
+        // Engine-computed "Filter by color" swatches — pass to CanvasGrid's `getFilterColors`.
+        getFilterColors,
+        getDependencyGraph,
+        getDependents,
+        getPrecedents,
+        onTraceDependents,
+        onTracePrecedents,
+        onRemoveArrows,
+        onViewPortChange,
+        evaluateConditionalFormatting,
+        evaluateConditionalFormattingForViewport,
+        evaluateDataValidations,
+        evaluateDataValidationsForViewport,
+        reevaluateDerivationsForCells,
+        applyPatch,
+        generateStatePatches,
+        createHistory,
+        onClearHistory,
+        getFormattingFromRange,
+        getFormulasFromRange,
+        getUserEnteredValuesFromRange,
+        getSheetProperties,
+        importExcelFile,
+        importCSVFile,
+        importCSVFileLegacy,
+        onUpdateSheet,
+        onRequestAddRows,
+        onChangeBatchStream,
+        clearStreamPreview,
+        onDeleteDataValidationRules,
+        onCopy,
+        onPaste,
+    }), [
+        state,
+        handlers,
+        ready,
+        hist,
+        onCommand,
+        undo,
+        redo,
+        onMoveChart,
+        onResizeChart,
+        onCreateConditionalFormattingRule,
+        onRepeatFormatting,
+        onSavePaintFormat,
+        onApplyPaintFormat,
+        paintFormat,
+        paintFormats,
+        onSelectLink,
+        citations,
+        load,
+        importXlsx,
+        setEffectiveValue,
+        registerCustomFunction,
+        activeSheetId,
+        activeCell,
+        selections,
+        onChangeActiveSheet,
+        onChangeActiveCell,
+        onChangeSelectionsInterceptor,
+        onViewPortChange,
+        rowCount,
+        columnCount,
+        frozenRowCount,
+        frozenColumnCount,
+        rowMetadata,
+        columnMetadata,
+        merges,
+        getCellData,
+        getFormattedValue,
+        getUserEnteredValue,
+        getEffectiveValue,
+        getEffectiveExtendedValue,
+        getEffectiveFormat,
+        getHyperlink,
+        getNote,
+        getRowHeight,
+        getColumnWidth,
+        isHiddenRow,
+        isHiddenColumn,
+        getSheetName,
+        getSheetId,
+        getSheetCount,
+        getSheetIndex,
+        getSheetRowCount,
+        getSheetColumnCount,
+        getDataRowCount,
+        findAll,
+        getSeriesValuesFromRange,
+        getDomainValuesFromRange,
+        getColumnarDataFromRange,
+        getTextFormatRuns,
+        getUserEnteredExtendedValue,
+        getUserEnteredFormat,
+        getErrorValue,
+        getMentionsFromCell,
+        getDataColumnCount,
+        getNonEmptyRowCount,
+        getNonEmptyColumnCount,
+        onSelectNextSheet,
+        onSelectPreviousSheet,
+        bandedRanges,
+        basicFilter,
+        hostHiddenRowRanges,
+        arrows,
+        conditionalFormats,
+        tables,
+        namedRanges,
+        protectedRanges,
+        embeds,
+        slicers,
+        getDataValidation,
+        activeCellBySheetId,
+        selectionsBySheetId,
+        cellXfsRegistry,
+        sharedStringRegistry,
+        getUserEnteredValuesFromRange,
+        getFormulasFromRange,
+        getFormattingFromRange,
+        getPrecedents,
+        getDependents,
+        onTraceDependents,
+        onTracePrecedents,
+        onRemoveArrows,
+        onUpdateSheet,
+        onChangeBatchStream,
+        clearStreamPreview,
+        onRequestAddRows,
+        onDeleteDataValidationRules,
+        onClearHistory,
+        onCopy,
+        onPaste,
+    ]);
+}