@rowsncolumns/y-spreadsheet 14.0.32

package/dist/esm/helpers.js

@@ -0,0 +1,1346 @@
+import { cellToAddress, getCellEffectiveValue, getCellUserEnteredValue, getExtendedValueBool, getExtendedValueError, getExtendedValueFormula, getExtendedValueNumber, getExtendedValueString, } from "@rowsncolumns/utils";
+import * as Y from "yjs";
+import cloneDeep from "lodash/cloneDeep";
+import isEqual from "lodash/isEqual";
+import set from "lodash/set";
+import get from "lodash/get";
+import unset from "lodash/unset";
+/**
+ * Apply patches to yjs
+ * @param doc
+ * @param userId
+ * @param patches
+ * @param source
+ * @param sheetDataVersion - Version of sheet data format ("v2" or "v3"). Falls back to docMeta if undefined.
+ */
+export const applyPatchesToYDoc = (doc, userId, patches, source, sheetDataVersion) => {
+    const ySheetDataV2 = doc.getMap("sheetDataV2");
+    const ySheetDataV3 = doc.getMap("sheetDataV3");
+    const yDocMeta = doc.getMap("docMeta");
+    const yRecalcCells = doc.getArray("recalcCells");
+    const ySheets = doc.getArray("sheets");
+    const yTables = doc.getArray("tables");
+    const yEmbeds = doc.getArray("embeds");
+    const yCharts = doc.getArray("charts");
+    const yConditionalFormats = doc.getArray("conditionalFormats");
+    const yDataValidations = doc.getArray("dataValidations");
+    const yNamedRanges = doc.getArray("namedRanges");
+    const ySharedStringsMap = doc.getMap("sharedStringsMap");
+    const yProtectedRanges = doc.getArray("protectedRanges");
+    const yCellXfs = doc.getMap("cellXfs");
+    const yDisableRecalc = doc.getMap("disableRecalc");
+    // Check version flag to determine which sheet data format to use
+    // Use param if provided, otherwise fall back to docMeta for backwards compatibility
+    const resolvedVersion = sheetDataVersion ?? yDocMeta.get("sheetDataVersion");
+    const isV3 = resolvedVersion === "v3";
+    for (let [patch, type = "redo"] of patches) {
+        type = type ?? "redo";
+        const patchKey = type === "redo" ? "patches" : "inversePatches";
+        if (patch.sheetData) {
+            const patches = patch.sheetData?.[patchKey];
+            if (isV3) {
+                addSheetDataPatchesV3(ySheetDataV3, patches);
+            }
+            else {
+                addSheetDataPatches(ySheetDataV2, patches);
+            }
+        }
+        if (patch.sheets) {
+            const patches = patch.sheets[patchKey];
+            updateArrayType(ySheets, patches);
+        }
+        if (patch.tables) {
+            const patches = patch.tables[patchKey];
+            updateArrayType(yTables, patches);
+        }
+        if (patch.embeds) {
+            const patches = patch.embeds[patchKey];
+            updateArrayType(yEmbeds, patches);
+        }
+        if (patch.charts) {
+            const patches = patch.charts[patchKey];
+            updateArrayType(yCharts, patches);
+        }
+        if (patch.conditionalFormats) {
+            const patches = patch.conditionalFormats[patchKey];
+            updateArrayType(yConditionalFormats, patches);
+        }
+        if (patch.dataValidations) {
+            const patches = patch.dataValidations[patchKey];
+            updateArrayType(yDataValidations, patches);
+        }
+        if (patch.namedRanges) {
+            const patches = patch.namedRanges[patchKey];
+            updateArrayType(yNamedRanges, patches);
+        }
+        if (patch.sharedStrings) {
+            const patches = patch.sharedStrings[patchKey];
+            // Always use Map for shared strings
+            applyMapPatches(ySharedStringsMap, patches);
+        }
+        if (patch.protectedRanges) {
+            const patches = patch.protectedRanges[patchKey];
+            updateArrayType(yProtectedRanges, patches);
+        }
+        if (patch.cellXfs) {
+            const patches = patch.cellXfs[patchKey];
+            applyMapPatches(yCellXfs, patches);
+        }
+        // Recalc cells
+        if (patch.recalcCells?.[type]) {
+            // Removing this
+            // multiple calls to update_sheet_range deletes recalc cells
+            // yRecalcCells.delete(0, yRecalcCells.length);
+            yRecalcCells.push([
+                {
+                    userId,
+                    patches: Array.from(patch.recalcCells[type]).map((value) => {
+                        return [...value, source ?? "agent"];
+                    }),
+                },
+            ]);
+        }
+    }
+    // Set disable recalc flag (only if it's currently truthy, to avoid redundant Y.Map writes)
+    if (yDisableRecalc.get("disableRecalc") !== false) {
+        yDisableRecalc.set("disableRecalc", false);
+    }
+};
+/**
+ * Add sheet data to a yjs map using immer patches
+ *
+ * Optimized for bulk operations (paste, import) by consolidating cell-level
+ * patches before applying to Y.js. This reduces overhead by:
+ * 1. Deduplicating patches targeting the same cell (later patches win)
+ * 2. Grouping updates by sheet/row for efficient batch application
+ */
+export const addSheetDataPatches = (ySheetData, patches) => {
+    // Optimization: Pre-process and consolidate cell-level patches
+    // For bulk operations like paste (10k+ rows), this dramatically reduces overhead
+    // Key format: "sheetId:rowIndex:columnIndex"
+    const cellUpdates = new Map();
+    const otherPatches = [];
+    // First pass: categorize and consolidate patches
+    for (const patch of patches) {
+        const { op, path, value } = patch;
+        const [sheetIdRaw] = path;
+        // Handle undefined sheetId separately (full replace)
+        if (typeof sheetIdRaw === "undefined") {
+            otherPatches.push(patch);
+            continue;
+        }
+        // Use string representation for sheet ID to handle both string and numeric IDs
+        const sheetIdStr = String(sheetIdRaw);
+        if (op === "replace" || op === "add") {
+            // [sheetId, rowIndex, 'values', columnIndex] - Single cell update (most common in paste)
+            if (path.length === 4) {
+                const [, rowIndex, , columnIndex] = path;
+                const rowIdx = Number(rowIndex);
+                const colIdx = Number(columnIndex);
+                const key = `${sheetIdStr}:${rowIdx}:${colIdx}`;
+                // Later patches override earlier ones for the same cell
+                cellUpdates.set(key, { sheetIdStr, rowIdx, colIdx, value });
+            }
+            else {
+                // Row-level or sheet-level updates
+                otherPatches.push(patch);
+            }
+        }
+        else if (op === "remove") {
+            if (path.length === 4) {
+                const [, rowIndex, , columnIndex] = path;
+                const rowIdx = Number(rowIndex);
+                const colIdx = Number(columnIndex);
+                const key = `${sheetIdStr}:${rowIdx}:${colIdx}`;
+                cellUpdates.set(key, { sheetIdStr, rowIdx, colIdx, value: null });
+            }
+            else {
+                otherPatches.push(patch);
+            }
+        }
+        else {
+            otherPatches.push(patch);
+        }
+    }
+    // Second pass: Group cell updates by sheet and row for efficient batch application
+    // This minimizes Y.js operations by batching updates to the same row
+    const sheetRowUpdates = new Map();
+    for (const [, { sheetIdStr, rowIdx, colIdx, value }] of cellUpdates) {
+        if (!sheetRowUpdates.has(sheetIdStr)) {
+            sheetRowUpdates.set(sheetIdStr, new Map());
+        }
+        const rowUpdates = sheetRowUpdates.get(sheetIdStr);
+        if (!rowUpdates.has(rowIdx)) {
+            rowUpdates.set(rowIdx, new Map());
+        }
+        rowUpdates.get(rowIdx).set(colIdx, value);
+    }
+    // Apply batched cell updates
+    for (const [sheetIdStr, rowUpdates] of sheetRowUpdates) {
+        const ysheet = getSheetFromYSheetData(ySheetData, sheetIdStr);
+        for (const [rowIdx, colUpdates] of rowUpdates) {
+            const rowData = getRowDataFromSheet(ysheet, rowIdx);
+            for (const [colIdx, value] of colUpdates) {
+                setCellDataInRowData(rowData, colIdx, value);
+            }
+        }
+    }
+    // Process non-cell-level patches using original logic
+    const processPatch = ({ op, path, value }) => {
+        let [sheetId] = path;
+        if (typeof sheetId === "undefined") {
+            // Replace. User is replacing the entire data
+            if (op === "replace") {
+                // Remove all sheet data
+                ySheetData.clear();
+            }
+            // Assign values
+            for (const curSheetId in value) {
+                let sheetId = Number(curSheetId);
+                processPatch({
+                    op: "replace",
+                    path: [sheetId],
+                    value: value[curSheetId],
+                });
+            }
+            return;
+        }
+        if (op === "replace" || op === "add") {
+            const ysheet = getSheetFromYSheetData(ySheetData, sheetId);
+            // Cell-level patches (path.length === 4) are already handled above via consolidation
+            // [sheetId, rowIndex, 'values'] - Replace values array directly
+            if (path.length === 3 && path[2] === "values") {
+                const [, rowIndex] = path;
+                const rowData = getRowDataFromSheet(ysheet, rowIndex);
+                // Clear existing row data
+                rowData.delete(0, rowData.length);
+                if (Array.isArray(value)) {
+                    // Value is the values array directly
+                    // Sort keys to maintain order during insertion
+                    Object.entries(value)
+                        .sort(([a], [b]) => Number(a) - Number(b))
+                        .forEach(([columnIndex, cellData]) => {
+                        setCellDataInRowData(rowData, Number(columnIndex), cellData);
+                    });
+                }
+            }
+            // [sheetId, rowIndex] - Entire row update
+            else if (path.length === 2) {
+                const [, rowIndex] = path;
+                if (value?.values) {
+                    // Replace entire row with new values
+                    const rowData = getRowDataFromSheet(ysheet, rowIndex);
+                    // Clear existing row data
+                    rowData.delete(0, rowData.length);
+                    // Add new cell values
+                    // Sort keys to maintain order during insertion
+                    Object.entries(value.values)
+                        .sort(([a], [b]) => Number(a) - Number(b))
+                        .forEach(([columnIndex, cellData]) => {
+                        setCellDataInRowData(rowData, Number(columnIndex), cellData);
+                    });
+                }
+                else {
+                    // Remove row if value is null/undefined
+                    removeRowData(ysheet, rowIndex);
+                }
+            }
+            // [sheetId] - Entire sheet update
+            else if (path.length === 1) {
+                if (value) {
+                    // Clear entire sheet
+                    ysheet.delete(0, ysheet.length);
+                    // Add all new data
+                    Object.entries(value)
+                        .sort(([a], [b]) => Number(a) - Number(b))
+                        .forEach(([rowIndex, rowData]) => {
+                        if (rowData?.values) {
+                            const rowDataArray = getRowDataFromSheet(ysheet, Number(rowIndex));
+                            Object.entries(rowData.values)
+                                .sort(([a], [b]) => Number(a) - Number(b))
+                                .forEach(([columnIndex, cellData]) => {
+                                setCellDataInRowData(rowDataArray, Number(columnIndex), cellData);
+                            });
+                        }
+                    });
+                }
+            }
+        }
+        else if (op === "remove") {
+            // Cell-level removes (path.length === 4) are already handled above via consolidation
+            // [sheetId, rowIndex] - Remove entire row
+            if (path.length === 2) {
+                const [, rowIndex] = path;
+                const ysheet = getSheetFromYSheetData(ySheetData, sheetId);
+                removeRowData(ysheet, rowIndex);
+            }
+            // [sheetId] - Remove entire sheet
+            else if (path.length === 1) {
+                deleteSheetFromYSheetData(ySheetData, sheetId);
+            }
+        }
+    };
+    // Only process non-cell-level patches (cell-level already handled via consolidation)
+    otherPatches.forEach(processPatch);
+};
+export const getSheetFromYSheetData = (ySheetData, sheetId) => {
+    const id = String(sheetId);
+    let sheet = ySheetData.get(id);
+    if (!sheet) {
+        sheet = new Y.Array();
+        ySheetData.set(id, sheet);
+    }
+    return sheet;
+};
+export const deleteSheetFromYSheetData = (ySheetData, sheetId) => {
+    const id = String(sheetId);
+    ySheetData.delete(id);
+};
+export const getRowDataFromSheet = (ysheet, rowIndex) => {
+    const index = Number(rowIndex);
+    if (index < 0) {
+        throw new Error("Row index cannot be negative");
+    }
+    // Extend array if needed
+    if (index >= ysheet.length) {
+        const padding = new Array(index - ysheet.length).fill(null);
+        ysheet.insert(ysheet.length, padding);
+        ysheet.insert(index, [null]); // Insert null first
+        // Create new row data
+        const newRowData = new Y.Map();
+        newRowData.set("values", new Y.Array());
+        // Replace the null
+        ysheet.insert(index, [newRowData]);
+        ysheet.delete(index + 1, 1);
+        // Delete the initially inserted null (wait, index shifts)
+        // index is target.
+        // Insert padding up to index. length = index.
+        // Insert null at index. length = index+1.
+        // Replace null at index.
+        // Insert newRowData at index. length = index+2.
+        // Delete at index+1. length = index+1.
+        // Correct.
+        return newRowData.get("values");
+    }
+    // Get or create existing row data
+    let rowData = ysheet.get(index);
+    if (!rowData || !rowData.get("values")) {
+        // Create new row data if it doesn't exist or is incomplete
+        const newRowData = new Y.Map();
+        newRowData.set("values", new Y.Array());
+        // Replace the existing item
+        ysheet.insert(index, [newRowData]);
+        ysheet.delete(index + 1, 1);
+        return newRowData.get("values");
+    }
+    return rowData.get("values");
+};
+export const setCellDataInRowData = (rowData, columnIndex, cellData = null) => {
+    const index = Number(columnIndex);
+    // Extend array if needed
+    if (index >= rowData.length) {
+        const padding = new Array(index - rowData.length).fill(null);
+        if (padding.length > 0) {
+            rowData.insert(rowData.length, padding);
+        }
+    }
+    if (index === rowData.length) {
+        rowData.insert(index, [cellData]);
+    }
+    else {
+        // Replace cell data
+        rowData.insert(index, [cellData]);
+        rowData.delete(index + 1, 1);
+    }
+};
+export const removeRowData = (ysheet, rowIndex) => {
+    const index = Number(rowIndex);
+    // Only remove if index is valid
+    if (index >= 0 && index < ysheet.length) {
+        ysheet.insert(index, [null]);
+        ysheet.delete(index + 1, 1);
+    }
+};
+/**
+ * Read a cell's data from the V2 Y.js structure without creating any
+ * missing sheet/row/values containers (unlike getSheetFromYSheetData /
+ * getRowDataFromSheet, which lazily create them).
+ */
+export const getCellDataFromYSheetData = (ySheetData, sheetId, rowIndex, columnIndex) => {
+    const sheet = ySheetData.get(String(sheetId));
+    const rowIdx = Number(rowIndex);
+    if (!sheet || rowIdx < 0 || rowIdx >= sheet.length) {
+        return undefined;
+    }
+    const row = sheet.get(rowIdx);
+    const values = row?.get("values");
+    const colIdx = Number(columnIndex);
+    if (!values || colIdx < 0 || colIdx >= values.length) {
+        return undefined;
+    }
+    return values.get(colIdx);
+};
+/**
+ * Extract the error effective value from cell data, if any.
+ * SheetCell.setErrorValue persists formula errors as
+ * `ev.ev = { type: "Error", name, message }` (legacy long form:
+ * `effectiveValue.errorValue`).
+ */
+export const getCellDataErrorValue = (cellData) => {
+    return getExtendedValueError(getCellEffectiveValue(cellData));
+};
+/**
+ * Keep only the cell-level sheetData patches
+ * (`[sheetId, rowIndex, "values", columnIndex]`) whose new cell data carries
+ * an error effective value (#VALUE!, #NAME?, …). Used to let calc-result
+ * errors bypass the leader gate: errors must reach the Y.Doc even from
+ * non-leader clients, otherwise they render blank after reload.
+ */
+export const filterErrorCellPatches = (patches) => {
+    return patches.filter((patch) => (patch.op === "add" || patch.op === "replace") &&
+        patch.path.length === 4 &&
+        patch.path[2] === "values" &&
+        Boolean(getCellDataErrorValue(patch.value)));
+};
+/**
+ * Normalize an extended value (short or legacy long keys) into the short-key
+ * shape so semantically identical values compare equal regardless of which
+ * key shape produced them.
+ */
+const normalizeExtendedValue = (extValue) => {
+    if (extValue === null || extValue === undefined) {
+        return undefined;
+    }
+    const normalized = {};
+    const numberValue = getExtendedValueNumber(extValue);
+    if (numberValue !== undefined) {
+        normalized.nv = numberValue;
+    }
+    const stringValue = getExtendedValueString(extValue);
+    if (stringValue !== undefined) {
+        normalized.sv = stringValue;
+    }
+    const boolValue = getExtendedValueBool(extValue);
+    if (boolValue !== undefined) {
+        normalized.bv = boolValue;
+    }
+    const formulaValue = getExtendedValueFormula(extValue);
+    if (formulaValue !== undefined) {
+        normalized.fv = formulaValue;
+    }
+    const errorValue = getExtendedValueError(extValue);
+    if (errorValue !== undefined) {
+        normalized.ev = errorValue;
+    }
+    return normalized;
+};
+/**
+ * Containment guard for the non-leader error-persistence path
+ * (use-yspreadsheet-v2 onBroadcastPatch, gated disableRecalc branch).
+ * A gated error cell patch may be written ONLY when all of these hold:
+ *
+ * 1. The incoming cell data carries an error effective value.
+ * 2. The current doc cell holds no effective value at all (the
+ *    blank-after-reload case) or its effective value is itself an error.
+ *    A non-error result (number/string/bool/formula result) is never
+ *    overwritten — a stale non-leader error must not clobber a newer
+ *    leader-written success.
+ * 3. If the doc cell exists, its user-entered value (`ue`, short or legacy
+ *    key shape) matches the incoming patch's — a cell edited after the
+ *    calculation started is never touched.
+ * 4. The persisted error differs from the incoming one (identical errors
+ *    are dropped so concurrent non-leaders don't append redundant
+ *    Y.js updates).
+ */
+export const shouldPersistErrorCellPatch = (currentCellData, incomingCellData) => {
+    const incomingError = getCellDataErrorValue(incomingCellData);
+    if (!incomingError) {
+        return false;
+    }
+    const currentEffectiveValue = getCellEffectiveValue(currentCellData);
+    const currentError = getExtendedValueError(currentEffectiveValue);
+    if (currentEffectiveValue !== null &&
+        currentEffectiveValue !== undefined &&
+        !currentError) {
+        return false;
+    }
+    if (currentCellData !== null && currentCellData !== undefined) {
+        const currentUserEnteredValue = normalizeExtendedValue(getCellUserEnteredValue(currentCellData));
+        const incomingUserEnteredValue = normalizeExtendedValue(getCellUserEnteredValue(incomingCellData));
+        if (!isEqual(currentUserEnteredValue, incomingUserEnteredValue)) {
+            return false;
+        }
+    }
+    return !isEqual(currentError, incomingError);
+};
+/**
+ * Build the cell data to write for a gated error patch that passed
+ * shouldPersistErrorCellPatch. If the doc cell doesn't exist yet there is
+ * nothing to destroy and the incoming cell data is written as-is. If it
+ * does exist, ONLY the error effective value is merged in — every other
+ * field of the doc cell (ue, formats, notes, …) is preserved so this write
+ * path can never remove doc state it didn't produce. The effective value is
+ * written into whichever key shape(s) the doc cell already uses (short `ev`
+ * by default).
+ */
+export const mergeErrorEffectiveValueIntoCellData = (currentCellData, incomingCellData) => {
+    if (currentCellData === null || currentCellData === undefined) {
+        return incomingCellData;
+    }
+    const incomingEffectiveValue = getCellEffectiveValue(incomingCellData);
+    const merged = { ...currentCellData };
+    const hasLegacyKey = "effectiveValue" in merged;
+    if (hasLegacyKey) {
+        merged.effectiveValue = incomingEffectiveValue;
+    }
+    if ("ev" in merged || !hasLegacyKey) {
+        merged.ev = incomingEffectiveValue;
+    }
+    return merged;
+};
+/**
+ * Update array type with immer patches
+ */
+export const updateArrayType = (yarray, patches) => {
+    // Consecutive nested-path patches targeting the same array item are
+    // consolidated into one cloneDeep + one Y.Array write. An immer splice on
+    // a nested array (e.g. a sheet's rowMetadata on row insert/delete) emits
+    // one patch per shifted entry; writing each patch individually clones and
+    // re-serializes the entire item per entry — O(n²) on large sheets, which
+    // freezes the tab.
+    let pending = null;
+    const flushPending = () => {
+        if (!pending) {
+            return;
+        }
+        const { index, item } = pending;
+        pending = null;
+        ensureArraySize(yarray, index);
+        yarray.insert(index, [item]);
+        yarray.delete(index + 1, 1);
+    };
+    patches.forEach(({ op, path, value }) => {
+        const [arrayIndex, ...nestedPath] = path;
+        const index = Number(arrayIndex);
+        if (isNaN(index)) {
+            flushPending();
+            // User is replacing the entire array
+            if (op === "replace") {
+                yarray.delete(0, yarray.length);
+                yarray.push(value);
+            }
+            return;
+        }
+        if (op === "replace" || op === "add") {
+            if (nestedPath.length === 0) {
+                flushPending();
+                // Direct array item replacement
+                ensureArraySize(yarray, index);
+                yarray.insert(index, [value]);
+                yarray.delete(index + 1, 1);
+            }
+            else {
+                // Nested property update within array item
+                let updatedItem;
+                if (pending && pending.index === index) {
+                    updatedItem = pending.item;
+                }
+                else {
+                    flushPending();
+                    const item = index < yarray.length ? yarray.get(index) : {};
+                    const baseItem = item === null || item === undefined ? {} : item;
+                    // Clone the item and use lodash to set the nested property
+                    updatedItem = cloneDeep(baseItem);
+                    pending = { index, item: updatedItem };
+                }
+                set(updatedItem, nestedPath, value);
+            }
+        }
+        else if (op === "remove") {
+            if (nestedPath.length === 0) {
+                flushPending();
+                // Remove entire array item
+                if (index >= 0 && index < yarray.length) {
+                    yarray.delete(index, 1);
+                }
+            }
+            else {
+                // Remove nested property from array item
+                let updatedItem = null;
+                if (pending && pending.index === index) {
+                    if (pending.item && typeof pending.item === "object") {
+                        updatedItem = pending.item;
+                    }
+                }
+                else {
+                    flushPending();
+                    if (index >= 0 && index < yarray.length) {
+                        const item = yarray.get(index);
+                        if (item && typeof item === "object") {
+                            updatedItem = cloneDeep(item);
+                            pending = { index, item: updatedItem };
+                        }
+                    }
+                }
+                if (updatedItem) {
+                    // Check if we're removing from an array
+                    const parentPath = nestedPath.slice(0, -1);
+                    const lastKey = nestedPath[nestedPath.length - 1];
+                    if (parentPath.length > 0) {
+                        const parentValue = get(updatedItem, parentPath);
+                        if (Array.isArray(parentValue) && typeof lastKey === "number") {
+                            // Remove array element using splice
+                            parentValue.splice(lastKey, 1);
+                        }
+                        else {
+                            // Remove object property
+                            unset(updatedItem, nestedPath);
+                        }
+                    }
+                    else {
+                        // Direct property removal
+                        unset(updatedItem, nestedPath);
+                    }
+                }
+            }
+        }
+    });
+    flushPending();
+};
+/**
+ * Helper function to ensure array is large enough
+ */
+function ensureArraySize(yarray, index) {
+    if (index >= yarray.length) {
+        const gaps = new Array(index - yarray.length).fill(null);
+        yarray.insert(yarray.length, gaps);
+        yarray.insert(index, [null]); // Insert placeholder that will be replaced
+    }
+}
+/**
+ * Normalize values to always be an array, converting object notation if needed
+ */
+function normalizeValuesToArray(values) {
+    if (!values) {
+        return [];
+    }
+    if (Array.isArray(values)) {
+        return [...values];
+    }
+    // Convert object notation to array
+    const entries = Object.entries(values);
+    if (entries.length === 0) {
+        return [];
+    }
+    const maxIndex = Math.max(...entries.map(([key]) => Number(key)));
+    const result = new Array(maxIndex + 1).fill(null);
+    entries.forEach(([key, value]) => {
+        result[Number(key)] = value;
+    });
+    return result;
+}
+/**
+ * Validate and clean sheets data
+ */
+export const validateSheets = (sheets) => {
+    return sheets.filter(Boolean).map((sheet) => ({
+        ...sheet,
+        // Ensure merges is always an array and filter out falsy values
+        merges: sheet.merges?.filter(Boolean),
+    }));
+};
+/**
+ * Map operations
+ */
+export const applyMapPatches = (yMap, patches) => {
+    for (const { op, path, value } of patches) {
+        if (!path || !path.length) {
+            if (op === "remove") {
+                // Only clear if there's something to clear
+                if (yMap.size > 0)
+                    yMap.clear();
+            }
+            else if (op === "replace") {
+                // Diff against current contents instead of clear-and-rewrite, so keys
+                // whose references haven't changed don't generate Y.Map tombstones.
+                const incoming = new Map(value);
+                for (const k of Array.from(yMap.keys())) {
+                    if (!incoming.has(k))
+                        yMap.delete(k);
+                }
+                for (const [k, v] of incoming) {
+                    if (yMap.get(k) !== v)
+                        yMap.set(k, v);
+                }
+            }
+            continue;
+        }
+        const index = path[0];
+        if (op === "remove") {
+            if (yMap.has(index))
+                yMap.delete(index);
+        }
+        else if (op === "add" || op === "replace") {
+            if (yMap.get(index) !== value)
+                yMap.set(index, value);
+        }
+    }
+};
+/**
+ * Process events to find changes in sheet data
+ * Returns a new sheet data object with only the changes applied if possible, or null if a full reload is needed
+ */
+export const processSheetDataEvents = (events, currentSheetData, ySheetDataV2) => {
+    const changes = new Map();
+    const fullReloadSheets = new Set();
+    for (const event of events) {
+        const path = event.path;
+        if (path.length > 0) {
+            const sheetId = String(path[0]);
+            if (!changes.has(sheetId)) {
+                changes.set(sheetId, new Map());
+            }
+            const rows = changes.get(sheetId);
+            // Path structure: [sheetId, rowIndex, "values", colIndex] or [sheetId, rowIndex]
+            if (path.length >= 4 && path[2] === "values") {
+                const rowIndex = Number(path[1]);
+                const columnIndex = Number(path[3]);
+                if (!isNaN(rowIndex) && !isNaN(columnIndex)) {
+                    const existing = rows.get(rowIndex);
+                    if (existing) {
+                        if (!existing.full) {
+                            existing.columns.add(columnIndex);
+                        }
+                    }
+                    else {
+                        rows.set(rowIndex, {
+                            full: false,
+                            columns: new Set([columnIndex]),
+                        });
+                    }
+                }
+            }
+            else if (path.length >= 2) {
+                const rowIndex = Number(path[1]);
+                if (!isNaN(rowIndex)) {
+                    const existing = rows.get(rowIndex);
+                    if (existing) {
+                        existing.full = true;
+                        existing.columns.clear();
+                    }
+                    else {
+                        rows.set(rowIndex, { full: true, columns: new Set() });
+                    }
+                }
+            }
+            else if (path.length === 1) {
+                if (event.isYArrayEvent && event.delta) {
+                    let index = 0;
+                    event.delta.forEach((op) => {
+                        if (op.retain) {
+                            index += op.retain;
+                        }
+                        if (op.insert) {
+                            const count = Array.isArray(op.insert) ? op.insert.length : 1;
+                            for (let i = 0; i < count; i++) {
+                                const rowIndex = index + i;
+                                const existing = rows.get(rowIndex);
+                                if (existing) {
+                                    existing.full = true;
+                                    existing.columns.clear();
+                                }
+                                else {
+                                    rows.set(rowIndex, { full: true, columns: new Set() });
+                                }
+                            }
+                            index += count;
+                        }
+                        if (op.delete) {
+                            fullReloadSheets.add(sheetId); // Mark full sheet reload
+                        }
+                    });
+                }
+            }
+        }
+    }
+    if (changes.size > 0 || fullReloadSheets.size > 0) {
+        const next = { ...currentSheetData };
+        let hasChanges = false;
+        fullReloadSheets.forEach((sheetId) => {
+            const ySheet = ySheetDataV2.get(sheetId);
+            if (!ySheet)
+                return;
+            const sheetData = ySheet.toJSON();
+            next[sheetId] = sheetData;
+            hasChanges = true;
+        });
+        changes.forEach((rowIndices, sheetId) => {
+            const ySheet = ySheetDataV2.get(sheetId);
+            if (!ySheet)
+                return;
+            // If full sheet reload needed
+            if (fullReloadSheets.has(sheetId)) {
+                const sheetData = ySheet.toJSON();
+                next[sheetId] = sheetData;
+                hasChanges = true;
+                return;
+            }
+            // Partial update
+            if (!next[sheetId]) {
+                next[sheetId] = [];
+            }
+            if (next[sheetId].length < ySheet.length) {
+                if (next[sheetId].length !== ySheet.length) {
+                    const sheetData = ySheet.toJSON();
+                    next[sheetId] = sheetData;
+                    hasChanges = true;
+                    return;
+                }
+            }
+            const nextSheet = [...next[sheetId]];
+            rowIndices.forEach((change, rowIndex) => {
+                if (rowIndex < 0 || rowIndex >= ySheet.length)
+                    return;
+                const yRow = ySheet.get(rowIndex);
+                if (change.full) {
+                    let normalizedRow = null;
+                    if (yRow) {
+                        const rowJson = yRow.toJSON();
+                        normalizedRow = rowJson;
+                    }
+                    nextSheet[rowIndex] = normalizedRow;
+                }
+                else {
+                    const currentRow = nextSheet[rowIndex] ?? null;
+                    if (!yRow) {
+                        if (currentRow) {
+                            nextSheet[rowIndex] = currentRow;
+                        }
+                        return;
+                    }
+                    const yValues = yRow.get("values");
+                    if (!yValues) {
+                        if (currentRow) {
+                            nextSheet[rowIndex] = currentRow;
+                        }
+                        return;
+                    }
+                    const baseRow = currentRow ?? yRow.toJSON();
+                    if (!baseRow) {
+                        return;
+                    }
+                    const baseValues = baseRow.values;
+                    // Always normalize to array to ensure .entries() works in calculation code
+                    const mergedValues = normalizeValuesToArray(baseValues);
+                    change.columns.forEach((columnIndex) => {
+                        const nextValue = yValues.get(columnIndex);
+                        mergedValues[columnIndex] =
+                            nextValue === undefined ? null : nextValue;
+                    });
+                    nextSheet[rowIndex] = {
+                        ...baseRow,
+                        values: mergedValues,
+                    };
+                }
+            });
+            next[sheetId] = nextSheet;
+            hasChanges = true;
+        });
+        return hasChanges ? next : null;
+    }
+    return null;
+};
+// ============================================================================
+// V3 Helper Functions (Flat Map Structure)
+// ============================================================================
+/**
+ * Convert letter to column index (1-based)
+ * A = 1, B = 2, ..., Z = 26, AA = 27, etc.
+ */
+const letterToColumnIndex = (letters) => {
+    return letters
+        .toUpperCase()
+        .split("")
+        .reduce((r, a) => r * 26 + parseInt(a, 36) - 9, 0);
+};
+/**
+ * Create a V3 cell key from sheet ID, row and column indices
+ * Format: `${sheetId}!${A1Address}` (e.g., "1!A1", "2!B5")
+ */
+export const createCellKeyV3 = (sheetId, rowIndex, columnIndex) => {
+    const address = cellToAddress({ rowIndex, columnIndex }) ??
+        `${String.fromCharCode(65 + columnIndex - 1)}${rowIndex}`;
+    return `${sheetId}!${address}`;
+};
+/**
+ * Parse a V3 cell key to extract sheet ID and position information
+ * Example: parseCellKeyV3("1!A1") => { sheetId: 1, address: "A1", rowIndex: 1, columnIndex: 1 }
+ */
+export const parseCellKeyV3 = (cellKey) => {
+    const match = cellKey.match(/^(\d+)!([A-Z]+)(\d+)$/i);
+    if (!match)
+        return null;
+    const [, sheetIdStr, columnLetters, rowIndexStr] = match;
+    return {
+        sheetId: Number(sheetIdStr),
+        address: `${columnLetters.toUpperCase()}${rowIndexStr}`,
+        rowIndex: Number(rowIndexStr),
+        columnIndex: letterToColumnIndex(columnLetters),
+    };
+};
+/**
+ * Create a CellDataV3 object with position and sheetId
+ */
+export const createCellDataV3 = (value, sheetId, rowIndex, columnIndex) => ({
+    value,
+    sId: sheetId,
+    r: rowIndex,
+    c: columnIndex,
+});
+/**
+ * Convert V2 SheetData to V3 flat Map format
+ * V2: { sheetId: [rows with values arrays] }
+ * V3: Map<cellKey, CellDataV3>
+ */
+export const sheetDataV2ToV3 = (v2Data) => {
+    const v3Map = new Map();
+    for (const sheetIdStr in v2Data) {
+        const sheetId = Number(sheetIdStr);
+        const rows = v2Data[sheetId];
+        if (!rows)
+            continue;
+        rows.forEach((row, rowIndex) => {
+            if (!row?.values)
+                return;
+            row.values.forEach((cellData, colIndex) => {
+                if (cellData) {
+                    const key = createCellKeyV3(sheetId, rowIndex, colIndex);
+                    v3Map.set(key, createCellDataV3(cellData, sheetId, rowIndex, colIndex));
+                }
+            });
+        });
+    }
+    return v3Map;
+};
+/**
+ * Convert V3 flat Map format to V2 SheetData
+ * V3: Map<cellKey, CellDataV3>
+ * V2: { sheetId: [rows with values arrays] }
+ */
+export const sheetDataV3ToV2 = (v3Data) => {
+    const sheetData = {};
+    for (const [_, cellDataV3] of v3Data) {
+        if (!cellDataV3)
+            continue;
+        const { sId: sheetId, r: rowIdx, c: colIdx, value } = cellDataV3;
+        // Ensure sheet exists
+        if (!sheetData[sheetId]) {
+            sheetData[sheetId] = [];
+        }
+        // Ensure row exists
+        while (sheetData[sheetId].length <= rowIdx) {
+            sheetData[sheetId].push(null);
+        }
+        if (!sheetData[sheetId][rowIdx]) {
+            sheetData[sheetId][rowIdx] = { values: [] };
+        }
+        const row = sheetData[sheetId][rowIdx];
+        if (!row.values)
+            row.values = [];
+        // Ensure values array is long enough
+        while (row.values.length <= colIdx) {
+            row.values.push(null);
+        }
+        row.values[colIdx] = value;
+    }
+    return sheetData;
+};
+/**
+ * Get a cell from V3 flat structure
+ */
+export const getCellV3 = (ySheetDataV3, sheetId, rowIndex, columnIndex) => {
+    const key = createCellKeyV3(sheetId, rowIndex, columnIndex);
+    return ySheetDataV3.get(key);
+};
+/**
+ * Set a cell in V3 flat structure
+ */
+export const setCellV3 = (ySheetDataV3, sheetId, rowIndex, columnIndex, value) => {
+    const key = createCellKeyV3(sheetId, rowIndex, columnIndex);
+    ySheetDataV3.set(key, createCellDataV3(value, sheetId, rowIndex, columnIndex));
+};
+/**
+ * Delete a cell from V3 flat structure
+ */
+export const deleteCellV3 = (ySheetDataV3, sheetId, rowIndex, columnIndex) => {
+    const key = createCellKeyV3(sheetId, rowIndex, columnIndex);
+    ySheetDataV3.delete(key);
+};
+/**
+ * Delete all cells for a sheet from V3 flat structure
+ */
+export const deleteSheetV3 = (ySheetDataV3, sheetId) => {
+    const prefix = `${sheetId}!`;
+    for (const key of ySheetDataV3.keys()) {
+        if (key.startsWith(prefix)) {
+            ySheetDataV3.delete(key);
+        }
+    }
+};
+/**
+ * Get V3 sheet data map from Y.Doc
+ */
+export const getSheetDataV3 = (doc) => {
+    return doc.getMap("sheetDataV3");
+};
+/**
+ * Apply immer patches to V3 sheet data (flat map structure)
+ *
+ * Optimized for bulk operations (paste, import) by consolidating cell-level
+ * patches before applying to Y.js. This reduces overhead by:
+ * 1. Deduplicating patches targeting the same cell (later patches win)
+ * 2. Processing all cell updates in a single pass
+ */
+export const addSheetDataPatchesV3 = (ySheetDataV3, patches) => {
+    // Optimization: Pre-process and consolidate cell-level patches
+    // For bulk operations like paste (10k+ rows), this dramatically reduces overhead
+    const cellUpdates = new Map();
+    const otherPatches = [];
+    // First pass: categorize and consolidate patches
+    for (const patch of patches) {
+        const { op, path, value } = patch;
+        const [sheetIdRaw] = path;
+        // Handle undefined sheetId separately (full replace)
+        if (typeof sheetIdRaw === "undefined") {
+            otherPatches.push(patch);
+            continue;
+        }
+        const sheetId = Number(sheetIdRaw);
+        if (op === "replace" || op === "add") {
+            // [sheetId, rowIndex, 'values', columnIndex] - Single cell update (most common in paste)
+            if (path.length === 4) {
+                const [, rowIndex, , columnIndex] = path;
+                const rowIdx = Number(rowIndex);
+                const colIdx = Number(columnIndex);
+                const key = createCellKeyV3(sheetId, rowIdx, colIdx);
+                // Later patches override earlier ones for the same cell
+                cellUpdates.set(key, { sheetId, rowIdx, colIdx, value });
+            }
+            else {
+                // Row-level or sheet-level updates
+                otherPatches.push(patch);
+            }
+        }
+        else if (op === "remove") {
+            if (path.length === 4) {
+                const [, rowIndex, , columnIndex] = path;
+                const rowIdx = Number(rowIndex);
+                const colIdx = Number(columnIndex);
+                const key = createCellKeyV3(sheetId, rowIdx, colIdx);
+                cellUpdates.set(key, { sheetId, rowIdx, colIdx, value: null });
+            }
+            else {
+                otherPatches.push(patch);
+            }
+        }
+        else {
+            otherPatches.push(patch);
+        }
+    }
+    // Second pass: Apply consolidated cell updates in batch
+    // This is much faster than processing each patch individually
+    for (const [key, { sheetId, rowIdx, colIdx, value }] of cellUpdates) {
+        if (value) {
+            ySheetDataV3.set(key, createCellDataV3(value, sheetId, rowIdx, colIdx));
+        }
+        else {
+            ySheetDataV3.delete(key);
+        }
+    }
+    // Row-targeted patches (e.g. the per-shifted-row patches an immer array
+    // splice emits for a row insert/delete) previously scanned the entire flat
+    // cell map once per patch — O(patches × totalCells), which freezes the tab
+    // when inserting a row near the top of a large sheet. Build a
+    // row → cell-keys index once per batch instead, and keep it in sync as
+    // patches apply.
+    let rowCellKeyIndex = null;
+    const rowIndexKey = (sheetId, rowIdx) => `${sheetId}:${rowIdx}`;
+    const ensureRowCellKeyIndex = () => {
+        if (rowCellKeyIndex) {
+            return rowCellKeyIndex;
+        }
+        rowCellKeyIndex = new Map();
+        for (const [key, cellData] of ySheetDataV3.entries()) {
+            const rk = rowIndexKey(cellData?.sId, cellData?.r);
+            let keys = rowCellKeyIndex.get(rk);
+            if (!keys) {
+                keys = new Set();
+                rowCellKeyIndex.set(rk, keys);
+            }
+            keys.add(key);
+        }
+        return rowCellKeyIndex;
+    };
+    const trackCellKeySet = (sheetId, rowIdx, key) => {
+        if (!rowCellKeyIndex) {
+            return;
+        }
+        const rk = rowIndexKey(sheetId, rowIdx);
+        let keys = rowCellKeyIndex.get(rk);
+        if (!keys) {
+            keys = new Set();
+            rowCellKeyIndex.set(rk, keys);
+        }
+        keys.add(key);
+    };
+    const deleteRowCells = (sheetId, rowIdx) => {
+        const keys = ensureRowCellKeyIndex().get(rowIndexKey(sheetId, rowIdx));
+        if (!keys) {
+            return;
+        }
+        for (const key of keys) {
+            ySheetDataV3.delete(key);
+        }
+        rowCellKeyIndex.delete(rowIndexKey(sheetId, rowIdx));
+    };
+    const dropSheetFromIndex = (sheetId) => {
+        if (!rowCellKeyIndex) {
+            return;
+        }
+        const prefix = `${sheetId}:`;
+        for (const rk of Array.from(rowCellKeyIndex.keys())) {
+            if (rk.startsWith(prefix)) {
+                rowCellKeyIndex.delete(rk);
+            }
+        }
+    };
+    // Process non-cell-level patches using original logic
+    const processPatch = ({ op, path, value }) => {
+        const [sheetIdRaw] = path;
+        if (typeof sheetIdRaw === "undefined") {
+            // Replace entire data
+            if (op === "replace") {
+                // Clear all cells
+                for (const key of ySheetDataV3.keys()) {
+                    ySheetDataV3.delete(key);
+                }
+                if (rowCellKeyIndex) {
+                    rowCellKeyIndex.clear();
+                }
+            }
+            // Assign values from the replacement object
+            for (const curSheetId in value) {
+                const sheetId = Number(curSheetId);
+                const rows = value[curSheetId];
+                if (!rows)
+                    continue;
+                Object.entries(rows).forEach(([rowIndexStr, rowData]) => {
+                    if (!rowData?.values)
+                        return;
+                    const rowIdx = Number(rowIndexStr);
+                    Object.entries(rowData.values).forEach(([colIndexStr, cellData]) => {
+                        if (cellData) {
+                            const colIdx = Number(colIndexStr);
+                            const key = createCellKeyV3(sheetId, rowIdx, colIdx);
+                            ySheetDataV3.set(key, createCellDataV3(cellData, sheetId, rowIdx, colIdx));
+                            trackCellKeySet(sheetId, rowIdx, key);
+                        }
+                    });
+                });
+            }
+            return;
+        }
+        const sheetId = Number(sheetIdRaw);
+        if (op === "replace" || op === "add") {
+            // Cell-level patches (path.length === 4) are already handled above via consolidation
+            // [sheetId, rowIndex, 'values', columnIndex, ...nestedPath] - Deep nested property update
+            if (path.length > 4) {
+                const [, rowIndex, , columnIndex, ...nestedPath] = path;
+                const rowIdx = Number(rowIndex);
+                const colIdx = Number(columnIndex);
+                const key = createCellKeyV3(sheetId, rowIdx, colIdx);
+                // Get existing cell data or create empty
+                const existing = ySheetDataV3.get(key);
+                const cellData = existing?.value ? cloneDeep(existing.value) : {};
+                // Apply nested property change
+                set(cellData, nestedPath, value);
+                ySheetDataV3.set(key, createCellDataV3(cellData, sheetId, rowIdx, colIdx));
+                trackCellKeySet(sheetId, rowIdx, key);
+            }
+            // [sheetId, rowIndex, 'values'] - Replace values array
+            else if (path.length === 3 && path[2] === "values") {
+                const [, rowIndex] = path;
+                const rowIdx = Number(rowIndex);
+                // Delete existing cells for this row
+                deleteRowCells(sheetId, rowIdx);
+                // Add new cells
+                if (Array.isArray(value)) {
+                    value.forEach((cellData, colIndex) => {
+                        if (cellData) {
+                            const key = createCellKeyV3(sheetId, rowIdx, colIndex);
+                            ySheetDataV3.set(key, createCellDataV3(cellData, sheetId, rowIdx, colIndex));
+                            trackCellKeySet(sheetId, rowIdx, key);
+                        }
+                    });
+                }
+            }
+            // [sheetId, rowIndex] - Entire row update
+            else if (path.length === 2) {
+                const [, rowIndex] = path;
+                const rowIdx = Number(rowIndex);
+                // Delete existing cells for this row
+                deleteRowCells(sheetId, rowIdx);
+                // Add new cells from row data
+                if (value?.values) {
+                    Object.entries(value.values).forEach(([colIndexStr, cellData]) => {
+                        if (cellData) {
+                            const colIndex = Number(colIndexStr);
+                            const key = createCellKeyV3(sheetId, rowIdx, colIndex);
+                            ySheetDataV3.set(key, createCellDataV3(cellData, sheetId, rowIdx, colIndex));
+                            trackCellKeySet(sheetId, rowIdx, key);
+                        }
+                    });
+                }
+            }
+            // [sheetId] - Entire sheet update
+            else if (path.length === 1) {
+                // Delete all cells for this sheet
+                const prefix = `${sheetId}!`;
+                for (const key of ySheetDataV3.keys()) {
+                    if (key.startsWith(prefix)) {
+                        ySheetDataV3.delete(key);
+                    }
+                }
+                dropSheetFromIndex(sheetId);
+                // Add all new data
+                if (value) {
+                    Object.entries(value).forEach(([rowIndexStr, rowData]) => {
+                        if (rowData?.values) {
+                            const rowIdx = Number(rowIndexStr);
+                            Object.entries(rowData.values).forEach(([colIndexStr, cellData]) => {
+                                if (cellData) {
+                                    const colIndex = Number(colIndexStr);
+                                    const key = createCellKeyV3(sheetId, rowIdx, colIndex);
+                                    ySheetDataV3.set(key, createCellDataV3(cellData, sheetId, rowIdx, colIndex));
+                                    trackCellKeySet(sheetId, rowIdx, key);
+                                }
+                            });
+                        }
+                    });
+                }
+            }
+        }
+        else if (op === "remove") {
+            // Cell-level removes (path.length === 4) are already handled above via consolidation
+            // [sheetId, rowIndex, values, columnIndex, ...nestedPath] - Remove nested property
+            if (path.length > 4) {
+                const [, rowIndex, , columnIndex, ...nestedPath] = path;
+                const rowIdx = Number(rowIndex);
+                const colIdx = Number(columnIndex);
+                const key = createCellKeyV3(sheetId, rowIdx, colIdx);
+                const existing = ySheetDataV3.get(key);
+                if (existing?.value && typeof existing.value === "object") {
+                    const cellData = cloneDeep(existing.value);
+                    unset(cellData, nestedPath);
+                    ySheetDataV3.set(key, createCellDataV3(cellData, sheetId, rowIdx, colIdx));
+                    trackCellKeySet(sheetId, rowIdx, key);
+                }
+            }
+            // [sheetId, rowIndex] - Remove entire row
+            else if (path.length === 2) {
+                const [, rowIndex] = path;
+                const rowIdx = Number(rowIndex);
+                deleteRowCells(sheetId, rowIdx);
+            }
+            // [sheetId] - Remove entire sheet
+            else if (path.length === 1) {
+                const prefix = `${sheetId}!`;
+                for (const key of ySheetDataV3.keys()) {
+                    if (key.startsWith(prefix)) {
+                        ySheetDataV3.delete(key);
+                    }
+                }
+                dropSheetFromIndex(sheetId);
+            }
+        }
+    };
+    // Only process non-cell-level patches (cell-level already handled via consolidation)
+    otherPatches.forEach(processPatch);
+};
+/**
+ * Process V3 events and return updated sheet data
+ * @param changedKeys - Pre-extracted changes from Yjs event
+ * @param currentSheetData - Current sheet data state
+ * @param ySheetDataV3 - The Y.Map for V3 data
+ */
+export const processSheetDataEventsV3 = (changedKeys, currentSheetData, ySheetDataV3) => {
+    if (changedKeys.size === 0)
+        return null;
+    const next = { ...currentSheetData };
+    // Track which sheets/rows have been cloned to avoid re-cloning
+    const clonedSheets = new Set();
+    const clonedRows = new Map(); // "sheetId:rowIdx" -> cloned
+    let hasChanges = false;
+    changedKeys.forEach((change, cellKey) => {
+        const parsed = parseCellKeyV3(cellKey);
+        if (!parsed)
+            return;
+        const { sheetId, rowIndex, columnIndex } = parsed;
+        const rowIdx = rowIndex;
+        const colIdx = columnIndex;
+        const rowKey = `${sheetId}:${rowIdx}`;
+        // Ensure sheet exists and is cloned (to avoid mutating frozen React state)
+        if (!next[sheetId]) {
+            next[sheetId] = [];
+            clonedSheets.add(sheetId);
+        }
+        else if (!clonedSheets.has(sheetId)) {
+            // Clone the sheet array to avoid mutating frozen state
+            next[sheetId] = [...next[sheetId]];
+            clonedSheets.add(sheetId);
+        }
+        const sheet = next[sheetId];
+        // Extend array efficiently using length assignment instead of while loop
+        if (sheet.length <= rowIdx) {
+            sheet.length = rowIdx + 1;
+        }
+        if (change.action === "delete") {
+            // Cell was deleted
+            const row = sheet[rowIdx];
+            if (row?.values && colIdx < row.values.length && row.values[colIdx]) {
+                // Clone row values only once per row
+                if (!clonedRows.has(rowKey)) {
+                    sheet[rowIdx] = { ...row, values: [...row.values] };
+                    clonedRows.set(rowKey, true);
+                }
+                sheet[rowIdx].values[colIdx] = null;
+                hasChanges = true;
+            }
+        }
+        else {
+            // Cell was added or updated
+            const cellDataV3 = ySheetDataV3.get(cellKey);
+            if (cellDataV3) {
+                // Ensure row exists
+                if (!sheet[rowIdx]) {
+                    sheet[rowIdx] = { values: [] };
+                    clonedRows.set(rowKey, true);
+                }
+                else if (!clonedRows.has(rowKey)) {
+                    // Clone row values only once per row
+                    const row = sheet[rowIdx];
+                    sheet[rowIdx] = { ...row, values: row.values ? [...row.values] : [] };
+                    clonedRows.set(rowKey, true);
+                }
+                const values = sheet[rowIdx].values;
+                // Extend array efficiently using length assignment
+                if (values.length <= colIdx) {
+                    values.length = colIdx + 1;
+                }
+                values[colIdx] = cellDataV3.value;
+                hasChanges = true;
+            }
+        }
+    });
+    return hasChanges ? next : null;
+};