@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/hooks/use-calculation.js

@@ -0,0 +1,2069 @@
+import { Calculator, cellCoordsToCellCoordinate, DataSource, } from "@rowsncolumns/calculator";
+import { isCellCoordinateWithinCellRange, StaticNode } from "@rowsncolumns/dag";
+import { CellRangeNode, isCellCoordinate, isCellNode, isCellRangeNode, isStaticNode, isStaticReference, makeKey, } from "@rowsncolumns/dag";
+import { CellNode } from "@rowsncolumns/dag";
+import { FormulaError } from "@rowsncolumns/fast-formula-parser";
+import { isAreasEqual } from "@rowsncolumns/grid";
+import { ERROR_COLOR, useCallbackRef } from "@rowsncolumns/spreadsheet";
+import { useIsomorphicLayoutEffect } from "@rowsncolumns/ui";
+import { alpha2number, debug, error, isAFormula, isBareFormulaExpression, isNil, scheduleAfterPaint, } from "@rowsncolumns/utils";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { getFunctionNamesFromFormula } from "../api/immer-utils";
+import { isEqualPosition } from "../api/range";
+import { AWAITING_CALCULATION, isCellRange } from "../helpers";
+import { computeDelta } from "../helpers/iterative-calculation";
+import { useCalculationProcessArray } from "./use-calculation-process-array";
+import { useDeferredCalculationFlush } from "./use-deferred-calculation-flush";
+import { useIdleScheduler } from "./use-idle-scheduler";
+const rangesOverlap = (left, right) => {
+    if (left.sheet !== right.sheet) {
+        return false;
+    }
+    return (left.from.row <= right.to.row &&
+        left.to.row >= right.from.row &&
+        left.from.col <= right.to.col &&
+        left.to.col >= right.from.col);
+};
+const isErrorResult = (value) => {
+    if (value instanceof FormulaError) {
+        return true;
+    }
+    return (!!value &&
+        typeof value === "object" &&
+        (value.type === "Error" ||
+            value.type === "Invalid"));
+};
+const isDerivedCellPosition = (position) => position.conditionalFormatId !== undefined ||
+    position.dataValidationId !== undefined;
+const findCircularKeys = (nodes) => {
+    if (!nodes.length) {
+        return new Set();
+    }
+    const nodeMap = new Map();
+    const nodesBySheet = new Map();
+    for (const node of nodes) {
+        nodeMap.set(node.key, node);
+        const bucket = nodesBySheet.get(node.position.sheetId);
+        if (bucket) {
+            bucket.push(node);
+        }
+        else {
+            nodesBySheet.set(node.position.sheetId, [node]);
+        }
+    }
+    const adjacency = new Map();
+    for (const node of nodes) {
+        const edges = new Set();
+        for (const input of node.inputKeys) {
+            if (isCellNode(input)) {
+                const cellInput = input;
+                if (nodeMap.has(cellInput.key)) {
+                    edges.add(cellInput.key);
+                }
+                continue;
+            }
+            if (isCellRangeNode(input)) {
+                const rangeInput = input;
+                const candidates = nodesBySheet.get(rangeInput.position.sheetId);
+                if (!candidates) {
+                    continue;
+                }
+                for (const candidate of candidates) {
+                    if (isCellNode(candidate) &&
+                        !isDerivedCellPosition(candidate.position) &&
+                        isCellCoordinateWithinCellRange(candidate.position, rangeInput)) {
+                        edges.add(candidate.key);
+                    }
+                }
+            }
+        }
+        adjacency.set(node.key, edges);
+    }
+    const indexMap = new Map();
+    const lowLink = new Map();
+    const stack = [];
+    const onStack = new Set();
+    let index = 0;
+    const components = [];
+    const strongConnect = (key) => {
+        indexMap.set(key, index);
+        lowLink.set(key, index);
+        index++;
+        stack.push(key);
+        onStack.add(key);
+        for (const neighbor of adjacency.get(key) ?? []) {
+            if (!indexMap.has(neighbor)) {
+                strongConnect(neighbor);
+                lowLink.set(key, Math.min(lowLink.get(key), lowLink.get(neighbor)));
+            }
+            else if (onStack.has(neighbor)) {
+                lowLink.set(key, Math.min(lowLink.get(key), indexMap.get(neighbor)));
+            }
+        }
+        if (lowLink.get(key) === indexMap.get(key)) {
+            const component = [];
+            let candidate;
+            do {
+                candidate = stack.pop();
+                onStack.delete(candidate);
+                component.push(candidate);
+            } while (candidate !== key);
+            components.push(component);
+        }
+    };
+    for (const key of nodeMap.keys()) {
+        if (!indexMap.has(key)) {
+            strongConnect(key);
+        }
+    }
+    const circular = new Set();
+    for (const component of components) {
+        if (!component.length)
+            continue;
+        if (component.length === 1 &&
+            !adjacency.get(component[0])?.has(component[0])) {
+            continue;
+        }
+        component.forEach((key) => circular.add(key));
+    }
+    return circular;
+};
+// List of ephemeral functions
+// Ephemeral functions are always recalculated when
+// a cell changes
+export const EPHEMERAL_FUNCTIONS = new Set([
+    "NOW",
+    "TODAY",
+    "RAND",
+    "RANDARRAY",
+    "RANDBETWEEN",
+    "SHEET",
+    "SHEETS",
+    "OFFSET",
+    "INDIRECT",
+]);
+const DEFAULT_BATCH_WEIGHT = 600;
+const ARRAY_FORMULA_WEIGHT = 300;
+const LARGE_RANGE_MIN_CELLS = 100;
+const MAX_CHUNK_DURATION_MS = 16;
+const getTimestamp = () => typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+const yieldToBrowser = () => new Promise((resolve) => {
+    scheduleAfterPaint(resolve);
+});
+const parseCellReference = (reference) => {
+    const match = /^\$?([A-Z]{1,3})\$?(\d+)$/i.exec(reference.trim());
+    if (!match) {
+        return null;
+    }
+    const column = alpha2number(match[1].toUpperCase());
+    if (column == null) {
+        return null;
+    }
+    const row = Number.parseInt(match[2], 10);
+    if (Number.isNaN(row)) {
+        return null;
+    }
+    return { column, row };
+};
+const toValidRange = (range) => {
+    const startRowIndex = Math.max(1, range.startRowIndex);
+    const endRowIndex = Math.max(startRowIndex, range.endRowIndex);
+    const startColumnIndex = Math.max(1, range.startColumnIndex);
+    const endColumnIndex = Math.max(startColumnIndex, range.endColumnIndex);
+    if (endRowIndex < startRowIndex || endColumnIndex < startColumnIndex) {
+        return null;
+    }
+    return {
+        sheetId: range.sheetId,
+        startRowIndex,
+        endRowIndex,
+        startColumnIndex,
+        endColumnIndex,
+    };
+};
+const getInvalidationRangeFromStructureChange = (change) => {
+    switch (change.kind) {
+        case "delete-row":
+        case "insert-row":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: change.index,
+                endRowIndex: change.rowCount,
+                startColumnIndex: 1,
+                endColumnIndex: change.columnCount,
+            });
+        case "delete-column":
+        case "insert-column":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: 1,
+                endRowIndex: change.rowCount,
+                startColumnIndex: change.index,
+                endColumnIndex: change.columnCount,
+            });
+        case "delete-cells-shift-up":
+        case "insert-cells-shift-down":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: change.startRowIndex,
+                endRowIndex: change.rowCount,
+                startColumnIndex: change.startColumnIndex,
+                endColumnIndex: change.endColumnIndex,
+            });
+        case "delete-cells-shift-left":
+        case "insert-cells-shift-right":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: change.startRowIndex,
+                endRowIndex: change.endRowIndex,
+                startColumnIndex: change.startColumnIndex,
+                endColumnIndex: change.columnCount,
+            });
+        case "delete-table-row":
+        case "insert-table-row":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: change.index,
+                endRowIndex: change.rowCount,
+                startColumnIndex: change.startColumnIndex,
+                endColumnIndex: change.endColumnIndex,
+            });
+        case "delete-table-column":
+        case "insert-table-column":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: change.startRowIndex,
+                endRowIndex: change.endRowIndex,
+                startColumnIndex: change.index,
+                endColumnIndex: change.columnCount,
+            });
+        case "invalidate-range":
+            return toValidRange({
+                sheetId: change.sheetId,
+                startRowIndex: change.startRowIndex,
+                endRowIndex: change.endRowIndex,
+                startColumnIndex: change.startColumnIndex,
+                endColumnIndex: change.endColumnIndex,
+            });
+        default:
+            return null;
+    }
+};
+const hasFullColumnReference = (formula) => {
+    const pattern = /(^|[^A-Z0-9_])(\$?[A-Z]{1,3})(?!\d)\s*:\s*(\$?[A-Z]{1,3})(?!\d)/gi;
+    return pattern.test(formula);
+};
+const hasFullRowReference = (formula) => {
+    const pattern = /(^|[^A-Z0-9_])(\$?\d+)\s*:\s*(\$?\d+)(?!\d)/gi;
+    return pattern.test(formula);
+};
+const hasLargeExplicitRange = (formula) => {
+    const pattern = /(\$?[A-Z]{1,3}\$?\d+)\s*:\s*(\$?[A-Z]{1,3}\$?\d+)/gi;
+    let match;
+    while ((match = pattern.exec(formula))) {
+        const start = parseCellReference(match[1]);
+        const end = parseCellReference(match[2]);
+        if (!start || !end) {
+            continue;
+        }
+        const rowCount = Math.abs(end.row - start.row) + 1;
+        const columnCount = Math.abs(end.column - start.column) + 1;
+        if (rowCount * columnCount >= LARGE_RANGE_MIN_CELLS) {
+            return true;
+        }
+    }
+    return false;
+};
+const isHeavyArrayFormula = (formula) => {
+    if (!formula)
+        return false;
+    return (hasFullColumnReference(formula) ||
+        hasFullRowReference(formula) ||
+        hasLargeExplicitRange(formula));
+};
+const cellPromises = new Map();
+export const useCalculation = ({ locale, functions, iterativeCalculation, onDemandFormulaPattern, activeSheetId, onSuccess, onChangeDependencyGraph, getSheetId, getSheetName, getSheetIndex, getSheetCount, getActiveSheetId, getEffectiveValue, getUserEnteredValue, getConditionalFormatFormula, getDataValidationFormula, getSheetProperties, getCellData, onStructuredReference, onNamedRange, namedRanges, onChangeStaticReference, onBeginCalculation, getEffectiveStructuredValue, isRowHidden, isRowHiddenByFilter, enableLazyCalculation = true, enabled = true, }) => {
+    // Convert string pattern to RegExp if provided
+    const onDemandPattern = useMemo(() => {
+        if (!onDemandFormulaPattern)
+            return undefined;
+        return new RegExp(onDemandFormulaPattern, "gi");
+    }, [onDemandFormulaPattern]);
+    const calculator = useRef(undefined);
+    const computationCache = useRef(undefined);
+    const iterativeCalculationRef = useRef(iterativeCalculation);
+    iterativeCalculationRef.current = iterativeCalculation;
+    const operationQueue = useRef([]);
+    const graphOperationQueue = useRef([]);
+    // Results queue
+    const resultsQueueRef = useRef(new Map());
+    const resultsFlushPendingRef = useRef(false);
+    const isFullRecalcRef = useRef(false);
+    const staticNodeArrayRef = useRef([]);
+    const initialCalculationArrayRef = useRef([]);
+    const getSheetNameStable = useCallbackRef(getSheetName);
+    const getSheetIdStable = useCallbackRef(getSheetId);
+    const getSheetIndexStable = useCallbackRef(getSheetIndex);
+    const getSheetCountStable = useCallbackRef(getSheetCount);
+    const getCellDataStable = useCallbackRef(getCellData);
+    const onStructuredReferenceStable = useCallbackRef(onStructuredReference);
+    const getUserEnteredValueStable = useCallbackRef(getUserEnteredValue);
+    const isRowHiddenStable = useCallbackRef(isRowHidden);
+    const isRowHiddenByFilterStable = useCallbackRef(isRowHiddenByFilter);
+    const initialArrayResults = useRef(new Map());
+    const ephemeralCellsRef = useRef(new Map());
+    const forceRecalcKeys = useRef(new Set());
+    // Keys actually consumed (evaluated with fresh state) during the current
+    // calculation cycle. Only these are cleared in `onAfterCalculation`; keys
+    // added concurrently (e.g. by a paste RAF while a calc was mid-flight, with
+    // stale closures) survive into the next cycle so they aren't dropped.
+    const consumedForceRecalcKeys = useRef(new Set());
+    // Position for each force key, so unconsumed keys can be re-dirtied + rescheduled.
+    const forceRecalcPositions = useRef(new Map());
+    // Guards the reschedule loop against an unconsumable key spinning forever.
+    const rescheduleCount = useRef(0);
+    const rafTimerMapRef = useRef(new Map());
+    const deferredOperationsBySheetRef = useRef(new Map());
+    const pendingStartResultsRef = useRef(new Map());
+    const pendingRecalculatedPositionRef = useRef(undefined);
+    const startCalculationRef = useRef(null);
+    const { schedule: scheduleStartCalculationIdle } = useIdleScheduler();
+    // Add to ephemeral function if required
+    const addToEphemeralFunction = useCallback((formulaValue, position) => {
+        const fns = getFunctionNamesFromFormula(formulaValue);
+        if (fns.some((fn) => EPHEMERAL_FUNCTIONS.has(fn.toUpperCase()))) {
+            ephemeralCellsRef.current.set(makeKey(position), position);
+        }
+    }, []);
+    // Remove from ephemeral function if required
+    const removeFromEphemeralFunction = useCallback((position) => {
+        ephemeralCellsRef.current.delete(makeKey(position));
+    }, []);
+    // Get all ephemeral functions
+    const getEphemeralCells = useCallback(() => {
+        const ephemeralCellsToRecalc = [
+            ...ephemeralCellsRef.current.values(),
+        ].map((position) => {
+            return {
+                type: "add",
+                position,
+            };
+        });
+        debug("Recalculation ephemeral cells", ephemeralCellsToRecalc);
+        return ephemeralCellsToRecalc;
+    }, []);
+    // Get computation cache
+    // Used for the current calculation frame
+    const getComputationCache = useCallback(() => {
+        if (computationCache.current === undefined) {
+            computationCache.current = new Map();
+        }
+        return computationCache.current;
+    }, []);
+    // Clear cache
+    const onAfterCalculation = useCallback(() => {
+        // Remove cached values
+        getComputationCache().clear();
+        // Cleanup the graph, so we dont have
+        // any stale nodes
+        getCalculator().cleanupGraph();
+        // Only clear keys that were actually consumed during this calculation cycle.
+        // Keys added concurrently (e.g. by a paste RAF while this calculation was
+        // running) must survive so the next cycle can evaluate them.
+        consumedForceRecalcKeys.current.forEach((key) => {
+            forceRecalcKeys.current.delete(key);
+            forceRecalcPositions.current.delete(key);
+        });
+        consumedForceRecalcKeys.current.clear();
+    }, []);
+    const getFunctions = useCallback(() => {
+        return functions;
+    }, [functions]);
+    const overridesRef = useRef(null);
+    // Get user entered value
+    const getFinalUserEnteredValue = (position) => {
+        const { conditionalFormatId, dataValidationId } = position;
+        if (!isNil(conditionalFormatId)) {
+            return getConditionalFormatFormula(position.sheetId, position.rowIndex, position.columnIndex, conditionalFormatId);
+        }
+        if (!isNil(dataValidationId)) {
+            return getDataValidationFormula(position.sheetId, position.rowIndex, position.columnIndex, dataValidationId);
+        }
+        // Read through the stable ref so a calc-captured closure (e.g. a paste RAF
+        // that ran with a pre-paste render's `getUserEnteredValue`) still resolves
+        // the latest user-entered value rather than a stale snapshot.
+        return getUserEnteredValueStable(position.sheetId, position.rowIndex, position.columnIndex);
+    };
+    const deferCalculationNodes = (positions) => {
+        if (!positions.length) {
+            return;
+        }
+        for (const position of positions) {
+            const key = makeKey(position);
+            const sheetId = position.sheetId;
+            const existing = deferredOperationsBySheetRef.current.get(sheetId) ??
+                new Map();
+            existing.set(key, {
+                type: "dirty",
+                position,
+                force: forceRecalcKeys.current.has(key),
+            });
+            deferredOperationsBySheetRef.current.set(sheetId, existing);
+            getCalculator().unMarkAsDirty(position);
+        }
+    };
+    const filterDirtyCellsForActiveSheet = (cells, rootSheetId) => {
+        if (!cells.length) {
+            return { included: cells, deferred: [] };
+        }
+        const cellNodeByKey = new Map();
+        const dirtyNodesBySheet = new Map();
+        for (const node of cells) {
+            cellNodeByKey.set(node.key, node);
+            const list = dirtyNodesBySheet.get(node.position.sheetId);
+            if (list) {
+                list.push(node);
+            }
+            else {
+                dirtyNodesBySheet.set(node.position.sheetId, [node]);
+            }
+        }
+        // Find cells that are inputs to static references (charts, etc.)
+        // These cells should not be deferred even if they're on other sheets
+        const staticInputKeys = new Set();
+        const staticInputs = getCalculator().getStaticReferenceInputs();
+        for (const inputNode of staticInputs) {
+            if (isCellNode(inputNode)) {
+                staticInputKeys.add(inputNode.key);
+            }
+            else if (isCellRangeNode(inputNode)) {
+                // For range inputs, check which dirty cells fall within the range
+                const rangeInput = inputNode;
+                for (const cell of cells) {
+                    if (!isDerivedCellPosition(cell.position) &&
+                        isCellCoordinateWithinCellRange(cell.position, rangeInput)) {
+                        staticInputKeys.add(cell.key);
+                    }
+                }
+            }
+        }
+        const includedKeys = new Set();
+        const forcedKeys = forceRecalcKeys.current;
+        const stack = [];
+        for (const node of cells) {
+            if (forcedKeys.has(node.key) ||
+                node.position.sheetId === rootSheetId ||
+                staticInputKeys.has(node.key)) {
+                includedKeys.add(node.key);
+                stack.push(node);
+            }
+        }
+        while (stack.length) {
+            const current = stack.pop();
+            if (!current) {
+                continue;
+            }
+            const userEnteredValue = getFinalUserEnteredValue(current.position);
+            if (!isAFormula(userEnteredValue) || !userEnteredValue) {
+                continue;
+            }
+            const formulaValue = String(userEnteredValue).slice(1);
+            const dependencies = getCalculator().dependencies(formulaValue, current.position);
+            for (const dependency of dependencies) {
+                // Named-range refs (StaticReference) come back as deps too
+                // now that the DAG is unified, but this code path is
+                // chasing grid-level cell/range dependencies for the
+                // active-sheet filter. Skip them.
+                if (isStaticReference(dependency))
+                    continue;
+                if (isCellCoordinate(dependency)) {
+                    const depKey = makeKey(dependency);
+                    const depNode = cellNodeByKey.get(depKey);
+                    if (depNode && !includedKeys.has(depKey)) {
+                        includedKeys.add(depKey);
+                        stack.push(depNode);
+                    }
+                    continue;
+                }
+                const candidates = dirtyNodesBySheet.get(dependency.sheetId);
+                if (!candidates) {
+                    continue;
+                }
+                for (const candidate of candidates) {
+                    if (includedKeys.has(candidate.key)) {
+                        continue;
+                    }
+                    if (isCellRangeNode(dependency) &&
+                        !isDerivedCellPosition(candidate.position) &&
+                        isCellCoordinateWithinCellRange(candidate.position, dependency)) {
+                        includedKeys.add(candidate.key);
+                        stack.push(candidate);
+                    }
+                }
+            }
+        }
+        const included = [];
+        const deferred = [];
+        for (const node of cells) {
+            if (includedKeys.has(node.key)) {
+                included.push(node);
+            }
+            else {
+                deferred.push(node);
+            }
+        }
+        return { included, deferred };
+    };
+    const scheduleStartCalculation = useCallback((results, recalculatedPosition) => {
+        if (results && results.size) {
+            for (const entry of results) {
+                pendingStartResultsRef.current.set(entry[0], entry[1]);
+            }
+        }
+        if (recalculatedPosition) {
+            pendingRecalculatedPositionRef.current = recalculatedPosition;
+        }
+        scheduleStartCalculationIdle(() => {
+            const pendingResults = pendingStartResultsRef.current;
+            pendingStartResultsRef.current = new Map();
+            const position = pendingRecalculatedPositionRef.current;
+            pendingRecalculatedPositionRef.current = undefined;
+            startCalculationRef.current?.(pendingResults, position);
+        });
+    }, [scheduleStartCalculationIdle]);
+    // Calculator instance
+    const getCalculator = () => {
+        if (!calculator.current) {
+            const overrideValuesRef = overridesRef;
+            calculator.current = new Calculator({
+                locale,
+                getSheetId: getSheetIdStable,
+                getSheetIndex: getSheetIndexStable,
+                getSheetCount: getSheetCountStable,
+                getSheetProperties: (sheetId = getActiveSheetId()) => getSheetProperties(sheetId),
+                getSheetName: getSheetNameStable,
+                isRowHidden: isRowHidden ? isRowHiddenStable : undefined,
+                isRowHiddenByFilter: isRowHiddenByFilter
+                    ? isRowHiddenByFilterStable
+                    : undefined,
+                getCellValue(sheetId, rowIndex, columnIndex, property) {
+                    const key = makeKey({
+                        sheetId,
+                        rowIndex,
+                        columnIndex,
+                    });
+                    if (overrideValuesRef.current?.has(key)) {
+                        const result = overrideValuesRef.current.get(key);
+                        if (property) {
+                            return getEffectiveStructuredValue?.(result, property);
+                        }
+                        return result;
+                    }
+                    const cachedValue = getComputationCache().has(key)
+                        ? getComputationCache().get(key)
+                        : null;
+                    if (cachedValue !== null) {
+                        // Cached structured value
+                        if (cachedValue &&
+                            typeof cachedValue === "object" &&
+                            cachedValue.kind &&
+                            getEffectiveStructuredValue) {
+                            return getEffectiveStructuredValue?.(cachedValue, property);
+                        }
+                        return cachedValue;
+                    }
+                    return getEffectiveValue(sheetId, rowIndex, columnIndex, property);
+                },
+                functions: getFunctions(),
+                onStructuredReference: onStructuredReferenceStable,
+                onVariable: onNamedRange,
+                onRecalculation: onRecalculation,
+                markAsQueued,
+                markAsLoading,
+                markAsError,
+                getCellData: (coords) => {
+                    if (isCellRange(coords)) {
+                        const arr = [];
+                        const sheetId = coords.sheet
+                            ? getSheetIdStable(coords.sheet)
+                            : getActiveSheetId();
+                        for (let rowIndex = coords.from.row; rowIndex <= coords.to.row; rowIndex++) {
+                            for (let columnIndex = coords.from.col; columnIndex <= coords.to.col; columnIndex++) {
+                                arr.push(getCellDataStable(sheetId, rowIndex, columnIndex));
+                            }
+                        }
+                        return arr;
+                    }
+                    else {
+                        const position = cellCoordsToCellCoordinate(coords, coords.sheet
+                            ? getSheetIdStable(coords.sheet)
+                            : getActiveSheetId());
+                        return getCellDataStable(position.sheetId, position.rowIndex, position.columnIndex);
+                    }
+                },
+            });
+        }
+        return calculator.current;
+    };
+    // Cleanup
+    useIsomorphicLayoutEffect(() => {
+        return () => {
+            calculator.current?.cleanup();
+        };
+    }, []);
+    // Phase 9 — virtual-cell named ranges. Sync the host's named-range
+    // list with the calculator's registered set. Each formula-typed
+    // named range becomes a DAG node; range-typed ones go straight
+    // through `onNamedRange` and are skipped here.
+    //
+    // Excel-correctness requires named ranges to be registered BEFORE
+    // any cell formula is parsed — otherwise the dep parser sees the
+    // name as `#NAME?` and no DAG edge to the static node is created.
+    // We do this via a callable `applyNamedRanges` that's invoked
+    // synchronously by the init hook at the top of its calculate
+    // pass (before walking sheetData), AND from a useEffect so
+    // ongoing changes (Name Manager edits) propagate too. Both paths
+    // are idempotent: the diff against `registeredNamedRangeFormulasRef`
+    // means re-calling with the same list is a no-op.
+    // Track both formula AND scope so we re-register when scope flips
+    // (workbook ↔ sheet) even if the formula text is unchanged. Scope
+    // is the numeric sheetId — names can be renamed, ids are stable.
+    const registeredNamedRangeFormulasRef = useRef(new Map());
+    // Diff the provided list against what's already registered and
+    // apply only the delta. Pure function over its arg — no implicit
+    // ref reads — so the init hook can call it with the same
+    // namedRanges prop it has, and tests can call it directly with
+    // any list.
+    const applyNamedRanges = useCallbackRef((list) => {
+        if (!enabled)
+            return;
+        const calc = getCalculator();
+        // Map key combines lowercase name + scope so workbook-scoped
+        // and sheet-scoped names with the same display name don't
+        // collide (Excel treats them as separate defined names).
+        const scopeKey = (name, sheetId) => `${sheetId == null ? "wb" : String(sheetId)}:${name.toLowerCase()}`;
+        const next = new Map();
+        for (const nr of list ?? []) {
+            const value = nr?.value;
+            if (typeof value !== "string")
+                continue;
+            // Accept both shapes: "=OFFSET(...)" (spreadsheet convention)
+            // and bare "OFFSET(...)" (OOXML definedName convention).
+            // Static literals and plain references are not registered —
+            // they resolve through the host's onNamedRange fallback.
+            const trimmedValue = value.trim();
+            let formula;
+            if (trimmedValue.startsWith("=")) {
+                formula = trimmedValue.slice(1).trim();
+            }
+            else if (isBareFormulaExpression(trimmedValue)) {
+                formula = trimmedValue;
+            }
+            else {
+                continue;
+            }
+            if (!formula)
+                continue;
+            // Sheet-scoped if NamedRange.range.sheetId is present; else
+            // workbook-scoped. sheetId is stable across sheet renames.
+            const sheetId = nr.range?.sheetId ?? undefined;
+            next.set(scopeKey(nr.name, sheetId), {
+                name: nr.name,
+                formula,
+                sheetId,
+            });
+        }
+        const prev = registeredNamedRangeFormulasRef.current;
+        // Removals: in prev, not in next.
+        for (const [key, prevEntry] of prev) {
+            if (!next.has(key)) {
+                // The map key is `<scope>:<name>`; recover the name by
+                // slicing past the first colon and pass the tracked
+                // sheetId so we hit the right scoped registration.
+                calc.unregisterNamedRange(key.slice(key.indexOf(":") + 1), prevEntry.sheetId);
+            }
+        }
+        // Collect adds + updates. Compare formula AND scope so a
+        // scope-only change still re-registers (scope changes also
+        // flip the map key, so they hit removal+add — defensive
+        // equality check kept for robustness).
+        const toApply = [];
+        const nextPrev = new Map();
+        for (const [key, { name, formula, sheetId }] of next) {
+            const prevEntry = prev.get(key);
+            nextPrev.set(key, { formula, sheetId });
+            if (prevEntry?.formula === formula && prevEntry.sheetId === sheetId) {
+                continue;
+            }
+            toApply.push({ name, formula, sheetId });
+        }
+        // Order-independent batch: cross-name edges
+        // (`fullPrice = price * 1.08`) get wired correctly regardless
+        // of the order the names appear in the host's array.
+        if (toApply.length)
+            calc.registerNamedRanges(toApply);
+        registeredNamedRangeFormulasRef.current = nextPrev;
+    });
+    // Re-apply whenever the host's namedRanges list changes.
+    useEffect(() => {
+        applyNamedRanges(namedRanges);
+    }, [namedRanges, enabled, applyNamedRanges]);
+    // Hook for processing arrays
+    const [processArrayResults, createArraySideEffectsAndGetResults, getErrorResultsFromArrayPosition,] = useCalculationProcessArray({
+        locale,
+        getCalculator,
+        getSheetId: getSheetIdStable,
+        getComputationCache,
+        getUserEnteredValue,
+        getCellData: getCellDataStable,
+    });
+    /**
+     * Mark a cell
+     */
+    const markCell = useCallback((coords, value, formatting) => {
+        const results = new Map();
+        const position = cellCoordsToCellCoordinate(coords, coords.sheet ? getSheetIdStable(coords.sheet) : getActiveSheetId());
+        const key = makeKey(position);
+        if (rafTimerMapRef.current.has(key)) {
+            const rafTimerId = rafTimerMapRef.current.get(key);
+            if (!isNil(rafTimerId)) {
+                cancelAnimationFrame(rafTimerId);
+                rafTimerMapRef.current.delete(key);
+            }
+        }
+        results.set(key, [position, value, formatting]);
+        publishResults(results.values());
+    }, []);
+    /**
+     * Mark a position as queue
+     */
+    const markAsQueued = useCallback((coords) => {
+        markCell(coords, "Queued", {
+            horizontalAlignment: "center",
+        });
+    }, [markCell]);
+    /**
+     * Mark a position as loading
+     */
+    const markAsLoading = useCallback((coords) => {
+        markCell(coords, "Loading...", {
+            horizontalAlignment: "center",
+        });
+    }, [markCell]);
+    /**
+     * Mark a position as error
+     */
+    const markAsError = useCallback((coords, value) => {
+        markCell(coords, value, {
+            horizontalAlignment: "center",
+            textFormat: {
+                color: ERROR_COLOR,
+            },
+        });
+    }, [markCell]);
+    // On Recalculation: For dynamically updating calculated values
+    const onRecalculation = (coords, calculationResults) => {
+        const results = new Map();
+        const position = cellCoordsToCellCoordinate(coords, coords.sheet ? getSheetIdStable(coords.sheet) : getActiveSheetId());
+        const key = makeKey(position);
+        /**
+         * Multitenant returns null for
+         * unsubscribe callback
+         */
+        if (calculationResults === null) {
+            return;
+        }
+        // Set this cell as dirty
+        getCalculator().markAsDirty(position);
+        if (Array.isArray(calculationResults)) {
+            const [collides, recomputeOperations] = processArrayResults(calculationResults, position, results, getDependents);
+            if (collides) {
+                getCalculator().cleanupPipelineFunction(position);
+            }
+            // New compuete
+            enqueueCalculations(recomputeOperations);
+        }
+        else {
+            // Add it to computation cache
+            getComputationCache().set(key, calculationResults);
+            // Push result to array
+            results.set(key, [position, calculationResults]);
+        }
+        scheduleStartCalculation(results, position);
+    };
+    // Begin calculation
+    const startCalculation = async (initialResults = new Map(), recalculatedPosition) => {
+        // `startCalculation` is invoked fire-and-forget (the RAF idle scheduler
+        // discards its promise, and `useDeferredCalculationFlush` types
+        // `onFlushComplete` as `() => void`), so a rejection here surfaces as a
+        // window `unhandledrejection` — seen in production as raw
+        // FormulaError("#NAME?", "Unknown range name") exceptions reaching users.
+        // Every per-cell path already converts FormulaError into a cell error
+        // value; this guard is the backstop for anything thrown outside those
+        // catches, so a recalc failure degrades to an aborted pass (dirty cells
+        // stay dirty for the next trigger) instead of an uncaught exception. The
+        // tail below still runs so calculation state is always released.
+        try {
+            // Publish initial results
+            if (initialResults.size) {
+                publishResults(initialResults.values());
+            }
+            // Per-batch processing of a run of dirty cells (lazy-calc
+            // filtering, circular detection, parallel evaluation). Extracted
+            // so the interleaved topo loop can call it per cell segment.
+            const runCellBatch = async (input) => {
+                let cellNodes = input;
+                const rootSheetId = enableLazyCalculation
+                    ? getActiveSheetId()
+                    : undefined;
+                if (typeof rootSheetId === "number") {
+                    const { included, deferred } = filterDirtyCellsForActiveSheet(cellNodes, rootSheetId);
+                    if (deferred.length) {
+                        deferCalculationNodes(deferred.map((cell) => cell.position));
+                    }
+                    cellNodes = included;
+                }
+                if (!cellNodes.length)
+                    return;
+                if (!iterativeCalculationRef.current?.enabled) {
+                    const circularKeys = findCircularKeys(cellNodes);
+                    if (circularKeys.size) {
+                        const results = new Map();
+                        for (const node of cellNodes) {
+                            if (!circularKeys.has(node.key)) {
+                                continue;
+                            }
+                            const error = new FormulaError("#REF!", "Circular dependency detected.");
+                            getComputationCache().set(node.key, error);
+                            results.set(node.key, [node.position, error]);
+                        }
+                        publishResults(results.values());
+                        cellNodes = cellNodes.filter((node) => !circularKeys.has(node.key));
+                    }
+                }
+                await processCells(cellNodes, recalculatedPosition);
+            };
+            let dirtyCells = [];
+            while ((dirtyCells = getCalculator().getDirtyCells()) &&
+                dirtyCells.length !== 0) {
+                // Walk the dirty list in topological order, interleaving:
+                //   - CellNode  → batched and run by `runCellBatch` (parallel
+                //                 within the batch).
+                //   - StaticNode that's a named-range virtual cell → evaluate
+                //                 inline; this populates the value cache so
+                //                 downstream cells in this same batch read
+                //                 the fresh value via `onVariable`.
+                //   - StaticNode other (array spill etc) → `publishStaticCells`.
+                //
+                // Named-range nodes can appear anywhere in the topo order —
+                // they may depend on dirty cells that need to recompute first,
+                // and other cells may depend on them. We flush the pending
+                // cell batch before each static, so writes land in host state
+                // (via onSuccess) before the next static reads them. This is
+                // the Excel unified-sort semantics.
+                const calc = getCalculator();
+                const pendingCells = [];
+                const flushPending = async () => {
+                    if (!pendingCells.length)
+                        return;
+                    const batch = pendingCells.slice();
+                    pendingCells.length = 0;
+                    await runCellBatch(batch);
+                };
+                for (const node of dirtyCells) {
+                    // Duck-type instead of `instanceof` to survive bundler
+                    // class-duplication: when @rowsncolumns/dag is inlined into separate
+                    // chunks (the published rnc-engine path), its classes get distinct
+                    // constructor identities and `instanceof` fails even for shape-identical
+                    // nodes. StaticNode has no `position` (created via `new StaticNode(id)`);
+                    // CellNode's `position` is a cell coordinate.
+                    if (!node.position) {
+                        await flushPending();
+                        if (calc.isNamedRangeNodeKey(node.key)) {
+                            await calc.evaluateNamedRangeNodeKey(node.key);
+                        }
+                        else {
+                            publishStaticCells(node);
+                        }
+                    }
+                    else if (isCellCoordinate(node.position)) {
+                        // `isCellCoordinate` narrows `node.position`, not `node`; the cast
+                        // reflects the shape the guard just confirmed (a cell-coordinate node).
+                        pendingCells.push(node);
+                    }
+                }
+                await flushPending();
+            }
+        }
+        catch (err) {
+            console.error("[spreadsheet-state] recalculation pass aborted:", err);
+        }
+        // Clear current calculation array results
+        initialArrayResults.current = new Map();
+        onAfterCalculation();
+        // If there are unconsumed forceRecalcKeys (added concurrently by a paste
+        // RAF while this calculation was running with stale closures), re-dirty
+        // those cells so the next calculation cycle (with fresh state) can evaluate
+        // them. Cap reschedules to prevent an infinite loop if a key can never be
+        // consumed.
+        if (forceRecalcKeys.current.size > 0) {
+            const MAX_RESCHEDULE = 50;
+            rescheduleCount.current = (rescheduleCount.current || 0) + 1;
+            if (rescheduleCount.current <= MAX_RESCHEDULE) {
+                forceRecalcPositions.current.forEach((pos) => {
+                    getCalculator().markAsDirty(pos);
+                });
+                scheduleStartCalculation();
+            }
+            else {
+                // Give up — clear to avoid infinite spin.
+                forceRecalcKeys.current.clear();
+                forceRecalcPositions.current.clear();
+                rescheduleCount.current = 0;
+            }
+        }
+        else {
+            rescheduleCount.current = 0;
+        }
+        // Trigger onChange
+        onChangeDependencyGraph?.(getCalculator().graph.toJSON());
+    };
+    startCalculationRef.current = startCalculation;
+    // Process async
+    async function processCells(cells, recalculatedPosition) {
+        if (!iterativeCalculationRef.current?.enabled) {
+            return processCellsInParallel(cells, recalculatedPosition);
+        }
+        const cellMap = new Map();
+        for (const cell of cells) {
+            cellMap.set(makeKey(cell.position), cell);
+        }
+        const adjacency = new Map();
+        const getDependencies = (cell) => {
+            const deps = getCalculator().getPrecedents(cell.position);
+            const depKeys = new Set();
+            for (const dep of deps) {
+                if (isCellNode(dep)) {
+                    const depKey = makeKey(dep.position);
+                    if (cellMap.has(depKey)) {
+                        depKeys.add(depKey);
+                    }
+                    continue;
+                }
+                if (isCellRangeNode(dep)) {
+                    const rangeDep = dep;
+                    for (const candidate of cells) {
+                        if (!isDerivedCellPosition(candidate.position) &&
+                            isCellCoordinateWithinCellRange(candidate.position, rangeDep)) {
+                            depKeys.add(makeKey(candidate.position));
+                        }
+                    }
+                }
+            }
+            return depKeys;
+        };
+        const hasSelfReference = (cell) => {
+            const userEnteredValue = getFinalUserEnteredValue(cell.position);
+            if (!isAFormula(userEnteredValue) || !userEnteredValue) {
+                return false;
+            }
+            const formulaValue = String(userEnteredValue).slice(1);
+            try {
+                const deps = getCalculator().dependencies(formulaValue, cell.position);
+                return deps.some((dep) => {
+                    // Named-range static refs can't self-reference a cell.
+                    if (isStaticReference(dep))
+                        return false;
+                    if (isCellCoordinate(dep)) {
+                        return isEqualPosition(dep, cell.position);
+                    }
+                    return (dep.sheetId === cell.position.sheetId &&
+                        cell.position.rowIndex >= dep.startRowIndex &&
+                        cell.position.rowIndex <= dep.endRowIndex &&
+                        cell.position.columnIndex >= dep.startColumnIndex &&
+                        cell.position.columnIndex <= dep.endColumnIndex);
+                });
+            }
+            catch {
+                return false;
+            }
+        };
+        const indices = new Map();
+        const lowlinks = new Map();
+        const stack = [];
+        const onStack = new Set();
+        const iterativeGroups = [];
+        let index = 0;
+        const strongConnect = (key) => {
+            indices.set(key, index);
+            lowlinks.set(key, index);
+            index++;
+            stack.push(key);
+            onStack.add(key);
+            const deps = adjacency.get(key) ?? new Set();
+            for (const depKey of deps) {
+                if (!indices.has(depKey)) {
+                    strongConnect(depKey);
+                    lowlinks.set(key, Math.min(lowlinks.get(key), lowlinks.get(depKey)));
+                }
+                else if (onStack.has(depKey)) {
+                    lowlinks.set(key, Math.min(lowlinks.get(key), indices.get(depKey)));
+                }
+            }
+            if (lowlinks.get(key) === indices.get(key)) {
+                const componentKeys = [];
+                let current;
+                do {
+                    current = stack.pop();
+                    if (!current) {
+                        break;
+                    }
+                    onStack.delete(current);
+                    componentKeys.push(current);
+                } while (current !== key);
+                if (componentKeys.length > 1) {
+                    iterativeGroups.push(componentKeys
+                        .map((componentKey) => cellMap.get(componentKey))
+                        .filter((cell) => !!cell));
+                    return;
+                }
+                const singleKey = componentKeys[0];
+                const cell = singleKey ? cellMap.get(singleKey) : undefined;
+                if (cell && hasSelfReference(cell)) {
+                    iterativeGroups.push([cell]);
+                }
+            }
+        };
+        for (const cell of cells) {
+            const key = makeKey(cell.position);
+            if (!adjacency.has(key)) {
+                adjacency.set(key, getDependencies(cell));
+            }
+        }
+        for (const cell of cells) {
+            const key = makeKey(cell.position);
+            if (!indices.has(key)) {
+                strongConnect(key);
+            }
+        }
+        if (!iterativeGroups.length) {
+            return processCellsInParallel(cells, recalculatedPosition);
+        }
+        const iterativeKeys = new Set();
+        for (const group of iterativeGroups) {
+            for (const cell of group) {
+                iterativeKeys.add(makeKey(cell.position));
+            }
+        }
+        const nonIterativeCells = cells.filter((cell) => !iterativeKeys.has(makeKey(cell.position)));
+        if (nonIterativeCells.length) {
+            await processCellsInParallel(nonIterativeCells, recalculatedPosition);
+        }
+        const maxIterations = Math.max(1, iterativeCalculationRef.current?.maxIterations ?? 100);
+        const maxChange = Math.max(0, iterativeCalculationRef.current?.maxChange ?? 0.001);
+        for (const group of iterativeGroups) {
+            for (const cell of group) {
+                const effectiveValue = getEffectiveValue?.(cell.position.sheetId, cell.position.rowIndex, cell.position.columnIndex);
+                if (isErrorResult(effectiveValue)) {
+                    getComputationCache().set(makeKey(cell.position), 0);
+                }
+            }
+            let previousValues = null;
+            let converged = false;
+            for (let iteration = 0; iteration < maxIterations; iteration++) {
+                const currentValues = new Map();
+                for (const cell of group) {
+                    if (recalculatedPosition &&
+                        isEqualPosition(cell.position, recalculatedPosition)) {
+                        continue;
+                    }
+                    const userEnteredValue = getFinalUserEnteredValue(cell.position);
+                    if (!isAFormula(userEnteredValue) || !userEnteredValue) {
+                        continue;
+                    }
+                    try {
+                        let result = await getCalculator().calculate(String(userEnteredValue).slice(1), cell.position);
+                        if (result instanceof DataSource) {
+                            result = await result.get();
+                        }
+                        const key = makeKey(cell.position);
+                        currentValues.set(key, result);
+                        if (!Array.isArray(result)) {
+                            getComputationCache().set(key, result);
+                        }
+                    }
+                    catch (err) {
+                        const error = err instanceof FormulaError
+                            ? err
+                            : new FormulaError(err?.name ?? "#ERROR!", err?.message ?? String(err), err?.stack);
+                        currentValues.set(makeKey(cell.position), error);
+                        getComputationCache().set(makeKey(cell.position), error);
+                    }
+                }
+                if (previousValues) {
+                    let maxDelta = 0;
+                    for (const [key, value] of currentValues) {
+                        const delta = computeDelta(previousValues.get(key), value);
+                        if (delta > maxDelta) {
+                            maxDelta = delta;
+                        }
+                    }
+                    previousValues = currentValues;
+                    if (maxDelta <= maxChange) {
+                        converged = true;
+                        break;
+                    }
+                }
+                else {
+                    previousValues = currentValues;
+                }
+            }
+            const finalValues = previousValues ?? new Map();
+            const results = new Map();
+            for (const cell of group) {
+                const key = makeKey(cell.position);
+                let value = finalValues.get(key);
+                if (!converged) {
+                    value = new FormulaError("#NUM!", "Iterative calculation did not converge");
+                }
+                if (value instanceof FormulaError) {
+                    const [arrayErrors, recomputeOperations] = getErrorResultsFromArrayPosition(cell.position);
+                    getComputationCache().set(key, value);
+                    enqueueCalculations(recomputeOperations);
+                    results.set(key, [cell.position, value]);
+                    for (const [errorKey, errorValue] of arrayErrors) {
+                        results.set(errorKey, errorValue);
+                    }
+                    continue;
+                }
+                if (Array.isArray(value)) {
+                    const [collides, recomputeOperations] = processArrayResults(value, cell.position, results, getDependents);
+                    if (collides) {
+                        getCalculator().cleanupPipelineFunction(cell.position);
+                    }
+                    enqueueCalculations(recomputeOperations);
+                }
+                else {
+                    getComputationCache().set(key, value);
+                    results.set(key, [cell.position, value]);
+                }
+            }
+            publishResults(results.values());
+        }
+        const followUpCells = new Map();
+        for (const group of iterativeGroups) {
+            for (const cell of group) {
+                const dependents = getDependents(cell.position);
+                for (const dependent of dependents) {
+                    if (isCellNode(dependent)) {
+                        const cellDep = dependent;
+                        const depKey = makeKey(cellDep.position);
+                        if (!iterativeKeys.has(depKey)) {
+                            followUpCells.set(depKey, cellDep);
+                        }
+                    }
+                }
+            }
+        }
+        if (followUpCells.size) {
+            await processCellsInParallel(Array.from(followUpCells.values()), recalculatedPosition);
+        }
+    }
+    async function processCellsInParallel(cells, recalculatedPosition) {
+        const processingCells = new Set();
+        async function processCellWithDependencies(cell) {
+            const cellKey = makeKey(cell.position);
+            // If the cell is already being processed, wait for it to complete
+            while (processingCells.has(cellKey)) {
+                await new Promise((resolve) => setTimeout(resolve, 0));
+            }
+            if (cellPromises.has(cellKey)) {
+                return cellPromises.get(cellKey).promise;
+            }
+            processingCells.add(cellKey);
+            try {
+                // Create a new AbortController for this cell
+                const controller = new AbortController();
+                const dependencies = getPrecedents(cell.position);
+                // Use `isCellNode` / `isCellRangeNode` instead of `instanceof`.
+                // When `@rowsncolumns/dag` is loaded through more than one
+                // module-resolution path in a consumer bundle (CJS/ESM
+                // dual-package hazard hits webpack/Next builds even with a
+                // single installed copy), each path produces its own
+                // constructor identity and `instanceof` returns `false` for
+                // shape-identical nodes. The `___type`-tag check in these
+                // helpers is identity-independent and survives across module
+                // instances.
+                const cellDependencies = dependencies.filter((dep) => isCellNode(dep) && cells.includes(dep));
+                const rangeDependencies = dependencies.filter((dep) => isCellRangeNode(dep));
+                for (const dep of rangeDependencies) {
+                    for (const cell of cells) {
+                        if (!isDerivedCellPosition(cell.position) &&
+                            isCellCoordinateWithinCellRange(cell.position, dep)) {
+                            cellDependencies.push(cell);
+                        }
+                    }
+                }
+                const dependencyPromises = cellDependencies.map((dep) => processCellWithDependencies(dep));
+                const cellPromise = (async () => {
+                    await Promise.allSettled(dependencyPromises);
+                    // Set signal
+                    cell.position.signal = controller.signal;
+                    // Process cell
+                    await processCell(cell, recalculatedPosition);
+                    // Remove signal after processing this cell
+                    delete cell.position.signal;
+                })();
+                cellPromises.set(cellKey, { promise: cellPromise, controller });
+                return cellPromise;
+            }
+            finally {
+                processingCells.delete(cellKey);
+            }
+        }
+        // Remove old promises
+        cells.forEach((cell) => {
+            const key = makeKey(cell.position);
+            if (key) {
+                cellPromises.get(key)?.controller.abort();
+                cellPromises.delete(key);
+            }
+        });
+        const getCellWeight = (cell) => {
+            const value = getFinalUserEnteredValue(cell.position);
+            if (typeof value === "string" && value.startsWith("=")) {
+                const formula = value.slice(1);
+                if (isHeavyArrayFormula(formula)) {
+                    return ARRAY_FORMULA_WEIGHT;
+                }
+            }
+            return 1;
+        };
+        const chunkCells = () => {
+            if (!cells.length) {
+                return [];
+            }
+            const chunks = [];
+            let current = [];
+            let weight = 0;
+            const flush = () => {
+                if (!current.length) {
+                    return;
+                }
+                chunks.push(current);
+                current = [];
+                weight = 0;
+            };
+            for (const cell of cells) {
+                const nextWeight = getCellWeight(cell);
+                if (current.length && weight + nextWeight > DEFAULT_BATCH_WEIGHT) {
+                    flush();
+                }
+                current.push(cell);
+                weight += nextWeight;
+                if (weight >= DEFAULT_BATCH_WEIGHT) {
+                    flush();
+                }
+            }
+            flush();
+            return chunks.length ? chunks : [cells];
+        };
+        const chunks = chunkCells();
+        for (let index = 0; index < chunks.length; index++) {
+            const chunk = chunks[index];
+            if (!chunk.length) {
+                continue;
+            }
+            const start = getTimestamp();
+            await Promise.allSettled(chunk.map(processCellWithDependencies));
+            const elapsed = getTimestamp() - start;
+            if (elapsed >= MAX_CHUNK_DURATION_MS && index < chunks.length - 1) {
+                await yieldToBrowser();
+            }
+        }
+        cellPromises.clear();
+    }
+    // Process a single dirty cell
+    const processCell = async (dirtyCell, recalculatedPosition) => {
+        const results = new Map();
+        const { position, key } = dirtyCell;
+        const userEnteredValue = getFinalUserEnteredValue(position);
+        const isFormula = isAFormula(userEnteredValue);
+        if (recalculatedPosition &&
+            isEqualPosition(position, recalculatedPosition)) {
+            debug("Prevent recalculation of pipeline function", key);
+            return;
+        }
+        // Check for force
+        if (onDemandPattern) {
+            onDemandPattern.lastIndex = 0;
+        }
+        if (isFormula &&
+            userEnteredValue &&
+            onDemandPattern?.test(userEnteredValue)) {
+            if (!forceRecalcKeys.current.has(key)) {
+                // Prevent calculation
+                const onDemandMap = new Map();
+                onDemandMap.set(key, [position, AWAITING_CALCULATION]);
+                onSuccess(onDemandMap.values());
+                return;
+            }
+            // Mark this on-demand key as consumed inside the gate's PASSED branch.
+            // A stale closure that reads userEnteredValue as undefined (pre-paste
+            // state) has isFormula === false, so it never enters this gate and thus
+            // never consumes the key. The key survives until the next calculation
+            // cycle runs with fresh React state, where getFinalUserEnteredValue
+            // returns the actual formula.
+            consumedForceRecalcKeys.current.add(key);
+        }
+        // For non-on-demand cells in forceRecalcKeys, only consume when we can
+        // confirm the cell actually holds a formula (guards against stale closures
+        // where userEnteredValue is undefined).
+        if (forceRecalcKeys.current.has(key) && isFormula && userEnteredValue) {
+            consumedForceRecalcKeys.current.add(key);
+        }
+        // Log
+        debug("Processing", position, key, userEnteredValue);
+        if (isFormula && userEnteredValue) {
+            let rafTimer;
+            try {
+                // Validate this formuala. Duck-type instead of `instanceof CellNode`
+                // to survive bundler class-duplication (see the dirtyCells loop).
+                const isCellNode = !!dirtyCell.position && isCellCoordinate(dirtyCell.position);
+                rafTimer = isCellNode
+                    ? requestAnimationFrame(() => publishBeginCalculation?.(dirtyCell))
+                    : undefined;
+                if (!isNil(rafTimer)) {
+                    rafTimerMapRef.current.set(key, rafTimer);
+                }
+                let result = await getCalculator().calculate(userEnteredValue.slice(1), position);
+                // Cancel
+                if (rafTimer) {
+                    cancelAnimationFrame(rafTimer);
+                    rafTimerMapRef.current.delete(key);
+                }
+                // Datasource
+                if (result instanceof DataSource) {
+                    result = await result.get();
+                }
+                // Array results
+                if (Array.isArray(result)) {
+                    // Get all array cells (excludes parent cell) for recomputing in the same RAF
+                    const [collides, recomputeOperations] = processArrayResults(result, position, results, getDependents);
+                    // If it does collide
+                    if (collides) {
+                        getCalculator().cleanupPipelineFunction(position);
+                    }
+                    // New compuete
+                    enqueueCalculations(recomputeOperations);
+                }
+                else {
+                    // Add it to computation cache
+                    getComputationCache().set(key, result);
+                    // Invalidate any cached ranges containing this cell
+                    getCalculator().invalidateCacheForCell(position.sheetId, position.rowIndex, position.columnIndex);
+                    // Push result to array
+                    results.set(key, [position, result]);
+                }
+            }
+            catch (err) {
+                if (rafTimer) {
+                    cancelAnimationFrame(rafTimer);
+                }
+                // Calculation error
+                if (err instanceof FormulaError || err instanceof Error) {
+                    // Cast error messages
+                    const error = err instanceof FormulaError
+                        ? err
+                        : new FormulaError(err.name, err.message, err.stack);
+                    // We have to check if this error is caused in a cell
+                    // containing array formula
+                    // If so we have to reset all values references by this
+                    // array
+                    debug("Computation Error", error, position, key, userEnteredValue);
+                    const [arrayErrors, recomputeOperations] = getErrorResultsFromArrayPosition(position);
+                    // Add it to computation cache
+                    getComputationCache().set(key, error);
+                    // Invalidate any cached ranges containing this cell
+                    getCalculator().invalidateCacheForCell(position.sheetId, position.rowIndex, position.columnIndex);
+                    // New compuete
+                    enqueueCalculations(recomputeOperations);
+                    // Add to results
+                    results.set(key, [position, error]);
+                    for (const [key, value] of arrayErrors) {
+                        results.set(key, value);
+                    }
+                }
+            }
+            publishResults(results.values());
+        }
+        else {
+            // Cleanup functions
+            // Scenario -
+            // 1. Delete a pipeline function
+            // 2. Undo
+            // 3. And then Redo - Cleanup should be called when formula is deleted
+            getCalculator().cleanupPipelineFunction(position);
+        }
+    };
+    /**
+     * Publish static cells back
+     */
+    const publishStaticCells = useCallback((node) => {
+        if (staticNodeArrayRef.current.push(node) === 1) {
+            requestAnimationFrame(() => {
+                try {
+                    onChangeStaticReference?.(staticNodeArrayRef.current);
+                }
+                catch (err) {
+                    console.error("[spreadsheet-state] recalculation pass aborted:", err);
+                }
+                finally {
+                    staticNodeArrayRef.current.length = 0;
+                }
+            });
+        }
+    }, [onChangeStaticReference]);
+    /**
+     * Publish loading cells
+     */
+    const publishBeginCalculation = useCallback((node) => {
+        if (initialCalculationArrayRef.current.push(node.position) === 1) {
+            requestAnimationFrame(() => {
+                try {
+                    onBeginCalculation?.(initialCalculationArrayRef.current);
+                }
+                catch (err) {
+                    console.error("[spreadsheet-state] recalculation pass aborted:", err);
+                }
+                finally {
+                    initialCalculationArrayRef.current.length = 0;
+                }
+            });
+        }
+    }, [onBeginCalculation]);
+    /**
+     * Publish results back to the
+     */
+    const publishResults = useCallback((item) => {
+        for (const entry of item) {
+            const [key] = entry;
+            resultsQueueRef.current.set(makeKey(key), entry);
+        }
+        if (resultsQueueRef.current.size === 0) {
+            return;
+        }
+        if (resultsFlushPendingRef.current) {
+            return;
+        }
+        resultsFlushPendingRef.current = true;
+        const isFullRecalc = isFullRecalcRef.current;
+        // The flush RAF is fire-and-forget: a throw from the host's `onSuccess`
+        // used to escape to `window.onerror` as a raw uncaught exception.
+        // Contain it, and clear the queue in `finally` so a throwing host
+        // callback can't replay the same results on every subsequent flush.
+        requestAnimationFrame(() => {
+            resultsFlushPendingRef.current = false;
+            if (!resultsQueueRef.current.size) {
+                return;
+            }
+            try {
+                onSuccess?.(resultsQueueRef.current.values(), isFullRecalc, {});
+            }
+            catch (err) {
+                console.error("[spreadsheet-state] recalculation pass aborted:", err);
+            }
+            finally {
+                resultsQueueRef.current.clear();
+                isFullRecalcRef.current = false;
+            }
+        });
+    }, [onSuccess]);
+    // Immediately enqueue a calculation
+    const enqueueCalculations = (operations) => {
+        operations.forEach(processSingleOperation);
+    };
+    // Seed the calculator's array range map with a persisted spill range.
+    // No-op when no spillRange is supplied or the sheet name can't be resolved.
+    const seedArraySpillRange = (position, spillRange) => {
+        if (!spillRange) {
+            return;
+        }
+        const calculator = getCalculator();
+        const sheetName = calculator.getSheetName(position.sheetId);
+        if (!sheetName) {
+            return;
+        }
+        calculator.setArrayRangeReference(position, {
+            sheet: sheetName,
+            from: {
+                row: spillRange.startRowIndex,
+                col: spillRange.startColumnIndex,
+            },
+            to: {
+                row: spillRange.endRowIndex,
+                col: spillRange.endColumnIndex,
+            },
+        });
+    };
+    // Process a single
+    const processSingleOperation = (operation) => {
+        const { position, type, force, spillRange } = operation;
+        const userEnteredValue = getFinalUserEnteredValue(position);
+        const isFormula = isAFormula(userEnteredValue);
+        const formulaValue = isFormula
+            ? String(userEnteredValue)?.slice(1)
+            : undefined;
+        if (force) {
+            const forceKey = makeKey(position);
+            forceRecalcKeys.current.add(forceKey);
+            forceRecalcPositions.current.set(forceKey, position);
+        }
+        try {
+            // Add/remove to DAG
+            if (isFormula && formulaValue) {
+                // Does both add and update formula. Updates DAG references
+                getCalculator().addFormula(formulaValue, position);
+                // Seed array spill range from persisted ref so dependents pointing
+                // into the spill region resolve on first load without re-eval.
+                seedArraySpillRange(position, spillRange);
+                // Add to ephemeral
+                addToEphemeralFunction(formulaValue, position);
+            }
+            else if (type === "add") {
+                // If user replaces a formula with static text
+                // Remove old references
+                getCalculator().removePrecedents(position);
+                // Mark this cell as dirty
+                getCalculator().markAsDirty(position);
+                // Cleanup ephemeral
+                removeFromEphemeralFunction(position);
+            }
+            else if (type === "dirty") {
+                getCalculator().markAsDirty(position);
+            }
+            else if (type === "remove") {
+                // Remove cell and mark its dependents dirty (not the cell itself)
+                getCalculator().removeCellAndMarkDependentsDirty(position);
+                // Remove ephemeral cells
+                removeFromEphemeralFunction(position);
+            }
+        }
+        catch (err) {
+            if (isFormula) {
+                // Delete formula references
+                getCalculator().removeFormula(position);
+            }
+            // Remove all cell dependencies
+            getCalculator().deleteCell(position);
+            // Remove it from being executed again
+            getCalculator().unMarkAsDirty(position);
+            // For circular dependencies
+            const errorMap = new Map([
+                [makeKey(position), [position, new FormulaError("#REF!", String(err))]],
+            ]);
+            publishResults(errorMap.values());
+        }
+    };
+    // Update dependency graph
+    // without making cells dirty
+    const processUpdateDependencyGraphOperation = useCallback((operation) => {
+        const { position, type, previousPosition, spillRange } = operation;
+        const userEnteredValue = getFinalUserEnteredValue(position);
+        const isFormula = isAFormula(userEnteredValue);
+        const formulaValue = isFormula
+            ? String(userEnteredValue)?.slice(1)
+            : undefined;
+        // We need to move array formulas
+        if (previousPosition) {
+            const shouldRemoveArrayReference = false;
+            const arraySideEffects = createArraySideEffectsAndGetResults({
+                position: previousPosition,
+                shouldRemoveArrayReference,
+                getDependents,
+            });
+            if (arraySideEffects.size) {
+                // Immediately publish array side effects
+                publishResults(arraySideEffects.values());
+            }
+            if (getCalculator().isArray(previousPosition)) {
+                getCalculator().shiftArrayFormula(previousPosition, position);
+            }
+        }
+        try {
+            // Add/remove to DAG
+            if (isFormula && formulaValue) {
+                // Does both add and update formula. Updates DAG references
+                getCalculator().addFormulaToGraph(formulaValue, position);
+                // Seed array spill range so dependents in the spill region resolve
+                // through the DAG even though we skipped evaluation.
+                seedArraySpillRange(position, spillRange);
+            }
+            else if (type === "remove") {
+                getCalculator().removeCellFromGraph(position);
+            }
+            else if (type === "add") {
+                // If user replaces a formula with static text
+                // Remove old references
+                getCalculator().removePrecendentsFromGraph(position);
+            }
+        }
+        catch (err) {
+            error("Error when updateDependencyGraphFromOperation", err);
+        }
+    }, [getFinalUserEnteredValue]);
+    /**
+     * Goes through the queue of update operations and processes them.
+     *
+     * Optimization: Instead of using shift() which is O(n) per call (making the
+     * entire loop O(n²)), we swap the queue with an empty array and iterate
+     * with a for loop. This makes the entire operation O(n).
+     *
+     * If new operations are enqueued during processing, they go into the new
+     * empty array and will be processed in the next animation frame.
+     */
+    const processUpdateDependencyGraphQueue = useCallback(() => {
+        // Swap queue with empty array - O(1) operation
+        const operations = graphOperationQueue.current;
+        if (operations.length === 0)
+            return;
+        graphOperationQueue.current = [];
+        // Process all operations - O(n) total
+        for (let i = 0; i < operations.length; i++) {
+            const operation = operations[i];
+            if (operation) {
+                processUpdateDependencyGraphOperation(operation);
+            }
+        }
+    }, [processUpdateDependencyGraphOperation]);
+    // Add to calculation queue
+    // Stable reference prevents re-render of grid
+    const enqueueGraphOperation = useCallbackRef(useCallback((operation) => {
+        if (graphOperationQueue.current.push(operation) === 1) {
+            requestAnimationFrame(() => {
+                try {
+                    // Process operation queuu
+                    processUpdateDependencyGraphQueue();
+                }
+                catch (err) {
+                    console.error("[spreadsheet-state] recalculation pass aborted:", err);
+                }
+            });
+        }
+    }, [processUpdateDependencyGraphQueue]));
+    useDeferredCalculationFlush({
+        activeSheetId: enableLazyCalculation && !isNil(activeSheetId)
+            ? activeSheetId
+            : undefined,
+        deferredOperationsBySheetRef,
+        enqueueOperation: processSingleOperation,
+        onChunkComplete: yieldToBrowser,
+        onFlushComplete: startCalculation,
+    });
+    // Get all precendets of a cell
+    const getPrecedents = useCallback((source, includeSource) => {
+        return getCalculator()
+            .getPrecedents(source)
+            .filter(
+        // Ignore source
+        (node) => {
+            if (isStaticNode(node)) {
+                return true;
+            }
+            // After isStaticNode early-return, node is CellNode or
+            // CellRangeNode — both have a defined position. The cast
+            // bridges a TS narrowing limitation across the union.
+            const pos = node.position;
+            if (!includeSource &&
+                isCellCoordinate(pos) &&
+                isCellCoordinate(source)) {
+                return !isEqualPosition(pos, source);
+            }
+            if (includeSource &&
+                !isCellCoordinate(pos) &&
+                !isCellCoordinate(source)) {
+                return !isAreasEqual(pos, source);
+            }
+            return true;
+        });
+    }, []);
+    // Get precedents from formula string
+    // Does not check with DAG
+    const getPrecedentsFromFormulaString = useCallback((value, source) => {
+        const dependencies = getCalculator().dependencies(value, source);
+        const nodes = [];
+        for (const pos of dependencies) {
+            if (isStaticReference(pos)) {
+                // Named-range static reference. Build a StaticNode shape
+                // — caller treats it as a non-cell precedent.
+                nodes.push(new StaticNode(makeKey(pos)));
+            }
+            else if (isCellCoordinate(pos)) {
+                nodes.push(new CellNode(makeKey(pos), pos));
+            }
+            else {
+                nodes.push(new CellRangeNode(makeKey(pos), pos));
+            }
+        }
+        return nodes;
+    }, []);
+    // Is array formula
+    const isArrayFormula = useCallbackRef(useCallback((position) => {
+        return (getCalculator().isArray(position) ||
+            getCalculator().isInArrayRange(position));
+    }, []));
+    // Get all dependents of a cell. Returns a mixed list — narrow with
+    // the `isCellNode`/`isStaticNode` helpers at call sites (NOT
+    // `instanceof`, which breaks across bundler module instances).
+    const getDependents = useCallback((source, includeSource) => {
+        return getCalculator()
+            .getDependents(source)
+            .filter(
+        // Ignore source
+        (node) => {
+            if (isStaticNode(node)) {
+                return true;
+            }
+            // Array formulas
+            if (isArrayFormula(node.position)) {
+                return true;
+            }
+            // For cell range
+            if (!includeSource && isCellRangeNode(node)) {
+                return !isAreasEqual(node.position, source);
+            }
+            if (!includeSource &&
+                isCellCoordinate(source) &&
+                isCellNode(node)) {
+                return (node.position.rowIndex !== source.rowIndex ||
+                    node.position.columnIndex !== source.columnIndex);
+            }
+            return true;
+        });
+    }, [isArrayFormula]);
+    /**
+     * Process the calculation operation queue.
+     *
+     * Optimization: Instead of using shift() which is O(n) per call (making the
+     * entire loop O(n²)), we swap the queue with an empty array and iterate
+     * with a for loop. This makes the entire operation O(n).
+     *
+     * If new operations are enqueued during processing (via processSingleOperation),
+     * they go into the new empty array and will trigger a new requestAnimationFrame
+     * via the enqueue logic.
+     */
+    const processOperationQueue = useCallback(() => {
+        // Swap queue with empty array - O(1) operation
+        const operations = operationQueue.current;
+        if (operations.length === 0)
+            return;
+        operationQueue.current = [];
+        // Process all operations - O(n) total
+        for (let i = 0; i < operations.length; i++) {
+            const operation = operations[i];
+            if (operation) {
+                const clearedArrayRange = operation.type !== "dirty" && isArrayFormula(operation.position)
+                    ? getCalculator().getArrayRange(operation.position)
+                    : undefined;
+                if (operation.type === "remove") {
+                    // Only publish undefined result for formulas or array formulas
+                    // Static cells don't need calculation results
+                    const userEnteredValue = getFinalUserEnteredValue(operation.position);
+                    if (isAFormula(userEnteredValue) ||
+                        isArrayFormula(operation.position)) {
+                        initialArrayResults.current.set(makeKey(operation.position), [
+                            operation.position,
+                            undefined,
+                        ]);
+                    }
+                }
+                if (operation.type !== "dirty" && isArrayFormula(operation.position)) {
+                    const parentCandidates = new Map();
+                    for (const [key, value] of createArraySideEffectsAndGetResults({
+                        position: operation.position,
+                        getDependents,
+                    })) {
+                        initialArrayResults.current.set(key, value);
+                        const [cellPosition] = value;
+                        const parent = getCalculator().getClosestArrayParentCell(cellPosition);
+                        if (parent &&
+                            !isEqualPosition(parent, cellPosition) &&
+                            !isEqualPosition(parent, operation.position)) {
+                            parentCandidates.set(makeKey(parent), parent);
+                        }
+                    }
+                    for (const parent of parentCandidates.values()) {
+                        getCalculator().markAsDirty(parent);
+                    }
+                    if (clearedArrayRange) {
+                        for (const [key, range] of getCalculator().arrayRangeMap) {
+                            if (!rangesOverlap(range, clearedArrayRange)) {
+                                continue;
+                            }
+                            const anchor = getCalculator().arrayReferenceMap.get(key);
+                            if (anchor && !isEqualPosition(anchor, operation.position)) {
+                                getCalculator().markAsDirty(anchor);
+                            }
+                        }
+                    }
+                }
+                const arrayParent = getCalculator().getClosestArrayParentCell(operation.position);
+                if (arrayParent && !isEqualPosition(arrayParent, operation.position)) {
+                    for (const [key, value] of createArraySideEffectsAndGetResults({
+                        position: arrayParent,
+                        shouldRemoveArrayReference: false,
+                        getDependents,
+                    })) {
+                        initialArrayResults.current.set(key, value);
+                    }
+                }
+                // Backend driven
+                // When a backend sets a effective value of a formula
+                // Only update the dependent cells.
+                // This can be removed if the agent can do cell dependency computation
+                // And update the changed cells in the back-end
+                if (operation.source === "backend") {
+                    const graph = getCalculator().graph;
+                    const hasRanges = graph.ranges.size > 0;
+                    let shouldResolveDependents = hasRanges;
+                    if (!hasRanges) {
+                        if (graph.hasNode(operation.position)) {
+                            const node = graph.getNode(operation.position);
+                            shouldResolveDependents = node.dependentKeys.size > 0;
+                        }
+                        else {
+                            shouldResolveDependents = false;
+                        }
+                    }
+                    if (!shouldResolveDependents) {
+                        continue;
+                    }
+                    const dependents = getDependents(operation.position);
+                    dependents.forEach((dependent) => {
+                        if (isCellNode(dependent)) {
+                            // CellNode.position is always defined — assertion to
+                            // bridge a TS narrowing limitation across the union.
+                            processSingleOperation({
+                                type: "dirty",
+                                position: dependent.position,
+                            });
+                        }
+                    });
+                }
+                else {
+                    // Process operation
+                    processSingleOperation(operation);
+                }
+            }
+        }
+    }, [
+        createArraySideEffectsAndGetResults,
+        getDependents,
+        processSingleOperation,
+    ]);
+    // Add to calculation queue
+    // Stable reference prevents re-render of grid
+    const enqueueCalculation = useCallbackRef(useCallback((operation) => {
+        if (operationQueue.current.push(operation) === 1) {
+            // The RAF callback runs the queue processing + initial publish
+            // synchronously, so a throw here escapes straight to
+            // `window.onerror` (the `$exception` twin of the fire-and-forget
+            // rejection guarded in `startCalculation`). Contain it the same
+            // way: abort this pass, leave the queue for the next trigger.
+            requestAnimationFrame(() => {
+                try {
+                    const hasValueAffectingNonEphemeralOp = operationQueue.current.some((queued) => !ephemeralCellsRef.current.has(makeKey(queued.position)));
+                    if (hasValueAffectingNonEphemeralOp) {
+                        // Add ephemeral functions
+                        operationQueue.current.push(...getEphemeralCells());
+                    }
+                    // Process operation queuu
+                    processOperationQueue();
+                    const initialResults = initialArrayResults.current;
+                    const shouldPublishInitialResults = initialResults.size > 0;
+                    if (shouldPublishInitialResults) {
+                        initialArrayResults.current = new Map();
+                        publishResults(initialResults.values());
+                        requestAnimationFrame(() => {
+                            scheduleStartCalculation();
+                        });
+                        return;
+                    }
+                    // Start calculation
+                    scheduleStartCalculation(initialResults);
+                }
+                catch (err) {
+                    console.error("[spreadsheet-state] recalculation pass aborted:", err);
+                }
+            });
+        }
+    }, [processOperationQueue, processSingleOperation, scheduleStartCalculation]));
+    // Delete all sheet references
+    const deleteSheetReferences = useCallback((sheetId) => {
+        return getCalculator().deleteSheet(sheetId);
+    }, []);
+    const enqueueStructureChange = useCallbackRef(useCallback((change) => {
+        const range = getInvalidationRangeFromStructureChange(change);
+        if (!range) {
+            return;
+        }
+        getCalculator().invalidateCacheForRange(range.sheetId, range.startRowIndex, range.startColumnIndex, range.endRowIndex, range.endColumnIndex);
+    }, []));
+    const clearRangeCache = useCallbackRef(useCallback(() => {
+        getCalculator().clearRangeCache();
+    }, []));
+    // Used for formula preview
+    const onRequestCalculate = useCallback(async (value, sheetId, rowIndex, columnIndex, options) => {
+        const isArray = options?.isArray ?? false;
+        const disablePreview = options?.disablePreview ?? false;
+        const skipOnDemand = options?.skipOnDemand ?? true;
+        if (skipOnDemand && onDemandPattern) {
+            onDemandPattern.lastIndex = 0;
+        }
+        if (skipOnDemand && isAFormula(value) && onDemandPattern?.test(value)) {
+            return undefined;
+        }
+        const previousOverrides = overridesRef.current;
+        overridesRef.current = options?.overrides ?? null;
+        const position = { sheetId, rowIndex, columnIndex };
+        try {
+            if (iterativeCalculationRef.current?.enabled &&
+                isAFormula(value) &&
+                !disablePreview) {
+                const precedents = getPrecedentsFromFormulaString(value.slice(1), position);
+                const isCircular = precedents.some((node) => {
+                    const range = node.position;
+                    // Named-range static nodes have no grid position — they
+                    // can't be a circular self-reference.
+                    if (!range)
+                        return false;
+                    if ("rowIndex" in range) {
+                        return (range.sheetId === sheetId &&
+                            range.rowIndex === rowIndex &&
+                            range.columnIndex === columnIndex);
+                    }
+                    return (range.sheetId === sheetId &&
+                        rowIndex >= range.startRowIndex &&
+                        rowIndex <= range.endRowIndex &&
+                        columnIndex >= range.startColumnIndex &&
+                        columnIndex <= range.endColumnIndex);
+                });
+                if (isCircular) {
+                    return undefined;
+                }
+            }
+            const isPreview = true;
+            return await getCalculator().calculate(value.slice(1), position, isArray, isPreview, disablePreview);
+        }
+        catch (err) {
+            // Formula errors (#NAME?, #REF!, …) are values, not
+            // exceptions — the recalc loop stores them as cell values,
+            // and fire-and-forget preview callers (charts, status bar,
+            // filter-by-condition) have no rejection handler, so a throw
+            // here escapes as an unhandled promise rejection.
+            if (err instanceof FormulaError) {
+                return err;
+            }
+            throw err;
+        }
+        finally {
+            overridesRef.current = previousOverrides ?? null;
+        }
+    }, []);
+    // Get all nodes from calculator
+    const getGraphNodes = useCallback(() => {
+        return getCalculator().graph.nodes;
+    }, []);
+    // Get sheet-bound nodes from the per-sheet bucket. Cheaper than
+    // `getGraphNodes()` for callers that only care about a single sheet —
+    // structural ops use this for the formula-cell sweep so cost scales with
+    // `nodes_in_sheet` rather than `nodes_in_workbook`.
+    const getGraphNodesInSheet = useCallback((sheetId) => {
+        return getCalculator().graph.getNodesInSheet(sheetId);
+    }, []);
+    // Add a static reference
+    const addStaticReference = useCallback((source, sourcePosition) => {
+        return getCalculator().addStaticReference(source, sourcePosition);
+    }, []);
+    const addFormulaToGraph = useCallbackRef(useCallback((formulaValue, position) => {
+        if (!formulaValue) {
+            return;
+        }
+        getCalculator().addFormulaToGraph(formulaValue, position);
+    }, []));
+    // Remove static reference
+    const removeStaticReference = useCallback((source) => {
+        return getCalculator().removeStaticReference(source);
+    }, []);
+    // Reset calculator
+    const onResetCalculator = useCallbackRef(useCallback(() => {
+        isFullRecalcRef.current = true;
+        // Reset graph
+        getCalculator().graph.reset();
+        getCalculator().arrayRangeMap.clear();
+        getCalculator().arrayRangeMap.clear();
+    }, []));
+    /**
+     * Get dependency graph
+     */
+    const getDependencyGraph = useCallbackRef(useCallback(() => {
+        return getCalculator().graph.toJSON();
+    }, []));
+    // Update dependency graph
+    const updateDependencyGraph = useCallbackRef(useCallback((nodes) => {
+        // Reset graph
+        getCalculator().graph.reset();
+        // Update graph
+        getCalculator().graph.fromJSON(JSON.parse(nodes));
+    }, []));
+    const noopCalculationApi = useMemo(() => ({
+        enqueueCalculation: () => { },
+        enqueueGraphOperation: () => { },
+        getPrecedents: () => [],
+        getPrecedentsFromFormulaString: () => [],
+        getDependents: () => [],
+        enqueueStructureChange: () => { },
+        clearRangeCache: () => { },
+        deleteSheetReferences: () => { },
+        onRequestCalculate: async () => undefined,
+        getGraphNodes: () => new Map(),
+        getGraphNodesInSheet: () => undefined,
+        addStaticReference: () => { },
+        addFormulaToGraph: () => { },
+        removeStaticReference: () => { },
+        onResetCalculator: () => { },
+        getDependencyGraph: () => "[]",
+        updateDependencyGraph: () => { },
+        isArrayFormula: () => false,
+        applyNamedRanges: (_list) => { },
+    }), []);
+    const api = {
+        enqueueCalculation,
+        enqueueGraphOperation,
+        getPrecedents,
+        getPrecedentsFromFormulaString,
+        getDependents,
+        enqueueStructureChange,
+        clearRangeCache,
+        deleteSheetReferences,
+        onRequestCalculate,
+        getGraphNodes,
+        getGraphNodesInSheet,
+        addStaticReference,
+        addFormulaToGraph,
+        removeStaticReference,
+        onResetCalculator,
+        getDependencyGraph,
+        updateDependencyGraph,
+        isArrayFormula,
+        // Phase 9 — exposed so `useCalculationInitialize` can guarantee
+        // named ranges are registered BEFORE cell formulas are parsed
+        // (otherwise cells using a named range would form no DAG edge
+        // to its static node — Excel registers names workbook-wide
+        // before any cell evaluates).
+        applyNamedRanges,
+    };
+    return enabled ? api : noopCalculationApi;
+};