@rowsncolumns/rnc-yrs-store 0.11.17 → 0.13.0-beta.0

package/dist/rnc_yrs_store.d.ts

@@ -2,13 +2,19 @@
 /* eslint-disable */
 
 /**
- * Thin wasm-bindgen shell over [`YDocEngine`]. Bytes cross as `Uint8Array` (`Vec<u8>`/`&[u8]`),
- * results as JSON strings — matching `YrsSheetDoc`, so it builds for both wasm and native.
+ * Thin wasm-bindgen shell over the engine router ([`DualEngine`]: the positional v3 store or the
+ * stable-ids v5 store, by document). Bytes cross as `Uint8Array` (`Vec<u8>`/`&[u8]`), results as
+ * JSON strings, so it builds for both wasm and native.
  */
 export class SpreadsheetEngine {
     free(): void;
     [Symbol.dispose](): void;
     addSheet(sheet_id: number, title: string): void;
+    /**
+     * Anchor a `GridRange` on `sheet_id`: an opaque string (base64 stable range) that
+     * `resolveAnchor` resolves later, on any replica, through any structural edit.
+     */
+    anchorRange(sheet_id: number, range_json: string): string;
     applyCommand(json: string): string;
     /**
      * `applyCommand` without write recording, undo history, or a `CommitResult` diff — and with
@@ -33,6 +39,10 @@ export class SpreadsheetEngine {
      * Drop the entire undo/redo history (`SpreadsheetEngineLike.clearHistory`).
      */
     clearHistory(): void;
+    /**
+     * JSON array of the sheet's column ids in grid order, as decimal strings.
+     */
+    columnIds(sheet_id: number): string;
     /**
      * Fold the style log into a base, keeping the newest `keep_tail` buffers live (see
      * `YrsStore::compact_style_log`). Meant for a host holding the workbook write lease (a server
@@ -45,7 +55,7 @@ export class SpreadsheetEngine {
      * as JSON `Vec<Vec<String>>`. The host writes the grid into the sheet via a `change-batch` command
      * so the values compute, persist, and collaborate through the normal engine path. Quoting,
      * embedded newlines, and ragged rows are handled by the `csv` crate.
-     * RFC 4180 CSV of one sheet's merged view (blocks + hot plane, geometry-aware). Formulas
+     * RFC 4180 CSV of one sheet's merged view (blocks + hot plane, at current positions). Formulas
      * export their computed display value, like Excel/Sheets "Save as CSV". One streaming pass
      * over the store — built to run in a Web Worker for million-row sheets.
      * Excel-style Ctrl/Cmd+Arrow target. One of `d_row`/`d_col` is ±1, the other 0; returns
@@ -224,6 +234,11 @@ export class SpreadsheetEngine {
     loadFromUpdateQuiet(bytes: Uint8Array): void;
     constructor();
     parseCsv(text: string): string;
+    /**
+     * JSON `{sheetId, row, col}` (1-based) of an `rncCells` / `rncNotes` key; `undefined` for a
+     * malformed key or an orphan (its row or column was deleted).
+     */
+    parseStableCellKey(key: string): string | undefined;
     /**
      * PRECEDENTS of a cell as `{cells, ranges}` JSON (`SpreadsheetEngineLike.precedents`).
      */
@@ -261,11 +276,33 @@ export class SpreadsheetEngine {
      * Register a host (JS) custom-function name (`SpreadsheetEngineLike.registerCustomFunction`).
      */
     registerCustomFunction(name: string): void;
+    /**
+     * JSON `{range: GridRange | null, status: "ok" | "gone" | "unknown"}` for an `anchorRange`
+     * anchor: `gone` once every row or column of it was deleted, `unknown` while its lines have
+     * not arrived on this replica; a malformed anchor is an `Err`.
+     */
+    resolveAnchor(anchor: string): string;
+    /**
+     * JSON array of the sheet's row ids in grid order, as decimal strings.
+     */
+    rowIds(sheet_id: number): string;
+    /**
+     * Create stable-ids (v5) documents with this engine; off by default. On, a document it creates
+     * starts as v5 — its first edit or import on a fresh engine, or a loaded document that holds no
+     * data yet. A document that holds data is never converted (existing documents stay v3), and a
+     * v5 document always runs as v5, whatever the setting. Set it from the asset's chosen version,
+     * for everyone who opens the asset. `true` when the call made the open (blank) document v5.
+     */
+    setStableIds(enabled: boolean): boolean;
     /**
      * Pin the evaluation timezone for `TODAY()` / `NOW()` as minutes east of UTC (`null` /
      * `undefined` restores the default `Local` clock). Returns `false` for an offset outside ±24h.
      */
     setTimezoneOffsetMinutes(minutes?: number | null): boolean;
+    /**
+     * `"v5"` while the document runs on the stable-ids store, else `"v3"`.
+     */
+    sheetDataVersion(): string;
     /**
      * Per-sheet 1-based data extents as JSON `[{"sheetId", "maxRow", "maxCol"}]`.
      */
@@ -294,6 +331,11 @@ export class SpreadsheetEngine {
      * [`YrsStore::shift_log_frontier`]).
      */
     shiftLogFrontier(): string;
+    /**
+     * The `rncCells` key (`"{sheetId}:{rowId}:{colId}"`) of 1-based `(row, col)`; `undefined`
+     * while the row or column is unnamed (past the sheet's named extent). Never names lines.
+     */
+    stableCellKey(sheet_id: number, row: number, col: number): string | undefined;
     stateAsUpdate(): Uint8Array;
     /**
      * JSON `{buffers, baseBuffers, bytes, seedEntries, styledCells}` — the style history a load
@@ -336,7 +378,9 @@ export class SpreadsheetEngine {
 }
 
 /**
- * Minimal yrs-backed sheet doc exposing the canonical `sheetDataV3` encoding + yjs v1 transport.
+ * Minimal positional (`sheetDataV3`) sheet doc + yjs v1 transport — the R0 interop spike, kept
+ * for the fixture tooling that reads a room the way the engine reads it. It knows the v3 plane
+ * only: a v5 document's cells are in `rncCells` (`libs/rnc-yrs-store/docs/v5-document-encoding.md`).
  */
 export class YrsSheetDoc {
     free(): void;
@@ -412,7 +456,9 @@ export interface InitOutput {
     readonly spreadsheetengine_redo: (a: number) => [number, number];
     readonly spreadsheetengine_redoDepth: (a: number) => number;
     readonly spreadsheetengine_registerCustomFunction: (a: number, b: number, c: number) => void;
+    readonly spreadsheetengine_setStableIds: (a: number, b: number) => [number, number, number];
     readonly spreadsheetengine_setTimezoneOffsetMinutes: (a: number, b: number) => number;
+    readonly spreadsheetengine_sheetDataVersion: (a: number) => [number, number];
     readonly spreadsheetengine_sheetExtents: (a: number) => [number, number];
     readonly spreadsheetengine_sheetIds: (a: number) => [number, number];
     readonly spreadsheetengine_sheetStats: (a: number) => [number, number];
@@ -430,6 +476,12 @@ export interface InitOutput {
     readonly yrssheetdoc_new: () => number;
     readonly yrssheetdoc_setCell: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
     readonly spreadsheetengine_stateAsUpdate: (a: number) => [number, number];
+    readonly spreadsheetengine_columnIds: (a: number, b: number) => [number, number];
+    readonly spreadsheetengine_parseStableCellKey: (a: number, b: number, c: number) => [number, number];
+    readonly spreadsheetengine_rowIds: (a: number, b: number) => [number, number];
+    readonly spreadsheetengine_stableCellKey: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly spreadsheetengine_anchorRange: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly spreadsheetengine_resolveAnchor: (a: number, b: number, c: number) => [number, number, number, number];
     readonly spreadsheetengine_shiftLogFrontier: (a: number) => [number, number];
     readonly spreadsheetengine_transformRange: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
     readonly transformRangeThroughOps: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];

package/dist/rnc_yrs_store.js

@@ -1,8 +1,9 @@
 /* @ts-self-types="./rnc_yrs_store.d.ts" */
 
 /**
- * Thin wasm-bindgen shell over [`YDocEngine`]. Bytes cross as `Uint8Array` (`Vec<u8>`/`&[u8]`),
- * results as JSON strings — matching `YrsSheetDoc`, so it builds for both wasm and native.
+ * Thin wasm-bindgen shell over the engine router ([`DualEngine`]: the positional v3 store or the
+ * stable-ids v5 store, by document). Bytes cross as `Uint8Array` (`Vec<u8>`/`&[u8]`), results as
+ * JSON strings, so it builds for both wasm and native.
  */
 export class SpreadsheetEngine {
     __destroy_into_raw() {
@@ -24,6 +25,33 @@ export class SpreadsheetEngine {
         const len0 = WASM_VECTOR_LEN;
         wasm.spreadsheetengine_addSheet(this.__wbg_ptr, sheet_id, ptr0, len0);
     }
+    /**
+     * Anchor a `GridRange` on `sheet_id`: an opaque string (base64 stable range) that
+     * `resolveAnchor` resolves later, on any replica, through any structural edit.
+     * @param {number} sheet_id
+     * @param {string} range_json
+     * @returns {string}
+     */
+    anchorRange(sheet_id, range_json) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(range_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.spreadsheetengine_anchorRange(this.__wbg_ptr, sheet_id, ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
     /**
      * @param {string} json
      * @returns {string}
@@ -113,6 +141,23 @@ export class SpreadsheetEngine {
     clearHistory() {
         wasm.spreadsheetengine_clearHistory(this.__wbg_ptr);
     }
+    /**
+     * JSON array of the sheet's column ids in grid order, as decimal strings.
+     * @param {number} sheet_id
+     * @returns {string}
+     */
+    columnIds(sheet_id) {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.spreadsheetengine_columnIds(this.__wbg_ptr, sheet_id);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * Fold the style log into a base, keeping the newest `keep_tail` buffers live (see
      * `YrsStore::compact_style_log`). Meant for a host holding the workbook write lease (a server
@@ -138,7 +183,7 @@ export class SpreadsheetEngine {
      * as JSON `Vec<Vec<String>>`. The host writes the grid into the sheet via a `change-batch` command
      * so the values compute, persist, and collaborate through the normal engine path. Quoting,
      * embedded newlines, and ragged rows are handled by the `csv` crate.
-     * RFC 4180 CSV of one sheet's merged view (blocks + hot plane, geometry-aware). Formulas
+     * RFC 4180 CSV of one sheet's merged view (blocks + hot plane, at current positions). Formulas
      * export their computed display value, like Excel/Sheets "Save as CSV". One streaming pass
      * over the store — built to run in a Web Worker for million-row sheets.
      * Excel-style Ctrl/Cmd+Arrow target. One of `d_row`/`d_col` is ±1, the other 0; returns
@@ -761,6 +806,23 @@ export class SpreadsheetEngine {
             wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
         }
     }
+    /**
+     * JSON `{sheetId, row, col}` (1-based) of an `rncCells` / `rncNotes` key; `undefined` for a
+     * malformed key or an orphan (its row or column was deleted).
+     * @param {string} key
+     * @returns {string | undefined}
+     */
+    parseStableCellKey(key) {
+        const ptr0 = passStringToWasm0(key, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.spreadsheetengine_parseStableCellKey(this.__wbg_ptr, ptr0, len0);
+        let v2;
+        if (ret[0] !== 0) {
+            v2 = getStringFromWasm0(ret[0], ret[1]).slice();
+            wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        }
+        return v2;
+    }
     /**
      * PRECEDENTS of a cell as `{cells, ranges}` JSON (`SpreadsheetEngineLike.precedents`).
      * @param {number} sheet_id
@@ -897,6 +959,66 @@ export class SpreadsheetEngine {
         const len0 = WASM_VECTOR_LEN;
         wasm.spreadsheetengine_registerCustomFunction(this.__wbg_ptr, ptr0, len0);
     }
+    /**
+     * JSON `{range: GridRange | null, status: "ok" | "gone" | "unknown"}` for an `anchorRange`
+     * anchor: `gone` once every row or column of it was deleted, `unknown` while its lines have
+     * not arrived on this replica; a malformed anchor is an `Err`.
+     * @param {string} anchor
+     * @returns {string}
+     */
+    resolveAnchor(anchor) {
+        let deferred3_0;
+        let deferred3_1;
+        try {
+            const ptr0 = passStringToWasm0(anchor, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+            const len0 = WASM_VECTOR_LEN;
+            const ret = wasm.spreadsheetengine_resolveAnchor(this.__wbg_ptr, ptr0, len0);
+            var ptr2 = ret[0];
+            var len2 = ret[1];
+            if (ret[3]) {
+                ptr2 = 0; len2 = 0;
+                throw takeFromExternrefTable0(ret[2]);
+            }
+            deferred3_0 = ptr2;
+            deferred3_1 = len2;
+            return getStringFromWasm0(ptr2, len2);
+        } finally {
+            wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+        }
+    }
+    /**
+     * JSON array of the sheet's row ids in grid order, as decimal strings.
+     * @param {number} sheet_id
+     * @returns {string}
+     */
+    rowIds(sheet_id) {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.spreadsheetengine_rowIds(this.__wbg_ptr, sheet_id);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+    /**
+     * Create stable-ids (v5) documents with this engine; off by default. On, a document it creates
+     * starts as v5 — its first edit or import on a fresh engine, or a loaded document that holds no
+     * data yet. A document that holds data is never converted (existing documents stay v3), and a
+     * v5 document always runs as v5, whatever the setting. Set it from the asset's chosen version,
+     * for everyone who opens the asset. `true` when the call made the open (blank) document v5.
+     * @param {boolean} enabled
+     * @returns {boolean}
+     */
+    setStableIds(enabled) {
+        const ret = wasm.spreadsheetengine_setStableIds(this.__wbg_ptr, enabled);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return ret[0] !== 0;
+    }
     /**
      * Pin the evaluation timezone for `TODAY()` / `NOW()` as minutes east of UTC (`null` /
      * `undefined` restores the default `Local` clock). Returns `false` for an offset outside ±24h.
@@ -907,6 +1029,22 @@ export class SpreadsheetEngine {
         const ret = wasm.spreadsheetengine_setTimezoneOffsetMinutes(this.__wbg_ptr, isLikeNone(minutes) ? Number.MAX_SAFE_INTEGER : (minutes) >> 0);
         return ret !== 0;
     }
+    /**
+     * `"v5"` while the document runs on the stable-ids store, else `"v3"`.
+     * @returns {string}
+     */
+    sheetDataVersion() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.spreadsheetengine_sheetDataVersion(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * Per-sheet 1-based data extents as JSON `[{"sheetId", "maxRow", "maxCol"}]`.
      * @returns {string}
@@ -989,6 +1127,23 @@ export class SpreadsheetEngine {
             wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * The `rncCells` key (`"{sheetId}:{rowId}:{colId}"`) of 1-based `(row, col)`; `undefined`
+     * while the row or column is unnamed (past the sheet's named extent). Never names lines.
+     * @param {number} sheet_id
+     * @param {number} row
+     * @param {number} col
+     * @returns {string | undefined}
+     */
+    stableCellKey(sheet_id, row, col) {
+        const ret = wasm.spreadsheetengine_stableCellKey(this.__wbg_ptr, sheet_id, row, col);
+        let v1;
+        if (ret[0] !== 0) {
+            v1 = getStringFromWasm0(ret[0], ret[1]).slice();
+            wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        }
+        return v1;
+    }
     /**
      * @returns {Uint8Array}
      */
@@ -1143,7 +1298,9 @@ export class SpreadsheetEngine {
 if (Symbol.dispose) SpreadsheetEngine.prototype[Symbol.dispose] = SpreadsheetEngine.prototype.free;
 
 /**
- * Minimal yrs-backed sheet doc exposing the canonical `sheetDataV3` encoding + yjs v1 transport.
+ * Minimal positional (`sheetDataV3`) sheet doc + yjs v1 transport — the R0 interop spike, kept
+ * for the fixture tooling that reads a room the way the engine reads it. It knows the v3 plane
+ * only: a v5 document's cells are in `rncCells` (`libs/rnc-yrs-store/docs/v5-document-encoding.md`).
  */
 export class YrsSheetDoc {
     __destroy_into_raw() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rowsncolumns/rnc-yrs-store",
-  "version": "0.11.17",
+  "version": "0.13.0-beta.0",
   "author": "Vinay M",
   "license": "SEE LICENSE IN LICENSE.md",
   "description": "Document-backed Rust→WASM spreadsheet calc engine (yrs/CRDT, canonical sheetDataV3). Ships the `SpreadsheetEngine` (a `Store<YrsStore>`): applyCommand / undo / redo / canUndo + the Yjs collaboration surface (applyUpdate / takePendingUpdates / loadFromUpdate / stateAsUpdate) the Keryx update-pump binds to. This is the 1,000,000-row engine the demo-app ships today — previously vendored, now a versioned package. The PREBUILT wasm is included (consumers need NO Rust/wasm toolchain); the glue's default init REQUIRES an explicit `module_or_path` — pass the URL of the served `rnc_yrs_store_bg.wasm` (webpack/Turbopack statically resolve a bundled `new URL`, which would 404 from this package, so the inline-default branch is intentionally a throw).",