@rowsncolumns/rnc-yrs-store 0.8.138

package/LICENSE.md

@@ -0,0 +1,100 @@
+# Rows n' Columns Commercial License Agreement
+
+This Rows n' Columns Commercial License Agreement (the "Agreement") governs
+the use of the Rows n' Columns software packages published under the
+`@rowsncolumns` npm scope, including associated JavaScript, WebAssembly
+binaries, stylesheets, type definitions and documentation (the "Software").
+
+The Software is **not** open source. Downloading or installing the Software
+from a public package registry does not grant any right to use it beyond the
+evaluation use described below.
+
+## 1. Definitions
+
+- **"Licensor"** means Rows n' Columns (rowsncolumns.app).
+- **"Licensee"** means the individual or legal entity identified in an Order.
+- **"Order"** means a purchase of a license for the Software from Licensor,
+  identified by an order ID and associated with a License Key.
+- **"License Key"** means the signed key issued by Licensor that identifies
+  the Licensee, license tier, and Update Window.
+- **"Update Window"** means the period stated in the Order during which
+  Software versions released by Licensor are covered by the License Key.
+
+## 2. License Grant
+
+Subject to payment of the applicable fees and compliance with this Agreement,
+Licensor grants Licensee a non-exclusive, non-transferable, worldwide license
+to use, and to distribute in compiled form as an embedded component of
+Licensee's own applications, any version of the Software released during the
+Update Window, in accordance with the license tier stated in the Order.
+
+This grant is perpetual for versions released during the Update Window:
+Licensee may continue to use those versions after the Update Window ends.
+Versions released after the Update Window ends require a new or renewed
+Order.
+
+## 3. Evaluation Use
+
+The Software may be used without a License Key solely for internal
+evaluation and development purposes. Evaluation use in production, or
+removal or suppression of evaluation notices, is not permitted.
+
+## 4. Restrictions
+
+Except as expressly permitted by this Agreement or by applicable law that
+cannot be contractually waived, Licensee shall not:
+
+1. redistribute, resell, sublicense, or otherwise make the Software
+   available as a standalone product, library, or development component;
+2. use the Software to build a product that competes with the Software;
+3. remove, alter, or circumvent License Key validation, evaluation notices,
+   watermarks, or copyright notices in the Software;
+4. share License Keys with any third party, or use a License Key outside
+   the scope of the tier stated in the Order;
+5. reverse engineer, decompile, or disassemble the Software except to the
+   extent permitted by applicable law.
+
+## 5. Ownership
+
+The Software is licensed, not sold. Licensor and its licensors retain all
+right, title, and interest in and to the Software, including all
+intellectual property rights.
+
+## 6. Third-Party Components
+
+The Software may include third-party open-source components. Those
+components remain governed by their own license terms, which are included
+with the applicable component and are not limited by this Agreement.
+
+## 7. Termination
+
+This Agreement terminates automatically upon material breach by Licensee
+that remains uncured 30 days after written notice. Upon termination,
+Licensee must cease use and distribution of the Software, except that
+end-user copies of Licensee applications already distributed in compliance
+with this Agreement are unaffected.
+
+## 8. Warranty Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.
+
+## 9. Limitation of Liability
+
+TO THE MAXIMUM EXTENT PERMITTED BY LAW, IN NO EVENT SHALL LICENSOR BE LIABLE
+FOR ANY INDIRECT, INCIDENTAL, SPECIAL, CONSEQUENTIAL, OR PUNITIVE DAMAGES,
+OR ANY LOSS OF PROFITS, DATA, OR GOODWILL, ARISING OUT OF OR RELATED TO THIS
+AGREEMENT, AND LICENSOR'S AGGREGATE LIABILITY SHALL NOT EXCEED THE FEES PAID
+BY LICENSEE IN THE TWELVE MONTHS PRECEDING THE CLAIM.
+
+## 10. General
+
+This Agreement constitutes the entire agreement between the parties
+concerning the Software and supersedes any prior agreements. If any
+provision is held unenforceable, the remainder remains in effect. Failure to
+enforce a provision is not a waiver.
+
+For licensing inquiries, visit <https://www.rowsncolumns.app/pricing>.
+
+Copyright © Rows n' Columns. All rights reserved.

package/README.md

@@ -0,0 +1,110 @@
+# vendored `rnc-yrs-store`
+
+Self-built artifact of the **document-backed** Rust→WASM spreadsheet calc engine from
+[`rowsncolumns/spreadsheet#168`](https://github.com/rowsncolumns/spreadsheet/pull/168).
+This is the `rnc-yrs-store` crate's `SpreadsheetEngine`: a `Store<YrsStore>` whose authoritative
+state lives in a `yrs` (yjs-compatible) CRDT document, written in the canonical `sheetDataV3`
+encoding. It supersedes the earlier in-memory `rnc-wasm` preview build — it exposes the same
+`addSheet` / `applyCommand` / `undo` / `redo` / `canUndo` / `canRedo` surface **plus** the
+collaboration surface (`applyUpdate` / `takePendingUpdates` / `loadFromUpdate` / `stateAsUpdate`)
+that the Keryx update-pump binds to.
+
+The package (`@rowsncolumns/rnc-engine`) is not yet published to npm, so the engine is vendored here.
+
+## Contents
+
+| File                                                   | Role                                                                                |
+| ------------------------------------------------------ | ----------------------------------------------------------------------------------- |
+| `rnc_yrs_store.js`                                     | wasm-bindgen JS glue (the `SpreadsheetEngine` class + init).                        |
+| `rnc_yrs_store.d.ts`                                   | Types for the glue (referenced via `@ts-self-types`).                               |
+| `../../../../../public/rnc-wasm/rnc_yrs_store_bg.wasm` | The compiled engine, served as a static asset at `/rnc-wasm/rnc_yrs_store_bg.wasm`. |
+
+## How it was built
+
+```bash
+# from a checkout of Athena-Intel/spreadsheet @ branch bgeils/rnc-lazy-filter-derivation
+# (private mirror of rowsncolumns/spreadsheet, based on feat/yrs-store-converged)
+cd rust
+wasm-pack build crates/rnc-yrs-store --target web --out-dir pkg-web --release
+# → pkg-web/rnc_yrs_store.js, pkg-web/rnc_yrs_store.d.ts, pkg-web/rnc_yrs_store_bg.wasm
+```
+
+The fix branch bumps `rnc-engine`'s `formualizer-eval` dep to `0.7` (from 0.5.9) — which
+resolves the cold structural-recalc hang — and routes structural ops (insert/delete row/column)
+on the capture-less CRDT store through a geometry-only fast path instead of an O(cells)
+whole-document snapshot. Together these take an insert on a dense 100k+-cell sheet from a
+multi-second (or unbounded) hang to sub-second.
+
+The `rnc-engine-collab-fixes` branch builds on that and adds a remote-collab fix:
+`apply_remote_changes` now registers a sheet a peer introduced via the merged CRDT update before
+projecting its cells, so a remotely-authored formula enters the calc engine (it previously rendered
+from cached values but never recomputed when a precedent changed).
+
+The `rnc-reload-facet-sync` branch extends `snapshot_commit` (the reproject/reload render) to emit
+the document facet planes — charts, pivots, conditional-formats, data-validations, citations —
+mirroring `load_document`, so a peer's facet edit renders on another client's reload instead of
+being dropped.
+
+The `rnc-remote-bulk-block-incremental` branch makes a remote peer's cold-plane block change ingest
+INCREMENTALLY — `apply_remote_update` re-loads only the touched bands via `bulk_load_sheet_at`
+instead of rebuilding the whole engine (geometry shifts and block removals still fall back to a full
+rebuild).
+
+The `rnc-capped-formulas-loading` branch surfaces formulas the engine drops at ingest because their
+row exceeds the 1,048,576-row calc-graph cap (rows are packed into 20 bits): they accumulate on the
+workbook and drain into `CommitResult.cappedFormulas` so the host can warn the user instead of
+silently losing them.
+
+The `rnc-lazy-filter-derivation` branch makes basic-filter row visibility LAZY: `apply_filter` no
+longer writes a `hidden_by_filter` flag per body row (an O(rows) write that bloats the doc ~50 MB at
+1M rows), it persists only the spec's `filterSpecs`. `read_window_commit` (the windowed tile read)
+and `snapshot_commit` (the full projection) DERIVE `hidden_by_filter` for just the rows they emit,
+from the stored spec — so a million-row filter costs only the rows actually read, and every client
+recomputes the same visibility (no per-row CRDT flags). `delete_filter` just clears the spec.
+Because filter apply/delete is now spec-only (zero body cells touched), the basic-filter commands
+(`filter-table` / `create-basic-filter` / `delete-filter`) join the structural-fast path on the
+capture-less store: they emit `full_resync_sheets` (the host refetches tiles and re-derives
+visibility) and skip the O(cells) snapshot/diff that otherwise hung the worker when a filter was
+applied to a million-row windowed doc. `snapshot_commit`'s full-projection derive is capped to a
+non-windowed-scale body (windowed docs derive per tile), so a misrouted huge doc can't 1M-row hang.
+The actual million-row filter "hang" was PER-ROW store reads in `read_window_commit`'s filter
+branch: the value-filter derivation called `get_cell` per body row (~512/tile) and the dims merge
+called `get_dimension` per row — each opens a yrs read transaction on the 1M doc, so ~512–1024
+per-row reads/tile cost ~12s and the grid's stream of tile reads saturated the single worker
+thread, leaving the filter command queued forever. Fixes: `read_window_commit` now (a) derives
+visibility from the cells it ALREADY fetched via one `get_range` (passes a (row,col)->text map into
+the filter's value path instead of per-row `get_cell`; a tile spans all columns so a miss = empty
+cell), and (b) emits only the derived `hidden_by_filter` flag with no per-row dim reads (persisted
+heights/hidden*by_user fold in from the initial windowed load), and (c) evaluates simple comparison
+CONDITIONS (NUMBER*\_, TEXT\_\_, BLANK) directly in Rust against that same tile-cell text
+(`condition_matches_text`) instead of `eval_formula_truthy` per row — the formula path loads a
+calc-engine band per row it touches, so a million-row condition filter's full-doc scan otherwise
+triggered ~hundreds of band loads (~seconds each). Aggregate/date/custom/list conditions (and the
+full-projection path) still fall back to the formula engine. (Re-attaching a custom body-row height
+under an active filter — one batched dim read — is a tracked follow-up.)
+
+The `rnc-filter-ranges-on-commit` branch makes the host drive filter visibility from the engine's
+COMPACT hidden-row ranges instead of a per-tile/per-row scan, fixing two ways the prior lazy approach
+made a 1M filter feel broken. (1) `document_facets_json` exposes `hiddenRowRanges` per basic filter —
+the contiguous `[start,end]` body rows the filter hides, from one filtered-column pass — read through a
+per-sheet memo (`filter_ranges_cache`): computed on a miss, invalidated by `apply_command` only on a
+filter command, a geometry shift, or an edit to a filtered column, and cleared on load / remote merge.
+So the full scan runs ONCE per filter change, not on every facets refresh (which fires on every edit).
+The host expands these ranges into the grid's `rowMetadata.hiddenByFilter` in one shot, so the grid has
+the complete filtered layout without fetching every tile to learn it. (2) `row_visible_under_filter`
+now treats an absent filtered cell as `""` and `condition_matches_text` coerces a blank cell to `0` for
+`NUMBER_*` (matching the formula engine), so a sparse/blank column under a simple condition decides on
+the fast path instead of a per-row `eval_formula_truthy` band load (which hung the worker). (Driving the
+grid's native `visibleRowRanges` directly — bypassing the per-row overlay entirely — is a tracked
+follow-up that needs a vendored-`CanvasGrid` change.)
+
+## Local modification
+
+`rnc_yrs_store.js` is generated, except for one deliberate edit: the default-init branch
+`module_or_path = new URL('rnc_yrs_store_bg.wasm', import.meta.url)` is replaced with a
+`throw`. webpack statically resolves `new URL(<literal>, import.meta.url)` at build
+time and would fail to find the wasm from this `src/` location, so callers MUST pass
+an explicit path. `use-rnc-engine.ts` passes the public URL (`/rnc-wasm/rnc_yrs_store_bg.wasm`).
+
+This directory is excluded from Biome (see `olympus/biome.json`); do not hand-format it.
+To refresh, re-run the build above, re-copy the three files, and re-apply the one edit.

package/dist/rnc_yrs_store.d.ts

@@ -0,0 +1,365 @@
+/* tslint:disable */
+/* 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.
+ */
+export class SpreadsheetEngine {
+    free(): void;
+    [Symbol.dispose](): void;
+    addSheet(sheet_id: number, title: string): void;
+    applyCommand(json: string): string;
+    /**
+     * `applyCommand` without write recording, undo history, or a `CommitResult` diff — and with
+     * `change-batch` eligible for the dense bulk path (>500k cells on an empty sheet land as
+     * column blocks). For hosts that discard the result, e.g. backend bulk ingestion.
+     */
+    applyCommandQuiet(json: string): void;
+    /**
+     * Merge a remote v1 update into the CRDT doc (`CollabSync.applyUpdate`); follow with `syncRemote()`
+     * to project + render. Split out of the old apply+project+commit so `useSpreadsheetEngine`'s collab
+     * bridge can drive applyUpdate→syncRemote without projecting twice. (`apply_remote_update` on the
+     * inner engine still does both in one call for the older bespoke/worker path.)
+     */
+    applyUpdate(bytes: Uint8Array): void;
+    /**
+     * Cold-block body cache diagnostics as JSON `{"hits", "misses", "bytes"}`.
+     */
+    blockCacheStats(): string;
+    canRedo(): boolean;
+    canUndo(): boolean;
+    /**
+     * Drop the entire undo/redo history (`SpreadsheetEngineLike.clearHistory`).
+     */
+    clearHistory(): void;
+    /**
+     * Parse CSV text into a row-major grid of cell strings using the fast Rust `csv` reader, returned
+     * 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
+     * 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
+     * the moved coordinate (row for vertical, column for horizontal), 1-based.
+     */
+    dataEdge(sheet_id: number, row: number, col: number, d_row: number, d_col: number, limit: number): number;
+    /**
+     * How many inbound updates are deferred on a causal gap (a dropped/reordered transport
+     * drain). Zero in a healthy stream; persistently non-zero means the host should run a
+     * state-vector diff exchange (`encodeStateVector`/`encodeDiffV1`) to fill the gap.
+     */
+    deferredRemoteUpdates(): number;
+    /**
+     * DEPENDENTS of a cell as a coordinate-array JSON (`SpreadsheetEngineLike.dependents`).
+     */
+    dependents(sheet_id: number, row: number, col: number): string;
+    /**
+     * Document-level facets JSON: basicFilters, conditionalFormats, dataValidations,
+     * citations, namedRanges, tables, embeds.
+     */
+    documentFacets(): string;
+    /**
+     * The v1 diff the remote (by its state vector) is missing (`CollabSync.encodeDiffV1`) — apply the
+     * result to the transport `Y.Doc` to propagate this peer's local edits.
+     */
+    encodeDiffV1(remote_state_vector: Uint8Array): Uint8Array;
+    /**
+     * Full document state as a v1 update (`CollabSync.encodeStateAsUpdate`) — the same bytes as
+     * `stateAsUpdate`, under the name `useSpreadsheetEngine`'s collab bridge calls.
+     */
+    encodeStateAsUpdate(): Uint8Array;
+    /**
+     * This peer's Yjs state vector — what it has seen (`CollabSync.encodeStateVector`).
+     */
+    encodeStateVector(): Uint8Array;
+    /**
+     * Scratch-evaluate a formula at a cell — `ExtendedValue` JSON or `"null"`. Read-only; powers
+     * the cell editor's live result preview (`onRequestCalculate`).
+     */
+    evalFormula(sheet_id: number, row: number, col: number, formula: string): string;
+    exportCsv(sheet_id: number): string;
+    /**
+     * Export the whole workbook to in-memory XLSX bytes (a JS `Uint8Array`). The merged block+hot
+     * view of every sheet via the `rnc-export` writer; read-only, no recompute.
+     */
+    exportXlsx(): Uint8Array;
+    /**
+     * [`exportXlsx`] with client export options JSON
+     * (`{"includeNotes":bool,"citationsAsNotes":bool}`, camelCase, fields optional).
+     */
+    exportXlsxWithOptions(options_json: string): Uint8Array;
+    /**
+     * Off-window search: coordinates of every matching cell on `sheet_id` (JSON `SheetCoordinate[]`,
+     * row-major). The windowed UI calls this so next/prev can navigate to matches outside the loaded
+     * viewport. `ranges_json` = JSON `SheetRange[]` (empty = whole sheet); match-case/whole-word/regex.
+     * Distinct fill/font colors + CF icons in one column's body rows — JSON
+     * `{cellColors, fontColors, icons}`; the "Filter by color" picker on windowed hosts.
+     */
+    filterColors(sheet_id: number, col: number, start_row: number, end_row: number): string;
+    findAll(sheet_id: number, ranges_json: string, find: string, match_case: boolean, whole_word: boolean, use_regex: boolean): string;
+    /**
+     * Stream CSV text into the sheet's dense column blocks anchored at `(start_row, start_col)`
+     * (1-based); returns the number of rows written. Designed to run in a Web Worker: one synchronous
+     * call ingests the whole file off the main thread, after which the host takes the pending update
+     * and applies it to the collaborative document.
+     *
+     * Unlike the prior path — which materialized the whole grid as a single `change-batch` `Value`
+     * (≈50M `Value` nodes for a 10M-row file, the wasm-heap OOM) — this routes each row straight into
+     * the dense bulk path (one block write per column·32k-row stripe), and SKIPS the calc engine for a
+     * literal-only CSV (no formulas), so a 10M-row import stays well under the wasm 4 GiB ceiling.
+     */
+    importCsv(text: string, sheet_id: number, start_row: number, start_col: number): number;
+    /**
+     * Bulk-import an xlsx workbook; returns a JSON summary `[{sheetId, name, rows, cols}]`.
+     */
+    importXlsx(bytes: Uint8Array): string;
+    /**
+     * Import exactly ONE sheet of the workbook — `sheet_id` is the positional (1-based) `sheetId`
+     * from [`listXlsxSheets`](Self::list_xlsx_sheets). Pass `finalize: false` on every call but the
+     * sequence's last: intermediate calls skip the whole-document recalc and the workbook-level
+     * facets (named ranges, slicers, pivots, calcPr, Power Query), which land on the `finalize`
+     * call together with the engine rebuild + recalc (or its over-cap skip — check
+     * [`lastImportRecalcSkipped`](Self::last_import_recalc_skipped) after finalizing). For a
+     * single-call import pass `finalize: true`. Returns `[{"sheetId": …, "name": …}]` for the
+     * imported sheet. See [`YDocEngine::import_xlsx_sheet`] for the full contract.
+     */
+    importXlsxSheet(bytes: Uint8Array, sheet_id: number, finalize: boolean): string;
+    /**
+     * [`importXlsxSheet`](Self::import_xlsx_sheet) selecting the sheet by its display name
+     * (matched exactly against the workbook's `<sheet name=…>`).
+     */
+    importXlsxSheetByName(bytes: Uint8Array, sheet_name: string, finalize: boolean): string;
+    /**
+     * Like [`SpreadsheetEngine::import_xlsx`] but for password-protected workbooks (ECMA-376 agile,
+     * standard AES, or RC4 CryptoAPI):
+     * decrypts with `password`, then runs the identical streaming import on the plaintext. A
+     * non-encrypted file imports directly (password ignored); a wrong password rejects with an error
+     * the UI can re-prompt on.
+     */
+    importXlsxWithPassword(bytes: Uint8Array, password: string): string;
+    /**
+     * Whether the bytes are an encrypted (OLE/CFB) workbook needing a password (vs a plain `.xlsx`).
+     */
+    isEncryptedXlsx(bytes: Uint8Array): boolean;
+    /**
+     * Whether the last `importXlsx` skipped its post-import recalc (workbook past the recalc
+     * caps). See [`YDocEngine::last_import_recalc_skipped`].
+     */
+    lastImportRecalcSkipped(): boolean;
+    /**
+     * Catalog the workbook's sheets WITHOUT ingesting any cells — JSON
+     * `[{sheetId, index, name, hidden}]` in tab order. The first step of the sheet-scoped import
+     * flow: list, then [`importXlsxSheet`](Self::import_xlsx_sheet) per sheet (in workbook order),
+     * draining `encodeDiffV1` between calls so each delta carries one sheet, not the workbook.
+     */
+    listXlsxSheets(bytes: Uint8Array): string;
+    /**
+     * Hydrate the engine from an initial document JSON (`{ sheets, sheetData, styles }`); returns the
+     * full `CommitResult` JSON (`SpreadsheetEngineLike.loadDocument`).
+     */
+    loadDocument(document_json: string): string;
+    /**
+     * Bulk-load a peer's full-state snapshot (`stateAsUpdate`) and rebuild the calc engine — the
+     * join/bootstrap path. Returns a `CommitResult` JSON of every loaded cell (render the restored
+     * document in one shot). Not echoed back to the transport.
+     */
+    loadFromUpdate(bytes: Uint8Array): string;
+    /**
+     * Load a full-state snapshot WITHOUT building the render commit — for hosts that already have
+     * the render projection (engine hydration for editing, the bulk-import worker). Skipping the
+     * 500k-cell snapshot serialization saves seconds on huge documents.
+     */
+    loadFromUpdateQuiet(bytes: Uint8Array): void;
+    constructor();
+    parseCsv(text: string): string;
+    /**
+     * PRECEDENTS of a cell as `{cells, ranges}` JSON (`SpreadsheetEngineLike.precedents`).
+     */
+    precedents(sheet_id: number, row: number, col: number): string;
+    /**
+     * Remove the host-seeded default `Sheet1` (sheetId 1) when a collab merge showed the
+     * workbook's real sheets live under other ids — see [`YDocEngine::prune_dangling_default_seed`]
+     * for the contract. Call right after merging the collab doc, and ONLY when the persisted doc's
+     * sheet registry is non-empty and contains no `sheetId: 1`. Returns `true` when pruned.
+     */
+    pruneDanglingDefaultSeed(): boolean;
+    readWindow(sheet_id: number, start_row: number, start_col: number, end_row: number, end_col: number): string;
+    /**
+     * A window's cells + effective styles as COMPACT JSON —
+     * `{"cells":[[row,col,cell],…],"styles":[[row,col,format],…]}` (1-based, inclusive). For
+     * snapshot/export tooling tiling a whole sheet: the same cell payload `readWindowCommit`
+     * carries, minus its render channels (per-tile filter-hidden derivation, row dims) and the
+     * per-cell change-wrapper objects — a fraction of the JSON to serialize and parse.
+     */
+    readWindowCells(sheet_id: number, start_row: number, start_col: number, end_row: number, end_col: number): string;
+    /**
+     * A rectangular window of FULL cells + styles as `CommitResult` JSON, for windowed rendering
+     * of huge sheets (fold each tile with the same machinery as any other commit).
+     */
+    readWindowCommit(sheet_id: number, start_row: number, start_col: number, end_row: number, end_col: number): string;
+    /**
+     * Force the full engine rebuild + recalc a capped import skipped. Can run minutes / trap on
+     * monster workbooks — callers must encode the doc state they need BEFORE calling, in a heap
+     * they can discard on failure. See [`YDocEngine::rebuild_and_recalc`].
+     */
+    rebuildAndRecalc(): void;
+    redo(): string;
+    redoDepth(): number;
+    /**
+     * Register a host (JS) custom-function name (`SpreadsheetEngineLike.registerCustomFunction`).
+     */
+    registerCustomFunction(name: string): void;
+    /**
+     * Per-sheet 1-based data extents as JSON `[{"sheetId", "maxRow", "maxCol"}]`.
+     */
+    sheetExtents(): string;
+    /**
+     * The workbook's sheet ids in tab order (`SpreadsheetEngineLike.sheetIds()`).
+     */
+    sheetIds(): Int32Array;
+    /**
+     * Per-sheet populated stats as JSON —
+     * `[{"sheetId","minRow","minCol","maxRow","maxCol","cellCount"}, …]`. `cellCount` counts
+     * POPULATED cells (not the dense extent product) and `minRow`/`minCol` complete the bounding
+     * box, so hosts can budget reads honestly on sparse sheets. Empty sheets report all-zeros.
+     * Presence-derived (block headers + hot-plane coords); cheap even on million-row sheets.
+     */
+    sheetStats(): string;
+    /**
+     * The workbook's sheets in tab order as JSON `[{sheetId, title, index, hidden?, tabColor?}]` —
+     * the engine's authoritative sheet identity/order/titles. Mirrors `SpreadsheetEngineLike.sheets()`
+     * (see `@rowsncolumns/rnc-engine`) so the Option-B chrome reconciles its tab list after each commit.
+     */
+    sheets(): string;
+    stateAsUpdate(): Uint8Array;
+    /**
+     * Project the cells touched by the preceding `applyUpdate` and return the `CommitResult` JSON
+     * (`CollabSync.syncRemote`).
+     */
+    syncRemote(): string;
+    /**
+     * Drain the row-capped dropped formulas accumulated by bulk ingests/imports, as a
+     * coordinate-array JSON. See [`CollabSpreadsheetEngine::take_capped_formulas_json`].
+     */
+    takeCappedFormulas(): string;
+    /**
+     * Drain the merged v1 update produced by local edits since the last call (empty = nothing).
+     */
+    takePendingUpdates(): Uint8Array;
+    undo(): string;
+    /**
+     * Undo / redo stack depth (`SpreadsheetEngineLike.undoDepth` / `redoDepth`).
+     */
+    undoDepth(): number;
+}
+
+/**
+ * Minimal yrs-backed sheet doc exposing the canonical `sheetDataV3` encoding + yjs v1 transport.
+ */
+export class YrsSheetDoc {
+    free(): void;
+    [Symbol.dispose](): void;
+    applyUpdate(update: Uint8Array): void;
+    encodeStateAsUpdate(): Uint8Array;
+    getCell(sheet_id: number, row: number, col: number): string | undefined;
+    constructor();
+    setCell(sheet_id: number, row: number, col: number, cell_json: string): void;
+}
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly __wbg_yrssheetdoc_free: (a: number, b: number) => void;
+    readonly yrssheetdoc_new: () => number;
+    readonly yrssheetdoc_setCell: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly yrssheetdoc_getCell: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly yrssheetdoc_applyUpdate: (a: number, b: number, c: number) => [number, number];
+    readonly yrssheetdoc_encodeStateAsUpdate: (a: number) => [number, number];
+    readonly __wbg_spreadsheetengine_free: (a: number, b: number) => void;
+    readonly spreadsheetengine_new: () => number;
+    readonly spreadsheetengine_addSheet: (a: number, b: number, c: number, d: number) => void;
+    readonly spreadsheetengine_applyCommand: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_applyCommandQuiet: (a: number, b: number, c: number) => [number, number];
+    readonly spreadsheetengine_dataEdge: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number;
+    readonly spreadsheetengine_documentFacets: (a: number) => [number, number];
+    readonly spreadsheetengine_sheets: (a: number) => [number, number];
+    readonly spreadsheetengine_sheetIds: (a: number) => [number, number];
+    readonly spreadsheetengine_pruneDanglingDefaultSeed: (a: number) => number;
+    readonly spreadsheetengine_loadDocument: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_registerCustomFunction: (a: number, b: number, c: number) => void;
+    readonly spreadsheetengine_precedents: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly spreadsheetengine_dependents: (a: number, b: number, c: number, d: number) => [number, number];
+    readonly spreadsheetengine_takeCappedFormulas: (a: number) => [number, number];
+    readonly spreadsheetengine_clearHistory: (a: number) => void;
+    readonly spreadsheetengine_undoDepth: (a: number) => number;
+    readonly spreadsheetengine_redoDepth: (a: number) => number;
+    readonly spreadsheetengine_importXlsx: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_importXlsxWithPassword: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly spreadsheetengine_isEncryptedXlsx: (a: number, b: number, c: number) => number;
+    readonly spreadsheetengine_listXlsxSheets: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_importXlsxSheet: (a: number, b: number, c: number, d: number, e: number) => [number, number, number, number];
+    readonly spreadsheetengine_importXlsxSheetByName: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+    readonly spreadsheetengine_lastImportRecalcSkipped: (a: number) => number;
+    readonly spreadsheetengine_rebuildAndRecalc: (a: number) => void;
+    readonly spreadsheetengine_exportCsv: (a: number, b: number) => [number, number];
+    readonly spreadsheetengine_exportXlsx: (a: number) => [number, number, number, number];
+    readonly spreadsheetengine_exportXlsxWithOptions: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_parseCsv: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_importCsv: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number];
+    readonly spreadsheetengine_undo: (a: number) => [number, number];
+    readonly spreadsheetengine_redo: (a: number) => [number, number];
+    readonly spreadsheetengine_canUndo: (a: number) => number;
+    readonly spreadsheetengine_canRedo: (a: number) => number;
+    readonly spreadsheetengine_readWindow: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly spreadsheetengine_evalFormula: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly spreadsheetengine_filterColors: (a: number, b: number, c: number, d: number, e: number) => [number, number];
+    readonly spreadsheetengine_findAll: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => [number, number];
+    readonly spreadsheetengine_readWindowCommit: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly spreadsheetengine_readWindowCells: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
+    readonly spreadsheetengine_sheetExtents: (a: number) => [number, number];
+    readonly spreadsheetengine_sheetStats: (a: number) => [number, number];
+    readonly spreadsheetengine_blockCacheStats: (a: number) => [number, number];
+    readonly spreadsheetengine_applyUpdate: (a: number, b: number, c: number) => [number, number];
+    readonly spreadsheetengine_syncRemote: (a: number) => [number, number];
+    readonly spreadsheetengine_loadFromUpdate: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_loadFromUpdateQuiet: (a: number, b: number, c: number) => [number, number];
+    readonly spreadsheetengine_takePendingUpdates: (a: number) => [number, number];
+    readonly spreadsheetengine_encodeStateAsUpdate: (a: number) => [number, number];
+    readonly spreadsheetengine_encodeStateVector: (a: number) => [number, number];
+    readonly spreadsheetengine_encodeDiffV1: (a: number, b: number, c: number) => [number, number, number, number];
+    readonly spreadsheetengine_deferredRemoteUpdates: (a: number) => number;
+    readonly spreadsheetengine_stateAsUpdate: (a: number) => [number, number];
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;