@rowsncolumns/y-spreadsheet 14.0.32

package/dist/esm/use-yspreadsheet-v2.js

@@ -0,0 +1,814 @@
+import { createNewSheet, } from "@rowsncolumns/spreadsheet";
+import { getCellUserEnteredValue, getExtendedValueFormula, isAFormula, isNil, sortSheetsByIndex, } from "@rowsncolumns/utils";
+import { useIsomorphicLayoutEffect } from "@rowsncolumns/ui";
+import { useCallback, useMemo, useRef, useState } from "react";
+import { flushSync } from "react-dom";
+import * as Y from "yjs";
+import { addSheetDataPatches, addSheetDataPatchesV3, applyMapPatches, createCellKeyV3, filterErrorCellPatches, getCellDataFromYSheetData, mergeErrorEffectiveValueIntoCellData, processSheetDataEvents, shouldPersistErrorCellPatch, processSheetDataEventsV3, sheetDataV2ToV3, sheetDataV3ToV2, updateArrayType, validateSheets, } from "./helpers";
+/**
+ * Convert Y.js events to SheetDataEvent format for incremental processing
+ */
+const convertToSheetDataEvents = (events) => {
+    return events.map((event) => {
+        const isYArrayEvent = event instanceof Y.YArrayEvent;
+        return {
+            path: event.path,
+            delta: isYArrayEvent
+                ? event.changes.delta
+                : undefined,
+            isYArrayEvent,
+        };
+    });
+};
+/**
+ * Read user entered value directly from Y.js data to avoid race conditions
+ * with React state updates. This is used when recalcCells observer fires
+ * before sheetData observer has updated React state.
+ */
+const getUserEnteredValueFromYDoc = (ySheetData, sheetId, rowIndex, columnIndex) => {
+    const sheet = ySheetData.get(String(sheetId));
+    if (!sheet || rowIndex >= sheet.length)
+        return undefined;
+    const row = sheet.get(rowIndex);
+    if (!row)
+        return undefined;
+    const values = row.get("values");
+    if (!values || columnIndex >= values.length)
+        return undefined;
+    const cell = values.get(columnIndex);
+    // Extract value from ExtendedValue, matching SheetCell.getUserEnteredValue() logic
+    // ue is the abbreviated form of userEnteredValue
+    const userEnteredValue = getCellUserEnteredValue(cell);
+    return getExtendedValueFormula(userEnteredValue);
+};
+/**
+ * Read user entered value from V3 Y.js data structure
+ */
+const getUserEnteredValueFromYDocV3 = (ySheetDataV3, sheetId, rowIndex, columnIndex) => {
+    const cellKey = createCellKeyV3(sheetId, rowIndex, columnIndex);
+    const cellDataV3 = ySheetDataV3.get(cellKey);
+    return getExtendedValueFormula(getCellUserEnteredValue(cellDataV3?.value));
+};
+import { createDeepObservable, createObservable, createSheetDataObservable, getPatchDeltasFromEvent, } from "./observables";
+// Add a single null entry to the YSheetData
+const origin = "local";
+export const useYSpreadsheetV2 = ({ onChangeSheetData, onChangeSheets, onChangeTables, onChangeCharts, onChangeEmbeds, onChangeConditionalFormats, onChangeDataValidations, onChangeCitations, onAfterBroadcastPatch, recalcCellsMaxEntries, onChangeNamedRanges, onChangeProtectedRanges, onChangePivotTables, enqueueCalculation, enqueueGraphOperation, reevaluateDerivationsForCells, onChangeCellXfs, onChangeSharedStrings, calculateNow, onChangeActiveSheet, clientOnlyFunctionPattern, initialSheets, awarenessScopeId, userId, title, sheetId, activeCell, kind, agentInitiator, selections, doc, provider, useV3 = false, sheetDataVersion = "v2", onMigrationComplete, deleteV2AfterMigration = false, skipInitialSync = false, supportLegacySharedStringsArray = false, }) => {
+    const [synced, setSynced] = useState(false);
+    const [users, setUsers] = useState([]);
+    const [isLeader, setIsLeader] = useState(false);
+    const isLeaderRef = useRef(false);
+    const resolvedAwarenessScopeId = awarenessScopeId;
+    // Listen to awareness
+    const awareness = provider?.awareness;
+    useIsomorphicLayoutEffect(() => {
+        if (!awareness)
+            return;
+        const updateLeader = () => {
+            const entries = Array.from(awareness.getStates().entries());
+            const docStates = resolvedAwarenessScopeId
+                ? entries.filter(([_, state]) => state?.docGuid === resolvedAwarenessScopeId)
+                : entries;
+            if (!docStates.length) {
+                setIsLeader(false);
+                return;
+            }
+            const states = docStates.map(([clientId]) => clientId);
+            const minId = Math.min(...states);
+            // Always include self in the elec
+            setIsLeader(doc.clientID === minId);
+        };
+        awareness.on("change", updateLeader);
+        updateLeader(); // Initial check
+        return () => awareness.off("change", updateLeader);
+    }, [awareness, doc, resolvedAwarenessScopeId]);
+    useIsomorphicLayoutEffect(() => {
+        isLeaderRef.current = isLeader;
+    }, [isLeader]);
+    const ySheetDataV2 = useMemo(() => doc.getMap("sheetDataV2"), [doc]);
+    // V3: Flat map structure - Map<cellKey, CellDataV3>
+    // cellKey format: `${sheetId}!${A1Address}` (e.g., "1!A1", "2!B5")
+    const ySheetDataV3 = useMemo(() => doc.getMap("sheetDataV3"), [doc]);
+    // Doc metadata - used as fallback for version when prop is undefined
+    const yDocMeta = useMemo(() => doc.getMap("docMeta"), [doc]);
+    const yDisableRecalc = useMemo(() => doc.getMap("disableRecalc"), [doc]);
+    // Recalc cells
+    const yRecalcCells = useMemo(() => doc.getArray("recalcCells"), [doc]);
+    // Make sure initialSheets is always filled
+    const getInitialSheets = useCallback(() => {
+        if (initialSheets.length) {
+            return initialSheets;
+        }
+        return [createNewSheet(1, "Sheet1")];
+    }, [initialSheets]);
+    // cellxfs
+    const yCellXfs = useMemo(() => doc.getMap("cellXfs"), [doc]);
+    // Shared strings - always use Map for new storage, Array kept for migration
+    const ySharedStringsArray = useMemo(() => doc.getArray("sharedStrings"), [doc]);
+    const ySharedStringsMap = useMemo(() => doc.getMap("sharedStringsMap"), [doc]);
+    // Track if initial sync has changed active sheet
+    const isActiveSheetChanged = useRef(false);
+    /**
+     * Handle shared strings updates from the Y.Map (new format).
+     * Merges incoming Map entries into the current shared strings state.
+     * Used for documents that store shared strings in the Map format.
+     */
+    const handleSharedStringsMapChange = useCallback((value) => {
+        onChangeSharedStrings?.((currentMap) => {
+            const newMap = new Map(currentMap);
+            for (const [key, val] of value) {
+                newMap.set(key, val);
+            }
+            return newMap;
+        });
+    }, [onChangeSharedStrings]);
+    /**
+     * Handle shared strings updates from the Y.Array (legacy format).
+     * Converts array indices to string keys and merges into current state.
+     * Provides backwards compatibility for older documents using array storage.
+     */
+    const handleSharedStringsArrayChange = useCallback((value) => {
+        onChangeSharedStrings?.((currentMap) => {
+            const newMap = new Map(currentMap);
+            value.forEach((v, index) => {
+                newMap.set(String(index), v);
+            });
+            return newMap;
+        });
+    }, [onChangeSharedStrings]);
+    const documentMap = useMemo(() => {
+        const entries = [
+            ["sheets", [doc.getArray("sheets"), onChangeSheets]],
+            ["tables", [doc.getArray("tables"), onChangeTables]],
+            [
+                "embeds",
+                [doc.getArray("embeds"), onChangeEmbeds],
+            ],
+            [
+                "charts",
+                [doc.getArray("charts"), onChangeCharts],
+            ],
+            [
+                "conditionalFormats",
+                [
+                    doc.getArray("conditionalFormats"),
+                    onChangeConditionalFormats,
+                ],
+            ],
+            [
+                "dataValidations",
+                [
+                    doc.getArray("dataValidations"),
+                    onChangeDataValidations,
+                ],
+            ],
+            [
+                "pivotTables",
+                [doc.getArray("pivotTables"), onChangePivotTables],
+            ],
+            [
+                "namedRanges",
+                [doc.getArray("namedRanges"), onChangeNamedRanges],
+            ],
+            [
+                "protectedRanges",
+                [
+                    doc.getArray("protectedRanges"),
+                    onChangeProtectedRanges,
+                ],
+            ],
+            [
+                "citations",
+                [doc.getArray("citations"), onChangeCitations],
+            ],
+            [
+                "sharedStrings",
+                [ySharedStringsMap, handleSharedStringsMapChange],
+            ],
+            ...(supportLegacySharedStringsArray
+                ? [
+                    [
+                        "sharedStringsArray",
+                        [ySharedStringsArray, handleSharedStringsArrayChange],
+                    ],
+                ]
+                : []),
+        ];
+        return new Map(entries);
+    }, [
+        doc,
+        onChangeSheets,
+        onChangeTables,
+        onChangeEmbeds,
+        onChangeCharts,
+        onChangeConditionalFormats,
+        onChangeDataValidations,
+        onChangePivotTables,
+        onChangeNamedRanges,
+        onChangeProtectedRanges,
+        onChangeCitations,
+        ySharedStringsMap,
+        handleSharedStringsMapChange,
+        supportLegacySharedStringsArray,
+        ySharedStringsArray,
+        handleSharedStringsArrayChange,
+    ]);
+    // Get backlog of recalc cells from backend
+    const getBacklog = useCallback(() => {
+        return yRecalcCells
+            .toArray()
+            .flatMap((entry) => entry.patches)
+            .filter(([, , source]) => source === "backend" || source === "agent");
+    }, [yRecalcCells]);
+    // Trigger cell recalcs
+    const syncRecalcCells = useCallback((recalcCells, origin) => {
+        for (const [_, position, source] of recalcCells) {
+            // backend will calculate results
+            const isAgent = source === "agent"; // Agent already does the calculation
+            // Read directly from Y.js to avoid race condition where recalcCells
+            // observer fires before sheetData observer has updated React state
+            const formulaValue = useV3
+                ? getUserEnteredValueFromYDocV3(ySheetDataV3, position.sheetId, position.rowIndex, position.columnIndex)
+                : getUserEnteredValueFromYDoc(ySheetDataV2, position.sheetId, position.rowIndex, position.columnIndex);
+            // Was this from a changeBatch event in the back-end?
+            // To support client functions to run only
+            const isChangeBatch = position.force && isAgent;
+            const isClientOnly = !isNil(formulaValue) &&
+                !isNil(clientOnlyFunctionPattern) &&
+                isAFormula(formulaValue)
+                ? clientOnlyFunctionPattern.test(String(formulaValue))
+                : false;
+            /**
+             * Determines whether to force immediate execution of the operation.
+             *
+             * Force execution is allowed only for leaders and under these conditions:
+             * - No source specified (backwards compatibility - treats as force exec)
+             * - Source is "backend" (backend-initiated changes)
+             * - Client-only mode with change batch (batch operations need immediate execution)
+             *
+             * Note: Agent sources never force execution since they've pre-calculated results.
+             */
+            const forceExecution = isLeaderRef.current &&
+                (!source || // backwards compatible: no source means force exec for leader
+                    source === "backend" ||
+                    (isClientOnly && isChangeBatch));
+            const enqueue = forceExecution
+                ? enqueueCalculation
+                : enqueueGraphOperation;
+            /**
+             * Selects the appropriate queue function for the operation.
+             *
+             * - enqueueCalculation: Used when forcing execution (immediate formula evaluation)
+             * - enqueueGraphOperation: Used for normal graph operations (no formula evaluation)
+             */
+            enqueue?.({
+                type: "add",
+                position,
+                source,
+                force: forceExecution,
+            });
+        }
+        // The agent/backend pre-computes cell VALUES (hence the graph-only
+        // enqueues above), but conditional-format / data-validation RESULTS
+        // are derived on the client — re-evaluate them for the changed cells
+        // so their paint tracks the new values.
+        if (recalcCells.length) {
+            reevaluateDerivationsForCells?.(recalcCells.map(([, position]) => ({
+                sheetId: position.sheetId,
+                rowIndex: position.rowIndex,
+                columnIndex: position.columnIndex,
+            })));
+        }
+    }, [
+        synced,
+        clientOnlyFunctionPattern,
+        ySheetDataV2,
+        ySheetDataV3,
+        useV3,
+        reevaluateDerivationsForCells,
+    ]);
+    // Setup initial sync
+    const setupInitialSync = useCallback(() => {
+        // Migration from sharedStrings (Array) to sharedStringsMap (Map) is disabled.
+        // Both formats are now supported simultaneously via handleSharedStringsMapChange
+        // and handleSharedStringsArrayChange callbacks.
+        const arrayData = ySharedStringsArray.toArray();
+        const mapData = ySharedStringsMap.toJSON();
+        const hasArrayData = arrayData.length > 0;
+        const isMapEmpty = Object.keys(mapData).length === 0;
+        // Migrate if array has data and map is empty
+        if (!supportLegacySharedStringsArray && hasArrayData && isMapEmpty) {
+            doc.transact(() => {
+                // Convert array to map with string keys
+                arrayData.forEach((value, index) => {
+                    ySharedStringsMap.set(String(index), value);
+                });
+                // Optional: Clear the old array to save space
+                // Uncomment if you want to remove old data after migration
+                // ySharedStringsArray.delete(0, ySharedStringsArray.length);
+            }, "migration");
+        }
+        for (const [mappingKey, [ydoc, callback]] of documentMap.entries()) {
+            let value = ydoc.toJSON();
+            if (mappingKey === "sheets") {
+                const sheets = (Array.isArray(value) && value.length
+                    ? validateSheets(value)
+                    : getInitialSheets());
+                callback?.(sheets);
+                // Set active sheet id
+                if (sheets.length && !isActiveSheetChanged.current) {
+                    onChangeActiveSheet?.(sortSheetsByIndex(sheets)[0].sheetId);
+                    isActiveSheetChanged.current = true;
+                }
+            }
+            else if (mappingKey === "sharedStrings") {
+                // Convert Map object to Map instance for shared strings
+                const sharedStringsMap = new Map(Object.entries(value ?? {}));
+                callback?.(sharedStringsMap);
+            }
+            else {
+                callback?.(value);
+            }
+        }
+        // Load sheet data based on V2 or V3 mode
+        if (useV3) {
+            // Check if we need to migrate from V2 to V3
+            // Use prop if provided, otherwise fall back to yDocMeta for backwards compatibility
+            const resolvedVersion = sheetDataVersion ?? yDocMeta.get("sheetDataVersion");
+            if (resolvedVersion !== "v3") {
+                const v2Data = ySheetDataV2.toJSON();
+                const hasV2Data = Object.keys(v2Data).length > 0;
+                if (hasV2Data) {
+                    // Migrate V2 data to V3
+                    doc.transact(() => {
+                        const v3Data = sheetDataV2ToV3(v2Data);
+                        // Add all V3 entries to the Y.Map
+                        for (const [key, cellData] of v3Data.entries()) {
+                            ySheetDataV3.set(key, cellData);
+                        }
+                        // Optionally clear V2 data after migration
+                        if (deleteV2AfterMigration) {
+                            for (const sheetId of ySheetDataV2.keys()) {
+                                ySheetDataV2.delete(sheetId);
+                            }
+                        }
+                    }, "migrate-v2-to-v3");
+                    // Notify backend that migration completed
+                    onMigrationComplete?.("v3");
+                }
+                else {
+                    // No V2 data, notify backend of version
+                    onMigrationComplete?.("v3");
+                }
+            }
+            // V3: Convert flat map to V2 format for React state
+            const v3Data = ySheetDataV3.toJSON();
+            const v3Map = new Map(Object.entries(v3Data));
+            onChangeSheetData?.(sheetDataV3ToV2(v3Map));
+        }
+        else {
+            onChangeSheetData?.(ySheetDataV2.toJSON());
+        }
+        // Cellxfs
+        const cellXfs = new Map(Object.entries(yCellXfs.toJSON() ?? {}));
+        onChangeCellXfs?.(cellXfs);
+    }, [
+        documentMap,
+        onChangeCellXfs,
+        onChangeSheetData,
+        ySheetDataV2,
+        ySheetDataV3,
+        yDocMeta,
+        yCellXfs,
+        getInitialSheets,
+        onChangeActiveSheet,
+        ySharedStringsArray,
+        ySharedStringsMap,
+        doc,
+        useV3,
+        sheetDataVersion,
+        onMigrationComplete,
+        deleteV2AfterMigration,
+    ]);
+    // Synced
+    const onSynced = useCallback(() => {
+        if (!synced) {
+            if (!skipInitialSync) {
+                // Use flushSync to ensure React state is updated before continuing
+                // This guarantees sheetData is available when syncRecalcCells runs
+                flushSync(() => {
+                    setupInitialSync();
+                });
+                // Build dependency graph, then sync backlog cells
+                requestAnimationFrame(async () => {
+                    await calculateNow({
+                        disableEvaluation: true,
+                        shouldResetCellDependencyGraph: true,
+                    });
+                    // Sync backlog after graph is initialized
+                    const backlog = getBacklog();
+                    if (backlog.length) {
+                        syncRecalcCells(backlog, "backend");
+                        // Clear processed backlog entries from yRecalcCells
+                        doc.transact(() => {
+                            yRecalcCells.delete(0, yRecalcCells.length);
+                        }, origin);
+                    }
+                });
+            }
+            setSynced(true);
+        }
+    }, [
+        calculateNow,
+        setupInitialSync,
+        synced,
+        syncRecalcCells,
+        getBacklog,
+        doc,
+        yRecalcCells,
+        skipInitialSync,
+    ]);
+    // Sync state
+    if (provider?.synced && !synced) {
+        onSynced();
+    }
+    useIsomorphicLayoutEffect(() => {
+        provider?.on("synced", onSynced);
+        return () => {
+            provider?.off("synced", onSynced);
+        };
+    }, [provider]);
+    // Only for sheet Data (V2 mode)
+    useIsomorphicLayoutEffect(() => {
+        if (useV3)
+            return; // Skip V2 observer in V3 mode
+        // Subscribe to sheet data
+        const subscription = createSheetDataObservable(ySheetDataV2).subscribe((events) => {
+            /**
+             * Disable recalc is a flag that is set ONLY locally
+             * when a calculation completes
+             *
+             * This is to prevent yjs from observing sheetdata
+             * and updating it, which is not necessary
+             */
+            if (events.length) {
+                const origin = events?.[0]?.transaction?.origin;
+                if (origin !== "local") {
+                    // Convert Y.js events to SheetDataEvent format and apply incremental updates
+                    const sheetDataEvents = convertToSheetDataEvents(events);
+                    onChangeSheetData((prevSheetData) => {
+                        const result = processSheetDataEvents(sheetDataEvents, prevSheetData, ySheetDataV2);
+                        // Fall back to full serialization only if incremental update fails
+                        return result ?? ySheetDataV2.toJSON();
+                    });
+                }
+            }
+        });
+        return () => {
+            subscription.unsubscribe();
+        };
+    }, [onChangeSheetData, ySheetDataV2, useV3]);
+    // Only for sheet Data (V3 mode)
+    useIsomorphicLayoutEffect(() => {
+        if (!useV3)
+            return; // Skip V3 observer in V2 mode
+        // Subscribe to V3 sheet data (flat Map)
+        const callback = (event) => {
+            if (event.transaction.origin !== "local") {
+                // Extract changes synchronously - Yjs requires accessing event.changes
+                // within the event handler, not in a deferred callback like setState
+                const changedKeys = new Map();
+                event.changes.keys.forEach((change, key) => {
+                    changedKeys.set(key, { action: change.action });
+                });
+                // Now we can safely use the extracted data in the async setState callback
+                onChangeSheetData((prevSheetData) => {
+                    const result = processSheetDataEventsV3(changedKeys, prevSheetData, ySheetDataV3);
+                    if (result) {
+                        return result;
+                    }
+                    // Fall back to full conversion
+                    const v3Data = ySheetDataV3.toJSON();
+                    const v3Map = new Map(Object.entries(v3Data));
+                    return sheetDataV3ToV2(v3Map);
+                });
+            }
+        };
+        ySheetDataV3.observe(callback);
+        return () => {
+            ySheetDataV3.unobserve(callback);
+        };
+    }, [onChangeSheetData, ySheetDataV3, useV3]);
+    // CellXfs
+    useIsomorphicLayoutEffect(() => {
+        // Subscribe to sheet data
+        const callback = (event) => {
+            if (event.transaction.origin !== "local") {
+                const cellXfs = new Map(Object.entries(yCellXfs.toJSON() ?? {}));
+                onChangeCellXfs?.(cellXfs);
+            }
+        };
+        yCellXfs.observe(callback);
+        return () => {
+            yCellXfs.unobserve(callback);
+        };
+    }, [onChangeCellXfs, yCellXfs]);
+    // All others
+    useIsomorphicLayoutEffect(() => {
+        const subs = [];
+        for (const [mappingKey, [ydoc, callback]] of documentMap.entries()) {
+            // Only observe Arrays (shared strings Map is handled separately if needed)
+            if (ydoc instanceof Y.Array) {
+                const subscription = createDeepObservable(ydoc).subscribe((events) => {
+                    for (const event of events) {
+                        if (event.transaction.origin !== "local") {
+                            let json = ydoc.toJSON();
+                            if (Array.isArray(json) &&
+                                json.length &&
+                                json[0]?.userId) {
+                                continue;
+                            }
+                            callback?.(json);
+                        }
+                    }
+                });
+                subs.push(subscription);
+            }
+            else if (ydoc instanceof Y.Map && mappingKey === "sharedStrings") {
+                // Handle shared strings Map observation
+                const callback_map = (event) => {
+                    if (event.transaction.origin !== "local") {
+                        const json = ydoc.toJSON();
+                        const sharedStringsMap = new Map(Object.entries(json ?? {}));
+                        callback?.(sharedStringsMap);
+                    }
+                };
+                ydoc.observe(callback_map);
+                subs.push({
+                    unsubscribe: () => ydoc.unobserve(callback_map),
+                });
+            }
+        }
+        return () => {
+            subs.forEach((sub) => sub.unsubscribe());
+        };
+    }, [documentMap]);
+    // Only for recalc cells
+    useIsomorphicLayoutEffect(() => {
+        if (!synced) {
+            return;
+        }
+        // Sync all cells that are updated in the backend
+        // // Observe recalc cells separat
+        const onRecalcCellsChange = (event) => {
+            const patches = getPatchDeltasFromEvent(event);
+            const origin = event.transaction.origin;
+            if (origin !== "local") {
+                requestAnimationFrame(() => {
+                    syncRecalcCells(patches, origin);
+                });
+            }
+        };
+        // Skip the first recalc cells change
+        const sub = createObservable(yRecalcCells).subscribe(onRecalcCellsChange);
+        return () => sub.unsubscribe();
+    }, [syncRecalcCells, recalcCellsMaxEntries, synced, yRecalcCells]);
+    // Broadcast patch
+    const onBroadcastPatch = useCallback((patches) => {
+        // Ignore push flag
+        const disableRecalc = Boolean(patches.find(([patch]) => patch?.disableRecalc));
+        // Check if this is a full recalc
+        const isFullRecalc = Boolean(patches.find(([patch]) => patch?.isFullRecalc));
+        const disableSync = isFullRecalc ? false : disableRecalc && !isLeader;
+        // Only leader can broadcast recalc patches. Error effective values are
+        // the exception: async custom-function failures (#VALUE!, #NAME?, …)
+        // only exist as disableRecalc calc-result patches, and the leader's
+        // write is deferred/lossy — if non-leaders drop them too, the error
+        // paints during the live session but the cell is blank after reload.
+        // Sync just the error-bearing cell patches; ordinary recalc results
+        // stay leader-gated so N clients don't all write identical results.
+        if (disableSync) {
+            const errorCellPatches = [];
+            for (let [patch, type = "redo"] of patches) {
+                if (!patch?.sheetData) {
+                    continue;
+                }
+                type = type ?? "redo";
+                const patchKey = type === "redo" ? "patches" : "inversePatches";
+                const sheetDataPatches = patch.sheetData[patchKey];
+                if (sheetDataPatches?.length) {
+                    errorCellPatches.push(...filterErrorCellPatches(sheetDataPatches));
+                }
+            }
+            // Containment for this non-leader write path: an error may only
+            // fill a cell with no effective value (the blank-after-reload case)
+            // or replace an existing error — never a non-error result; a cell
+            // whose formula (ue) changed since the calculation started is
+            // skipped; identical persisted errors are skipped so concurrent
+            // non-leaders don't append redundant Y.js updates; and a proceeding
+            // write merges ONLY the error effective value into the existing doc
+            // cell, preserving every other persisted field.
+            const persistableErrorCellPatches = [];
+            for (const errorPatch of errorCellPatches) {
+                const [patchSheetId, rowIndex, , columnIndex] = errorPatch.path;
+                const currentCellData = useV3
+                    ? ySheetDataV3.get(createCellKeyV3(Number(patchSheetId), Number(rowIndex), Number(columnIndex)))?.value
+                    : getCellDataFromYSheetData(ySheetDataV2, patchSheetId, Number(rowIndex), Number(columnIndex));
+                const incomingCellData = errorPatch.value;
+                if (!shouldPersistErrorCellPatch(currentCellData, incomingCellData)) {
+                    continue;
+                }
+                persistableErrorCellPatches.push({
+                    ...errorPatch,
+                    value: mergeErrorEffectiveValueIntoCellData(currentCellData, incomingCellData),
+                });
+            }
+            if (persistableErrorCellPatches.length) {
+                doc.transact(() => {
+                    if (useV3) {
+                        addSheetDataPatchesV3(ySheetDataV3, persistableErrorCellPatches);
+                    }
+                    else {
+                        addSheetDataPatches(ySheetDataV2, persistableErrorCellPatches);
+                    }
+                }, origin);
+            }
+            return;
+        }
+        doc.transact(() => {
+            for (let [patch, type = "redo"] of patches) {
+                // Check for existence of patch
+                // Investigate when when importing csv, it create a [undefined, undefined] patch object
+                // todo @Vinay
+                if (!patch) {
+                    continue;
+                }
+                type = type ?? "redo";
+                const patchKey = type === "redo" ? "patches" : "inversePatches";
+                if (patch.sheetData) {
+                    const patches = patch.sheetData?.[patchKey];
+                    if (useV3) {
+                        addSheetDataPatchesV3(ySheetDataV3, patches);
+                    }
+                    else {
+                        addSheetDataPatches(ySheetDataV2, patches);
+                    }
+                }
+                if (patch.cellXfs) {
+                    const patches = patch.cellXfs?.[patchKey];
+                    applyMapPatches(yCellXfs, patches);
+                }
+                for (const [mappingKey, [ydoc]] of documentMap.entries()) {
+                    if (patch?.[mappingKey]) {
+                        const patches = patch[mappingKey]?.[patchKey];
+                        // Handle shared strings Map (always use Map now)
+                        if (mappingKey === "sharedStrings" && ydoc instanceof Y.Map) {
+                            applyMapPatches(ydoc, patches);
+                        }
+                        else if (ydoc instanceof Y.Array) {
+                            // Check if we are updating sheets
+                            if (mappingKey === "sheets" && ydoc.length === 0) {
+                                // Add initial sheets
+                                ydoc.insert(0, getInitialSheets());
+                            }
+                            updateArrayType(ydoc, patches);
+                        }
+                    }
+                }
+                // Recalc cells
+                if (patch.recalcCells?.[type]) {
+                    if (isLeader) {
+                        // Remove old cells
+                        yRecalcCells.delete(0, yRecalcCells.length);
+                    }
+                    yRecalcCells.push([
+                        {
+                            userId,
+                            patches: Array.from(patch.recalcCells[type]),
+                        },
+                    ]);
+                }
+            }
+        }, origin);
+        onAfterBroadcastPatch?.(patches, doc);
+    }, [
+        onAfterBroadcastPatch,
+        documentMap,
+        yRecalcCells,
+        doc,
+        userId,
+        yDisableRecalc,
+        ySheetDataV2,
+        ySheetDataV3,
+        isLeader,
+        recalcCellsMaxEntries,
+        useV3,
+    ]);
+    // Listen to active cell change
+    useIsomorphicLayoutEffect(() => {
+        if (activeCell) {
+            awareness?.setLocalStateField("activeCell", activeCell);
+        }
+    }, [awareness, activeCell]);
+    // Listen to sheet change
+    useIsomorphicLayoutEffect(() => {
+        awareness?.setLocalStateField("sheetId", sheetId);
+    }, [awareness, sheetId]);
+    // Listen to selection range change
+    useIsomorphicLayoutEffect(() => {
+        if (selections && selections.length > 0) {
+            awareness?.setLocalStateField("selections", selections);
+        }
+    }, [awareness, selections]);
+    // Awareness
+    useIsomorphicLayoutEffect(() => {
+        const onChangeAwareness = () => {
+            if (awareness) {
+                const collaborators = [];
+                for (const [_, value] of awareness.getStates().entries()) {
+                    if (!value)
+                        continue;
+                    // States with no docGuid are accepted as a wildcard so REST
+                    // writers or pre-scoped clients still appear as collaborators.
+                    const docMatches = !resolvedAwarenessScopeId ||
+                        !value.docGuid ||
+                        value.docGuid === resolvedAwarenessScopeId;
+                    if (!docMatches)
+                        continue;
+                    // Canonical shape is the nested `state.user = { kind, name, userId,
+                    // agentInitiator? }` used by Olympus, pptx-studio, and the keryx
+                    // agentTask helper. Fall back to legacy flat fields for one
+                    // release so callers can migrate at their own pace.
+                    const userBlock = (value.user ?? null);
+                    const resolvedUserId = userBlock?.userId ?? value.userId;
+                    const resolvedTitle = userBlock?.name ?? value.title;
+                    const resolvedKind = userBlock?.kind ?? value.kind;
+                    const resolvedAgentInitiator = userBlock?.agentInitiator ?? value.agentInitiator;
+                    if (!resolvedUserId)
+                        continue;
+                    if (!value.activeCell && !value.selections)
+                        continue;
+                    collaborators.push({
+                        activeCell: value.activeCell,
+                        title: (resolvedTitle ?? ""),
+                        userId: resolvedUserId,
+                        sheetId: value.sheetId,
+                        kind: resolvedKind,
+                        agentInitiator: resolvedAgentInitiator,
+                        selections: value.selections,
+                    });
+                }
+                setUsers(collaborators);
+            }
+        };
+        // Listen to awareness
+        awareness?.on("change", onChangeAwareness);
+        return () => {
+            awareness?.off("change", onChangeAwareness);
+        };
+    }, [awareness, resolvedAwarenessScopeId]);
+    // Set local awareness state.
+    //
+    // Use setLocalStateField for each field individually so sibling consumers
+    // (Olympus's unified presence layer, agent-task helpers, etc.) can compose
+    // their own fields on the same awareness state without us clobbering them.
+    useIsomorphicLayoutEffect(() => {
+        if (!awareness)
+            return;
+        awareness.setLocalStateField("userId", userId);
+        awareness.setLocalStateField("title", title);
+        awareness.setLocalStateField("sheetId", sheetId);
+        if (resolvedAwarenessScopeId) {
+            awareness.setLocalStateField("docGuid", resolvedAwarenessScopeId);
+        }
+        // Mirror the canonical nested shape so other Athena editors can read
+        // state.user.* without falling back to the legacy flat fields.
+        const userBlock = {
+            userId,
+            name: title,
+        };
+        if (kind)
+            userBlock.kind = kind;
+        if (agentInitiator)
+            userBlock.agentInitiator = agentInitiator;
+        awareness.setLocalStateField("user", userBlock);
+        if (kind)
+            awareness.setLocalStateField("kind", kind);
+        if (agentInitiator)
+            awareness.setLocalStateField("agentInitiator", agentInitiator);
+    }, [
+        awareness,
+        resolvedAwarenessScopeId,
+        userId,
+        title,
+        sheetId,
+        kind,
+        agentInitiator,
+    ]);
+    return {
+        synced,
+        users,
+        onBroadcastPatch,
+        isLeader,
+        setupInitialSync,
+    };
+};