@rowsncolumns/rnc-engine 0.10.132

package/dist/esm/index.js

@@ -0,0 +1,425 @@
+import { cellKey } from "./keys";
+import init, { CollabSpreadsheetEngine, SpreadsheetEngine, } from "./wasm/rnc_wasm.js";
+// The wasm module initializes once per page.
+let initPromise = null;
+/** Initialize the wasm module (idempotent). Called by {@link RncEngine.create}; exported for control. */
+export function initEngine() {
+    return (initPromise ??= init());
+}
+/**
+ * Ergonomic, typed handle to a standalone in-memory spreadsheet engine.
+ * Commands go in; value/style change-sets and windowed reads come out — all using the exact
+ * `rnc-model` shapes the rest of the app already speaks.
+ */
+export class RncEngine {
+    inner;
+    listeners = new Set();
+    constructor(inner) {
+        this.inner = inner;
+    }
+    /**
+     * Initialize wasm (idempotent) and create an engine with the given sheets registered.
+     *
+     * By default the backend is the single-user {@link SpreadsheetEngine}. Pass `options.engine` to
+     * inject a different store — e.g. `new CollabSpreadsheetEngine()` (yhub/collab) or your own wasm
+     * store implementing {@link SpreadsheetEngineLike}. When the store implements `initGrid`
+     * (positional/CRDT), each registered sheet is pre-sized to `gridRows`×`gridCols`.
+     */
+    static async create(sheets = [], options = {}) {
+        await initEngine();
+        const inner = options.engine ?? new SpreadsheetEngine();
+        const rows = options.gridRows ?? 1000;
+        const cols = options.gridCols ?? 26;
+        for (const sheet of sheets) {
+            inner.addSheet(sheet.sheetId, sheet.title);
+            // Positional/CRDT stores (collab) must pre-size the grid before cells are written; stores that
+            // grow on demand omit `initGrid`, so this is a no-op for them.
+            inner.initGrid?.(sheet.sheetId, rows, cols);
+        }
+        return new RncEngine(inner);
+    }
+    /**
+     * Wrap an ALREADY-INITIALIZED backing engine — skips {@link initEngine} (the caller owns wasm
+     * init). Use this when the wasm module is loaded by a different path than the vendored
+     * `--target web` build: a `--target nodejs` engine in tests/SSR, a `CollabSpreadsheetEngine` you
+     * constructed yourself, or any custom {@link SpreadsheetEngineLike} store. Registers `sheets` (and
+     * pre-sizes the grid via `initGrid` when the store supports it) exactly like {@link create}.
+     */
+    static fromEngine(inner, sheets = [], options = {}) {
+        const rows = options.gridRows ?? 1000;
+        const cols = options.gridCols ?? 26;
+        for (const sheet of sheets) {
+            inner.addSheet(sheet.sheetId, sheet.title);
+            inner.initGrid?.(sheet.sheetId, rows, cols);
+        }
+        return new RncEngine(inner);
+    }
+    /** Whether the backing engine is collaborative (implements the Yjs {@link CollabSync} surface). */
+    get isCollab() {
+        return (typeof this.inner.applyUpdate === "function");
+    }
+    collab() {
+        if (!this.isCollab)
+            throw new Error("RncEngine: backing engine is not collaborative (no Yjs sync surface)");
+        return this.inner;
+    }
+    /** Pre-size a sheet's grid on a positional/CRDT store. No-op for stores without `initGrid`. */
+    initGrid(sheetId, rows, cols) {
+        this.inner.initGrid?.(sheetId, rows, cols);
+    }
+    /** Register a sheet (`id` → display name). */
+    addSheet(sheetId, name) {
+        this.inner.addSheet(sheetId, name);
+    }
+    // ── Streaming hydration (for huge workbooks) ──────────────────────────────────────────────
+    // NDJSON streaming hydration (huge workbooks). Optional on the backend: the single-user engine
+    // supports it; a collab store hydrates from the CRDT update stream instead, so these no-op there.
+    /** Begin a streaming hydration. Feed NDJSON byte chunks with {@link streamWrite}, then {@link streamEnd}. */
+    streamBegin() {
+        this.inner.streamBegin?.();
+    }
+    /** Ingest one NDJSON byte chunk (boundaries may fall anywhere — partial lines are buffered). */
+    streamWrite(chunk) {
+        this.inner.streamWrite?.(chunk);
+    }
+    /** Finish hydration: ingest the trailing line and recompute once. Read the viewport via `readWindow`. */
+    streamEnd() {
+        this.inner.streamEnd?.();
+    }
+    /**
+     * Hydrate from a byte stream of NDJSON records — e.g. `(await fetch(url)).body`. The 100 MB+
+     * workbook flows network → wasm in chunks and is never held whole in JS. Records are
+     * `{"t":"sheet"|"cell"|"style", …}` (see the Rust `StreamRecord`). Nothing is returned; call
+     * `readWindow` for the visible area once this resolves.
+     */
+    async hydrateFromStream(stream) {
+        this.streamBegin();
+        const reader = stream.getReader();
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                if (value)
+                    this.streamWrite(value);
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+        this.streamEnd();
+    }
+    /**
+     * Hydrate the engine from an initial document (sheets + cells + styles, the shape your API
+     * returns). Recomputes formulas and delivers the full change-set to {@link onChanges} subscribers
+     * — so initial load uses the exact same path as every other change. Returns it inline too.
+     */
+    load(document) {
+        const commit = JSON.parse(this.inner.loadDocument(JSON.stringify(document)));
+        this.listeners.forEach((listener) => listener(commit));
+        return commit;
+    }
+    /**
+     * Apply a `commands.ts` command. The resulting change-set is delivered to every
+     * {@link onChanges} subscriber; it's also returned for callers that want it inline.
+     */
+    applyCommand(command) {
+        const commit = JSON.parse(this.inner.applyCommand(JSON.stringify(command)));
+        // The wasm `&mut self` borrow is released here (the call above already returned), so a
+        // subscriber may safely re-enter the engine (e.g. `readWindow`). That's why the subscriber
+        // lives in this TS layer, not as a wasm-bindgen callback (which would re-enter mid-borrow).
+        this.listeners.forEach((listener) => listener(commit));
+        return commit;
+    }
+    /**
+     * Declare whether the host renders WINDOWED, so the backing engine can omit the per-cell commit
+     * channels the windowed render discards (it re-reads the viewport via {@link readWindow}). Forwarded
+     * to the injected engine's `setWindowed` when it implements it; a no-op otherwise (the windowed fold
+     * still ignores those channels correctly — it just pays to transfer them). Called once by the
+     * windowed hook after engine creation. See {@link SpreadsheetEngineLike.setWindowed}.
+     */
+    setWindowed(on) {
+        this.inner.setWindowed?.(on);
+    }
+    /**
+     * Subscribe to the change-sets the engine produces. Returns an unsubscribe function.
+     *
+     * Today this fires synchronously after each {@link applyCommand}. The same API is the seam for
+     * out-of-band changes later — volatile recalc ticks, or Worker `postMessage` when calc moves off
+     * the main thread — without the UI's subscribe code changing.
+     */
+    onChanges(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * Undo / redo the last document mutation in the engine. The resulting change-set (reverted input
+     * AND recomputed values, across any sheets touched) is delivered to {@link onChanges} subscribers.
+     */
+    undo() {
+        const commit = JSON.parse(this.inner.undo());
+        this.listeners.forEach((listener) => listener(commit));
+        return commit;
+    }
+    redo() {
+        const commit = JSON.parse(this.inner.redo());
+        this.listeners.forEach((listener) => listener(commit));
+        return commit;
+    }
+    /** Whether an undo / redo is currently available (for enabling toolbar buttons). */
+    canUndo() {
+        return this.inner.canUndo();
+    }
+    canRedo() {
+        return this.inner.canRedo();
+    }
+    /** Drop the entire undo/redo history (the document is unchanged). Backs `onClearHistory`. */
+    clearHistory() {
+        this.inner.clearHistory();
+    }
+    /** Undo / redo stack depth. A UI that keeps parallel per-edit state (cursor, selection, active
+     * sheet) watches these to push/pop its own snapshots in lockstep — a command that recorded an undo
+     * entry bumps `undoDepth`, so the UI knows whether to snapshot (and skips no-op-inverse commands). */
+    undoDepth() {
+        return this.inner.undoDepth();
+    }
+    redoDepth() {
+        return this.inner.redoDepth();
+    }
+    /** Read a 1-indexed, inclusive window of cells + consolidated styles. Prefers the LOSSLESS full-cell
+     * read (`readWindowCommit`): each cell is carried VERBATIM (`ue`/formula source, hyperlink, note, full
+     * `ev`) under `cell`, so the windowed render uses it as-is rather than reconstructing a lossy cell
+     * from a lean formatted/number/isFormula projection (which dropped `ue.fv` — the formula bar then
+     * showed the computed value, not `=SUM(4,4)`). Falls back to the lean `readWindow` for engines without
+     * it. The window is only viewport-sized, so carrying whole cells costs nothing. */
+    readWindow(sheetId, startRow, startCol, endRow, endCol) {
+        const inner = this.inner;
+        if (typeof inner.readWindowCommit === "function") {
+            const commit = JSON.parse(inner.readWindowCommit(sheetId, startRow, startCol, endRow, endCol));
+            return {
+                sheetId,
+                startRowIndex: startRow,
+                startColumnIndex: startCol,
+                endRowIndex: endRow,
+                endColumnIndex: endCol,
+                cells: (commit.changes ?? [])
+                    .filter((ch) => ch.cell != null)
+                    .map((ch) => ({
+                    rowIndex: ch.rowIndex,
+                    columnIndex: ch.columnIndex,
+                    formatted: ch.cell?.fv ?? "",
+                    number: ch.cell?.ev?.nv ?? null,
+                    isFormula: ch.cell?.ue?.fv != null,
+                    cell: ch.cell ?? undefined,
+                })),
+                styles: commit.styleChanges ?? [],
+            };
+        }
+        return JSON.parse(inner.readWindow(sheetId, startRow, startCol, endRow, endCol));
+    }
+    /**
+     * Selection statistics (sum / count / numericalCount / average / min / max) over a 1-indexed
+     * inclusive {@link SheetRange} — what the status bar shows for a selection. Computed in Rust over
+     * the stored cells, so it stays cheap even on a million-cell selection (no value round-trip to JS,
+     * no main-thread iteration — the reason the old JS path refused selections over ~200k cells).
+     *
+     * Returns `null` if the backing engine doesn't expose `rangeStats` (the host then falls back to
+     * its own JS computation). Numeric fields are `null` when the range holds no numbers.
+     */
+    rangeStats(range) {
+        const json = this.inner.rangeStats?.(range.sheetId, range.startRowIndex, range.startColumnIndex, range.endRowIndex, range.endColumnIndex);
+        if (json == null)
+            return null;
+        return JSON.parse(json);
+    }
+    /** Off-window search: every cell on `sheetId` whose display text matches `find`, returned row-major
+     * (the order next/prev navigation walks). The windowed UI's JS search only sees the loaded viewport,
+     * so matches OUTSIDE it must come from the engine, which holds the whole document. `ranges` restricts
+     * the scope (whole sheet when omitted). Match-case / whole-word (`\b`) / regex mirror the JS search.
+     * Returns `[]` if the find is empty or the backing engine can't search. */
+    findAll(sheetId, find, options, ranges) {
+        if (!find || !this.inner.findAll)
+            return [];
+        const json = this.inner.findAll(sheetId, ranges && ranges.length ? JSON.stringify(ranges) : "", find, options?.matchCase ?? false, options?.wholeWord ?? false, options?.useRegex ?? false);
+        return JSON.parse(json);
+    }
+    /** Scratch-evaluate `formula` at `(rowIndex, columnIndex)` on `sheetId` — the cell editor's live
+     * result preview. Read-only: nothing is installed or committed, no dirty marks; a host
+     * custom-function call (`=AOP(...)`) evaluates to `#NAME?` with NO `customEvals` request (host
+     * calls are recognised at set-value time only), so previewing can never fire one. Returns the
+     * result as an `ExtendedValue`, or `undefined` when the backing engine can't evaluate it (no
+     * capability, parse failure, unknown sheet, unpopulated engine). */
+    evalFormula(sheetId, rowIndex, columnIndex, formula) {
+        if (!formula || !this.inner.evalFormula)
+            return undefined;
+        const json = this.inner.evalFormula(sheetId, rowIndex, columnIndex, formula);
+        const parsed = json ? JSON.parse(json) : null;
+        return parsed ?? undefined;
+    }
+    /** Distinct fill/font colors + CF icons present in one column's body rows — the FilterBox
+     * "Filter by color" swatches, computed engine-side in ONE column scan (the windowed
+     * alternative to the JS per-row `getEffectiveFormat` scan). `undefined` when the backing
+     * engine doesn't expose it. */
+    filterColors(sheetId, columnIndex, startRow, endRow) {
+        if (!this.inner.filterColors)
+            return undefined;
+        const json = this.inner.filterColors(sheetId, columnIndex, startRow, endRow);
+        if (!json || json === "null")
+            return undefined;
+        return JSON.parse(json);
+    }
+    /** Sheet ids, in order. */
+    sheetIds() {
+        return Array.from(this.inner.sheetIds());
+    }
+    /**
+     * Remove the host-seeded default `Sheet1` (sheetId 1) once a collab merge showed the workbook's
+     * real sheets live under other ids — without it, the seed's live structs ship with every outbound
+     * flush, materializing an empty ghost `Sheet1` tab for every collaborator (and re-materializing
+     * it after a peer's explicit delete-sheet). Call right after merging the collab doc, and ONLY
+     * when the persisted doc's sheet registry is non-empty and contains no sheetId 1; the store
+     * guards the rest (exact seed title, zero populated cells, ≥1 other sheet) and removes the seed
+     * WITHOUT a commit fan-out — the tombstones ride the next flushed update. No-op (returns false)
+     * on stores without a construction seed.
+     */
+    pruneDanglingDefaultSeed() {
+        return this.inner.pruneDanglingDefaultSeed?.() ?? false;
+    }
+    /** The workbook's sheets in tab order — the engine's AUTHORITATIVE identity/order/titles (it
+     * generates ids for `create-sheet`, rewrites titles on rename, reorders on move). A thin UI
+     * reconciles its tab list from this after each commit. Returns `[]` if the backing engine doesn't
+     * expose it (the hook then keeps its seeded sheet list). */
+    sheets() {
+        const json = this.inner.sheets?.();
+        if (json == null)
+            return [];
+        return JSON.parse(json);
+    }
+    /** Per-sheet 1-based data extent: `[sheetId, rowCount, columnCount][]`. A windowed renderer sizes
+     * the grid's scroll extent to this (so it holds only the visible viewport in JS yet scrolls the
+     * full sheet). Returns `[]` if the backing engine doesn't expose extents. */
+    sheetExtents() {
+        const json = this.inner.sheetExtents?.();
+        if (json == null)
+            return [];
+        return JSON.parse(json);
+    }
+    /** A sheet's display values as RFC-4180 CSV. Empty string if the backing engine can't export. */
+    exportCsv(sheetId) {
+        return this.inner.exportCsv?.(sheetId) ?? "";
+    }
+    /** The whole workbook as in-memory XLSX bytes (a `Uint8Array`), or `undefined` if the backing
+     * engine wasn't built with export support. Reads the full document inside the engine (works even in
+     * windowed mode, where the JS side holds only the viewport). */
+    exportXlsx() {
+        return this.inner.exportXlsx?.();
+    }
+    /**
+     * Import an `.xlsx` workbook with the native Rust reader (`rnc-import`), REPLACING the engine's
+     * document, and return the full {@link CommitResult} (every cell + style + structural change — the
+     * same shape as {@link load}). Returns `undefined` if the backend has no import capability.
+     *
+     * NOTE: unlike {@link load}, this does NOT notify {@link onChanges} subscribers — because import is a
+     * full replace, the caller must reset its render state and fold this commit onto sheets seeded from
+     * {@link sheets} (merges/dimensions fold only onto pre-existing sheet objects). The windowed hook's
+     * `importXlsx` does exactly that. Only backends whose commit shape matches {@link CommitResult}
+     * (rnc-engine's built-in engine) are driven here; the collab (yrs-store) engine imports via its delta.
+     */
+    importXlsx(bytes) {
+        if (!this.inner.importXlsx)
+            return undefined;
+        return JSON.parse(this.inner.importXlsx(bytes));
+    }
+    /** Raw JSON of {@link documentFacets} — the hook diffs this string against the previous commit's to
+     * skip a no-op facet update (so a pure cell edit doesn't churn the facet props and re-render the grid). */
+    documentFacetsJson() {
+        return this.inner.documentFacets();
+    }
+    /** The document-level facets the renderer draws (CF rules, tables, named/protected ranges, embeds,
+     * slicers, banded ranges, basic filters, DV rules) in their canonical shapes. Cheap and re-read by
+     * the thin hook once per commit — they're small and change rarely, so they ride this getter rather
+     * than a per-facet `CommitResult` channel. */
+    documentFacets() {
+        return JSON.parse(this.documentFacetsJson());
+    }
+    /** Register a host (JS) custom-function NAME so `=NAME(…)` resolves (deps tracked) instead of
+     * `#NAME?`. On recalc the engine emits a `customEvals` request the host answers via
+     * `setEffectiveValue`. (The function body itself lives in JS — see the hook's
+     * `registerCustomFunction`, which pairs this with the resolve loop.) */
+    registerCustomFunction(name) {
+        this.inner.registerCustomFunction(name);
+    }
+    /** The PRECEDENTS of a cell — the cells + ranges its formula references (engine-parsed, exact). The
+     * engine owns the dependency data, so `getPrecedents` is backed by real graph data, not a stub. */
+    precedents(sheetId, rowIndex, columnIndex) {
+        return JSON.parse(this.inner.precedents(sheetId, rowIndex, columnIndex));
+    }
+    /** The DEPENDENTS of a cell — every formula cell that references it (directly or within a range). */
+    dependents(sheetId, rowIndex, columnIndex) {
+        return JSON.parse(this.inner.dependents(sheetId, rowIndex, columnIndex));
+    }
+    // ── Yjs sync (collab engines only) ────────────────────────────────────────────────────────
+    // Present when the injected engine implements {@link CollabSync} (i.e. `CollabSpreadsheetEngine`).
+    // The host bridges these to a `Y.Doc`: feed remote peer/yhub updates in via `applyRemoteUpdate`,
+    // and push local edits out by applying `encodeDiffV1(remoteStateVector)` to the doc after a commit.
+    /** Apply a remote Yjs v1 update (a peer's / yhub's delta) into the CRDT doc, rebuild, and fold the
+     * resulting change-set to {@link onChanges} subscribers. Returns it inline too. Throws if the
+     * backing engine isn't collaborative ({@link isCollab}). */
+    applyRemoteUpdate(update) {
+        const collab = this.collab();
+        collab.applyUpdate(update);
+        const commit = JSON.parse(collab.syncRemote());
+        this.listeners.forEach((listener) => listener(commit));
+        return commit;
+    }
+    /** Encode the full document state as a Yjs v1 update (initial sync to a peer / persistence). */
+    encodeStateAsUpdate() {
+        return this.collab().encodeStateAsUpdate();
+    }
+    /** Encode this peer's Yjs state vector (a compact summary of what it has seen). */
+    encodeStateVector() {
+        return this.collab().encodeStateVector();
+    }
+    /** Encode the diff a remote peer (identified by its state vector) is missing — apply the result to
+     * the transport doc (`Y.applyUpdate`) to propagate local edits. */
+    encodeDiffV1(remoteStateVector) {
+        return this.collab().encodeDiffV1(remoteStateVector);
+    }
+    /** Release the underlying wasm memory. */
+    free() {
+        this.inner.free();
+    }
+    /** Fold `StyleEntry[]` into the consolidated `Map<"sheetId!A1", CellFormat>` the UI consumes.
+     * A `null` format clears the entry. */
+    static toStyleMap(styles) {
+        const map = new Map();
+        for (const style of styles) {
+            const key = cellKey(style.sheetId, style.rowIndex, style.columnIndex);
+            if (style.format)
+                map.set(key, style.format);
+            else
+                map.delete(key);
+        }
+        return map;
+    }
+}
+// Re-export the collaborative wasm engine so consumers can inject it into the hook:
+// `useSpreadsheetEngine({ createEngine: () => new CollabSpreadsheetEngine() })`. The single-user
+// `SpreadsheetEngine` is the default backend, so it stays internal (no export needed).
+export { CollabSpreadsheetEngine };
+// Cell-address key helpers live in a wasm-free module so the pure fold reducers can share them.
+export { cellKey, columnLabel, parseCellKey } from "./keys";
+// The Option B "UI is a renderer" surface: pure fold reducers + the engine-backed React hook.
+export * from "./fold";
+export { useEngineCore, } from "./use-engine-core";
+export { useSpreadsheetUI, } from "./use-spreadsheet-ui";
+export { useSpreadsheetEngine, } from "./use-spreadsheet-engine";
+// The pivot-settings-sidebar bridge: drives `@rowsncolumns/pivot`'s `<PivotEditor>` with pure
+// spec transforms over `update-pivot-table` (the engine re-renders on every update).
+export { useEnginePivotEditor, VALUES_PIVOT_FIELD, } from "./use-engine-pivot-editor";
+// File ⇄ engine I/O: bridge the `@rowsncolumns/toolkit` XLSX/ODS/CSV importer+exporter to the
+// engine (no Rust changes). Import → `engine.load`/NDJSON stream; export → windowed `readWindow` →
+// `createExcelFile`/`createODSFile`; CSV export passes through `engine.exportCsv`.
+export { parseWorkbook, importXlsx, importOds, importCsv, streamWorkbookInto, exportXlsx, exportOds, exportCsv, } from "./io";

package/dist/esm/io.d.ts

@@ -0,0 +1,119 @@
+/**
+ * `@rowsncolumns/rnc-engine/io` — file ⇄ engine bridge.
+ *
+ * Wires the existing `@rowsncolumns/toolkit` XLSX / ODS / CSV importer + exporter to {@link RncEngine}
+ * with NO Rust changes: both sides already speak the same `{ sheets, sheetData, sharedStrings, … }`
+ * `rnc-model` shape (`SheetData<T>` == `LoadDocument.sheetData`), so this is pure TS wiring.
+ *
+ * ── Import ────────────────────────────────────────────────────────────────────────────────────
+ *   `importXlsx` / `importOds` drive the toolkit's `WorkBook` plugin DIRECTLY (it does the parsing —
+ *   the published `./worker` entry is just a Web-Worker wrapper around it, unavailable in Node). Its
+ *   chunked `processSheetData()` rows are assembled into `SheetData` and fed to the engine. For very
+ *   large inputs `streamWorkbookInto` emits one `{"t":"cell",…}` NDJSON record per cell into the
+ *   engine's `streamBegin/streamWrite/streamEnd`, so the workbook never lands whole in the engine in
+ *   one `loadDocument` call. CSV uses the toolkit's `createRowDataFromCSVString` → `engine.load`.
+ *
+ * ── Export ────────────────────────────────────────────────────────────────────────────────────
+ *   `exportXlsx` / `exportOds` read the engine back: `documentFacets()` for the document facets,
+ *   `sheetExtents()` for each sheet's used 1-based extent, and `readWindow` over that extent (in row
+ *   bands) for the cell VALUES + consolidated styles, which are assembled into the toolkit's export
+ *   input and handed to `createExcelFile` / `createODSFile`. CSV is direct: `engine.exportCsv`.
+ *
+ *   CONSTRAINT (engine surface): `readWindow` returns the value-side render data only
+ *   (`{ rowIndex, columnIndex, formatted, number, isFormula }`) plus consolidated styles — it does
+ *   NOT carry a cell's verbatim `CellData`, so the FORMULA SOURCE TEXT of a `=…` cell is not
+ *   recoverable. Exported cells therefore carry their COMPUTED value (number / formatted string) +
+ *   style, exactly like the engine's own CSV export. This is the same lossy boundary `exportCsv` has;
+ *   a lossless formula export would need a new engine reader (out of scope — no Rust changes).
+ */
+import type { CellData, CommentThread, SheetData } from "@rowsncolumns/common-types";
+import type { Sheet } from "@rowsncolumns/spreadsheet";
+import { RncEngine, type LoadDocument } from "./index";
+/** A loaded workbook in the `rnc-model` shape both the toolkit and the engine speak. */
+export interface ParsedWorkbook {
+    sheets: Sheet[];
+    sheetData: SheetData<CellData>;
+    /** Shared-string table keyed by its string index (cells reference it via `cell.ss`). */
+    sharedStrings: Map<string, string>;
+    tables: LoadDocument["tables"];
+    conditionalFormats: LoadDocument["conditionalFormats"];
+    dataValidations: LoadDocument["dataValidations"];
+    namedRanges: LoadDocument["namedRanges"];
+    /**
+     * Threaded comments in the exporter's `comments` model. The engine only
+     * stores the per-cell `commentThreadId` anchors (thread CONTENT is
+     * host-managed state, exactly as `useSpreadsheetState` models it), so
+     * hosts must persist this list themselves to render / re-export threads.
+     */
+    commentThreads: CommentThread[];
+}
+/** Options shared by the file-importing entry points. */
+export interface ImportOptions {
+    /** BCP-47 locale used when the parser infers value types (e.g. CSV `3/3/2022` → date serial). */
+    locale?: string;
+    /** Minimum grid rows/cols to request from the workbook plugin (passed to `getSheets`). */
+    minRowCount?: number;
+    minColumnCount?: number;
+}
+/**
+ * Parse an XLSX (or any format the toolkit's `WorkBook` plugin registry handles for the given file
+ * name — `.xlsx` / `.xlsm` …) buffer into the common `rnc-model` shape, WITHOUT touching the engine.
+ * Drives the toolkit `WorkBook` directly (Node-safe: it uses `@zip.js/zip.js` + `fast-xml-parser`,
+ * no browser/Worker APIs). Shared-string cells (which the plugin emits as a bare `ss` index) are
+ * resolved inline to their value via {@link resolveSharedStrings}, since the engine has no SST table.
+ */
+export declare function parseWorkbook(buffer: ArrayBuffer, fileName?: string, options?: ImportOptions): Promise<ParsedWorkbook>;
+/**
+ * Import an XLSX buffer into the engine via the toolkit. Returns the engine the cells were loaded
+ * into (a fresh one when `engine` is omitted). Hydrates through {@link RncEngine.load}, so it
+ * delivers the full change-set to `onChanges` subscribers like every other load.
+ */
+export declare function importXlsx(buffer: ArrayBuffer, options?: ImportOptions & {
+    engine?: RncEngine;
+    fileName?: string;
+}): Promise<RncEngine>;
+/** Import an ODS buffer into the engine. Same path as {@link importXlsx} with an `.ods` file name so
+ * the toolkit selects its ODS plugin. */
+export declare function importOds(buffer: ArrayBuffer, options?: ImportOptions & {
+    engine?: RncEngine;
+    fileName?: string;
+}): Promise<RncEngine>;
+/**
+ * Stream a parsed workbook's cells into the engine's NDJSON hydration path instead of one big
+ * `loadDocument`, so a huge workbook is fed cell-by-cell (one `{"t":"cell",…}` record each) and never
+ * materialized whole on the engine side in a single call. The sheets are registered first (as
+ * `{"t":"sheet",…}` records). Pull the visible area with `readWindow` afterward.
+ *
+ * NOTE: document facets (CF / DV / tables / named ranges) are NOT carried by the NDJSON stream — load
+ * those separately if needed. Use this for value-heavy bulk imports; use {@link importXlsx} for the
+ * full-fidelity (facets included) path.
+ */
+export declare function streamWorkbookInto(engine: RncEngine, parsed: ParsedWorkbook): void;
+/**
+ * Import a CSV string (or `File`) into the engine via the toolkit's CSV parser. The CSV becomes a
+ * single sheet (`sheetId` / `title`, both defaultable). Returns the engine.
+ */
+export declare function importCsv(csv: string | File, options?: ImportOptions & {
+    engine?: RncEngine;
+    sheetId?: number;
+    title?: string;
+}): Promise<RncEngine>;
+/**
+ * Export the engine's contents to an XLSX file (a `Uint8Array` of the .xlsx zip) via the toolkit's
+ * `createExcelFile`. Reads VALUES + styles from the engine (see the formula-source caveat in the file
+ * header). `bandRows` controls the row-band height of the windowed reads.
+ */
+export declare function exportXlsx(engine: RncEngine, options?: {
+    bandRows?: number;
+}): Promise<Uint8Array>;
+/** Export the engine's contents to an ODS file (a `Uint8Array`) via the toolkit's `createODSFile`
+ * (which returns a raw `ArrayBuffer` — wrapped here so both exporters return a `Uint8Array`). */
+export declare function exportOds(engine: RncEngine, options?: {
+    bandRows?: number;
+}): Promise<Uint8Array>;
+/**
+ * Export a sheet's display values as RFC-4180 CSV — a thin pass-through to the engine's native
+ * `exportCsv` (already a direct capability; re-exported here so all file I/O lives in one module).
+ */
+export declare function exportCsv(engine: RncEngine, sheetId: number): string;
+//# sourceMappingURL=io.d.ts.map

package/dist/esm/io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"io.d.ts","sourceRoot":"","sources":["../../src/io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,KAAK,EACV,QAAQ,EACR,aAAa,EAEb,SAAS,EACV,MAAM,4BAA4B,CAAC;AACpC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,2BAA2B,CAAC;AAQvD,OAAO,EAAE,SAAS,EAAuB,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAE5E,wFAAwF;AACxF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC,QAAQ,CAAC,CAAC;IAC/B,wFAAwF;IACxF,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,EAAE,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC/B,kBAAkB,EAAE,YAAY,CAAC,oBAAoB,CAAC,CAAC;IACvD,eAAe,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACjD,WAAW,EAAE,YAAY,CAAC,aAAa,CAAC,CAAC;IACzC;;;;;OAKG;IACH,cAAc,EAAE,aAAa,EAAE,CAAC;CACjC;AAED,yDAAyD;AACzD,MAAM,WAAW,aAAa;IAC5B,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAmCD;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,WAAW,EACnB,QAAQ,SAAkB,EAC1B,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAqDzB;AAyBD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,aAAa,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,OAAO,CAAC,SAAS,CAAC,CAUpB;AAED;yCACyC;AACzC,wBAAsB,SAAS,CAC7B,MAAM,EAAE,WAAW,EACnB,OAAO,GAAE,aAAa,GAAG;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACtE,OAAO,CAAC,SAAS,CAAC,CAKpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,cAAc,GACrB,IAAI,CA0CN;AA6CD;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,GAAG,EAAE,MAAM,GAAG,IAAI,EAClB,OAAO,GAAE,aAAa,GAAG;IACvB,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;CACX,GACL,OAAO,CAAC,SAAS,CAAC,CAoBpB;AAsFD;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;iGACiG;AACjG,wBAAsB,SAAS,CAC7B,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,UAAU,CAAC,CAGrB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAEpE"}