@rowsncolumns/spreadsheet-state 28.0.66

package/dist/esm/interface/calculation-interface.js

@@ -0,0 +1,339 @@
+import { CalculationGraph, CalculationWorkerClient, createNamedRangeResolver, createStructuredReferenceResolver, enqueueCalculationOperations, mapOperationToGraphOperation, } from "@rowsncolumns/calculation-worker/server";
+import { FormulaError } from "@rowsncolumns/fast-formula-parser";
+const isSerializedFormulaError = (value) => {
+    return Boolean(value &&
+        typeof value === "object" &&
+        "type" in value &&
+        value.type === "FormulaError");
+};
+const deserializeWorkerValue = (value) => {
+    if (isSerializedFormulaError(value)) {
+        const details = typeof value.details === "string"
+            ? value.details
+            : value.details?.reason;
+        return new FormulaError(value.error, details);
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => Array.isArray(entry)
+            ? entry.map((child) => deserializeWorkerValue(child))
+            : deserializeWorkerValue(entry));
+    }
+    return value;
+};
+const normalizeMatrixValue = (value) => {
+    if (!Array.isArray(value)) {
+        return null;
+    }
+    if (!value.length) {
+        return [[undefined]];
+    }
+    if (Array.isArray(value[0])) {
+        return value;
+    }
+    return [value];
+};
+const expandWorkerResult = (result) => {
+    if (!result.position) {
+        return [];
+    }
+    const position = result.position;
+    const resolvedValue = deserializeWorkerValue(result.value);
+    const matrix = normalizeMatrixValue(resolvedValue);
+    if (!matrix) {
+        return [[position, resolvedValue]];
+    }
+    const entries = [];
+    for (let rowOffset = 0; rowOffset < matrix.length; rowOffset += 1) {
+        const row = matrix[rowOffset] ?? [];
+        for (let colOffset = 0; colOffset < row.length; colOffset += 1) {
+            entries.push([
+                {
+                    sheetId: position.sheetId,
+                    rowIndex: position.rowIndex + rowOffset,
+                    columnIndex: position.columnIndex + colOffset,
+                },
+                row[colOffset],
+            ]);
+        }
+    }
+    return entries;
+};
+export class CalculationInterface {
+    options;
+    graph;
+    workerClient;
+    operationQueue = [];
+    graphOperationQueue = [];
+    flushScheduled = false;
+    graphFlushScheduled = false;
+    metadataDirty = true;
+    lastMetadataSignature = "";
+    pendingFlush = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        const structuredReferenceResolver = createStructuredReferenceResolver({
+            getTables: () => options.getTables(),
+            getSheetName: (sheetId) => options.getSheetName(sheetId),
+            getSheetId: (sheetName) => sheetName ? options.getSheetId(sheetName) : undefined,
+        });
+        const namedRangeResolver = createNamedRangeResolver({
+            getNamedRanges: () => options.getNamedRanges(),
+            getSheetName: (sheetId) => options.getSheetName(sheetId),
+        });
+        this.graph = new CalculationGraph({
+            getSheetId: (sheetName) => options.getSheetId(sheetName),
+            getSheetName: (sheetId) => options.getSheetName(sheetId),
+            getFormula: (position) => options.getFinalUserEnteredValue(position),
+            getCellValue: (position, property) => {
+                const value = options.getEffectiveValue(position.sheetId, position.rowIndex, position.columnIndex, property);
+                if (property && options.getEffectiveStructuredValue) {
+                    return options.getEffectiveStructuredValue(value, property);
+                }
+                return value;
+            },
+            depParserConfig: {
+                onStructuredReference: structuredReferenceResolver,
+                onVariable: namedRangeResolver,
+            },
+            iterativeCalculation: options.iterativeCalculation,
+        });
+        const worker = this.ensureWorker(options.createWorker?.() ?? this.createDefaultWorker());
+        this.workerClient = new CalculationWorkerClient({
+            worker,
+            enableNumericMatrixTransfer: true,
+        });
+    }
+    enqueueCalculation = (operation) => {
+        this.operationQueue.push(operation);
+    };
+    enqueueGraphOperation = (operation) => {
+        this.graphOperationQueue.push(operation);
+    };
+    enqueueStructureChange = (_change) => {
+        // Worker calculation uses per-batch range caches, so no persistent
+        // calculator range cache needs explicit structural invalidation here.
+    };
+    getDependents(source) {
+        return this.graph.getDependents(source);
+    }
+    getPrecedents(source) {
+        return this.graph.getPrecedents(source);
+    }
+    getNodes() {
+        return this.graph.getNodes();
+    }
+    getNodesInSheet(sheetId) {
+        return this.graph.getNodesInSheet(sheetId);
+    }
+    markMetadataDirty = () => {
+        this.metadataDirty = true;
+    };
+    async flush() {
+        if (!this.operationQueue.length) {
+            return this.pendingFlush;
+        }
+        const operations = this.operationQueue;
+        this.operationQueue = [];
+        const run = async () => {
+            await this.executeOperations(operations);
+        };
+        this.pendingFlush = this.pendingFlush.then(run, run);
+        return this.pendingFlush;
+    }
+    async flushWithResults() {
+        if (!this.operationQueue.length) {
+            return [];
+        }
+        const operations = this.operationQueue;
+        this.operationQueue = [];
+        const run = async () => this.executeOperations(operations);
+        const pending = this.pendingFlush.then(run, run);
+        this.pendingFlush = pending.then(() => undefined, () => undefined);
+        return pending;
+    }
+    async calculate(operations) {
+        if (!operations.length) {
+            return [];
+        }
+        return this.executeOperations(operations);
+    }
+    rebuildGraph(operations) {
+        this.graph.reset();
+        const graphOperations = operations
+            .map((operation) => mapOperationToGraphOperation(operation, (op) => {
+            const value = this.options.getFinalUserEnteredValue(op.position);
+            return typeof value === "string" ? value : undefined;
+        }))
+            .filter((op) => Boolean(op));
+        if (!graphOperations.length) {
+            return;
+        }
+        this.graph.applyGraphOperations(graphOperations);
+    }
+    dispose() {
+        this.workerClient.dispose();
+    }
+    scheduleFlush() {
+        if (this.flushScheduled) {
+            return;
+        }
+        this.flushScheduled = true;
+        queueMicrotask(() => {
+            this.flushScheduled = false;
+            void this.flush();
+        });
+    }
+    scheduleGraphFlush() {
+        if (this.graphFlushScheduled) {
+            return;
+        }
+        this.graphFlushScheduled = true;
+        queueMicrotask(() => {
+            this.graphFlushScheduled = false;
+            if (!this.graphOperationQueue.length) {
+                return;
+            }
+            const operations = this.graphOperationQueue;
+            this.graphOperationQueue = [];
+            const graphOperations = operations
+                .map((operation) => mapOperationToGraphOperation(operation, (op) => {
+                const value = this.options.getFinalUserEnteredValue(op.position);
+                return typeof value === "string" ? value : undefined;
+            }, { markDirty: false }))
+                .filter((op) => Boolean(op));
+            if (!graphOperations.length) {
+                return;
+            }
+            this.graph.applyGraphOperations(graphOperations);
+        });
+    }
+    buildWorkerMetadata() {
+        return this.options.getSheets().map((sheet) => ({
+            id: sheet.sheetId,
+            name: sheet.title,
+        }));
+    }
+    buildMetadataSignature() {
+        const sheets = this.buildWorkerMetadata();
+        const tables = this.options.getTables();
+        const namedRanges = this.options.getNamedRanges();
+        return JSON.stringify({ sheets, tables, namedRanges });
+    }
+    async ensureWorkerMetadata() {
+        const signature = this.buildMetadataSignature();
+        if (!this.metadataDirty && signature === this.lastMetadataSignature) {
+            return;
+        }
+        this.metadataDirty = false;
+        this.lastMetadataSignature = signature;
+        await this.workerClient.initialize({
+            sheets: this.buildWorkerMetadata(),
+            tables: this.options.getTables(),
+            namedRanges: this.options.getNamedRanges(),
+            locale: this.options.locale,
+        });
+    }
+    isClientOnlyFormula(position) {
+        const value = this.options.getFinalUserEnteredValue(position);
+        if (typeof value !== "string") {
+            return false;
+        }
+        if (!value.trim().startsWith("=")) {
+            return false;
+        }
+        if (!this.options.clientOnlyFunctionPattern) {
+            return false;
+        }
+        return this.options.clientOnlyFunctionPattern.test(value);
+    }
+    async executeOperations(operations) {
+        await this.ensureWorkerMetadata();
+        const filteredOperations = operations;
+        if (!filteredOperations.length) {
+            return [];
+        }
+        const results = await enqueueCalculationOperations({
+            graph: this.graph,
+            workerClient: this.workerClient,
+            operations: filteredOperations,
+            resolveFormula: (operation) => {
+                const value = this.options.getFinalUserEnteredValue(operation.position);
+                return typeof value === "string" ? value : undefined;
+            },
+            onPlanBuilt: (plan) => {
+                if (!this.options.onBeginCalculation)
+                    return;
+                const dirtyCells = plan.nodes
+                    .filter((node) => node.kind === "cell")
+                    .map((node) => node.position);
+                this.options.onBeginCalculation(dirtyCells);
+            },
+            shouldSkipNode: (node) => this.isClientOnlyFormula(node.position),
+            normalizePropertyOverride: (value, property) => {
+                if (!this.options.getEffectiveStructuredValue) {
+                    return undefined;
+                }
+                return this.options.getEffectiveStructuredValue(value, property);
+            },
+        });
+        const expandedResults = results.flatMap((result) => expandWorkerResult(result));
+        if (expandedResults.length) {
+            this.options.onResults(expandedResults);
+        }
+        return expandedResults;
+    }
+    createDefaultWorker() {
+        if (typeof require !== "function") {
+            throw new Error("createCalculationWorker must be provided outside of Node.js.");
+        }
+        const requireFunc = require;
+        const { Worker } = requireFunc("node:worker_threads");
+        const workerPath = requireFunc.resolve("@rowsncolumns/calculation-worker/worker");
+        return new Worker(workerPath, { type: "module" });
+    }
+    ensureWorker(worker) {
+        if ("addEventListener" in worker) {
+            return worker;
+        }
+        const nodeWorker = worker;
+        const handlerMap = new Map();
+        const addEventListener = (type, listener) => {
+            const handlers = handlerMap.get(type) ?? new Map();
+            const handler = type === "message"
+                ? (data) => {
+                    if (typeof listener === "function") {
+                        listener({ data });
+                    }
+                    else {
+                        listener.handleEvent({ data });
+                    }
+                }
+                : (error) => {
+                    if (typeof listener === "function") {
+                        listener({ error });
+                    }
+                    else {
+                        listener.handleEvent({ error });
+                    }
+                };
+            handlers.set(listener, handler);
+            handlerMap.set(type, handlers);
+            nodeWorker.on(type, handler);
+        };
+        const removeEventListener = (type, listener) => {
+            const handlers = handlerMap.get(type);
+            const handler = handlers?.get(listener);
+            if (!handler) {
+                return;
+            }
+            nodeWorker.off(type, handler);
+            handlers?.delete(listener);
+            if (handlers && handlers.size === 0) {
+                handlerMap.delete(type);
+            }
+        };
+        nodeWorker.addEventListener = addEventListener;
+        nodeWorker.removeEventListener = removeEventListener;
+        return nodeWorker;
+    }
+}

package/dist/esm/interface/change-batch-stream.d.ts

@@ -0,0 +1,25 @@
+import type { CellInterface, GridRange } from "@rowsncolumns/common-types";
+import { type CellCoordinate } from "@rowsncolumns/dag";
+import type { CellData, ChangeBatchStreamOptions, ParsedToken, Sheet } from "@rowsncolumns/spreadsheet";
+import type { useCalculation } from "../hooks/use-calculation";
+import type { CellXfsRegistry } from "../hooks/use-cellxfs-registry";
+import type { UseOnChangeBatchProps } from "../hooks/use-on-change-batch";
+import type { ChangeBatchStreamInput } from "../types";
+export type ChangeBatchStreamAddFormulaToGraph = (formulaValue: string, position: CellCoordinate) => void;
+export type ChangeBatchStreamProps<T extends CellData, S extends Sheet = Sheet> = Pick<UseOnChangeBatchProps<T, S>, "onChangeSheetData" | "getEffectiveValuesFromRange" | "locale" | "getDataValidationById" | "enqueueCalculation"> & {
+    onChangeSheets?: UseOnChangeBatchProps<T, S>["onChangeSheets"];
+    getFormattedValue?: UseOnChangeBatchProps<T, S>["getFormattedValue"];
+    getCellDimensions?: UseOnChangeBatchProps<T, S>["getCellDimensions"];
+    getRowHeight?: UseOnChangeBatchProps<T, S>["getRowHeight"];
+    isMergedCell?: UseOnChangeBatchProps<T, S>["isMergedCell"];
+    onRequestCalculate?: ReturnType<typeof useCalculation>["onRequestCalculate"];
+    getPrecedentsFromFormulaString?: ReturnType<typeof useCalculation>["getPrecedentsFromFormulaString"];
+    getSheetId?: (sheetName: string) => number;
+    cellXfsRegistry?: CellXfsRegistry;
+    tokenizer?: (value: string) => ParsedToken[];
+    onStreamStart?: (streamId: string) => void;
+    onStreamProgress?: (streamId: string, sheetId: number, lastCellPosition: CellInterface | null) => void;
+    onStreamEnd?: (streamId: string) => void;
+};
+export declare const changeBatchStream: <T extends CellData, S extends Sheet = Sheet>({ locale, onChangeSheetData, onChangeSheets, getEffectiveValuesFromRange, getFormattedValue, getCellDimensions, getRowHeight, isMergedCell, getDataValidationById, onRequestCalculate, getPrecedentsFromFormulaString, getSheetId, cellXfsRegistry, tokenizer, onStreamStart, onStreamProgress, onStreamEnd, }: ChangeBatchStreamProps<T, S>) => (sheetId: number, range: GridRange, stream: ChangeBatchStreamInput, streamOptions?: ChangeBatchStreamOptions) => Promise<void>;
+//# sourceMappingURL=change-batch-stream.d.ts.map

package/dist/esm/interface/change-batch-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-batch-stream.d.ts","sourceRoot":"","sources":["../../../interface/change-batch-stream.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAAE,KAAK,cAAc,EAAW,MAAM,mBAAmB,CAAC;AACjE,OAAO,KAAK,EACV,QAAQ,EAER,wBAAwB,EAExB,WAAW,EACX,KAAK,EACN,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EAEV,cAAc,EACf,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAE1E,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,MAAM,MAAM,kCAAkC,GAAG,CAC/C,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,cAAc,KACrB,IAAI,CAAC;AAEV,MAAM,MAAM,sBAAsB,CAChC,CAAC,SAAS,QAAQ,EAClB,CAAC,SAAS,KAAK,GAAG,KAAK,IACrB,IAAI,CACN,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,EACzB,mBAAmB,GACnB,6BAA6B,GAC7B,QAAQ,GACR,uBAAuB,GACvB,oBAAoB,CACvB,GAAG;IACF,cAAc,CAAC,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,gBAAgB,CAAC,CAAC;IAC/D,iBAAiB,CAAC,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACrE,iBAAiB,CAAC,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC;IACrE,YAAY,CAAC,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IAC3D,YAAY,CAAC,EAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC;IAC3D,kBAAkB,CAAC,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC,oBAAoB,CAAC,CAAC;IAC7E,8BAA8B,CAAC,EAAE,UAAU,CACzC,OAAO,cAAc,CACtB,CAAC,gCAAgC,CAAC,CAAC;IACpC,UAAU,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,MAAM,CAAC;IAC3C,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,WAAW,EAAE,CAAC;IAC7C,aAAa,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,gBAAgB,CAAC,EAAE,CACjB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,aAAa,GAAG,IAAI,KACnC,IAAI,CAAC;IACV,WAAW,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1C,CAAC;AAyBF,eAAO,MAAM,iBAAiB,GAAI,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,KAAK,GAAG,KAAK,EAAE,gTAkB5E,sBAAsB,CAAC,CAAC,EAAE,CAAC,CAAC,MAE3B,SAAS,MAAM,EACf,OAAO,SAAS,EAChB,QAAQ,sBAAsB,EAC9B,gBAAgB,wBAAwB,kBA4W3C,CAAC"}

package/dist/esm/interface/change-batch-stream.js

@@ -0,0 +1,294 @@
+import { makeKey } from "@rowsncolumns/dag";
+import { isNil } from "@rowsncolumns/utils";
+import { produce } from "immer";
+import { createSheetDraft } from "../api/immer-utils";
+import { SheetCell } from "../sheet-cell";
+const normalizeFormula = (value) => {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return null;
+    }
+    const formulaInput = trimmed.startsWith("=") ? trimmed : `=${trimmed}`;
+    const formulaValue = formulaInput.slice(1);
+    return { formulaInput, formulaValue };
+};
+const hasStreamValue = (cellInput) => !isNil(cellInput?.formula) && cellInput?.formula !== ""
+    ? true
+    : !isNil(cellInput?.value) && cellInput?.value !== ""
+        ? true
+        : !isNil(cellInput?.cell_styles);
+export const changeBatchStream = ({ locale, onChangeSheetData, onChangeSheets, getEffectiveValuesFromRange, getFormattedValue, getCellDimensions, getRowHeight, isMergedCell, getDataValidationById, onRequestCalculate, getPrecedentsFromFormulaString, getSheetId, cellXfsRegistry, tokenizer, onStreamStart, onStreamProgress, onStreamEnd, }) => {
+    return async (sheetId, range, stream, streamOptions) => {
+        const streamId = `stream_${Date.now()}_${Math.random()
+            .toString(36)
+            .substring(2, 9)}`;
+        onStreamStart?.(streamId);
+        const sheetCell = new SheetCell();
+        const rowCursorByIndex = new Map();
+        const overrides = new Map();
+        const disableDeltaUpdates = streamOptions?.disableDelta ?? true;
+        const disableEvaluation = streamOptions?.disableEvaluation;
+        const skipInvalidValues = streamOptions?.skipInvalidValues ?? false;
+        const preserveExistingValues = streamOptions?.preserveExistingValues ?? false;
+        const shouldUpdateRowHeights = streamOptions?.shouldUpdateRowHeights ?? true;
+        try {
+            for await (const rows of stream) {
+                if (!Array.isArray(rows) || !rows.length) {
+                    continue;
+                }
+                const formulaCells = [];
+                const rowStyleUpdates = new Map();
+                const cellUpdates = [];
+                let lastCellPosition = null;
+                for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+                    const row = rows[rowIndex];
+                    if (!row) {
+                        continue;
+                    }
+                    const absoluteRowIndex = range.startRowIndex + rowIndex;
+                    if (absoluteRowIndex > range.endRowIndex) {
+                        continue;
+                    }
+                    const startColumnIndex = disableDeltaUpdates
+                        ? 0
+                        : rowCursorByIndex.get(rowIndex) ?? 0;
+                    let lastNonEmptyIndex = -1;
+                    for (let columnIndex = startColumnIndex; columnIndex < row.length; columnIndex++) {
+                        if (absoluteRowIndex > range.endRowIndex) {
+                            continue;
+                        }
+                        const absoluteColumnIndex = range.startColumnIndex + columnIndex;
+                        if (absoluteColumnIndex > range.endColumnIndex) {
+                            continue;
+                        }
+                        const cellInput = row[columnIndex];
+                        const position = {
+                            sheetId,
+                            rowIndex: absoluteRowIndex,
+                            columnIndex: absoluteColumnIndex,
+                        };
+                        const formula = cellInput?.formula;
+                        if (disableEvaluation && !isNil(formula) && formula !== "") {
+                            continue;
+                        }
+                        if (hasStreamValue(cellInput)) {
+                            lastNonEmptyIndex = Math.max(lastNonEmptyIndex, columnIndex);
+                            lastCellPosition = {
+                                rowIndex: position.rowIndex,
+                                columnIndex: position.columnIndex,
+                            };
+                            onStreamProgress?.(streamId, sheetId, lastCellPosition);
+                        }
+                        cellUpdates.push({ position, cellInput });
+                        if (!disableEvaluation && !isNil(formula) && formula !== "") {
+                            const normalizedFormula = normalizeFormula(String(formula));
+                            if (normalizedFormula) {
+                                formulaCells.push({
+                                    position,
+                                    formulaInput: normalizedFormula.formulaInput,
+                                    formulaValue: normalizedFormula.formulaValue,
+                                });
+                            }
+                        }
+                    }
+                    if (!disableDeltaUpdates && lastNonEmptyIndex >= startColumnIndex) {
+                        rowCursorByIndex.set(rowIndex, lastNonEmptyIndex + 1);
+                    }
+                }
+                // Abortd
+                if (streamOptions?.isAborted?.()) {
+                    return;
+                }
+                const calculationResults = new Map();
+                if (!disableEvaluation && formulaCells.length && onRequestCalculate) {
+                    for (const { position, cellInput } of cellUpdates) {
+                        if (!cellInput) {
+                            continue;
+                        }
+                        // Only store effective value
+                        const overrideValue = cellInput.value;
+                        if (!isNil(overrideValue)) {
+                            overrides.set(makeKey(position), overrideValue);
+                        }
+                    }
+                    for (const cell of formulaCells) {
+                        try {
+                            const result = await onRequestCalculate(cell.formulaInput, sheetId, cell.position.rowIndex, cell.position.columnIndex, {
+                                overrides,
+                                isArray: false,
+                                disablePreview: true,
+                                skipOnDemand: true,
+                            });
+                            // Set overrides for subsequent calculation calls
+                            // that require this cell result works
+                            overrides.set(makeKey(cell.position), result);
+                            if (isNil(result) || Array.isArray(result)) {
+                                continue;
+                            }
+                            calculationResults.set(makeKey(cell.position), result);
+                        }
+                        catch (err) { }
+                    }
+                }
+                // Abortd
+                if (streamOptions?.isAborted?.()) {
+                    return;
+                }
+                onChangeSheetData?.((prevSheetData) => {
+                    const nextState = produce(prevSheetData, (draft) => {
+                        for (const { position, cellInput } of cellUpdates) {
+                            const currentSheet = createSheetDraft(draft, sheetId, position.rowIndex);
+                            const cellData = currentSheet[position.rowIndex].values?.[position.columnIndex];
+                            sheetCell.assign(sheetId, position, cellData, {
+                                getRangeValues: getEffectiveValuesFromRange,
+                                locale,
+                                cellXfsRegistry,
+                                getDataValidationById,
+                            });
+                            const formula = cellInput?.formula;
+                            const cellStyles = cellInput?.cell_styles;
+                            let normalizedFormula = null;
+                            // Formulae
+                            if (!disableEvaluation && !isNil(formula) && formula !== "") {
+                                normalizedFormula = normalizeFormula(String(formula));
+                                if (normalizedFormula) {
+                                    sheetCell.setUserEnteredValue(normalizedFormula.formulaInput);
+                                }
+                                else {
+                                    sheetCell.deleteContents();
+                                }
+                            }
+                            else if (!isNil(cellInput?.value) &&
+                                !(preserveExistingValues && cellInput.value === "")) {
+                                sheetCell.setUserEnteredValue(cellInput.value);
+                                // A streamed write has no dialog to confirm through: a value
+                                // failing a blocking rule is dropped silently and the cell
+                                // keeps its previous content, mirroring the agent-write
+                                // guard. Warning/information rules write through flagged,
+                                // like a user clicking past the prompt.
+                                if (skipInvalidValues && sheetCell.failsBlockingValidation) {
+                                    continue;
+                                }
+                            }
+                            else if (cellStyles) {
+                                // Preserve existing value when only styles are provided.
+                            }
+                            else if (preserveExistingValues) {
+                                // An empty/absent cell input in the stream leaves the
+                                // existing cell untouched instead of clearing it. Cumulative
+                                // AI feeds (magic fill, tool-UI previews) re-send the whole
+                                // range every chunk with holes for cells they never fill —
+                                // without this, pre-filled cells (dropdown defaults) get
+                                // wiped by the first partial chunk.
+                                continue;
+                            }
+                            else {
+                                sheetCell.deleteContents();
+                            }
+                            if (cellStyles) {
+                                for (const key in cellStyles) {
+                                    sheetCell.setUserEnteredFormat(key, cellStyles[key]);
+                                }
+                            }
+                            const isCalculatedValue = calculationResults.has(makeKey(position));
+                            if (isCalculatedValue) {
+                                const calculatedValue = calculationResults.get(makeKey(position));
+                                const preserveStringLiteral = typeof calculatedValue === "string";
+                                sheetCell.setEffectiveValue(calculatedValue, false, preserveStringLiteral);
+                                // Effective number format is derived at render time via
+                                // `useSheetProperties.getEffectiveFormat`, so we no longer
+                                // walk precedents and persist the result here.
+                            }
+                            // Disable cellXfs and shared strings
+                            currentSheet[position.rowIndex].values[position.columnIndex] =
+                                sheetCell.getCellData({ disableRegistry: true });
+                            if (cellStyles) {
+                                cellXfsRegistry?.registerCellXfs(sheetCell);
+                                if (shouldUpdateRowHeights &&
+                                    (cellStyles.textFormat || cellStyles.wrapStrategy)) {
+                                    const rowUpdates = rowStyleUpdates.get(position.rowIndex) ?? [];
+                                    rowUpdates.push({
+                                        columnIndex: position.columnIndex,
+                                        cellStyles,
+                                        overrideValue: cellInput?.value,
+                                    });
+                                    rowStyleUpdates.set(position.rowIndex, rowUpdates);
+                                }
+                            }
+                        }
+                    });
+                    return nextState;
+                });
+                if (shouldUpdateRowHeights &&
+                    rowStyleUpdates.size > 0 &&
+                    onChangeSheets &&
+                    getRowHeight &&
+                    getCellDimensions) {
+                    onChangeSheets((prevSheets) => {
+                        return produce(prevSheets, (draft) => {
+                            const sheet = draft.find((sheet) => sheet.sheetId === sheetId);
+                            if (!sheet) {
+                                return;
+                            }
+                            for (const [rowIndex, updates] of rowStyleUpdates.entries()) {
+                                const isResizedByUser = !!sheet.rowMetadata?.[rowIndex]?.resizedByUser;
+                                if (isResizedByUser) {
+                                    continue;
+                                }
+                                const columnsToCheck = new Set(updates.map((update) => update.columnIndex));
+                                const currentRowHeight = getRowHeight(sheetId, rowIndex, (index) => columnsToCheck.has(index));
+                                if (isNil(currentRowHeight)) {
+                                    continue;
+                                }
+                                let maxRowHeight = currentRowHeight ?? 0;
+                                let didUpdateRowHeight = false;
+                                for (const update of updates) {
+                                    const cellStyles = update.cellStyles;
+                                    if (!cellStyles ||
+                                        (!cellStyles.textFormat && !cellStyles.wrapStrategy)) {
+                                        continue;
+                                    }
+                                    if (isMergedCell?.(sheetId, rowIndex, update.columnIndex) ===
+                                        true) {
+                                        continue;
+                                    }
+                                    const formattedValue = !isNil(update.overrideValue) && update.overrideValue !== ""
+                                        ? String(update.overrideValue)
+                                        : getFormattedValue?.(sheetId, rowIndex, update.columnIndex);
+                                    const shouldWrap = cellStyles.wrapStrategy
+                                        ? cellStyles.wrapStrategy === "wrap"
+                                        : undefined;
+                                    const fontSize = cellStyles.textFormat?.fontSize;
+                                    const newCellDimension = getCellDimensions(sheetId, rowIndex, update.columnIndex, "x", {
+                                        textOverride: formattedValue ?? undefined,
+                                        textFormatOverride: fontSize ? { fontSize } : undefined,
+                                        shouldWrapOverride: shouldWrap,
+                                    });
+                                    if (!isNil(newCellDimension)) {
+                                        maxRowHeight = Math.max(maxRowHeight, newCellDimension?.height ?? 0);
+                                        didUpdateRowHeight = true;
+                                    }
+                                }
+                                if (didUpdateRowHeight && maxRowHeight > 0) {
+                                    if (!sheet.rowMetadata) {
+                                        sheet.rowMetadata = [];
+                                    }
+                                    if (!sheet.rowMetadata[rowIndex] ||
+                                        typeof sheet.rowMetadata[rowIndex] !== "object") {
+                                        sheet.rowMetadata[rowIndex] = {};
+                                    }
+                                    sheet.rowMetadata[rowIndex].size = maxRowHeight;
+                                }
+                            }
+                        });
+                    });
+                }
+                // Save cellXfs
+                cellXfsRegistry?.getPatches();
+            }
+        }
+        finally {
+            onStreamEnd?.(streamId);
+        }
+    };
+};