@rowsncolumns/spreadsheet-state 28.0.66

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

@@ -0,0 +1,1688 @@
+import { CalculationGraph, CalculationWorkerClient, createNamedRangeResolver, createStructuredReferenceResolver, enqueueCalculationOperations, mapOperationToGraphOperation, } from "@rowsncolumns/calculation-worker";
+import { tokenize as formulaTokenizer } from "@rowsncolumns/calculator";
+import { CellNode, CellRangeNode, isCellCoordinate, isCellNode, isCellRangeNode, isStaticNode, makeKey, } from "@rowsncolumns/dag";
+import { FormulaError } from "@rowsncolumns/fast-formula-parser";
+import { isAreasEqual } from "@rowsncolumns/grid";
+import { useCallbackRef } from "@rowsncolumns/spreadsheet";
+import { isAFormula, isNil, scheduleAfterPaint } from "@rowsncolumns/utils";
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import { BehaviorSubject } from "rxjs";
+import { parseFilterSourceRange } from "../api/filter-range";
+import { getFunctionNamesFromFormula } from "../api/immer-utils";
+import { generateCollisionError, isEqualPosition } from "../api/range";
+import { AWAITING_CALCULATION } from "../helpers";
+import { SheetCell } from "../sheet-cell";
+import { useDeferredCalculationFlush } from "./use-deferred-calculation-flush";
+const ensureBatchTiming = (store, batchId) => {
+    let timing = store.get(batchId);
+    if (!timing) {
+        timing = {};
+        store.set(batchId, timing);
+    }
+    return timing;
+};
+const getTimestamp = () => typeof performance !== "undefined" && typeof performance.now === "function"
+    ? performance.now()
+    : Date.now();
+class CalculationMetrics {
+    histogram = new Map();
+    record(phase, duration) {
+        if (duration == null || Number.isNaN(duration)) {
+            return;
+        }
+        const bucket = this.histogram.get(phase);
+        if (bucket) {
+            bucket.push(duration);
+        }
+        else {
+            this.histogram.set(phase, [duration]);
+        }
+    }
+    report() {
+        const result = {};
+        for (const [phase, values] of this.histogram) {
+            if (!values.length)
+                continue;
+            const sorted = [...values].sort((a, b) => a - b);
+            result[phase] = {
+                p50: this.getPercentileFromSorted(sorted, 0.5),
+                p95: this.getPercentileFromSorted(sorted, 0.95),
+                p99: this.getPercentileFromSorted(sorted, 0.99),
+            };
+        }
+        return result;
+    }
+    getPercentileFromSorted(values, percentile) {
+        if (!values.length)
+            return 0;
+        const index = Math.min(values.length - 1, Math.max(0, Math.floor(percentile * values.length)));
+        return values[index];
+    }
+    clear() {
+        this.histogram.clear();
+    }
+}
+const isSerializedFormulaError = (value) => {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "type" in value &&
+        value.type === "FormulaError");
+};
+const toCellRange = (position) => {
+    if ("startRowIndex" in position) {
+        return position;
+    }
+    return {
+        sheetId: position.sheetId,
+        startRowIndex: position.rowIndex,
+        endRowIndex: position.rowIndex,
+        startColumnIndex: position.columnIndex,
+        endColumnIndex: position.columnIndex,
+    };
+};
+const isWorkerFormulaErrorDetails = (details) => {
+    return (!!details &&
+        typeof details === "object" &&
+        "reason" in details &&
+        typeof details.reason === "string");
+};
+const normalizeArrayResult = (value) => {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    if (!value.length) {
+        return [[undefined]];
+    }
+    if (Array.isArray(value[0])) {
+        return value;
+    }
+    return [value];
+};
+const getOperationKey = (operation) => {
+    return makeKey(operation.position);
+};
+const VOLATILE_FUNCTIONS = new Set([
+    "NOW",
+    "TODAY",
+    "RAND",
+    "RANDARRAY",
+    "RANDBETWEEN",
+    "SHEET",
+    "SHEETS",
+    "OFFSET",
+    "INDIRECT",
+]);
+const MAX_BUFFERED_RESULTS = 2000;
+const mergePendingOperation = (current, incoming) => {
+    if (!current) {
+        return incoming;
+    }
+    if (incoming.type === "add" || incoming.type === "remove") {
+        return incoming;
+    }
+    if (incoming.type === "dirty") {
+        if (current.type === "add" || current.type === "remove") {
+            return current;
+        }
+        if (current.type === "dirty") {
+            return {
+                ...current,
+                force: current.force || incoming.force,
+            };
+        }
+    }
+    return incoming;
+};
+const createRangeFromMatrix = (anchor, matrix) => {
+    const rowCount = Math.max(matrix.length, 1);
+    const columnCount = Math.max(matrix[0]?.length ?? 1, 1);
+    return {
+        sheetId: anchor.sheetId,
+        startRowIndex: anchor.rowIndex,
+        startColumnIndex: anchor.columnIndex,
+        endRowIndex: anchor.rowIndex + rowCount - 1,
+        endColumnIndex: anchor.columnIndex + columnCount - 1,
+    };
+};
+const forEachCellInRange = (range, iteratee) => {
+    let rowOffset = 0;
+    for (let row = range.startRowIndex; row <= range.endRowIndex; row++, rowOffset++) {
+        let columnOffset = 0;
+        for (let column = range.startColumnIndex; column <= range.endColumnIndex; column++, columnOffset++) {
+            const shouldStop = iteratee({ sheetId: range.sheetId, rowIndex: row, columnIndex: column }, { row: rowOffset, column: columnOffset });
+            if (shouldStop) {
+                return;
+            }
+        }
+    }
+};
+const isCoordinateWithinRange = (position, range) => {
+    return (range.sheetId === position.sheetId &&
+        position.rowIndex >= range.startRowIndex &&
+        position.rowIndex <= range.endRowIndex &&
+        position.columnIndex >= range.startColumnIndex &&
+        position.columnIndex <= range.endColumnIndex);
+};
+const rangesOverlap = (left, right) => {
+    if (left.sheetId !== right.sheetId) {
+        return false;
+    }
+    return (left.startRowIndex <= right.endRowIndex &&
+        left.endRowIndex >= right.startRowIndex &&
+        left.startColumnIndex <= right.endColumnIndex &&
+        left.endColumnIndex >= right.startColumnIndex);
+};
+export const useCalculationWorker = (props) => {
+    const { sheets, worker, createWorker, workerLogger, activeSheetId, getSheetId, getSheetName, getEffectiveValue, getCellData, getUserEnteredValue, getConditionalFormatFormula, getDataValidationFormula, getEffectiveStructuredValue, onSuccess, onBeginCalculation, onChangeStaticReference, locale, tables, namedRanges, onDemandFormulaPattern, coalesceDelayMs = 0, enablePerformanceLogging = false, iterativeCalculation, enableLazyCalculation = true, enabled = true, } = props;
+    const onSuccessRef = useCallbackRef(onSuccess);
+    const onBeginCalculationRef = useCallbackRef(onBeginCalculation);
+    const onChangeStaticReferenceRef = useCallbackRef(onChangeStaticReference);
+    const getUserEnteredValueRef = useCallbackRef(getUserEnteredValue);
+    const getConditionalFormatFormulaRef = useCallbackRef(getConditionalFormatFormula);
+    const getDataValidationFormulaRef = useCallbackRef(getDataValidationFormula);
+    const getEffectiveValueRef = useCallbackRef(getEffectiveValue);
+    const getEffectiveStructuredValueRef = useCallbackRef(getEffectiveStructuredValue);
+    const getSheetIdRef = useCallbackRef(getSheetId);
+    const getSheetNameRef = useCallbackRef(getSheetName);
+    const onPerformanceEventRef = useCallbackRef(props.onPerformanceEvent);
+    const emitPerformanceEvent = useCallback((event) => {
+        if (enablePerformanceLogging && typeof console !== "undefined") {
+            const logger = console.debug ?? console.log;
+            logger.call(console, "[calc-worker]", event);
+        }
+        onPerformanceEventRef?.(event);
+    }, [enablePerformanceLogging, onPerformanceEventRef]);
+    const pendingVolatileTrackingRef = useRef(new Map());
+    const deferredOperationsBySheetRef = useRef(new Map());
+    const completedCountRef = useRef(0);
+    const statsSubjectRef = useRef(null);
+    if (!statsSubjectRef.current) {
+        statsSubjectRef.current = new BehaviorSubject({
+            queuedCount: 0,
+            inFlightCount: 0,
+            completedCount: 0,
+            deferredCount: 0,
+        });
+    }
+    const processFrameRef = useRef(null);
+    const processingRef = useRef(false);
+    const pendingOperationQueueRef = useRef([]);
+    const pendingOperationMapRef = useRef(new Map());
+    const enqueuePendingOperationRef = useRef(undefined);
+    const isFullRecalcRef = useRef(false);
+    const computedValuesRef = useRef(new Map());
+    const pendingResultsRef = useRef(new Map());
+    const resultFrameRef = useRef(null);
+    const volatileCellsRef = useRef(new Map());
+    const pendingStaticNodesRef = useRef([]);
+    const staticFrameRef = useRef(null);
+    const beginQueueRef = useRef([]);
+    const beginPendingKeysRef = useRef(new Set());
+    const pendingArrayDirtyAnchorsRef = useRef(new Map());
+    const graphRef = useRef(null);
+    const workerInstanceRef = useRef(null);
+    const workerErrorPromiseRef = useRef(null);
+    const workerErrorRejectRef = useRef(null);
+    const workerErrorCleanupRef = useRef(null);
+    const tablesRef = useRef(tables);
+    const namedRangesRef = useRef(namedRanges);
+    const sheetsRef = useRef(sheets);
+    tablesRef.current = tables;
+    namedRangesRef.current = namedRanges;
+    sheetsRef.current = sheets;
+    const scheduleVolatileTracking = useCallback((position) => {
+        pendingVolatileTrackingRef.current.set(makeKey(position), position);
+    }, []);
+    const structuredReferenceResolver = useMemo(() => createStructuredReferenceResolver({
+        getTables: () => tablesRef.current,
+        getSheetName: (sheetId) => getSheetNameRef(sheetId),
+        getSheetId: (sheetName) => sheetName ? getSheetIdRef(sheetName) : undefined,
+    }), [getSheetNameRef, getSheetIdRef]);
+    const namedRangeResolver = useMemo(() => createNamedRangeResolver({
+        getNamedRanges: () => namedRangesRef.current,
+        getSheetName: (sheetId) => getSheetNameRef(sheetId),
+    }), [getSheetNameRef]);
+    if (!graphRef.current) {
+        graphRef.current = new CalculationGraph({
+            getSheetId: (name) => getSheetIdRef(name),
+            getSheetName: (id) => getSheetNameRef(id),
+            getFormula: (position) => {
+                const value = getFinalUserEnteredValue(position);
+                return typeof value === "string" ? value : undefined;
+            },
+            getCellValue: (position, property) => {
+                const key = makeKey(position);
+                if (computedValuesRef.current.has(key)) {
+                    const cached = computedValuesRef.current.get(key);
+                    if (property) {
+                        if (!getEffectiveStructuredValueRef) {
+                            return undefined;
+                        }
+                        const resolved = getEffectiveStructuredValueRef(cached, property);
+                        return resolved;
+                    }
+                    return cached;
+                }
+                return getEffectiveValueRef(position.sheetId, position.rowIndex, position.columnIndex, property);
+            },
+            getSheetProperties: (sheetId) => {
+                const sheet = sheetsRef.current.find((s) => s.id === sheetId);
+                if (!sheet)
+                    return undefined;
+                return {
+                    rowCount: sheet.rowCount,
+                    columnCount: sheet.columnCount,
+                };
+            },
+            depParserConfig: {
+                onStructuredReference: structuredReferenceResolver,
+                onVariable: namedRangeResolver,
+            },
+            iterativeCalculation,
+        });
+    }
+    const graph = graphRef.current;
+    useEffect(() => {
+        graph.setIterativeCalculationOptions(iterativeCalculation);
+    }, [graph, iterativeCalculation]);
+    const ensureWorkerInstance = () => {
+        if (workerInstanceRef.current) {
+            return workerInstanceRef.current;
+        }
+        const instance = worker ?? createWorker?.();
+        if (!instance) {
+            throw new Error("Calculation worker not provided. Pass a worker or createWorker factory.");
+        }
+        workerInstanceRef.current = instance;
+        workerErrorPromiseRef.current = new Promise((_, reject) => {
+            workerErrorRejectRef.current = reject;
+        });
+        const handleWorkerError = (event) => {
+            const error = event?.error instanceof Error
+                ? event.error
+                : new Error(event?.message ?? "Calculation worker failed to load.");
+            workerErrorRejectRef.current?.(error);
+        };
+        instance.addEventListener("error", handleWorkerError);
+        workerErrorCleanupRef.current = () => {
+            instance.removeEventListener("error", handleWorkerError);
+        };
+        return instance;
+    };
+    const workerClientRef = useRef(null);
+    const workerClientStub = useMemo(() => ({
+        initialize: async () => { },
+        dispose: () => { },
+        cancel: () => { },
+        evaluate: async () => [],
+    }), []);
+    if (!workerClientRef.current) {
+        workerClientRef.current = enabled
+            ? new CalculationWorkerClient({
+                worker: ensureWorkerInstance(),
+                logger: workerLogger,
+                enableNumericMatrixTransfer: true,
+            })
+            : workerClientStub;
+    }
+    else if (enabled && workerClientRef.current === workerClientStub) {
+        workerClientRef.current = new CalculationWorkerClient({
+            worker: ensureWorkerInstance(),
+            logger: workerLogger,
+            enableNumericMatrixTransfer: true,
+        });
+    }
+    else if (!enabled && workerClientRef.current !== workerClientStub) {
+        workerErrorCleanupRef.current?.();
+        workerClientRef.current.dispose();
+        workerInstanceRef.current = null;
+        workerErrorPromiseRef.current = null;
+        workerErrorRejectRef.current = null;
+        workerClientRef.current = workerClientStub;
+    }
+    const workerClient = workerClientRef.current;
+    const workerReadyRef = useRef(false);
+    const pendingUserValueEditsRef = useRef(new Map());
+    const getFinalUserEnteredValue = useCallback((position) => {
+        const pendingKey = makeKey(position);
+        if (pendingUserValueEditsRef.current.has(pendingKey)) {
+            return pendingUserValueEditsRef.current.get(pendingKey);
+        }
+        const { conditionalFormatId, dataValidationId } = position;
+        if (!isNil(conditionalFormatId)) {
+            return getConditionalFormatFormulaRef(position.sheetId, position.rowIndex, position.columnIndex, conditionalFormatId);
+        }
+        if (!isNil(dataValidationId)) {
+            return getDataValidationFormulaRef(position.sheetId, position.rowIndex, position.columnIndex, dataValidationId);
+        }
+        return getUserEnteredValueRef(position.sheetId, position.rowIndex, position.columnIndex);
+    }, [
+        getConditionalFormatFormulaRef,
+        getDataValidationFormulaRef,
+        getUserEnteredValueRef,
+    ]);
+    const updateVolatileFormulaTracking = useCallback((position) => {
+        const userValue = getFinalUserEnteredValue(position);
+        const key = makeKey(position);
+        volatileCellsRef.current.delete(key);
+        if (typeof userValue !== "string") {
+            return;
+        }
+        const normalized = userValue.trim();
+        if (!normalized.startsWith("=")) {
+            return;
+        }
+        const formula = normalized.slice(1);
+        const fns = getFunctionNamesFromFormula(formula);
+        if (fns.some((fn) => VOLATILE_FUNCTIONS.has(fn.toUpperCase()))) {
+            volatileCellsRef.current.set(key, position);
+        }
+    }, [getFinalUserEnteredValue]);
+    const flushVolatileTracking = useCallback(() => {
+        // Volatile formulas enqueue themselves asynchronously—flush the buffered
+        // positions once per processing pass so we only rescan the formulas we saw.
+        if (!pendingVolatileTrackingRef.current.size) {
+            return;
+        }
+        pendingVolatileTrackingRef.current.forEach((position) => updateVolatileFormulaTracking(position));
+        pendingVolatileTrackingRef.current.clear();
+    }, [updateVolatileFormulaTracking]);
+    const queueAnchorDirty = useCallback((anchor) => {
+        // Array anchors can request a follow-up recalc once spill conflicts clear;
+        // track a pending flag so we only enqueue a single dirty op per anchor.
+        const key = makeKey(anchor);
+        if (collisionAnchorsRef.current.has(key)) {
+            return;
+        }
+        const pending = pendingArrayDirtyAnchorsRef.current;
+        if (pending.has(key)) {
+            pending.set(key, true);
+            return;
+        }
+        if (!enqueuePendingOperationRef.current) {
+            return;
+        }
+        pending.set(key, false);
+        enqueuePendingOperationRef.current({
+            type: "dirty",
+            position: anchor,
+            force: true,
+        });
+    }, []);
+    const markAnchorProcessed = useCallback((anchor) => {
+        const key = makeKey(anchor);
+        const pending = pendingArrayDirtyAnchorsRef.current;
+        const shouldRetry = pending.get(key);
+        pending.delete(key);
+        if (shouldRetry) {
+            queueAnchorDirty(anchor);
+        }
+    }, [queueAnchorDirty]);
+    const graphOperationQueueRef = useRef([]);
+    const graphOperationFrameRef = useRef(null);
+    const arrayRangeCacheRef = useRef(new Map());
+    const findCachedArrayAnchor = useCallback((position) => {
+        for (const entry of arrayRangeCacheRef.current.values()) {
+            if (isCoordinateWithinRange(position, entry.range)) {
+                return entry.anchor;
+            }
+        }
+        return undefined;
+    }, []);
+    const workerForceRecalcKeysRef = useRef(new Set());
+    const activeWorkerKeysRef = useRef(new Set());
+    const activeExecutionsRef = useRef(0);
+    const emitStats = useCallback(() => {
+        const statsSubject = statsSubjectRef.current;
+        if (!statsSubject) {
+            return;
+        }
+        let deferredCount = 0;
+        deferredOperationsBySheetRef.current.forEach((operations) => {
+            deferredCount += operations.size;
+        });
+        statsSubject.next({
+            queuedCount: pendingOperationMapRef.current.size,
+            inFlightCount: activeWorkerKeysRef.current.size,
+            completedCount: completedCountRef.current,
+            deferredCount,
+        });
+    }, []);
+    const deferCalculationNodes = useCallback((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: workerForceRecalcKeysRef.current.has(key),
+            });
+            deferredOperationsBySheetRef.current.set(sheetId, existing);
+        }
+        emitStats();
+    }, [emitStats]);
+    const cancelInflightEvaluation = useCallback((target) => {
+        if (!target) {
+            return;
+        }
+        const key = typeof target === "string" ? target : makeKey(target);
+        if (activeWorkerKeysRef.current.has(key)) {
+            activeWorkerKeysRef.current.delete(key);
+            emitStats();
+        }
+        workerClient.cancel([key]);
+    }, [emitStats, workerClient]);
+    const onDemandPattern = useMemo(() => {
+        if (!onDemandFormulaPattern)
+            return undefined;
+        return new RegExp(onDemandFormulaPattern, "gi");
+    }, [onDemandFormulaPattern]);
+    const workerBatchTimingRef = useRef(new Map());
+    const batchSizesRef = useRef(new Map());
+    const batchesWithFirstResultLoggedRef = useRef(new Set());
+    const metricsRef = useRef(new CalculationMetrics());
+    const emitBatchPhaseEvent = useCallback((phase, options) => {
+        const { batchId } = options;
+        if (!batchId) {
+            return;
+        }
+        const size = options.size && options.size > 0
+            ? options.size
+            : batchSizesRef.current.get(batchId) ?? 0;
+        const timestamp = options.timestamp ?? getTimestamp();
+        const timing = ensureBatchTiming(workerBatchTimingRef.current, batchId);
+        // The switch below materializes a pseudo state machine so we can derive
+        // durations for every phase even if some events arrive out of order.
+        let duration = options.duration;
+        switch (phase) {
+            case "start":
+                timing.start = timestamp;
+                break;
+            case "plan-built":
+                if (!timing.start) {
+                    timing.start = timestamp;
+                }
+                duration ??=
+                    timing.start != null ? timestamp - timing.start : undefined;
+                timing.planBuilt = timestamp;
+                break;
+            case "worker-dispatch":
+                duration ??=
+                    timing.planBuilt != null
+                        ? timestamp - timing.planBuilt
+                        : timing.start != null
+                            ? timestamp - timing.start
+                            : undefined;
+                timing.workerDispatch = timestamp;
+                break;
+            case "worker-runtime-complete":
+                if (duration == null) {
+                    duration =
+                        timing.workerDispatch != null
+                            ? timestamp - timing.workerDispatch
+                            : undefined;
+                }
+                timing.workerRuntimeComplete = timestamp;
+                break;
+            case "first-result":
+                if (timing.firstResult) {
+                    return;
+                }
+                duration ??=
+                    timing.workerDispatch != null
+                        ? timestamp - timing.workerDispatch
+                        : timing.planBuilt != null
+                            ? timestamp - timing.planBuilt
+                            : undefined;
+                timing.firstResult = timestamp;
+                break;
+            case "worker-complete":
+                duration ??=
+                    timing.workerRuntimeComplete != null
+                        ? timestamp - timing.workerRuntimeComplete
+                        : undefined;
+                timing.workerComplete = timestamp;
+                break;
+            case "complete":
+                duration ??=
+                    timing.start != null ? timestamp - timing.start : undefined;
+                timing.complete = timestamp;
+                workerBatchTimingRef.current.delete(batchId);
+                batchSizesRef.current.delete(batchId);
+                batchesWithFirstResultLoggedRef.current.delete(batchId);
+                break;
+        }
+        metricsRef.current.record(phase, duration);
+        if (enablePerformanceLogging && phase === "complete") {
+            const report = metricsRef.current.report();
+            if (Object.keys(report).length && typeof console !== "undefined") {
+                if (typeof console.table === "function") {
+                    console.table(report);
+                }
+                else if (typeof console.debug === "function") {
+                    console.debug("[calc-worker][metrics]", report);
+                }
+                else if (typeof console.log === "function") {
+                    console.log("[calc-worker][metrics]", report);
+                }
+            }
+        }
+        emitPerformanceEvent({
+            type: "worker-batch",
+            phase,
+            batchId,
+            size,
+            timestamp,
+            duration,
+        });
+    }, [emitPerformanceEvent, enablePerformanceLogging]);
+    const beginBatchTracking = useCallback((plan, size, startTimestamp) => {
+        batchSizesRef.current.set(plan.id, size);
+        emitBatchPhaseEvent("start", {
+            batchId: plan.id,
+            size,
+            timestamp: startTimestamp,
+        });
+    }, [emitBatchPhaseEvent]);
+    const handlePlanBuilt = useCallback((plan, startTimestamp) => {
+        const cellCount = plan.nodes.filter((node) => node.kind === "cell").length;
+        if (!cellCount) {
+            return;
+        }
+        beginBatchTracking(plan, cellCount, startTimestamp);
+        emitBatchPhaseEvent("plan-built", { batchId: plan.id, size: cellCount });
+    }, [emitBatchPhaseEvent, beginBatchTracking]);
+    const handleWorkerBatchEvent = useCallback((event, batchId) => {
+        if (event.phase === "worker-dispatch") {
+            batchSizesRef.current.set(batchId, event.batchSize);
+            emitBatchPhaseEvent("worker-dispatch", {
+                batchId,
+                timestamp: event.timestamp,
+                size: event.batchSize,
+            });
+            return;
+        }
+        emitBatchPhaseEvent("worker-runtime-complete", {
+            batchId,
+            timestamp: event.timestamp,
+            duration: event.duration,
+            size: event.batchSize,
+        });
+    }, [emitBatchPhaseEvent]);
+    const pushPendingOperation = useCallback((operation) => {
+        // Prevent stale worker responses from racing the new work by tearing down
+        // any inflight evaluations for the affected cells.
+        cancelInflightEvaluation(operation.position);
+        if (operation.previousPosition) {
+            cancelInflightEvaluation(operation.previousPosition);
+        }
+        if (operation.type !== "dirty") {
+            const anchor = graph.getArrayParent(operation.position) ??
+                findCachedArrayAnchor(operation.position);
+            if (anchor && !isEqualPosition(anchor, operation.position)) {
+                queueAnchorDirty(anchor);
+            }
+        }
+        const key = getOperationKey(operation);
+        const existing = pendingOperationMapRef.current.get(key);
+        // Coalesce successive edits on the same cell so we only schedule the most
+        // recent intent and avoid redundant graph rebuilds.
+        const merged = mergePendingOperation(existing, operation);
+        if (merged === existing) {
+            return false;
+        }
+        pendingOperationMapRef.current.set(key, merged);
+        if (!existing) {
+            pendingOperationQueueRef.current.push(key);
+        }
+        if (operation.force) {
+            workerForceRecalcKeysRef.current.add(key);
+        }
+        return true;
+    }, [cancelInflightEvaluation, graph, findCachedArrayAnchor, queueAnchorDirty]);
+    const enqueueVolatileCells = useCallback(() => {
+        // Volatile cells always recalc with the next batch so they can pick up
+        // global changes (time, randomization, etc.).
+        volatileCellsRef.current.forEach((position) => {
+            const key = makeKey(position);
+            if (!pendingOperationMapRef.current.has(key)) {
+                pushPendingOperation({
+                    type: "dirty",
+                    position,
+                    force: true,
+                });
+            }
+        });
+    }, [pushPendingOperation]);
+    const deserializeResultValue = useCallback((value) => {
+        if (isSerializedFormulaError(value)) {
+            const rawDetails = value.details;
+            let structured;
+            let summary;
+            if (typeof rawDetails === "string") {
+                summary = rawDetails;
+            }
+            else if (isWorkerFormulaErrorDetails(rawDetails)) {
+                structured = rawDetails;
+                summary = structured.reason;
+            }
+            else if (rawDetails != null) {
+                summary = String(rawDetails.message ?? rawDetails);
+            }
+            const error = new FormulaError(value.error, summary, summary);
+            error.details = structured ?? rawDetails;
+            return error;
+        }
+        return value;
+    }, []);
+    const flushStaticNotifications = useCallback(() => {
+        staticFrameRef.current = null;
+        if (!pendingStaticNodesRef.current.length)
+            return;
+        onChangeStaticReferenceRef?.(pendingStaticNodesRef.current.slice());
+        pendingStaticNodesRef.current = [];
+    }, [onChangeStaticReferenceRef]);
+    const queueStaticNotification = useCallback((node) => {
+        pendingStaticNodesRef.current.push(node);
+        if (staticFrameRef.current == null) {
+            staticFrameRef.current = requestAnimationFrame(flushStaticNotifications);
+        }
+    }, [flushStaticNotifications]);
+    const flushResults = useCallback(() => {
+        resultFrameRef.current = null;
+        if (!pendingResultsRef.current.size)
+            return;
+        const isFullRecalc = isFullRecalcRef.current;
+        const pendingResults = pendingResultsRef.current;
+        onSuccessRef?.(pendingResults.values(), isFullRecalc, {});
+        // Once the consumer receives the batch we can drop the temporary cache so
+        // large evaluations (e.g. VLOOKUP matrices) don't accumulate in memory.
+        for (const key of pendingResults.keys()) {
+            computedValuesRef.current.delete(key);
+        }
+        pendingResults.clear();
+        isFullRecalcRef.current = false;
+    }, [onSuccessRef]);
+    const queueCellValue = useCallback((position, value, formatting) => {
+        // Buffer results until the next frame so grid updates stay batched and
+        // React state observers only process one consolidated payload.
+        const key = makeKey(position);
+        pendingUserValueEditsRef.current.delete(key);
+        computedValuesRef.current.set(key, value);
+        pendingResultsRef.current.set(key, [position, value, formatting]);
+        workerForceRecalcKeysRef.current.delete(key);
+        beginPendingKeysRef.current.delete(key);
+        if (pendingResultsRef.current.size >= MAX_BUFFERED_RESULTS) {
+            const frame = resultFrameRef.current;
+            if (frame != null) {
+                cancelAnimationFrame(frame);
+                resultFrameRef.current = null;
+            }
+            flushResults();
+            return;
+        }
+        if (resultFrameRef.current == null) {
+            resultFrameRef.current = requestAnimationFrame(flushResults);
+        }
+    }, [flushResults]);
+    const flushBeginNotifications = useCallback(() => {
+        if (!beginQueueRef.current.length)
+            return;
+        // Swap queue with empty array - O(1) operation
+        // This avoids O(n²) complexity from using shift() in a loop
+        const operations = beginQueueRef.current;
+        beginQueueRef.current = [];
+        const pending = [];
+        const pendingKeys = beginPendingKeysRef.current;
+        // Process all operations - O(n) total
+        for (let i = 0; i < operations.length; i++) {
+            const position = operations[i];
+            if (!position) {
+                continue;
+            }
+            const key = makeKey(position);
+            if (pendingKeys.has(key)) {
+                pendingKeys.delete(key);
+                pending.push(position);
+            }
+        }
+        if (!pending.length)
+            return;
+        onBeginCalculationRef?.(pending);
+    }, [onBeginCalculationRef]);
+    const enqueueBeginPosition = useCallback((position) => {
+        const key = makeKey(position);
+        if (beginPendingKeysRef.current.has(key)) {
+            return;
+        }
+        beginPendingKeysRef.current.add(key);
+        // Ignore other node types
+        if (position.conditionalFormatId || position.dataValidationId) {
+            return;
+        }
+        beginQueueRef.current.push(position);
+        flushBeginNotifications();
+    }, [flushBeginNotifications]);
+    const preparePlanForExecution = useCallback((plan) => {
+        const cellNodes = plan.nodes.filter((node) => node.kind === "cell");
+        if (!cellNodes.length)
+            return;
+        // Cancel any inflight evaluations for nodes in this plan
+        const keysToCancel = [];
+        for (const node of cellNodes) {
+            const key = makeKey(node.position);
+            if (activeWorkerKeysRef.current.has(key)) {
+                keysToCancel.push(key);
+                activeWorkerKeysRef.current.delete(key);
+            }
+        }
+        if (keysToCancel.length) {
+            workerClient.cancel(keysToCancel);
+        }
+        const filteredNodes = [];
+        for (const node of cellNodes) {
+            const key = makeKey(node.position);
+            if (onDemandPattern) {
+                onDemandPattern.lastIndex = 0;
+            }
+            const userValue = getFinalUserEnteredValue(node.position);
+            if (typeof userValue === "string" &&
+                userValue.startsWith("=") &&
+                onDemandPattern?.test(userValue) &&
+                !workerForceRecalcKeysRef.current.has(key)) {
+                // On-demand formulas opt-out of real execution until explicitly
+                // forced; they still emit begin/end notifications so the UI shows a
+                // deterministic "Awaiting calculation" placeholder.
+                beginPendingKeysRef.current.delete(key);
+                queueCellValue(node.position, AWAITING_CALCULATION);
+                continue;
+            }
+            filteredNodes.push(node);
+        }
+        if (filteredNodes.length !== cellNodes.length) {
+            const staticNodes = plan.nodes.filter((node) => node.kind === "static");
+            plan.nodes = [...staticNodes, ...filteredNodes];
+        }
+        for (const node of filteredNodes) {
+            activeWorkerKeysRef.current.add(makeKey(node.position));
+        }
+        emitStats();
+    }, [
+        getFinalUserEnteredValue,
+        emitStats,
+        workerClient,
+        onDemandPattern,
+        queueCellValue,
+    ]);
+    const handleNodeBegin = useCallback((node) => {
+        // Track inflight keys so late worker responses can be ignored/cancelled.
+        activeWorkerKeysRef.current.add(makeKey(node.position));
+        if (node.kind === "cell") {
+            enqueueBeginPosition(node.position);
+        }
+    }, [enqueueBeginPosition]);
+    const normalizePropertyOverride = useCallback((value, property) => {
+        // Property accessors piggyback on the sheet-side structured resolver so
+        // worker scopes respect table/object semantics already in place.
+        if (value == null || typeof value !== "object" || Array.isArray(value)) {
+            return value;
+        }
+        if (!getEffectiveStructuredValueRef) {
+            return undefined;
+        }
+        return getEffectiveStructuredValueRef(value, property);
+    }, [getEffectiveStructuredValueRef]);
+    const detectArrayCollision = useCallback((range, anchor, preserve) => {
+        // Spills cannot overwrite typed-in values or another array range.
+        const anchorKey = makeKey(anchor);
+        let conflict;
+        forEachCellInRange(range, (cell) => {
+            const key = makeKey(cell);
+            if (key === anchorKey || preserve?.has(key)) {
+                return;
+            }
+            const userValue = getFinalUserEnteredValue(cell);
+            if (userValue != null) {
+                conflict = cell;
+                return true;
+            }
+            const parent = graph.getArrayParent(cell);
+            if (parent && isEqualPosition(parent, anchor)) {
+                return;
+            }
+            if (parent) {
+                conflict = cell;
+                return true;
+            }
+            return;
+        });
+        return conflict;
+    }, [getFinalUserEnteredValue, graph]);
+    const pendingSpillDependentAnchorsRef = useRef(new Set());
+    const collisionAnchorsRef = useRef(new Set());
+    const scheduleSpillDependents = useCallback((range, anchor) => {
+        // Any dependent referencing a previously spilled cell must be dirtied so
+        // it recomputes with the anchor's new footprint.
+        if (!enqueuePendingOperationRef.current)
+            return;
+        const scheduled = new Set();
+        forEachCellInRange(range, (cell) => {
+            if (isEqualPosition(cell, anchor)) {
+                return;
+            }
+            const dependents = graph.getDependents(cell);
+            for (const dependent of dependents) {
+                if (!isCellNode(dependent) || !dependent.position) {
+                    continue;
+                }
+                if (isEqualPosition(dependent.position, anchor)) {
+                    continue;
+                }
+                const dependentKey = makeKey(dependent.position);
+                if (scheduled.has(dependentKey))
+                    continue;
+                scheduled.add(dependentKey);
+                enqueuePendingOperationRef.current?.({
+                    type: "dirty",
+                    position: dependent.position,
+                    force: true,
+                });
+            }
+        });
+    }, [graph]);
+    const clearArrayValues = useCallback((anchor, options = {}) => {
+        // Helper for resetting existing spill results before writing new matrix
+        // values, with knobs for preserving user edits/registration metadata.
+        const anchorKey = makeKey(anchor);
+        const cachedEntry = arrayRangeCacheRef.current.get(anchorKey);
+        const range = graph.getArrayRangeFor(anchor) ?? cachedEntry?.range;
+        if (range) {
+            const preserve = new Set(options.preserveKeys);
+            if (options.preserveUserEntries) {
+                forEachCellInRange(range, (cell) => {
+                    if (isEqualPosition(cell, anchor)) {
+                        return;
+                    }
+                    const userValue = getFinalUserEnteredValue(cell);
+                    if (userValue != null &&
+                        (typeof userValue !== "string" || !userValue.startsWith("="))) {
+                        preserve.add(makeKey(cell));
+                    }
+                });
+            }
+            forEachCellInRange(range, (cell) => {
+                const key = makeKey(cell);
+                if ((!options.includeAnchor && key === anchorKey) ||
+                    preserve.has(key)) {
+                    return;
+                }
+                if (options.preserveComputedValues && key !== anchorKey) {
+                    return;
+                }
+                queueCellValue(cell, undefined);
+            });
+            if (options.notifyDependents) {
+                scheduleSpillDependents(range, anchor);
+            }
+            else if (options.deferDependents) {
+                pendingSpillDependentAnchorsRef.current.add(anchorKey);
+            }
+        }
+        if (!options.preserveRegistration) {
+            graph.unregisterArrayFormula(anchor);
+        }
+        if (options.forgetRange) {
+            arrayRangeCacheRef.current.delete(anchorKey);
+        }
+        else if (range) {
+            arrayRangeCacheRef.current.set(anchorKey, {
+                anchor,
+                range,
+            });
+        }
+    }, [graph, queueCellValue, scheduleSpillDependents, getFinalUserEnteredValue]);
+    const handleArrayEvaluation = useCallback((position, rawValue) => {
+        // Array formulas emit either matrices or scalars; normalize + register
+        // spill metadata before writing values back to cells.
+        const matrix = normalizeArrayResult(rawValue);
+        if (!matrix) {
+            clearArrayValues(position, { preserveUserEntries: true });
+            queueCellValue(position, deserializeResultValue(rawValue));
+            markAnchorProcessed(position);
+            return;
+        }
+        clearArrayValues(position, {
+            preserveUserEntries: true,
+            preserveComputedValues: true,
+            deferDependents: true,
+        });
+        const range = createRangeFromMatrix(position, matrix);
+        const collision = detectArrayCollision(range, position);
+        graph.registerArrayFormula(position, range);
+        arrayRangeCacheRef.current.set(makeKey(position), {
+            anchor: position,
+            range,
+        });
+        const anchorFormula = getFinalUserEnteredValue(position);
+        const filterSourceRange = parseFilterSourceRange(typeof anchorFormula === "string" ? anchorFormula : undefined, position.sheetId, getSheetIdRef, formulaTokenizer);
+        const sourceSheetCell = new SheetCell();
+        const filterColumnFormattingCache = new Map();
+        const getFilterFormatting = (columnOffset, rowOffset) => {
+            if (!filterSourceRange) {
+                return undefined;
+            }
+            const sourceColumnIndex = filterSourceRange.startColumnIndex + columnOffset;
+            if (sourceColumnIndex < filterSourceRange.startColumnIndex ||
+                sourceColumnIndex > filterSourceRange.endColumnIndex) {
+                return undefined;
+            }
+            const cachedFormatting = filterColumnFormattingCache.get(sourceColumnIndex);
+            if (cachedFormatting) {
+                return cachedFormatting;
+            }
+            const preferredSourceRowIndex = filterSourceRange.startRowIndex + rowOffset;
+            const getSourceNumberFormat = (sourceRowIndex) => {
+                const sourceCellData = getCellData(filterSourceRange.sheetId, sourceRowIndex, sourceColumnIndex);
+                return sourceSheetCell
+                    .assign(filterSourceRange.sheetId, {
+                    rowIndex: sourceRowIndex,
+                    columnIndex: sourceColumnIndex,
+                }, sourceCellData, { locale })
+                    .getEffectiveCellFormat()?.numberFormat;
+            };
+            if (preferredSourceRowIndex >= filterSourceRange.startRowIndex &&
+                preferredSourceRowIndex <= filterSourceRange.endRowIndex) {
+                const preferredNumberFormat = getSourceNumberFormat(preferredSourceRowIndex);
+                if (preferredNumberFormat) {
+                    const formatting = { numberFormat: preferredNumberFormat };
+                    filterColumnFormattingCache.set(sourceColumnIndex, formatting);
+                    return formatting;
+                }
+            }
+            for (let sourceRowIndex = filterSourceRange.startRowIndex; sourceRowIndex <= filterSourceRange.endRowIndex; sourceRowIndex += 1) {
+                const sourceNumberFormat = getSourceNumberFormat(sourceRowIndex);
+                if (sourceNumberFormat) {
+                    const formatting = { numberFormat: sourceNumberFormat };
+                    filterColumnFormattingCache.set(sourceColumnIndex, formatting);
+                    return formatting;
+                }
+            }
+            filterColumnFormattingCache.set(sourceColumnIndex, undefined);
+            return undefined;
+        };
+        if (collision) {
+            const preserve = new Set([makeKey(collision)]);
+            clearArrayValues(position, {
+                preserveKeys: preserve,
+                preserveUserEntries: true,
+                includeAnchor: false,
+                preserveRegistration: true,
+            });
+            let conflictingValue = getFinalUserEnteredValue(collision);
+            const collisionKey = makeKey(collision);
+            let usedPendingUserEdit = false;
+            if (conflictingValue === undefined) {
+                const pendingValue = pendingUserValueEditsRef.current.get(collisionKey);
+                if (pendingValue !== undefined) {
+                    conflictingValue = pendingValue;
+                    usedPendingUserEdit = true;
+                }
+            }
+            if (conflictingValue === undefined &&
+                computedValuesRef.current.has(collisionKey)) {
+                conflictingValue = computedValuesRef.current.get(collisionKey);
+            }
+            if (conflictingValue === undefined) {
+                const effective = getEffectiveValueRef(collision.sheetId, collision.rowIndex, collision.columnIndex);
+                if (effective != null) {
+                    conflictingValue = effective;
+                }
+            }
+            if (conflictingValue !== undefined) {
+                queueCellValue(collision, conflictingValue);
+                flushResults();
+                if (usedPendingUserEdit) {
+                    pendingUserValueEditsRef.current.delete(collisionKey);
+                }
+            }
+            queueCellValue(position, generateCollisionError(collision));
+            scheduleSpillDependents(range, position);
+            collisionAnchorsRef.current.add(makeKey(position));
+            pendingSpillDependentAnchorsRef.current.delete(makeKey(position));
+            markAnchorProcessed(position);
+            return;
+        }
+        forEachCellInRange(range, (cell, offsets) => {
+            const value = matrix[offsets.row]?.[offsets.column];
+            queueCellValue(cell, value ?? undefined, getFilterFormatting(offsets.column, offsets.row));
+        });
+        pendingSpillDependentAnchorsRef.current.delete(makeKey(position));
+        scheduleSpillDependents(range, position);
+        collisionAnchorsRef.current.delete(makeKey(position));
+        markAnchorProcessed(position);
+    }, [
+        flushResults,
+        clearArrayValues,
+        detectArrayCollision,
+        graph,
+        queueCellValue,
+        deserializeResultValue,
+        scheduleSpillDependents,
+        getFinalUserEnteredValue,
+        getCellData,
+        getEffectiveValueRef,
+        getSheetIdRef,
+        markAnchorProcessed,
+        locale,
+    ]);
+    const resolveFormulaForOperation = useCallback((operation) => {
+        const userValue = getFinalUserEnteredValue(operation.position);
+        return typeof userValue === "string" ? userValue : undefined;
+    }, [getFinalUserEnteredValue]);
+    const flushGraphOperations = useCallback(() => {
+        // Some graph operations (like static reference tweaks) are buffered so we
+        // can batch DAG mutations alongside user edits.
+        graphOperationFrameRef.current = null;
+        if (!graphOperationQueueRef.current.length)
+            return;
+        const operations = graphOperationQueueRef.current;
+        graphOperationQueueRef.current = [];
+        const graphOperations = operations
+            .map((operation) => mapOperationToGraphOperation(operation, resolveFormulaForOperation))
+            .filter((op) => Boolean(op));
+        if (!graphOperations.length)
+            return;
+        graph.applyGraphOperations(graphOperations);
+    }, [graph, resolveFormulaForOperation]);
+    const onAfterCalculation = useCallback(() => {
+        // Once every batch completes we either cleanup immediately or defer if more
+        // dirty anchors/operations are queued, preventing premature cache resets.
+        if (pendingOperationQueueRef.current.length ||
+            pendingArrayDirtyAnchorsRef.current.size) {
+            graph.cleanup();
+            workerForceRecalcKeysRef.current.clear();
+            return;
+        }
+        computedValuesRef.current.clear();
+        graph.cleanup();
+        workerForceRecalcKeysRef.current.clear();
+    }, [graph]);
+    const scheduleProcessingRef = useRef(() => { });
+    const handleResult = useCallback((result, batchId) => {
+        // Record the first payload for perf metrics before we mutate caches.
+        if (batchId && !batchesWithFirstResultLoggedRef.current.has(batchId)) {
+            batchesWithFirstResultLoggedRef.current.add(batchId);
+            emitBatchPhaseEvent("first-result", { batchId });
+        }
+        let shouldEmitStats = false;
+        if (result.key && activeWorkerKeysRef.current.has(result.key)) {
+            activeWorkerKeysRef.current.delete(result.key);
+            shouldEmitStats = true;
+        }
+        if (result.staticReferenceId) {
+            const node = graph.getNodes().get(result.staticReferenceId);
+            if (isStaticNode(node)) {
+                queueStaticNotification(node);
+            }
+            if (shouldEmitStats) {
+                emitStats();
+            }
+            return;
+        }
+        if (!result.position) {
+            if (shouldEmitStats) {
+                emitStats();
+            }
+            return;
+        }
+        completedCountRef.current += 1;
+        shouldEmitStats = true;
+        const enrichedPosition = result.position;
+        if (Array.isArray(result.value)) {
+            // Spilled arrays require special handling: persist matrix values and
+            // dirty downstream dependents tied to the old spill footprint.
+            handleArrayEvaluation(enrichedPosition, result.value);
+            emitStats();
+            return;
+        }
+        clearArrayValues(enrichedPosition, {
+            notifyDependents: true,
+            forgetRange: true,
+        });
+        queueCellValue(enrichedPosition, deserializeResultValue(result.value));
+        markAnchorProcessed(enrichedPosition);
+        if (shouldEmitStats) {
+            emitStats();
+        }
+    }, [
+        clearArrayValues,
+        deserializeResultValue,
+        graph,
+        handleArrayEvaluation,
+        queueCellValue,
+        queueStaticNotification,
+        emitBatchPhaseEvent,
+        markAnchorProcessed,
+        emitStats,
+    ]);
+    const processOperations = useCallback(async () => {
+        // This is the main scheduler loop: drain the pending queue, build plans,
+        // and stream results back while accounting for volatile + array mechanics.
+        if (processingRef.current)
+            return;
+        processingRef.current = true;
+        try {
+            flushVolatileTracking();
+            const hasValueAffectingNonVolatileOps = pendingOperationQueueRef.current.some((key) => !volatileCellsRef.current.has(key));
+            if (hasValueAffectingNonVolatileOps) {
+                enqueueVolatileCells();
+            }
+            while (pendingOperationQueueRef.current.length) {
+                const keys = pendingOperationQueueRef.current.splice(0);
+                const operations = [];
+                for (const key of keys) {
+                    const operation = pendingOperationMapRef.current.get(key);
+                    if (operation) {
+                        operations.push(operation);
+                        pendingOperationMapRef.current.delete(key);
+                    }
+                }
+                emitStats();
+                if (!operations.length) {
+                    continue;
+                }
+                operations.sort((a, b) => {
+                    const order = (type) => {
+                        if (type === "remove")
+                            return 0;
+                        if (type === "add")
+                            return 1;
+                        return 2;
+                    };
+                    return order(a.type) - order(b.type);
+                });
+                const evaluationOperations = operations;
+                if (!evaluationOperations.length) {
+                    continue;
+                }
+                activeExecutionsRef.current++;
+                let currentBatchId = null;
+                const enqueueStartTime = getTimestamp();
+                const forcedPositions = evaluationOperations
+                    .filter((operation) => "position" in operation &&
+                    Boolean(operation.force) &&
+                    isCellCoordinate(operation.position))
+                    .map((operation) => operation.position);
+                const onPlanBuiltWrapper = (plan) => {
+                    currentBatchId = plan.id;
+                    handlePlanBuilt(plan, enqueueStartTime);
+                };
+                const onWorkerBatchWrapper = (event) => {
+                    if (currentBatchId) {
+                        handleWorkerBatchEvent(event, currentBatchId);
+                    }
+                };
+                const onResultWrapper = (result) => {
+                    handleResult(result, currentBatchId ?? undefined);
+                };
+                const enqueuePromise = enqueueCalculationOperations({
+                    graph,
+                    workerClient,
+                    operations: evaluationOperations,
+                    resolveFormula: resolveFormulaForOperation,
+                    onResult: onResultWrapper,
+                    onPlan: preparePlanForExecution,
+                    onPlanBuilt: onPlanBuiltWrapper,
+                    onWorkerBatch: onWorkerBatchWrapper,
+                    onNodeBegin: handleNodeBegin,
+                    normalizePropertyOverride,
+                    planOptions: enableLazyCalculation && typeof activeSheetId === "number"
+                        ? {
+                            rootSheetId: activeSheetId,
+                            onDeferredNodes: deferCalculationNodes,
+                            includePositions: forcedPositions.length
+                                ? forcedPositions
+                                : undefined,
+                        }
+                        : undefined,
+                });
+                // Fire and forget (tracked by activeExecutionsRef)
+                enqueuePromise
+                    .then(() => {
+                    if (currentBatchId) {
+                        emitBatchPhaseEvent("worker-complete", {
+                            batchId: currentBatchId,
+                        });
+                        emitBatchPhaseEvent("complete", { batchId: currentBatchId });
+                    }
+                })
+                    .catch((error) => {
+                    console.error("Calculation error: ", error);
+                })
+                    .finally(() => {
+                    activeExecutionsRef.current--;
+                    if (activeExecutionsRef.current === 0) {
+                        onAfterCalculation();
+                        pendingArrayDirtyAnchorsRef.current.clear();
+                        activeWorkerKeysRef.current.clear();
+                        emitStats();
+                    }
+                });
+            }
+        }
+        finally {
+            processingRef.current = false;
+            if (pendingOperationQueueRef.current.length) {
+                scheduleProcessingRef.current();
+            }
+        }
+    }, [
+        activeSheetId,
+        enableLazyCalculation,
+        graph,
+        workerClient,
+        resolveFormulaForOperation,
+        handleResult,
+        preparePlanForExecution,
+        handlePlanBuilt,
+        handleWorkerBatchEvent,
+        emitBatchPhaseEvent,
+        emitStats,
+        handleNodeBegin,
+        normalizePropertyOverride,
+        deferCalculationNodes,
+        flushVolatileTracking,
+        enqueueVolatileCells,
+        onAfterCalculation,
+    ]);
+    const scheduleProcessing = useCallback(() => {
+        if (!workerReadyRef.current) {
+            return;
+        }
+        if (processFrameRef.current !== null) {
+            return;
+        }
+        const schedule = (cb) => {
+            if (coalesceDelayMs > 0) {
+                return setTimeout(() => scheduleAfterPaint(cb), coalesceDelayMs);
+            }
+            scheduleAfterPaint(cb);
+            return 0;
+        };
+        processFrameRef.current = schedule(() => {
+            processFrameRef.current = null;
+            processOperations();
+        });
+    }, [coalesceDelayMs, processOperations]);
+    scheduleProcessingRef.current = scheduleProcessing;
+    const enqueuePendingOperation = useCallback((operation) => {
+        if (pushPendingOperation(operation)) {
+            emitStats();
+            scheduleProcessing();
+        }
+    }, [emitStats, pushPendingOperation, scheduleProcessing]);
+    useEffect(() => {
+        enqueuePendingOperationRef.current = enqueuePendingOperation;
+    }, [enqueuePendingOperation]);
+    // Deferred activesheetid callbacks
+    useDeferredCalculationFlush({
+        activeSheetId: enableLazyCalculation && typeof activeSheetId === "number"
+            ? activeSheetId
+            : undefined,
+        deferredOperationsBySheetRef,
+        enqueueOperation: enqueuePendingOperation,
+        onFlushComplete: emitStats,
+    });
+    // Initialize
+    const workerInitSnapshotRef = useRef(undefined);
+    useEffect(() => {
+        if (!enabled || workerClient === workerClientStub) {
+            return;
+        }
+        const nextSnapshot = { sheets, locale, tables, namedRanges };
+        const prevSnapshot = workerInitSnapshotRef.current;
+        if (prevSnapshot &&
+            prevSnapshot.locale === nextSnapshot.locale &&
+            prevSnapshot.tables === nextSnapshot.tables &&
+            prevSnapshot.namedRanges === nextSnapshot.namedRanges &&
+            prevSnapshot.sheets === nextSnapshot.sheets) {
+            return;
+        }
+        workerInitSnapshotRef.current = nextSnapshot;
+        let cancelled = false;
+        workerReadyRef.current = false;
+        (async () => {
+            try {
+                const initialization = workerErrorPromiseRef.current
+                    ? Promise.race([
+                        workerClient.initialize(nextSnapshot),
+                        workerErrorPromiseRef.current,
+                    ])
+                    : workerClient.initialize(nextSnapshot);
+                await initialization;
+            }
+            catch (error) {
+                console.error("Failed to initialize calculation worker", error);
+                return;
+            }
+            if (cancelled) {
+                return;
+            }
+            workerReadyRef.current = true;
+            scheduleProcessing();
+        })();
+        return () => {
+            cancelled = true;
+            workerReadyRef.current = false;
+        };
+    }, [
+        enabled,
+        workerClient,
+        workerClientStub,
+        sheets,
+        locale,
+        tables,
+        namedRanges,
+        scheduleProcessing,
+    ]);
+    useEffect(() => {
+        if (workerClient === workerClientStub) {
+            return;
+        }
+        return () => {
+            workerErrorCleanupRef.current?.();
+            workerClient.dispose();
+        };
+    }, [workerClient, workerClientStub]);
+    useEffect(() => {
+        return () => {
+            if (resultFrameRef.current != null) {
+                cancelAnimationFrame(resultFrameRef.current);
+            }
+        };
+    }, []);
+    const prepareArrayOperation = useCallback((operation) => {
+        if (operation.type === "dirty") {
+            return;
+        }
+        const anchor = graph.getArrayParent(operation.position) ??
+            findCachedArrayAnchor(operation.position);
+        if (!anchor) {
+            return;
+        }
+        const anchorKey = makeKey(anchor);
+        const clearedRange = operation.type === "remove" &&
+            isEqualPosition(anchor, operation.position)
+            ? graph.getArrayRangeFor(anchor) ??
+                arrayRangeCacheRef.current.get(anchorKey)?.range
+            : undefined;
+        const isAnchorTarget = isEqualPosition(anchor, operation.position);
+        const preserve = new Set();
+        if (!isAnchorTarget) {
+            preserve.add(makeKey(operation.position));
+        }
+        const shouldNotifyDependents = !!isAnchorTarget;
+        clearArrayValues(anchor, {
+            preserveKeys: preserve,
+            includeAnchor: operation.type === "remove" && isAnchorTarget,
+            notifyDependents: shouldNotifyDependents,
+            forgetRange: operation.type === "remove" && isAnchorTarget,
+            preserveUserEntries: !isAnchorTarget,
+            preserveComputedValues: !isAnchorTarget && operation.type !== "remove",
+            deferDependents: !shouldNotifyDependents,
+            preserveRegistration: !isAnchorTarget,
+        });
+        if (clearedRange) {
+            for (const entry of arrayRangeCacheRef.current.values()) {
+                if (!rangesOverlap(entry.range, clearedRange)) {
+                    continue;
+                }
+                const key = makeKey(entry.anchor);
+                if (key === anchorKey) {
+                    continue;
+                }
+                collisionAnchorsRef.current.delete(key);
+                queueAnchorDirty(entry.anchor);
+            }
+        }
+    }, [clearArrayValues, findCachedArrayAnchor, graph, queueAnchorDirty]);
+    const enqueueCalculation = useCallbackRef((operation) => {
+        if (operation.type !== "dirty") {
+            const anchor = graph.getArrayParent(operation.position) ??
+                findCachedArrayAnchor(operation.position);
+            if (anchor) {
+                collisionAnchorsRef.current.delete(makeKey(anchor));
+            }
+        }
+        scheduleVolatileTracking(operation.position);
+        prepareArrayOperation(operation);
+        enqueuePendingOperation(operation);
+    });
+    const enqueueGraphOperation = useCallbackRef((operation) => {
+        graphOperationQueueRef.current.push(operation);
+        if (graphOperationFrameRef.current == null) {
+            graphOperationFrameRef.current =
+                requestAnimationFrame(flushGraphOperations);
+        }
+    });
+    const isArrayFormula = useCallbackRef((position) => {
+        return graph.isArrayFormula(position) || graph.isInArrayRange(position);
+    });
+    const getPrecedents = useCallback((source, includeSource) => {
+        return graph.getPrecedents(source).filter((node) => {
+            if (isStaticNode(node))
+                return true;
+            if (!includeSource && isCellNode(node) && isCellCoordinate(source)) {
+                return !isEqualPosition(node.position, source);
+            }
+            if (!includeSource &&
+                isCellRangeNode(node) &&
+                !isCellCoordinate(source)) {
+                return !isAreasEqual(node.position, source);
+            }
+            return true;
+        });
+    }, [graph]);
+    const getPrecedentsFromFormulaString = useCallback((value, source) => {
+        const dependencies = graph.getDependenciesFromFormula(value, source);
+        return dependencies.map((dependency) => {
+            if (dependency.kind === "cell") {
+                return new CellNode(makeKey(dependency.position), dependency.position);
+            }
+            return new CellRangeNode(makeKey(dependency.range), dependency.range);
+        });
+    }, [graph]);
+    const getDependents = useCallback((source, includeSource) => {
+        return graph.getDependents(source).filter((node) => {
+            if (isStaticNode(node)) {
+                return true;
+            }
+            if ((isCellNode(node) || isCellRangeNode(node)) &&
+                node.position &&
+                isCellCoordinate(node.position) &&
+                isArrayFormula(node.position)) {
+                return true;
+            }
+            if (includeSource &&
+                isCellRangeNode(node) &&
+                !isCellCoordinate(source)) {
+                return !isAreasEqual(node.position, source);
+            }
+            if (!includeSource && isCellCoordinate(source) && isCellNode(node)) {
+                const cellNode = node;
+                return (cellNode.position.rowIndex !== source.rowIndex ||
+                    cellNode.position.columnIndex !== source.columnIndex);
+            }
+            return true;
+        });
+    }, [graph, isArrayFormula]);
+    const deleteSheetReferences = useCallback((sheetId) => {
+        graph.deleteSheetReferences(sheetId);
+    }, [graph]);
+    const onRequestCalculate = useCallback(async (value, sheetId, rowIndex, columnIndex, options) => {
+        const disablePreview = options?.disablePreview ?? false;
+        if (!enabled || workerClient === workerClientStub) {
+            return undefined;
+        }
+        const skipOnDemand = options?.skipOnDemand ?? true;
+        if (skipOnDemand && onDemandPattern) {
+            onDemandPattern.lastIndex = 0;
+        }
+        if (skipOnDemand && isAFormula(value) && onDemandPattern?.test(value)) {
+            return undefined;
+        }
+        if (!isAFormula(value)) {
+            return null;
+        }
+        const formula = value.startsWith("=") ? value.slice(1) : value;
+        if (!formula) {
+            return null;
+        }
+        const position = { sheetId, rowIndex, columnIndex };
+        const dependencies = graph.getDependenciesFromFormula(formula, position);
+        if (iterativeCalculation?.enabled && !disablePreview) {
+            const isCircular = dependencies.some((dependency) => {
+                if (dependency.kind === "cell") {
+                    return (dependency.position.sheetId === sheetId &&
+                        dependency.position.rowIndex === rowIndex &&
+                        dependency.position.columnIndex === columnIndex);
+                }
+                const range = dependency.range;
+                return (range.sheetId === sheetId &&
+                    rowIndex >= range.startRowIndex &&
+                    rowIndex <= range.endRowIndex &&
+                    columnIndex >= range.startColumnIndex &&
+                    columnIndex <= range.endColumnIndex);
+            });
+            if (isCircular) {
+                return undefined;
+            }
+        }
+        const scope = graph.collectScope(dependencies);
+        if (options?.overrides?.size) {
+            for (const [key, value] of options.overrides) {
+                scope[key] = value;
+            }
+        }
+        const plan = {
+            id: `preview-${Date.now()}`,
+            nodes: [
+                {
+                    kind: "cell",
+                    key: `preview-node-${Date.now()}`,
+                    position,
+                    formula,
+                    precedents: dependencies,
+                    isPreview: !disablePreview,
+                },
+            ],
+        };
+        const [result] = await workerClient.evaluate(plan, () => scope);
+        const resultValue = deserializeResultValue(result.value);
+        if (resultValue instanceof FormulaError) {
+            return undefined;
+        }
+        return resultValue;
+    }, [
+        enabled,
+        graph,
+        workerClient,
+        workerClientStub,
+        deserializeResultValue,
+        iterativeCalculation,
+    ]);
+    const getGraphNodes = useCallback(() => {
+        return graph.getNodes();
+    }, [graph]);
+    const getGraphNodesInSheet = useCallback((sheetId) => graph.getNodesInSheet(sheetId), [graph]);
+    const addStaticReference = useCallback((source, sourcePosition) => {
+        graph.applyOperations([
+            {
+                kind: "static:add",
+                reference: source,
+                range: toCellRange(sourcePosition),
+            },
+        ]);
+    }, [graph]);
+    const addFormulaToGraph = useCallbackRef(useCallback((formulaValue, position) => {
+        if (!formulaValue) {
+            return;
+        }
+        const formula = formulaValue.startsWith("=")
+            ? formulaValue
+            : `=${formulaValue}`;
+        graph.applyOperations([{ kind: "upsert", position, formula }]);
+    }, [graph]));
+    const removeStaticReference = useCallback((source) => {
+        graph.applyOperations([
+            {
+                kind: "static:remove",
+                reference: source,
+            },
+        ]);
+    }, [graph]);
+    const onResetCalculator = useCallbackRef(() => {
+        isFullRecalcRef.current = true;
+        graph.reset();
+        computedValuesRef.current.clear();
+    });
+    const getDependencyGraph = useCallbackRef(() => graph.serialize());
+    const updateDependencyGraph = useCallbackRef((nodes) => graph.hydrate(nodes));
+    const enqueueStructureChange = useCallbackRef((_change) => { });
+    const clearRangeCache = useCallbackRef(() => { });
+    const noopCalculationApi = useMemo(() => ({
+        enqueueCalculation: () => { },
+        enqueueGraphOperation: () => { },
+        getPrecedents: () => [],
+        getPrecedentsFromFormulaString: () => [],
+        getDependents: () => [],
+        enqueueStructureChange: () => { },
+        clearRangeCache: () => { },
+        deleteSheetReferences: () => { },
+        onRequestCalculate: async () => undefined,
+        getGraphNodes: () => new Set(),
+        getGraphNodesInSheet: () => undefined,
+        addStaticReference: () => { },
+        addFormulaToGraph: () => { },
+        removeStaticReference: () => { },
+        onResetCalculator: () => { },
+        getDependencyGraph: () => "[]",
+        updateDependencyGraph: () => { },
+        isArrayFormula: () => false,
+        applyNamedRanges: (_list) => { },
+        stats$: statsSubjectRef.current.asObservable(),
+    }), []);
+    const api = {
+        enqueueCalculation,
+        enqueueGraphOperation,
+        getPrecedents,
+        getPrecedentsFromFormulaString,
+        getDependents,
+        enqueueStructureChange,
+        clearRangeCache,
+        deleteSheetReferences,
+        onRequestCalculate,
+        getGraphNodes,
+        getGraphNodesInSheet,
+        addStaticReference,
+        addFormulaToGraph,
+        removeStaticReference,
+        onResetCalculator,
+        getDependencyGraph,
+        updateDependencyGraph,
+        isArrayFormula,
+        // Worker re-inits on namedRanges change (sent via WorkerInit
+        // payload), so there's no host-side calculator to apply to.
+        // No-op to satisfy the shared API contract.
+        applyNamedRanges: (_list) => { },
+        stats$: statsSubjectRef.current.asObservable(),
+    };
+    return (enabled
+        ? api
+        : noopCalculationApi);
+};