@rowsncolumns/y-spreadsheet 16.0.0 → 16.1.0

package/dist/esm/helpers-v5.js

@@ -0,0 +1,733 @@
+// ============================================================================
+// V5 documents (stable line ids): reader and legacy-path writer
+// ============================================================================
+// Encoding: libs/rnc-yrs-store/docs/v5-document-encoding.md. Names in comments
+// (`RNC_CELLS`, `c0_floor`, …) are the Rust ones in rust/crates/rnc-yrs-store/src
+// (lib.rs unless a module is named); they win over this module.
+//
+// Readers (hot plane only; cold-block cells are not decoded): `sheetDataV5ToV2`,
+// `getCellV5`, `processSheetDataChangesV5`; `uf` from the composed style plane,
+// `note` from `rncNotes`, so a cell read here can be written back unchanged.
+// Writer: `addSheetDataPatchesV5` applies immer `SheetData` patches positionally
+// (a structural edit arrives as rewritten rows, v3 parity); it names lines past
+// an axis with client-0 ids exactly as `YrsStore::ensure_lines` does and logs
+// `uf` changes as `STYLE_LOG_V2` ops. It never writes `ft`: a JS formula is
+// positional in its write frame.
+import { getCellUserEnteredFormat } from "@rowsncolumns/utils";
+import * as decoding from "lib0/decoding";
+import * as encoding from "lib0/encoding";
+import cloneDeep from "lodash/cloneDeep";
+import isEqual from "lodash/isEqual";
+import set from "lodash/set";
+import unset from "lodash/unset";
+const CELLS_V5 = "rncCells"; // RNC_CELLS
+const NOTES_V5 = "rncNotes"; // NOTES
+const DIMS_V5 = "rncDimensions"; // DIMS
+const STYLES_SEED_V5 = "rncCellStyles"; // RNC_STYLES (legacy, read-only seed)
+const STYLES_LOG_V5 = "rncCellStylesLog"; // RNC_STYLES_LOG
+const BLOCKS_V5 = "rncColumnBlocks"; // RNC_COLUMN_BLOCKS
+const BLOCK_ROWS = 32768; // BLOCK_ROWS
+const BLOCK_V2_MAGIC = 0x80000000; // BLOCK_V2_MAGIC
+const BLOCK_V2_DENSE = 0x40000000; // BLOCK_V2_DENSE
+const STYLE_LOG_V1 = 1; // STYLE_LOG_V1
+const STYLE_LOG_V2 = 2; // STYLE_LOG_V2
+const CELL_KEY_V5 = /^(-?\d+):(-?\d+):(-?\d+)$/; // cell_key
+const BLOCK_KEY_V5 = /^(-?\d+):(-?\d+):(\d+)$/; // block_key
+const DIM_KEY_V5 = /^(-?\d+):([RC]):(-?\d+)$/; // dim_id_key
+const SEED_KEY = /^(-?\d+)!([A-Z]+)(\d+)$/; // `"{sheetId}!{A1}"`, parse_a1
+// ── ids (axis.rs: make_id, id_client, id_counter) ───────────────────────────
+const idCounter = (id) => Number((BigInt.asUintN(64, id) >> BigInt(32)) & BigInt(0xffffffff));
+const idClient = (id) => Number(BigInt.asUintN(32, id));
+/** Decimal client-0 id of `counter` (`make_id(0, counter)`). */
+const c0Id = (counter) => (BigInt(counter) << BigInt(32)).toString();
+/** Client-0 counter of a decimal id; 0 for another client's id. */
+const c0Counter = (id) => {
+    const value = BigInt(id);
+    return idClient(value) === 0 ? idCounter(value) : 0;
+};
+/** The array value of a padded id: `counter << 32` is exact as a float (yjs cannot insert a bigint). */
+const idValue = (counter) => counter * 4294967296;
+const lineIdsRootName = (sheetId, axis) => `${axis === "row" ? "rncRowIds" : "rncColIds"}:${sheetId}`;
+/** Decimal text of a stored line id (yjs gives a number or a bigint); null otherwise. */
+const lineIdText = (value) => {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return BigInt(Math.trunc(value)).toString();
+    }
+    return null;
+};
+/**
+ * A sheet's line ids in grid order (position = index + 1), as decimal strings.
+ * Later duplicates and non-id values are skipped, as the engine's index does.
+ */
+export const readLineIds = (doc, sheetId, axis) => {
+    const name = lineIdsRootName(sheetId, axis);
+    if (!doc.share.has(name))
+        return [];
+    const ids = [];
+    const seen = new Set();
+    for (const value of doc.getArray(name).toArray()) {
+        const id = lineIdText(value);
+        if (id === null || seen.has(id))
+            continue;
+        seen.add(id);
+        ids.push(id);
+    }
+    return ids;
+};
+/** The `rncCells` / `rncNotes` key of a cell by its line ids. */
+export const createCellKeyV5 = (sheetId, rowId, colId) => `${sheetId}:${rowId}:${colId}`;
+/** Parse a v5 key `"{sheetId}:{rowId}:{colId}"`; null when malformed. */
+export const parseCellKeyV5 = (key) => {
+    const match = CELL_KEY_V5.exec(key);
+    if (!match)
+        return null;
+    const sheetId = Number(match[1]);
+    const rowId = BigInt(match[2]);
+    const colId = BigInt(match[3]);
+    if (!Number.isSafeInteger(sheetId) ||
+        BigInt.asIntN(64, rowId) !== rowId ||
+        BigInt.asIntN(64, colId) !== colId) {
+        return null;
+    }
+    return { sheetId, rowId: rowId.toString(), colId: colId.toString() };
+};
+const isPlainObject = (value) => value !== null &&
+    typeof value === "object" &&
+    Object.getPrototypeOf(value) === Object.prototype;
+/** A stored v5 value as `CellData` without the engine-owned `ft`; null for a tombstone. */
+const cellDataV5 = (value) => {
+    if (!isPlainObject(value))
+        return null;
+    const { ft: _ft, ...cell } = value;
+    return cell;
+};
+const toPositions = (ids) => new Map(ids.map((id, i) => [id, i + 1]));
+/** The line index of a sheet, read once per call site into `cache`. */
+const sheetLinesV5 = (doc, cache, sheetId) => {
+    let lines = cache.get(sheetId);
+    if (!lines) {
+        lines = {
+            rows: toPositions(readLineIds(doc, sheetId, "row")),
+            cols: toPositions(readLineIds(doc, sheetId, "column")),
+        };
+        cache.set(sheetId, lines);
+    }
+    return lines;
+};
+/** 1-based `[row, col]` of a parsed key; null for an orphan (a deleted or unknown line). */
+const positionV5 = (doc, cache, { sheetId, rowId, colId }) => {
+    const { rows, cols } = sheetLinesV5(doc, cache, sheetId);
+    const row = rows.get(rowId);
+    const col = cols.get(colId);
+    return row === undefined || col === undefined ? null : [row, col];
+};
+// ── style plane (encode_style_ops, fold_style_ops, CellFormat::merge) ───────
+const isStyleReference = (format) => isPlainObject(format) && ("sid" in format || "styleId" in format);
+/**
+ * `CellFormat::merge`: each set property of `patch` wins; `textFormat` and
+ * `borders` merge one level deep; a `""` colour removes it. Pure (both inputs
+ * may be frozen). `mergeFormat({}, f)` = `into_normalized`.
+ */
+const mergeFormat = (base, patch) => {
+    const out = { ...base };
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null || value === undefined)
+            continue;
+        if ((key === "textFormat" || key === "borders") && isPlainObject(value)) {
+            const prev = out[key];
+            const nested = isPlainObject(prev) ? { ...prev } : {};
+            for (const [k, v] of Object.entries(value)) {
+                if (v === null || v === undefined)
+                    continue;
+                if (key === "textFormat" && k === "color" && v === "")
+                    delete nested[k];
+                else
+                    nested[k] = v;
+            }
+            out[key] = nested;
+        }
+        else if ((key === "backgroundColor" || key === "foregroundColor") &&
+            value === "") {
+            delete out[key];
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+};
+/** A cell's `uf` comparable with the composed plane: unset fields dropped; a reference as is. */
+const normalizedFormat = (format) => isPlainObject(format) && !isStyleReference(format)
+    ? mergeFormat({}, format)
+    : (format ?? null);
+const letterIndex = (letters) => letters.split("").reduce((n, ch) => n * 26 + ch.charCodeAt(0) - 64, 0);
+/** Fold one log buffer onto `overlay`; a truncated buffer keeps the ops before the cut. */
+const foldStyleBuffer = (overlay, buf) => {
+    const decoder = decoding.createDecoder(buf);
+    if (!decoding.hasContent(decoder))
+        return;
+    const version = decoding.readUint8(decoder);
+    if (version !== STYLE_LOG_V1 && version !== STYLE_LOG_V2)
+        return;
+    try {
+        while (decoding.hasContent(decoder)) {
+            const sheet = decoding.readBigInt64(decoder);
+            const [row, col] = version === STYLE_LOG_V1
+                ? [c0Id(decoding.readVarUint(decoder)), c0Id(decoding.readVarUint(decoder))]
+                : [
+                    decoding.readBigInt64(decoder).toString(),
+                    decoding.readBigInt64(decoder).toString(),
+                ];
+            const value = decoding.readAny(decoder);
+            const key = `${sheet}:${row}:${col}`;
+            // A `STYLE_LOG_BASE_SENTINEL_SHEET` op is a clear of a cell that cannot exist.
+            if (value === null || value === undefined) {
+                overlay.delete(key);
+            }
+            else if (isPlainObject(value)) {
+                const prev = overlay.get(key);
+                overlay.set(key, mergeFormat(prev ?? {}, value));
+            }
+        }
+    }
+    catch (_e) {
+        // Reading past the end: the buffer stops here, as `fold_style_ops` does.
+    }
+};
+/**
+ * The composed style plane of a v5 doc (`refold_style_overlay`): the legacy
+ * `rncCellStyles` seed (`"{sheetId}!{A1}"`, the client-0 ids of that position)
+ * with every `rncCellStylesLog` buffer folded on in array order. Walks the log.
+ */
+export const readStyleOverlayV5 = (doc) => {
+    const overlay = new Map();
+    if (doc.share.has(STYLES_SEED_V5)) {
+        doc.getMap(STYLES_SEED_V5).forEach((value, key) => {
+            const match = SEED_KEY.exec(key);
+            if (!match || !isPlainObject(value))
+                return;
+            const row = c0Id(Number(match[3]));
+            const col = c0Id(letterIndex(match[2]));
+            overlay.set(`${BigInt(match[1])}:${row}:${col}`, mergeFormat({}, value));
+        });
+    }
+    if (doc.share.has(STYLES_LOG_V5)) {
+        for (const buf of doc.getArray(STYLES_LOG_V5).toArray()) {
+            if (buf instanceof Uint8Array)
+                foldStyleBuffer(overlay, buf);
+        }
+    }
+    return overlay;
+};
+/** `STYLE_LOG_V2`, then per op `i64 sheet, i64 rowId, i64 colId` (big-endian) and one `Any`. */
+const encodeStyleOps = (ops) => {
+    const encoder = encoding.createEncoder();
+    encoding.writeUint8(encoder, STYLE_LOG_V2);
+    for (const [sheetId, rowId, colId, format] of ops) {
+        encoding.writeBigInt64(encoder, BigInt(sheetId));
+        encoding.writeBigInt64(encoder, BigInt(rowId));
+        encoding.writeBigInt64(encoder, BigInt(colId));
+        encoding.writeAny(encoder, format);
+    }
+    return encoding.toUint8Array(encoder);
+};
+// ── cold blocks (encode_cell_block, decode_cell_block_bodies, block_row_offsets) ──
+/** Row offsets of a block from its uncompressed header (no inflate). */
+const blockRowOffsets = (buf) => {
+    if (buf.length < 4)
+        return [];
+    const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+    const first = view.getUint32(0, true);
+    const out = [];
+    if (first & BLOCK_V2_MAGIC) {
+        const count = Math.min(buf.length >= 8 ? view.getUint32(4, true) : 0, BLOCK_ROWS);
+        if (first & BLOCK_V2_DENSE) {
+            for (let i = 0; i < count; i++)
+                out.push(i);
+            return out;
+        }
+        for (let i = 0, pos = 8; i < count && pos + 4 <= buf.length; i++, pos += 4) {
+            out.push(view.getUint32(pos, true));
+        }
+        return out;
+    }
+    for (let i = 0, pos = 4; i < first && pos + 8 <= buf.length; i++) {
+        out.push(view.getUint32(pos, true));
+        pos += 8 + view.getUint32(pos + 4, true);
+    }
+    return out;
+};
+/** Whether `rowId`'s client-0 counter has an entry in the column's block (header only). */
+const coldCellExists = (doc, cache, sheetId, rowId, colId) => {
+    const counter = c0Counter(rowId);
+    if (!counter || !doc.share.has(BLOCKS_V5))
+        return false;
+    const key = `${sheetId}:${colId}:${Math.floor((counter - 1) / BLOCK_ROWS)}`;
+    let offsets = cache.get(key);
+    if (!offsets) {
+        const buf = doc.getMap(BLOCKS_V5).get(key);
+        offsets = new Set(buf instanceof Uint8Array ? blockRowOffsets(buf) : []);
+        cache.set(key, offsets);
+    }
+    return offsets.has((counter - 1) % BLOCK_ROWS);
+};
+// ── readers ─────────────────────────────────────────────────────────────────
+/**
+ * The cell under `key` as the readers show it: the hot value (`ft` stripped),
+ * `uf` from `styles` where it has an entry, `note` from `rncNotes` where it has
+ * one. Null when none of the three holds anything.
+ */
+const composeCell = (doc, key, styles) => {
+    let cell = doc.share.has(CELLS_V5)
+        ? cellDataV5(doc.getMap(CELLS_V5).get(key))
+        : null;
+    const uf = styles.get(key);
+    if (uf)
+        cell = { ...cell, uf };
+    const note = doc.share.has(NOTES_V5) ? doc.getMap(NOTES_V5).get(key) : undefined;
+    if (typeof note === "string")
+        cell = { ...cell, note };
+    return cell;
+};
+/**
+ * A v5 doc as V2 `SheetData` (same shape as `sheetDataV3ToV2`), hot plane only:
+ * every key of `rncCells`, `rncNotes` and the composed style plane composed as
+ * `composeCell` does (tombstones and orphans skipped).
+ */
+export const sheetDataV5ToV2 = (doc, styles = readStyleOverlayV5(doc)) => {
+    const sheetData = {};
+    const cache = new Map();
+    const keys = new Set(styles.keys());
+    for (const name of [CELLS_V5, NOTES_V5]) {
+        if (doc.share.has(name))
+            for (const key of doc.getMap(name).keys())
+                keys.add(key);
+    }
+    for (const key of keys) {
+        const parsed = parseCellKeyV5(key);
+        const pos = parsed && positionV5(doc, cache, parsed);
+        const cell = pos && composeCell(doc, key, styles);
+        if (!parsed || !pos || !cell)
+            continue;
+        const [rowIdx, colIdx] = pos;
+        const rows = (sheetData[parsed.sheetId] ??= []);
+        while (rows.length <= rowIdx)
+            rows.push(null);
+        const row = (rows[rowIdx] ??= { values: [] });
+        if (!row.values)
+            row.values = [];
+        while (row.values.length <= colIdx)
+            row.values.push(null);
+        row.values[colIdx] = cell;
+    }
+    return sheetData;
+};
+/**
+ * A reader of the cell at a 1-based position (`composeCell`), line ids read once
+ * per sheet. Undefined when nothing is there or the line is unnamed.
+ */
+export const createCellReaderV5 = (doc, styles = readStyleOverlayV5(doc)) => {
+    const lines = new Map();
+    return (sheetId, rowIndex, columnIndex) => {
+        let ids = lines.get(sheetId);
+        if (!ids) {
+            ids = [readLineIds(doc, sheetId, "row"), readLineIds(doc, sheetId, "column")];
+            lines.set(sheetId, ids);
+        }
+        const rowId = ids[0][rowIndex - 1];
+        const colId = ids[1][columnIndex - 1];
+        if (rowId === undefined || colId === undefined)
+            return undefined;
+        return composeCell(doc, createCellKeyV5(sheetId, rowId, colId), styles) ?? undefined;
+    };
+};
+/** `createCellReaderV5` for one cell (reads both id arrays: O(lines)). */
+export const getCellV5 = (doc, sheetId, rowIndex, columnIndex, styles) => createCellReaderV5(doc, styles)(sheetId, rowIndex, columnIndex);
+/**
+ * Apply changed `rncCells` / `rncNotes` keys to `currentSheetData` (copy-on-write,
+ * like `processSheetDataEventsV3`), `uf` from `styles`. Only valid while no id
+ * array and no style changed (those need `sheetDataV5ToV2`). Null when nothing changed.
+ */
+export const processSheetDataChangesV5 = (changedKeys, currentSheetData, doc, styles = readStyleOverlayV5(doc)) => {
+    const cache = new Map();
+    const next = { ...currentSheetData };
+    const clonedSheets = new Set();
+    const clonedRows = new Set();
+    let hasChanges = false;
+    for (const key of new Set(changedKeys)) {
+        const parsed = parseCellKeyV5(key);
+        const pos = parsed && positionV5(doc, cache, parsed);
+        if (!parsed || !pos)
+            continue;
+        const [rowIdx, colIdx] = pos;
+        const { sheetId } = parsed;
+        const cell = composeCell(doc, key, styles);
+        const row = next[sheetId]?.[rowIdx];
+        if (!cell && !row?.values?.[colIdx])
+            continue;
+        if (!clonedSheets.has(sheetId)) {
+            next[sheetId] = [...(next[sheetId] ?? [])];
+            clonedSheets.add(sheetId);
+        }
+        const sheet = next[sheetId];
+        if (sheet.length <= rowIdx)
+            sheet.length = rowIdx + 1;
+        const rowKey = `${sheetId}:${rowIdx}`;
+        if (!clonedRows.has(rowKey)) {
+            const prev = sheet[rowIdx];
+            sheet[rowIdx] = { ...prev, values: prev?.values ? [...prev.values] : [] };
+            clonedRows.add(rowKey);
+        }
+        const values = sheet[rowIdx].values;
+        if (values.length <= colIdx)
+            values.length = colIdx + 1;
+        values[colIdx] = cell;
+        hasChanges = true;
+    }
+    return hasChanges ? next : null;
+};
+const axisKey = (sheetId, isRow) => `${sheetId}:${isRow ? "R" : "C"}`;
+const writerStyles = (w) => (w.styles ??= readStyleOverlayV5(w.doc));
+const writerAxis = (w, sheetId, isRow) => {
+    const key = axisKey(sheetId, isRow);
+    let axis = w.axes.get(key);
+    if (!axis) {
+        const ids = readLineIds(w.doc, sheetId, isRow ? "row" : "column");
+        axis = { ids, maxC0: ids.reduce((max, id) => Math.max(max, c0Counter(id)), 0) };
+        w.axes.set(key, axis);
+    }
+    return axis;
+};
+/**
+ * `YrsStore::c0_floor` of every sheet and axis, keyed by `axisKey`: the highest
+ * client-0 counter any hot key (tombstones and orphans too), composed style,
+ * note, dimension or cold block references. One pass over the keys.
+ */
+const c0Floors = (doc, styles) => {
+    const floors = new Map();
+    const raise = (sheetId, isRow, counter) => {
+        const key = axisKey(Number(sheetId), isRow);
+        if (counter > (floors.get(key) ?? 0))
+            floors.set(key, counter);
+    };
+    const cellKey = (key) => {
+        const match = CELL_KEY_V5.exec(key);
+        if (!match)
+            return;
+        raise(match[1], true, c0Counter(match[2]));
+        raise(match[1], false, c0Counter(match[3]));
+    };
+    for (const name of [CELLS_V5, NOTES_V5]) {
+        if (doc.share.has(name))
+            doc.getMap(name).forEach((_v, key) => cellKey(key));
+    }
+    styles.forEach((_v, key) => cellKey(key));
+    if (doc.share.has(DIMS_V5)) {
+        doc.getMap(DIMS_V5).forEach((_v, key) => {
+            const match = DIM_KEY_V5.exec(key);
+            if (match && idCounter(BigInt(match[3])) !== 0) {
+                raise(match[1], match[2] === "R", c0Counter(match[3]));
+            }
+        });
+    }
+    if (doc.share.has(BLOCKS_V5)) {
+        // Rows: the last offset of each column's highest block (`block_c0_max`).
+        const top = new Map();
+        doc.getMap(BLOCKS_V5).forEach((value, key) => {
+            const match = BLOCK_KEY_V5.exec(key);
+            if (!match || idCounter(BigInt(match[2])) === 0)
+                return;
+            raise(match[1], false, c0Counter(match[2]));
+            const block = Number(match[3]);
+            const col = `${match[1]}:${match[2]}`;
+            if (value instanceof Uint8Array && block >= (top.get(col)?.[1] ?? -1)) {
+                top.set(col, [match[1], block, value]);
+            }
+        });
+        top.forEach(([sheetId, block, buf]) => {
+            const offsets = blockRowOffsets(buf);
+            if (offsets.length) {
+                raise(sheetId, true, block * BLOCK_ROWS + Math.max(...offsets) + 1);
+            }
+        });
+    }
+    return floors;
+};
+/**
+ * The id of 1-based line `pos`, naming every line up to it first: implicit
+ * client-0 ids, counters past the axis's highest client-0 counter and past the
+ * floor (`AxisIndex::ensure_len`), appended at the array's end.
+ */
+const ensureLine = (w, sheetId, isRow, pos) => {
+    const axis = writerAxis(w, sheetId, isRow);
+    if (pos > axis.ids.length) {
+        w.floors ??= c0Floors(w.doc, writerStyles(w));
+        const start = Math.max(axis.maxC0, w.floors.get(axisKey(sheetId, isRow)) ?? 0) + 1;
+        const counters = Array.from({ length: pos - axis.ids.length }, (_, i) => start + i);
+        w.doc
+            .getArray(lineIdsRootName(sheetId, isRow ? "row" : "column"))
+            .push(counters.map(idValue));
+        axis.ids.push(...counters.map(c0Id));
+        axis.maxC0 = start + counters.length - 1;
+    }
+    return axis.ids[pos - 1];
+};
+const validPosition = (row, col) => Number.isInteger(row) && Number.isInteger(col) && row >= 1 && col >= 1;
+/** Queues a style op and applies it to the writer's composed plane. */
+const queueStyle = (w, sheetId, rowId, colId, format) => {
+    w.ops.push([sheetId, rowId, colId, format]);
+    const key = createCellKeyV5(sheetId, rowId, colId);
+    if (format)
+        writerStyles(w).set(key, format);
+    else
+        writerStyles(w).delete(key);
+};
+/**
+ * Writes `cell` at a position. A `uf` that differs from the stored one (the
+ * composed plane's entry, else the inline `uf`) is logged as a replace (a
+ * clear, then the format; a style reference only clears: the engine cannot
+ * resolve it). A note lives in `rncNotes` when the key has an entry there,
+ * inline otherwise. An unchanged cell is not rewritten (its `ft` survives).
+ */
+const writeCell = (w, sheetId, row, col, cell) => {
+    if (!validPosition(row, col))
+        return;
+    const rowId = ensureLine(w, sheetId, true, row);
+    const colId = ensureLine(w, sheetId, false, col);
+    const key = createCellKeyV5(sheetId, rowId, colId);
+    const stored = cellDataV5(w.cells.get(key));
+    const format = normalizedFormat(getCellUserEnteredFormat(cell));
+    const storedFormat = normalizedFormat(writerStyles(w).get(key) ?? getCellUserEnteredFormat(stored));
+    if (!isEqual(format, storedFormat)) {
+        queueStyle(w, sheetId, rowId, colId, null);
+        if (isPlainObject(format) && !isStyleReference(format)) {
+            queueStyle(w, sheetId, rowId, colId, format);
+        }
+    }
+    let next = cell;
+    const notes = w.doc.share.has(NOTES_V5) ? w.doc.getMap(NOTES_V5) : null;
+    if (notes?.has(key)) {
+        const { note, ...rest } = cell;
+        if (typeof note === "string" && note) {
+            if (notes.get(key) !== note)
+                notes.set(key, note);
+        }
+        else {
+            notes.delete(key);
+        }
+        next = rest;
+    }
+    if (!stored || !isEqual(stored, next))
+        w.cells.set(key, next);
+};
+/**
+ * Removes the cell at a position (`remove_cell`): a hot `null` when a cold block
+ * holds it, else the hot entry is dropped; its composed style is cleared and its
+ * `rncNotes` entry removed. An unnamed position holds nothing.
+ */
+const removeCell = (w, sheetId, row, col) => {
+    if (!validPosition(row, col))
+        return;
+    const rowId = writerAxis(w, sheetId, true).ids[row - 1];
+    const colId = writerAxis(w, sheetId, false).ids[col - 1];
+    if (rowId === undefined || colId === undefined)
+        return;
+    const key = createCellKeyV5(sheetId, rowId, colId);
+    if (coldCellExists(w.doc, w.offsets, sheetId, rowId, colId)) {
+        if (w.cells.get(key) !== null)
+            w.cells.set(key, null);
+    }
+    else if (w.cells.has(key)) {
+        w.cells.delete(key);
+    }
+    if (writerStyles(w).has(key))
+        queueStyle(w, sheetId, rowId, colId, null);
+    if (w.doc.share.has(NOTES_V5)) {
+        const notes = w.doc.getMap(NOTES_V5);
+        if (notes.has(key))
+            notes.delete(key);
+    }
+};
+/** The cells of a row value (`{ values }`), by 1-based column. */
+const rowCells = (row) => {
+    const out = new Map();
+    const values = isPlainObject(row) ? row.values : undefined;
+    if (values && typeof values === "object") {
+        for (const [col, cell] of Object.entries(values)) {
+            if (isPlainObject(cell))
+                out.set(Number(col), cell);
+        }
+    }
+    return out;
+};
+/** Replaces a whole row: every named column the new row leaves empty is removed. */
+const replaceRow = (w, sheetId, row, value) => {
+    if (!Number.isInteger(row) || row < 1)
+        return;
+    const cells = rowCells(value);
+    const named = writerAxis(w, sheetId, false).ids.length;
+    for (let col = 1; col <= named; col++) {
+        if (!cells.has(col))
+            removeCell(w, sheetId, row, col);
+    }
+    cells.forEach((cell, col) => writeCell(w, sheetId, row, col, cell));
+};
+const writeSheet = (w, sheetId, rows) => {
+    if (!rows || typeof rows !== "object")
+        return;
+    for (const [row, value] of Object.entries(rows)) {
+        rowCells(value).forEach((cell, col) => writeCell(w, sheetId, Number(row), col, cell));
+    }
+};
+/**
+ * Removes every cell of the matching sheets (`remove_sheet`'s point data): hot
+ * keys (orphans and tombstones too), cold blocks, composed styles (clear ops)
+ * and legacy seed entries, notes. Walks those planes; id arrays and dimensions stay.
+ */
+const clearSheets = (w, match) => {
+    const sheetOf = (key) => Number(key.slice(0, Math.max(0, key.search(/[:!]/))));
+    const drop = (name) => {
+        if (!w.doc.share.has(name))
+            return;
+        const map = w.doc.getMap(name);
+        for (const key of Array.from(map.keys())) {
+            if (match(sheetOf(key)))
+                map.delete(key);
+        }
+    };
+    drop(CELLS_V5);
+    drop(BLOCKS_V5);
+    drop(NOTES_V5);
+    drop(STYLES_SEED_V5);
+    for (const key of Array.from(writerStyles(w).keys())) {
+        const parsed = parseCellKeyV5(key);
+        if (parsed && match(parsed.sheetId)) {
+            queueStyle(w, parsed.sheetId, parsed.rowId, parsed.colId, null);
+        }
+    }
+    w.offsets.clear();
+};
+/** The cell a nested patch edits: the stored cell as the readers show it. */
+const nestedBase = (w, sheetId, row, col) => {
+    const rowId = writerAxis(w, sheetId, true).ids[row - 1];
+    const colId = writerAxis(w, sheetId, false).ids[col - 1];
+    if (rowId === undefined || colId === undefined)
+        return {};
+    const key = createCellKeyV5(sheetId, rowId, colId);
+    if (!w.cells.has(key) && coldCellExists(w.doc, w.offsets, sheetId, rowId, colId)) {
+        return null;
+    }
+    return composeCell(w.doc, key, writerStyles(w)) ?? {};
+};
+const applyPatchV5 = (w, { op, path, value }) => {
+    if (path.length === 0) {
+        if (op === "replace")
+            clearSheets(w, () => true);
+        if (value && typeof value === "object") {
+            for (const [sheetId, rows] of Object.entries(value)) {
+                writeSheet(w, Number(sheetId), rows);
+            }
+        }
+        return;
+    }
+    const sheetId = Number(path[0]);
+    const row = Number(path[1]);
+    if (path.length > 4) {
+        const col = Number(path[3]);
+        if (!validPosition(row, col))
+            return;
+        const base = nestedBase(w, sheetId, row, col);
+        if (base === null) {
+            // Cold-only cell: its body needs an async inflate, a sync writer cannot merge into it.
+            console.warn(`y-spreadsheet v5: nested patch on cold cell ${sheetId}!R${row}C${col} skipped`);
+            return;
+        }
+        const cell = cloneDeep(base);
+        const nested = path.slice(4);
+        if (op === "remove") {
+            if (!Object.keys(base).length)
+                return;
+            unset(cell, nested);
+        }
+        else {
+            set(cell, nested, cloneDeep(value));
+        }
+        writeCell(w, sheetId, row, col, cell);
+    }
+    else if (path.length === 3 && path[2] === "values") {
+        if (op !== "remove")
+            replaceRow(w, sheetId, row, { values: value });
+    }
+    else if (path.length === 2) {
+        replaceRow(w, sheetId, row, op === "remove" ? null : value);
+    }
+    else if (path.length === 1) {
+        clearSheets(w, (id) => id === sheetId);
+        if (op !== "remove")
+            writeSheet(w, sheetId, value);
+    }
+};
+/**
+ * Apply immer `SheetData` patches to a v5 doc in one transaction (`origin`, the
+ * caller's; nested in an open transaction it joins that one). Positional, like
+ * the v3 path: a row insert/delete arrives as rewritten rows and is applied as
+ * cell writes/removals at each position's line ids; no line is inserted or
+ * deleted. Writes past an axis name lines (client-0 padding, `ensure_lines`).
+ * `uf` changes append ONE `STYLE_LOG_V2` buffer to `rncCellStylesLog` and stay
+ * inline on the cell. `styles`, when given, is the caller's composed style plane
+ * (`readStyleOverlayV5`), used instead of folding the log and updated in place.
+ */
+export const addSheetDataPatchesV5 = (doc, patches, origin = null, styles) => {
+    if (!patches?.length)
+        return;
+    doc.transact(() => {
+        const w = {
+            doc,
+            cells: doc.getMap(CELLS_V5),
+            axes: new Map(),
+            floors: null,
+            styles: styles ?? null,
+            ops: [],
+            offsets: new Map(),
+        };
+        // Consecutive cell patches are consolidated (the later one wins) but never
+        // reordered across a row-, sheet- or document-level patch (v3 parity).
+        const pending = new Map();
+        const flush = () => {
+            pending.forEach(([sheetId, row, col, cell]) => cell ? writeCell(w, sheetId, row, col, cell) : removeCell(w, sheetId, row, col));
+            pending.clear();
+        };
+        for (const patch of patches) {
+            const { op, path, value } = patch;
+            if (path.length === 4 &&
+                (op === "replace" || op === "add" || op === "remove")) {
+                const [sheetId, row, , col] = path.map(Number);
+                pending.set(`${sheetId}:${row}:${col}`, [
+                    sheetId,
+                    row,
+                    col,
+                    op !== "remove" && isPlainObject(value) ? value : null,
+                ]);
+                continue;
+            }
+            flush();
+            applyPatchV5(w, patch);
+        }
+        flush();
+        if (w.ops.length) {
+            doc.getArray(STYLES_LOG_V5).push([encodeStyleOps(w.ops)]);
+        }
+    }, origin);
+};
+/** Set one cell of a v5 doc (see `addSheetDataPatchesV5`). */
+export const setCellV5 = (doc, sheetId, rowIndex, columnIndex, value) => addSheetDataPatchesV5(doc, [
+    { op: "replace", path: [sheetId, rowIndex, "values", columnIndex], value },
+]);
+/** Remove one cell of a v5 doc (see `addSheetDataPatchesV5`). */
+export const deleteCellV5 = (doc, sheetId, rowIndex, columnIndex) => addSheetDataPatchesV5(doc, [
+    { op: "remove", path: [sheetId, rowIndex, "values", columnIndex] },
+]);
+/** Remove every cell of a sheet of a v5 doc; its line ids and dimensions stay. */
+export const deleteSheetV5 = (doc, sheetId) => addSheetDataPatchesV5(doc, [{ op: "remove", path: [sheetId] }]);