# Sheetwrite — full documentation text

> Sheetwrite is a framework-agnostic, high-performance spreadsheet grid: a canvas grid backed by a Rust/WASM columnar engine, with an imperative core and React, Vue, and Svelte adapters.

Every authored guide in the Sheetwrite documentation, followed by every compiler-verified public API declaration. Generated reference tables (API pages, formula functions, compatibility results, entry-point inventory, performance evidence) are published as HTML and are linked from https://sheetwrite.vercel.app/llms.txt instead of being repeated here.

Packages: 0.4.0. Canonical HTML: https://sheetwrite.vercel.app/docs/

## Contents

- [Runtime ownership](#runtime-ownership)
- [Adapter lifecycle](#adapter-lifecycle)
- [React](#react)
- [Svelte](#svelte)
- [Vanilla JavaScript](#vanilla-javascript)
- [Vue](#vue)
- [Accessibility](#accessibility)
- [Collaboration and offline work](#collaboration-and-offline-work)
- [Configuration](#configuration)
- [Data operations and export](#data-operations-and-export)
- [Formulas](#formulas)
- [Keep app rows in your store](#keep-app-rows-in-your-store)
- [Interaction and editing](#interaction-and-editing)
- [Persistence and recovery](#persistence-and-recovery)
- [Styling and theming](#styling-and-theming)
- [Worker rendering](#worker-rendering)
- [XLSX and export](#xlsx-and-export)
- [Public API contract](#public-api-contract)
- [Compatibility and limits](#compatibility-and-limits)
- [Document operations](#document-operations)
- [Error handling](#error-handling)
- [Your first grid](#your-first-grid)
- [Installation](#installation)
- [Public API declarations](#public-api-declarations)

## Authored guides

### Runtime ownership

Source: https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

## Architecture at a glance

Sheetwrite splits cleanly into a **data engine** (Rust → WASM) and a **renderer**
(canvas). The TypeScript core (`@sheetwrite/core`) owns the host DOM, the
scroll/virtualization math, interactions, and the bridge between the two.

The renderer never owns document cells. Each frame requests one bulk resolved
window per painted pane; an unfrozen sheet uses one window, while frozen panes
use up to four clipped windows.

`GridImpl` is the composition root rather than the owner of every subsystem.
`DocumentController` owns document commits and history, `DatasourceController`
owns paged request generations and cancellation, `GeometryLayoutController`
owns row/column indexes and frozen-window mapping, and `RenderCoordinator` is
the sole animation-frame and paint-cache owner. Interaction-specific controllers
remain separate. These are internal ownership boundaries; the public API stays
the `Grid` and `Store` contracts.

## Canvas rendering and the WASM columnar store

Cells live in the WASM module as typed columns, not as objects. Each cell has a
kind—`EMPTY=0`, `NUMBER=1`, `STRING=2`, `BOOLEAN=3`, or `FORMULA=4`—and
numeric/string data is held in parallel typed arrays. This keeps memory flat and
lets the store hand the renderer a transferable, typed-array-backed window.

Because the engine is columnar and WASM-resident:

- A sheet of 100k+ rows costs no DOM nodes and no per-cell JS objects.
- The render hot path is a single bulk read, not N cell lookups.
- The same snapshot can be transferred to a worker for off-thread painting (see
[Worker rendering](https://sheetwrite.vercel.app/docs/guides/worker-rendering/)).

## Virtualization & scaled scroll

Only the rows intersecting the viewport are ever painted. `computeWindow` turns the
current scroll offset and viewport height into a half-open row range
`[start, end)`, padded by `overscan` rows on each side so a fast scroll reveals
already-painted rows:

```ts
declare function computeWindow(index: unknown, contentTop: number, viewportHeight: number, overscan: number): { start: number; end: number };
```

Row positions come from an `OffsetIndex` — a Fenwick (binary-indexed) tree over
row heights giving `O(log n)` scrollTop ↔ row mapping and `O(log n)` single-row
height edits, so variable row heights stay cheap.

Browsers clamp an element's height at an engine-specific ceiling — Chromium sits
near 33.5 million CSS pixels at 100% zoom, and the ceiling **shrinks with browser
zoom and `devicePixelRatio`**. At the default 28px row height that can be barely
~1M rows, so Sheetwrite never trusts a constant: it measures the real clamp with
a probe element (re-measuring on zoom changes), pins the DOM sizer to that cap,
and `ScaledScroll` maps the capped scrollbar position linearly onto the real
virtual range:

```ts
// DOM scrollTop -> content-space offset (identity below the cap)
declare function toContent(scrollTop: number): number;
// content-space offset -> DOM scrollTop
declare function toScroll(contentOffset: number): number;
```

Below the cap the mapping is the identity; above it, scrolling stays smooth while
the few-pixel-per-row resolution loss is invisible at that scale.

## The Store contract

A grid talks to its data through the `Store` interface. The two reads are
deliberately different:

| Method | Use |
| --- | --- |
| `getVisibleWindow(sheet, rows, cols)` | The **render hot path**. Returns one `VisibleWindowView` for a whole rectangle. The renderer paints from this and must never read cell-by-cell. |
| `getCell(addr)` | A **single-cell** read for interactions, API reads, and tests — never per frame. Returns `{ resolved, style }`. |

`VisibleWindowView` is backed by typed arrays (`values`, `styleIds: Uint32Array`,
a shared `styles` dictionary) so it is worker-transferable, and it is valid only
until the next store mutation or window refresh.

The full interface:

```ts
interface StoreContract {
  getWorkbook(): Workbook;
  getCell(addr: CellAddress): ResolvedCell;
  getVisibleWindow(
    sheet: SheetId,
    rows: { start: number; end: number },
    cols: readonly number[],
  ): VisibleWindowView;
  applyTransaction: Store["applyTransaction"];
  on: Store["on"];
  acknowledgeOperations?(operations: readonly DocumentOp[]): void;
}
```

## Document protocol and storage transactions

`WorkbookSnapshot` is the versioned, JSON-safe authoritative document. Schema 1
contains sheet order and identity, stable column keys, literal/formula/reference
cell inputs, sparse styles and row metadata, merges, frozen panes, conditional
formats, validation rules, protected ranges, notes, row groups, hidden document
metadata, filters, sort keys, and named ranges. Formula source is authoritative;
resolved values are derived caches and are not serialized.

`DocumentOp` is the exhaustive plain-data mutation vocabulary for that document.
Cells, ranges, rows/columns, merges, row metadata, frozen panes, conditional
formats, validation, protection, notes, row groups, named ranges, and sheet
lifecycle operations use the same store reducer and change-event shape. Local
operations submitted through `Grid` enter grid undo/redo history;
`SyncCoordinator` observes each non-empty local transaction and owns its durable
mutation-ID record. Direct `Store.applyTransaction` calls deliberately bypass
grid read-only/history policy. Remote operations remain observable with
`source: "remote"` but enter neither local history nor outgoing synchronization.

```ts
const checked = validateWorkbookSnapshot(JSON.parse(payload));
if (!checked.ok) throw new Error(checked.errors[0]?.message);

const outcome = grid.store.applyTransaction({
  patches: [
    {
      op: "set",
      addr,
      value: { kind: "literal", value: "authoritative input" },
      style: { backgroundColor: "#fde68a" },
    },
  ],
});
```

Snapshot hydration is a separate, validated path: it creates every sheet handle,
bulk-loads literal runs, installs formula/reference/style exceptions, then
recomputes after the complete graph exists. It emits no user event, dirty patch,
or undo entry. Export uses one bulk data-order read per sheet, ignores local
sort/filter views and conditional render styles, and emits deterministic sparse
blocks.

```ts
const saved = await adapter.load(documentId, signal);
const grid = createGridFromSnapshot(host, saved);
const sync = new SyncCoordinator(grid, adapter, {
  documentId,
  serverVersion: saved.version ?? 0,
});

await sync.ready();
const unsubscribeRemote = sync.subscribe(remoteOperationSource);
await sync.sendNext(); // host chooses send/retry timing
```

Each local grid transaction becomes one immutable `PendingCommit` with a stable
`clientMutationId` and explicit `baseVersion`. Records move from `pending` to
`sending`; an applied or duplicate response acknowledges store dirty state and
removes only the matching ID. Transport failure returns that record to `pending`,
so retry sends the same ID. A conflict remains `conflicted` with its local
operations intact and exposes server operations or a snapshot; Sheetwrite does
not silently merge ambiguous structural edits. See
[Offline and collaboration](https://sheetwrite.vercel.app/docs/guides/collaboration/) for durable storage, recovery,
presence, comments, revisions, and the conservative rebase gate.

Remote operations must arrive at exactly `serverVersion + 1`. Older versions and
known mutation echoes are idempotently ignored; a gap emits `reload-required`
instead of guessing. Canonical server operations apply with source `remote`, so
they repaint/recompute without entering the outgoing queue.

Document state does **not** include selection, scroll position, editor/caret
state, search results, temporary highlights, renderer choice, read-only policy,
or local zoom. Those are session state. `Workbook.activeSheet` remains document
metadata in schema 1.

Validation and protection run at the shared local transaction boundary, not only
inside the inline editor. Validation policies can reject atomically, apply with a
warning, or allow input. Protected ranges deny local writes unless the host's
`ProtectionResolver` allows them; the default is deny. `atomic` mode rejects a
transaction containing any denied operation, while `partial` mode filters denied
operations and reports them in `rejections`. Protection is client UX policy, not
server authorization. Remote operations intentionally bypass local protection.

Applied storage transactions emit `change` with the filtered transaction,
per-cell rollback data, accumulated dirty patches, epoch, commit reason, and an
explicit `source` (`local` or `remote`). Remote operations still update formulas
and rendering, but do not re-enter outgoing persistence. Conflicts and no-ops
return explicit outcomes rather than throwing.

Sheet IDs remain stable across rename and reorder. Renaming rewrites canonical
cross-sheet formula source while preserving the stable formula-engine handle.
Removing a referenced sheet rewrites dependents to `#REF!`; undo restores the
sheet snapshot, formulas, styles, metadata, and dependencies. Removing the active
sheet selects the nearest surviving sheet. The final sheet cannot be removed.
All public document actions, including custom calls through `grid.actions`, are
no-ops when the grid is read-only.

### Cell values

A cell value is one of three shapes:

```ts
type CellValue =
  | { kind: "literal"; value: string | number | boolean | null }
  | { kind: "ref"; target: CellAddress } // a plain cross-reference
  | { kind: "formula"; src: string }; // authoritative source; "=" is optional at storage
```

## Headers: letters vs. field names

The grid chrome is a real spreadsheet: the top band shows **column letters**
(A, B, C, … AA) centered, and the left gutter shows **row numbers** (its width is
`theme.rowHeaderWidth`; set it to `0` to hide the gutter). These letters are the
column headers the renderer draws — the `header` you set on a `Column` is metadata
(it is what CSV/XLSX export writes), not the on-canvas header.

Named **field** titles are therefore not chrome. The convention, exactly as in a
real sheet, is to put them in **row 0** (the first data row) and style them
yourself. The live [Vanilla example](https://sheetwrite.vercel.app/vanilla/) reserves row 0 and writes a
styled header band over it once the initial page loads:

```ts
const FIELD_HEADERS = ["ID", "Date", "Customer", "City", "Amount"];

function applyFieldHeader(): void {
  grid.store.applyTransaction({
    patches: FIELD_HEADERS.map((label, col) => ({
      op: "set",
      addr: { sheet: "sales", row: 0, col },
      value: { kind: "literal", value: label },
      style: { bold: true, align: "center", backgroundColor: "#eef1f5" },
    })),
  });
}
```

Datasource pages can carry the same authoritative `CellValue` shapes as eager
data, plus `{ value, style }` wrappers. Formula sources, references, and styles
hydrate without entering dirty history. If row 0 is styled locally while a
page is outstanding, the local edit wins over that stale response; reserving an
empty row 0 in the source remains useful when the source itself should never
provide a title row.

## See also

- [Configuration](https://sheetwrite.vercel.app/docs/guides/configuration/) for the option and method reference.
- [Data operations](https://sheetwrite.vercel.app/docs/guides/data-operations/) for sort/filter views built on the same window read.

### Adapter lifecycle

Source: https://sheetwrite.vercel.app/docs/frameworks/lifecycle/

Every adapter follows one lifecycle:

1. mount the framework component;
2. initialize the shared WASM runtime;
3. create one `Grid` generation;
4. publish readiness;
5. reset only when structural ownership changes;
6. destroy the generation on unmount.

Pick a framework in any tab group below; the selection is remembered and reused across documentation pages.

## Pick the ownership model

Use **`Sheetwrite`** for a data-first, uncontrolled grid: pass columns plus initial rows and let the component own the live document.

Use **`SheetwriteGrid`** for an advanced `Workbook` plus eager data or a datasource. It exposes the imperative `Grid` after readiness and keeps structural configuration under the host's control.

**Vanilla**

The imperative core has one ownership mode: the host supplies the workbook and data, awaits runtime initialization, and destroys the returned grid.

```ts
import { createGrid, initSheetwrite } from "@sheetwrite/core";

await initSheetwrite();
const grid = createGrid(host, { workbook, data });

// Later, when the host DOM lifetime ends:
grid.destroy();
```

**React**

```tsx
<Sheetwrite
  columns={columns}
  defaultRows={rows}
  onGridChange={persist}
  onReady={({ grid, generation, reason }) => observe(grid, generation, reason)}
/>
```

```tsx
<SheetwriteGrid
  ref={gridRef}
  workbook={workbook}
  datasource={datasource}
  onReady={({ grid }) => connect(grid)}
/>
```

`defaultRows` is seed data. Changing it after mount does not replace committed edits; a new `columns`, `defaultRows`, or `sheetName` identity derives a new document and creates a new generation.

**Vue**

```vue
<Sheetwrite
  :columns="columns"
  :default-rows="rows"
  @grid-change="persist"
  @ready="({ grid, generation, reason }) => observe(grid, generation, reason)"
/>
```

```vue
<SheetwriteGrid
  ref="gridComponent"
  :workbook="workbook"
  :datasource="datasource"
  @ready="({ grid }) => connect(grid)"
/>
```

The template ref exposes `{ grid }` after readiness. `defaultRows` seeds the document once; a new `columns`, `defaultRows`, or `sheetName` identity creates a new generation.

**Svelte**

```svelte
<script lang="ts">
  import type { GridReadyEvent } from "@sheetwrite/core/adapter";
  const handleReady = ({ grid, generation, reason }: GridReadyEvent) =>
    observe(grid, generation, reason);
</script>

<Sheetwrite {columns} defaultRows={rows} onGridChange={persist} onReady={handleReady} />
```

```svelte
<script lang="ts">
  import type { Grid } from "@sheetwrite/core";
  import type { GridReadyEvent } from "@sheetwrite/core/adapter";
  let gridRef: Grid | undefined;
  const handleReady = ({ grid }: GridReadyEvent) => connect(grid);
</script>

<SheetwriteGrid bind:grid={gridRef} {workbook} {datasource} onReady={handleReady} />
```

`bind:grid` publishes the live handle and clears it on reset or unmount. `defaultRows` seeds the document once; a new `columns`, `defaultRows`, or `sheetName` identity creates a new generation.

## Readiness is generation-scoped

`onReady` receives `{ grid, generation, reason }`. `generation` is one-based and increments whenever the adapter replaces its `Grid`. `reason` is exactly one of:

- `"initial"` — the first generation after mount and WASM initialization;
- `"input-reset"` — a reset-classified document input changed identity;
- `"renderer-reset"` — `renderer`, `workerUrl`, or `renderers` changed identity.

The exposed handle (React ref, Vue `expose`, Svelte `bind:grid`) is assigned before `onReady` runs and cleared when that generation is destroyed. Reattach subscriptions and collaboration coordinators inside `onReady`; never retain a stale `Grid` across a reset.

## Controlled values do not reset the document

`theme`, `readOnly`, `config`, `overscan`, and `minColumns` are live: changing them updates the current generation in place without recreating the grid or replaying `defaultRows`. Callbacks and host sizing (`height`, `fill`, `className`/`class`, `style`) are also safe to change live.

Structural changes are different. Every reset-classified input is compared by identity:

| Change | Result |
| --- | --- |
| `workbook`, `data`, `datasource`, `datasourceStorage`, `presentation` | New generation, `reason: "input-reset"` |
| `editors`, `protectionResolver`, `mutationPolicy`, `transactionResourceLimits` | New generation, `reason: "input-reset"` |
| `renderer`, `workerUrl`, `renderers` | New generation, `reason: "renderer-reset"` |
| `columns`, `defaultRows`, `sheetName` (simple component) | New derived document, `reason: "input-reset"` |
| `theme`, `readOnly`, `config`, `overscan`, `minColumns` | In-place update, no reset |

Keep reset-classified inputs referentially stable (module constants, memoized values, or state) unless you intend to create a new generation.

## Transactions and persistence

`onGridChange` receives committed transactions. `transaction.patches` is the exhaustive document operation list; `changes` is the cell-level compatibility view.

```ts
function persist(event: ChangeEvent): void {
  if (event.source === "local") operationQueue.push(...event.transaction.patches);
}
```

Use `event.reason` for audit context, not to reconstruct the transaction. For offline durability and replay, persist operations with `SheetwriteStore` or your own `PersistenceAdapter`.

## Initialization failures

Framework components surface initialization errors instead of rendering a dead grid. React uses `fallback` and `onInitializationError`; Vue and Svelte support fallback content or slots plus their error callback/event.

WASM initialization is process-wide and monotonic: every adapter converges on the same runtime, and when several pass an explicit `wasmSource` concurrently, the first source wins. While initialization has not yet succeeded, a changed `wasmSource` or a remount retries it; after the runtime is ready, the source is fixed for the process.

## Server rendering

Importing an adapter during SSR is safe, but the grid initializes only after a browser mount. Put it behind the host framework's client boundary:

- React/Next.js: a client component;
- Nuxt: `<ClientOnly>`;
- SvelteKit: a browser-only branch or client-mounted component.

No framework owns the global runtime. All adapters converge on the same monotonic initializer.

### React

Source: https://sheetwrite.vercel.app/docs/frameworks/react/

`@sheetwrite/react` initializes WASM after client mount. Use `Sheetwrite` for the simple `columns` and `defaultRows` contract; use `SheetwriteGrid` when the host supplies a `Workbook` plus eager data or a datasource.

`onGridChange` reports committed grid changes. `onReady` receives `{ grid, generation, reason }` after the forwarded ref is assigned. Replacing reset-sensitive inputs creates a new generation; destroy persistence/sync coordinators attached to the previous grid.

```tsx
import { Sheetwrite, type GridReadyEvent, type SimpleColumn } from "@sheetwrite/react";
import type { Transaction } from "@sheetwrite/core";
import "@sheetwrite/react/styles.css";

type Row = { name: string; amount: number };

interface SheetProps {
  columns: readonly SimpleColumn<Row>[];
  rows: readonly Row[];
  save: (transaction: Transaction) => void;
  onReady: (event: GridReadyEvent) => void;
}

export function Sheet({ columns, rows, save, onReady }: SheetProps) {
  return (
    <Sheetwrite
      columns={columns}
      defaultRows={rows}
      onGridChange={(event) => save(event.transaction)}
      onReady={onReady}
    />
  );
}
```

Server rendering the component does not initialize WASM. Mount it in a client component in frameworks that render on the server.

- [Run the React example](https://sheetwrite.vercel.app/react/)
- [Lifecycle and reset semantics](https://sheetwrite.vercel.app/docs/frameworks/lifecycle/)
- [`@sheetwrite/react` API](https://sheetwrite.vercel.app/docs/api/react/)

### Svelte

Source: https://sheetwrite.vercel.app/docs/frameworks/svelte/

`@sheetwrite/svelte` initializes WASM in the browser. Bind `grid` when the host needs imperative access and pass `onGridChange` or `onReady` callbacks using the adapter's camel-case props.

The binding is populated before `onReady` and cleared before reset or unmount. A reset publishes a new generation and reason; coordinators attached to the previous grid must be destroyed and recreated.

```svelte
<script lang="ts">
  import {
    Sheetwrite,
    type Grid,
    type GridReadyEvent,
    type SimpleColumn,
  } from "@sheetwrite/svelte";
  import type { ChangeEvent, Transaction } from "@sheetwrite/core";
  import "@sheetwrite/svelte/styles.css";

  type Row = { name: string; amount: number };
  interface Props {
    columns: readonly SimpleColumn<Row>[];
    rows: readonly Row[];
    save: (transaction: Transaction) => void;
    onReady: (event: GridReadyEvent) => void;
  }

  let { columns, rows, save, onReady }: Props = $props();
  let grid: Grid | undefined;
  const handleGridChange = (event: ChangeEvent) => save(event.transaction);
</script>

<Sheetwrite
  {columns}
  defaultRows={rows}
  bind:grid
  onGridChange={handleGridChange}
  {onReady}
/>
```

Use a client-only boundary in SvelteKit when the surrounding route is server rendered.

- [Run the Svelte shell example](https://sheetwrite.vercel.app/svelte/)
- [Lifecycle and reset semantics](https://sheetwrite.vercel.app/docs/frameworks/lifecycle/)
- [`@sheetwrite/svelte` API](https://sheetwrite.vercel.app/docs/api/svelte/)

### Vanilla JavaScript

Source: https://sheetwrite.vercel.app/docs/frameworks/vanilla/

Use `@sheetwrite/core` when the host owns DOM lifetime directly. Call `initSheetwrite()` on the client, pass an existing element to `createGrid`, and retain the returned `Grid` for events and commands.

```ts
import {
  createGrid,
  initSheetwrite,
  type ChangeEvent,
  type ColumnarData,
  type Workbook,
} from "@sheetwrite/core";

export async function mountSheetwrite(
  host: HTMLElement,
  workbook: Workbook,
  data: ColumnarData,
  persistChange: (event: ChangeEvent) => void,
) {
  await initSheetwrite();
  const grid = createGrid(host, { workbook, data });
  const off = grid.on("change", persistChange);

  return () => {
    off();
    grid.destroy();
  };
}
```

A datasource-backed grid may use dense storage or allocation-lazy paged storage. Full-sheet operations can throw `IncompleteDataError` until every required page is loaded. Worker rendering automatically falls back to the main-thread canvas when capabilities or startup fail; observe `renderer-fallback` if the host needs to report that transition.

- [Run the Vanilla example](https://sheetwrite.vercel.app/vanilla/)
- [Installation and explicit WASM sources](https://sheetwrite.vercel.app/docs/start/installation/)
- [Runtime ownership](https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/)
- [`@sheetwrite/core` API](https://sheetwrite.vercel.app/docs/api/core/)

### Vue

Source: https://sheetwrite.vercel.app/docs/frameworks/vue/

`@sheetwrite/vue` initializes WASM after client mount. The simple component accepts `columns` and `defaultRows`; Vue templates use kebab-case event listeners such as `@grid-change` and `@ready`.

The component exposes `grid` before emitting `ready`. A reset clears the old exposed handle, creates a new generation, and then publishes the replacement. Reattach any coordinator that subscribed to the old grid.

```vue
<script setup lang="ts">
import { Sheetwrite, type GridReadyEvent, type SimpleColumn } from "@sheetwrite/vue";
import type { ChangeEvent } from "@sheetwrite/core";
import "@sheetwrite/vue/styles.css";

type Row = { name: string; amount: number };

const { columns, rows } = defineProps<{
  columns: readonly SimpleColumn<Row>[];
  rows: readonly Row[];
}>();
const emit = defineEmits<{
  gridChange: [event: ChangeEvent];
  ready: [event: GridReadyEvent];
}>();

const handleGridChange = (event: ChangeEvent) => emit("gridChange", event);
const handleReady = (event: GridReadyEvent) => emit("ready", event);
</script>

<template>
  <Sheetwrite
    :columns="columns"
    :default-rows="rows"
    @grid-change="handleGridChange"
    @ready="handleReady"
  />
</template>
```

Use a client-only boundary in Nuxt or another server-rendered host; importing or rendering the component on the server does not start WASM.

- [Run the Vue datasource example](https://sheetwrite.vercel.app/vue/)
- [Lifecycle and reset semantics](https://sheetwrite.vercel.app/docs/frameworks/lifecycle/)
- [`@sheetwrite/vue` API](https://sheetwrite.vercel.app/docs/api/vue/)

### Accessibility

Source: https://sheetwrite.vercel.app/docs/guides/accessibility/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

The grid paints to a `<canvas>`, which assistive technology can not read. To make
it navigable, Sheetwrite maintains a parallel **ARIA shadow tree**: a
visually-hidden DOM mirror of the visible window that carries the grid semantics,
while the canvas itself is hidden from the accessibility tree.

## The host grid

`createGrid` annotates the host element as the grid:

| Attribute | Value |
| --- | --- |
| `role` | `"grid"` |
| `aria-multiselectable` | `"true"` |
| `aria-rowcount` | total rows **+ 1** (the column-letter header counts as a row) |
| `aria-colcount` | number of visible columns |
| `aria-readonly` | `"true"` when the grid is `readOnly` (omitted otherwise) |
| `aria-label` | `"Spreadsheet grid"` (default; not overwritten if you set your own) |
| `aria-activedescendant` | the id of the focused cell in the mirror |

The visual layers — the scroller, the overlay, and the `<canvas>` — are all marked
`aria-hidden="true"`, so screen readers ignore the pixels and read the mirror.

## The SR-only mirror

Alongside the host the grid appends a visually-hidden `<div class="sheetwrite-aria">`
with a unique id (`sheetwrite-grid-<n>`) and `role="rowgroup"`. It contains:

- A **header row** — `role="row"`, `aria-rowindex="1"` — whose cells are
`role="columnheader"` with a 1-based `aria-colindex`. Spreadsheet presentation
uses the positional column letter (`A`, `B`, …); data-grid presentation uses
the semantic `Column.header`.
- One **data row** per visible row — `role="row"` with `aria-rowindex` set to the
true row position (data row + 2, leaving index 1 for the header). Its cells are
`role="gridcell"` with a 1-based `aria-colindex`, a stable id
(`<gridId>-<row>-<col>`), and the cell's value as text.
- Every visible cell covered by the current cell/range/multi selection carries
`aria-selected="true"`. A row selection marks its visible row; a column
selection marks both its header and visible cells. The focused cell's id is
mirrored into the host's `aria-activedescendant`.

Sketch of the emitted structure:

```html
<div role="grid" aria-multiselectable="true" aria-rowcount="100001" aria-colcount="5"
     aria-activedescendant="sheetwrite-grid-1-0-0" tabindex="0">
  <!-- canvas / scroller / overlay, all aria-hidden -->
  <div class="sheetwrite-aria" id="sheetwrite-grid-1" role="rowgroup">
    <div role="row" aria-rowindex="1">
      <div role="columnheader" aria-colindex="1">A</div>
      <div role="columnheader" aria-colindex="2">B</div>
    </div>
    <div role="row" aria-rowindex="2">
      <div role="gridcell" aria-colindex="1" id="sheetwrite-grid-1-0-0"
           aria-selected="true">Widget</div>
      <div role="gridcell" aria-colindex="2" id="sheetwrite-grid-1-0-1">12</div>
    </div>
    <!-- … one row per visible row … -->
  </div>
</div>
```

As keyboard or pointer input changes the selection, `aria-selected` and the
host's `aria-activedescendant` update. Scrolling rebuilds the visible mirror.
Horizontal virtualization does not renumber the mirror: if the visible window
starts at sheet column G, its header and cells use `aria-colindex="7"`. Frozen
and scrolling columns likewise keep their absolute one-based sheet positions.
A focused cell note is connected through `aria-describedby` to hidden plain text.
Validation list and checkbox editors use real `listbox` / `option` and `checkbox`
semantics, with the rule help text as their accessible label.
Host-supplied editors receive a `context.label` composed from that same
semantic/positional header and row number. Core applies it to the retained editor
wrapper and to the first focusable control when the editor did not provide its
own name. Commit, cancel, reset, and unmount return focus to the grid; teardown
aborts the editor signal before removing its DOM.

Custom DOM renderer output uses the same mirror for its default cell value.
Non-semantic renderer elements are hidden from assistive technology to avoid a
duplicate announcement. A renderer can expose an explicitly interactive,
labelled control; its keyboard events remain with that control, its element is
retained across scroll and geometry updates, and focus returns to the grid if
virtualization or renderer replacement removes it.

## Limitation: the mirror reflects the visible window

The mirror contains **only the rows and columns currently rendered** (the same
virtualized window the canvas paints, plus overscan) — not the entire sheet. This
is deliberate: materializing 100k+ rows of DOM would defeat the point of canvas
rendering.

The consequences to be aware of:

- `aria-rowindex` / `aria-colindex` carry the **true** positions, so assistive
technology can announce "row N of `aria-rowcount`" correctly even though only a
window is present.
- A screen reader's own virtual cursor can only walk the cells in the rendered
window. Use the grid's keyboard navigation (arrows, Page Up/Down, Home/End — see
[Interaction](https://sheetwrite.vercel.app/docs/guides/interaction/#keyboard-navigation)) to move focus; that scrolls
new rows into view and into the mirror, and updates `aria-activedescendant`.

### Collaboration and offline work

Source: https://sheetwrite.vercel.app/docs/guides/collaboration/

Sheetwrite provides transport-, database-, and authentication-neutral collaboration primitives. The host still owns server sequencing, durable document storage, user identity, authorization, and network lifecycle.

## Load, mount, queue, and acknowledge

Load a validated snapshot before mounting, then let one `SyncCoordinator`
observe local grid transactions. Do not also save `event.changes`: that list is
cell-oriented rollback detail and omits document metadata operations.

```ts
import {
  createGridFromSnapshot,
  SyncCoordinator,
  type PersistenceAdapter,
  type RemoteOperationSource,
} from "@sheetwrite/core";

const documentId = "workbook-42";
const snapshot = await persistenceAdapter.load(documentId);
const grid = createGridFromSnapshot(document.querySelector("#grid")!, snapshot);
const sync = new SyncCoordinator(grid, persistenceAdapter, {
  documentId,
  serverVersion: snapshot.version ?? 0,
});

sync.on((event) => {
  if (event.type === "acknowledged") {
    console.log(`server version ${event.version} acknowledged ${event.clientMutationId}`);
  } else if (event.type === "conflict") {
    console.error("conflict retained for host recovery", event.mutation);
  }
});

await sync.ready();
const unsubscribeRemote = sync.subscribe(remoteOperationSource);

saveButton.addEventListener("click", () => {
  void sync.flush(); // sends in order; each response acknowledges only its mutation ID
});

// Teardown:
// unsubscribeRemote();
// sync.destroy();
// grid.destroy();
```

`SyncCoordinator` subscribes to `Grid` changes itself. Local rendering remains
optimistic; the host controls when to call `sendNext`, `flush`, or `retry`.
`applied` and `duplicate` responses acknowledge the matching operations and
remove that mutation. A transport error leaves the immutable record pending.

An HTTP adapter can stay transport-neutral at the core boundary:

```ts
import type {
  PersistenceAdapter,
  PersistenceCommitRequest,
  PersistenceCommitResponse,
  WorkbookSnapshot,
} from "@sheetwrite/core";

async function responseJson<T>(response: Response): Promise<T> {
  if (!response.ok) throw new Error(`Persistence request failed: ${response.status}`);
  return (await response.json()) as T;
}

const persistenceAdapter: PersistenceAdapter = {
  async load(documentId, signal) {
    const response = await fetch(`/api/documents/${encodeURIComponent(documentId)}`, { signal });
    return responseJson<WorkbookSnapshot>(response);
  },
  async commit(request: PersistenceCommitRequest) {
    const { signal, ...body } = request;
    const response = await fetch(
      `/api/documents/${encodeURIComponent(request.documentId)}/operations`,
      {
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify(body),
        signal,
      },
    );
    return responseJson<PersistenceCommitResponse>(response);
  },
};
```

The server must authenticate the request, authorize every operation, validate
the document schema/policy, and assign the version. Client protection metadata
is not authorization.

## Database-neutral server model

A snapshot plus append-only operation log is the default persistence shape:

```sql
documents(
  document_id       primary key,
  current_version   integer not null,
  snapshot_version  integer not null,
  snapshot_json     json not null
)

document_operations(
  document_id        not null,
  version            integer not null,
  client_mutation_id text not null,
  operations_json    json not null,
  created_at         server_timestamp not null,
  primary key(document_id, version),
  unique(document_id, client_mutation_id)
)
```

Handle `commit()` in one database transaction:

1. Return `duplicate` with the existing version when
`(document_id, client_mutation_id)` already exists.
2. Lock/read the document version. If it differs from `baseVersion`, return
`conflict` with ordered operations since base or a current snapshot.
3. Validate and authorize the submitted `DocumentOp[]` on the server.
4. Append at `current_version + 1`, update the document version, and return
`applied` with the same mutation ID.
5. Periodically fold the log into `snapshot_json`; never rewrite operation
versions or accept client-authored server timestamps.

Normalized cell tables are an alternative for products that need SQL queries
over cell values. They do not replace the protocol: the host must still
reconstruct a complete schema-versioned `WorkbookSnapshot`, preserve formula
source/style/metadata, and serialize structural operations under one document
version. Mixing independent cell writes with the operation log breaks atomic
row/column/formula semantics.

## Durable pending commits

`SyncCoordinator` can receive a `PendingCommitStorage` adapter. With one configured, it:

1. persists each immutable commit before it can be sent;
2. restores pending commits on startup and reapplies them locally as remote-source operations, so restoration does not echo into the outgoing queue;
3. retries with the original `clientMutationId` after reconnect or reload;
4. removes durable work only after an `applied` or `duplicate` acknowledgement; and
5. retains conflicts and storage failures for explicit host recovery.

Await `coordinator.ready()` before declaring startup synchronized. Use `initialConnection: "offline"` for offline-first startup, `setOnline(false)` on disconnect, and `setOnline(true)` to reconnect and drain pending work in order. `coordinator.state` distinguishes connection state from hydration, persistence, sending, conflict, and error activity.

The browser IndexedDB implementation is intentionally isolated from Node and SSR entrypoints:

```ts
import { SyncCoordinator } from "@sheetwrite/core";
import { IndexedDbPendingCommitStorage } from "@sheetwrite/core/browser";

const pendingStorage = new IndexedDbPendingCommitStorage({
  databaseName: "my-product-sheetwrite",
});

const sync = new SyncCoordinator(grid, persistenceAdapter, {
  documentId: "workbook-42",
  serverVersion: snapshot.version ?? 0,
  pendingStorage,
  initialConnection: navigator.onLine ? "online" : "offline",
});

await sync.ready();
window.addEventListener("online", () => sync.setOnline(true));
window.addEventListener("offline", () => sync.setOnline(false));
```

IndexedDB record migration is versioned. Unsupported future schemas, blocked upgrades, quota exhaustion, transaction failures, and aborts surface as typed `IndexedDbPendingCommitStorageError` codes. Core continues to work without IndexedDB when no durable adapter is supplied.

## Remote operations and version gaps

`SyncCoordinator.subscribe` accepts either `RemoteOperationSource` or `AsyncIterable<VersionedOperation>`. Operations apply only at `serverVersion + 1`; own echoed mutation IDs and already acknowledged IDs are deduplicated. Remote application uses `Grid.applyRemoteOperations`, so it does not create outgoing dirty work or local undo entries.

A gap emits `reload-required`. Prefer fetching missing ordered operations through
`recoverVersionGap`; the coordinator applies them in sequence. A returned
snapshot is a host remount signal, not an automatic store replacement.
`resumeAfterReload(snapshot)` updates retained queue base versions only after the
host has installed that snapshot and reapplied local work; it does not hydrate a
grid or attach the coordinator to a newly created grid.

### Conflict and snapshot reload

Never acknowledge or discard a conflicted mutation implicitly. If the server
returns both `operationsSinceBase` and a current snapshot, the host can gate
every pending transaction through the conservative rebaser, clear the old
durable IDs, remount, and submit the safe results as new mutations:

```ts
import {
  createGridFromSnapshot,
  rebaseDocumentOperations,
  SyncCoordinator,
  type Grid,
  type PersistenceCommitResponse,
} from "@sheetwrite/core";

type ConflictResponse = Extract<PersistenceCommitResponse, { status: "conflict" }>;
interface SyncSession {
  grid: Grid;
  sync: SyncCoordinator;
  unsubscribeRemote: () => void;
}

async function reloadAfterConflict(
  session: SyncSession,
  response: ConflictResponse,
): Promise<SyncSession> {
  if (!response.operationsSinceBase) {
    console.error("Manual conflict review required: server did not return an operation tail");
    return session;
  }

  const pending = session.sync.pendingCommits();
  const remoteOperations = response.operationsSinceBase.flatMap((entry) => [
    ...entry.operations,
  ]);
  const safeBatches: Array<ReturnType<typeof rebaseDocumentOperations> & {
    status: "rebased";
  }> = [];

  for (const record of pending) {
    const result = rebaseDocumentOperations(record.operations, remoteOperations);
    if (result.status === "conflict") {
      console.error("Manual conflict review required", result.conflict);
      return session; // old queue and grid remain intact
    }
    safeBatches.push(result);
  }

  const latest = response.snapshot ?? (await persistenceAdapter.load(documentId));
  for (const record of pending) {
    await pendingStorage.remove(documentId, record.clientMutationId);
  }

  session.unsubscribeRemote();
  session.sync.destroy();
  session.grid.destroy();

  const grid = createGridFromSnapshot(document.querySelector("#grid")!, latest);
  const sync = new SyncCoordinator(grid, persistenceAdapter, {
    documentId,
    serverVersion: latest.version ?? 0,
    pendingStorage,
  });
  await sync.ready(); // the stale IDs were removed before hydration

  for (const batch of safeBatches) {
    const outcome = grid.applyTransaction({ patches: [...batch.operations] });
    if (outcome.status !== "applied") {
      throw new Error(`Rebased local transaction was not applied: ${outcome.status}`);
    }
  }

  const unsubscribeRemote = sync.subscribe(remoteOperationSource);
  await sync.flush();
  return { grid, sync, unsubscribeRemote };
}
```

When the rebaser reports `conflict`—overlap, formulas across structural changes,
concurrent moves, or sheet lifecycle ambiguity—keep the original queue and show
product-specific conflict UI. If the server returns only a snapshot, the host
cannot infer a safe transform; offer explicit discard/export/manual re-entry
instead. Reloading a snapshot over pending edits without this decision loses
intent.

## Presence

`PresenceCoordinator` publishes actor metadata, active sheet, and bounded selection ranges through a host `PresenceTransport`. Presence:

- is never written to document operations, snapshots, dirty state, or history;
- expires according to local heartbeat receipt time;
- is bounded by actor and range limits;
- clamps ranges to valid visible grid geometry and hides other-sheet or filtered selections;
- reuses the grid overlay element pool rather than mutating canvas cells; and
- supports privacy controls for display name, selections, inbound presence, and actor filtering.

Presence is advisory UI state. Do not use it for authorization, locking, or conflict prevention.

## Revisions

`RevisionCoordinator` delegates revision listing, loading, and restore to a `RevisionAdapter`. Preview snapshots pass through the optional host schema migrator and mount with `readOnly: true`. Restore requests include `targetVersion`, current `baseVersion`, and a stable mutation ID. The adapter contract requires restore to create a newer auditable server version; it must never rewind database state in place.

## Comments

Comments are document-adjacent server entities, not fields on every cell. `CommentCoordinator` stores stable thread/message IDs and range or cell anchors, while adapters supply authenticated author references and server timestamps. Create, reply, and resolve requests contain no client-authored identity or time fields. Authorization remains entirely host/server-owned.

Comment streams are versioned independently. Out-of-order events emit a gap rather than being applied speculatively.

## Concurrent structural editing decision

Sheetwrite uses deterministic server ordering plus conservative rebase, not a CRDT or general OT layer.

`rebaseDocumentOperations` safely shifts non-overlapping literal edits and references across server-ordered row/column insertions and deletions. It reports explicit conflicts for:

- edits or range pastes overlapping inserted/deleted boundaries;
- targets or references deleted by a concurrent operation;
- formula source crossing structural edits, because text-only rewriting cannot preserve sheet-aware reference intent;
- concurrent row/column moves;
- conflicting sheet lifecycle operations; and
- metadata families that need domain-specific transforms.

This choice preserves stable sheet IDs and authoritative formula source without lossy adapters. A CRDT/OT dependency is not justified by current scenarios: short-lived offline and online collaboration converge under server sequencing, while long-lived offline concurrent structural edits require product-level conflict UX and spreadsheet-specific formula/range semantics that generic sequence CRDTs do not supply. Revisit only if requirements demand automatic preservation of those ambiguous edits and scenario tests define the intended result for every structural/formula case.

### Configuration

Source: https://sheetwrite.vercel.app/docs/guides/configuration/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

Everything you pass to `createGrid(host, opts)` lives in `GridOptions`. This page
lists every field with its type and default, the optional toolbar `GridConfig`,
and the `Grid` instance API.

## GridOptions

```ts
type CreateGrid = (host: HTMLElement, opts: GridOptions) => Grid;
```

| Field | Type | Default | Notes |
| --- | --- | --- | --- |
| `workbook` | `Workbook` | — (required) | Sheets, columns, row counts, and the `activeSheet` id. |
| `presentation` | `"spreadsheet" \| "data-grid"` | `"spreadsheet"` | Positional A/B/C headers or semantic `Column.header` labels. Addressing and data rows are unchanged. |
| `data` | `ColumnarData` | `undefined` | Eager, in-memory, column-major values. Pass this **or** `datasource`. |
| `datasource` | `DataSource` | `undefined` | Lazy, paged async source; rows fetched per visible window. |
| `datasourceStorage` | `DataSourceStorageOptions` | `{ mode: "dense" }` | Use `{ mode: "paged", chunkRows?, cacheBytes? }` for allocation-lazy datasource storage. |
| `renderer` | `"canvas" \| "worker"` | `"canvas"` | `"worker"` paints off-thread via OffscreenCanvas, falling back to canvas. See [Worker rendering](https://sheetwrite.vercel.app/docs/guides/worker-rendering/). |
| `workerUrl` | `string \| URL` | `undefined` | Browser-fetchable module URL, e.g. `"/sheetwrite/worker.js"` after copying the package `dist/`; Vite can import `@sheetwrite/core/worker?worker&url`. See [Worker rendering](https://sheetwrite.vercel.app/docs/guides/worker-rendering/). |
| `theme` | `Partial<Theme>` | `undefined` | Overrides merged over `DEFAULT_THEME` and any `--sheetwrite-*` CSS vars. See [Styling](https://sheetwrite.vercel.app/docs/guides/styling/). |
| `readOnly` | `boolean` | `false` | When `true`, all mutating interactions (edit, clear, fill, paste, restyle) are disabled and the host gets `aria-readonly="true"`. |
| `protectionResolver` | `ProtectionResolver` | `undefined` | Host callback for protected local mutations; no resolver means deny. Client-side UX policy only, never server authorization. |
| `mutationPolicy` | `"atomic" \| "partial"` | `"atomic"` | Reject the whole local transaction on a denied protected operation, or apply allowed operations and report denied ones. |
| `renderers` | `Record<string, CellRenderer>` | `{}` | Custom cell renderers registered up front; reference one by name via `Column.renderer`. Also see `defineCellRenderer`. |
| `editors` | `Record<string, CellEditor>` | `{}` | Host-owned cell editors registered up front; reference one by name via `Column.editor`. |
| `overscan` | `number` | `6` | Row and visible-column positions painted on each viewport edge; `0` disables the buffer. |
| `minColumns` | `number` | workbook width | Minimum rendered/store column count, including empty spreadsheet padding columns. |
| `config` | `GridConfig` | `undefined` | Presence opts into the built-in toolbar (see below). Omit for no toolbar. |

Framework adapters classify every `GridOptions` field centrally. `workbook`,
`data`, `datasource`, `datasourceStorage`, `presentation`, `editors`,
`protectionResolver`, `mutationPolicy`, and `transactionResourceLimits` create
an `input-reset`; `renderer`, `workerUrl`, and `renderers` create a
`renderer-reset`. `theme`, `readOnly`, `config`, `overscan`, and `minColumns`
update the existing grid live. Readiness includes the resulting generation and
reset reason.

Framework adapters also accept `wasmSource`. Initialization is process-wide and
first-source-wins: concurrent calls using the same source share one attempt, while
a different source rejects until that attempt settles. If the winning attempt
succeeds, every still-mounted adapter becomes ready even when its prop changed
during the attempt. Changing `wasmSource` after readiness warns and keeps the live
grid, selection, edits, generation, and ready-event count unchanged. A true
initialization failure remains observable through `onInitializationError` and a
later source can retry it.

## Spreadsheet and data-grid presentation

`presentation: "spreadsheet"` is the backward-compatible default. It paints and
announces positional column headers (`A`, `B`, `C`, …). Use
`presentation: "data-grid"` when the columns describe row-object fields:

```ts
const workbook: Workbook = {
  activeSheet: "people",
  sheets: [{
    id: "people",
    name: "People",
    rowCount: people.length,
    columns: [
      { key: "name", header: "Customer name", width: 220, type: "text" },
      { key: "status", header: "Account status", width: 160, type: "text" },
    ],
  }],
};

const grid = createGrid(host, {
  workbook,
  data,
  presentation: "data-grid",
});
```

The semantic header occupies the same header band as `A/B/C`; it does **not**
consume row 0. Cell addresses, formulas, selections, row numbers, clipboard
payloads, CSV/XLSX schema labels, mutation events, and datasource ranges keep
their existing zero-based data coordinates. Table exports use `Column.header`
in both presentation modes. The data-first `Sheetwrite` components select
`"data-grid"` automatically because every `SimpleColumn` requires a `title`.

Presentation is construction-bound. Changing it through a framework adapter
replaces the grid with `reason: "input-reset"` rather than renaming columns or
moving data in place.

## Host-supplied editors

Set `Column.editor` to a key in `GridOptions.editors`. A custom editor takes
precedence over the built-in validation-list editor. If the key is absent,
Sheetwrite falls back to validation editing or its stock text/date editor.

```ts
const statusEditor: CellEditor = {
  mount(host, context) {
    const select = document.createElement("select");
    select.setAttribute("aria-label", context.label);
    for (const value of ["Prospect", "Active", "Paused"]) {
      select.add(new Option(value, value));
    }
    select.value = context.text;
    host.appendChild(select);
    select.focus();

    return {
      update(next) {
        select.setAttribute("aria-label", next.label);
        select.value = next.text;
      },
      reposition(rect) {
        select.style.width = `${rect.width}px`;
        select.style.height = `${rect.height}px`;
      },
      commit() {
        return select.value;
      },
      cancel() {},
      destroy() {
        select.remove();
      },
    };
  },
};

const grid = createGrid(host, {
  workbook,
  data,
  presentation: "data-grid",
  editors: { status: statusEditor },
});
```

The returned value is parsed with the column's normal type and committed through
the same document transaction as stock editing. That preserves protection,
validation, mutation policy, undo/redo, change events, and edit-commit events.
An asynchronous commit remains bound to the data row captured at `mount`, even
when sorting or `clearView()` moves that row before the promise settles. If a
filter removes the row from the view, Sheetwrite cancels and aborts the pending
edit instead of retargeting another row. Returning a rejected promise,
`undefined`, or a non-string value from untyped JavaScript cancels without a
mutation. Enter commits and moves down, Tab/Shift+Tab commit and move
horizontally, and Escape cancels. Focus returns to the grid after commit or
cancel.

For remote choices, use the editor-owned `AbortSignal`; never let a late request
write into a destroyed editor:

```ts
const assigneeAutocomplete: CellEditor = {
  mount(host, context) {
    const input = document.createElement("input");
    const list = document.createElement("datalist");
    list.id = `assignees-${context.address.row}-${context.address.col}`;
    input.setAttribute("list", list.id);
    input.setAttribute("role", "combobox");
    input.setAttribute("aria-label", context.label);
    input.value = context.initialInput ?? context.text;
    host.append(input, list);
    input.focus();

    void fetch(`/api/people?q=${encodeURIComponent(input.value)}`, {
      signal: context.signal,
    })
      .then((response) => response.json() as Promise<Array<{ id: string; name: string }>>)
      .then((people) => {
        if (context.signal.aborted) return;
        list.replaceChildren(
          ...people.map((person) => {
            const option = document.createElement("option");
            option.value = person.name;
            option.dataset.id = person.id;
            return option;
          }),
        );
      })
      .catch((error: unknown) => {
        if (!(error instanceof DOMException && error.name === "AbortError")) throw error;
      });

    return {
      update(next) {
        input.setAttribute("aria-label", next.label);
      },
      reposition(rect) {
        input.style.width = `${rect.width}px`;
      },
      async commit() {
        await Promise.resolve();
        return input.value;
      },
      cancel() {},
      destroy() {
        input.remove();
        list.remove();
      },
    };
  },
};
```

One retained wrapper and one `CellEditorInstance` exist per active edit:

| Hook / value | Guarantee |
| --- | --- |
| `mount(host, context)` | Runs once. The host is positioned over the active cell. |
| `context.address` / `viewAddress` | Canonical data-row and current displayed-row snapshots. They are readonly and mutating a JavaScript object received by the editor cannot retarget the edit. |
| `context.value` / `text` / `initialInput` | Resolved scalar, formatted text, and optional typed character. |
| `context.label` | Accessible name derived from semantic/positional header plus row number. |
| `context.signal` | Aborted before the editor's `cancel()` or `destroy()` hook on cancel, commit, reset, or unmount. |
| `context.commit()` / `cancel()` | Optional editor-driven completion using the canonical path. A non-string commit from untyped JavaScript cancels safely. |
| `update(context)` | External value, theme, zoom, view permutation, or geometry-sensitive state changed without replacing ownership. |
| `reposition(rect)` | The active cell moved or resized. |
| `commit()` | May return input synchronously or asynchronously; duplicate completion is ignored. |
| `cancel()` | Notification before a host-requested cancellation; the signal is already aborted. |
| `destroy()` | Runs exactly once; late async work must observe the aborted signal. A thrown hook error is reported without interrupting Sheetwrite's DOM, listener, or store cleanup. |

`editors` is construction-bound so React/Vue/Svelte resets safely abort and
destroy an active editor before publishing the new grid generation. All adapters
accept the same registry:

```tsx
<SheetwriteGrid
  ref={gridRef}
  workbook={workbook}
  data={data}
  presentation="data-grid"
  editors={{ status: statusEditor, assignee: assigneeAutocomplete }}
  onCommandStateChange={({ states }) => setCommandStates(states)}
/>
```

```vue
<SheetwriteGrid
  ref="gridComponent"
  :workbook="workbook"
  :data="data"
  presentation="data-grid"
  :editors="{ status: statusEditor, assignee: assigneeAutocomplete }"
  @command-state-change="({ states }) => commandStates = states"
/>
```

```svelte
<SheetwriteGrid
  bind:grid
  {workbook}
  {data}
  presentation="data-grid"
  editors={{ status: statusEditor, assignee: assigneeAutocomplete }}
  onCommandStateChange={(event: GridEvents["command-state-change"]) => commandStates = event.states}
/>
```

### Datasource pages

The cancellable request API owns one visible-window generation. Pages can carry
authoritative formula source and style rather than only resolved scalars:

```ts
import type { DataSource } from "@sheetwrite/core";

interface ApiRow {
  label: string;
  quantity: number;
  price: number;
}

const datasource: DataSource = {
  async getRows({ sheet, start, end, signal, revision }) {
    const response = await fetch(
      `/sheets/${encodeURIComponent(sheet)}?start=${start}&end=${end}`,
      { signal },
    );
    if (!response.ok) throw new Error(`Datasource request failed: ${response.status}`);
    const records = (await response.json()) as ApiRow[];
    return {
      start,
      revision: response.headers.get("etag") ?? revision,
      rows: records.map((record, index) => ({
        label: record.label,
        quantity: record.quantity,
        price: record.price,
        total: {
          value: {
            kind: "formula",
            src: `=B${start + index + 1}*C${start + index + 1}`,
          },
          style: { numberFormat: "$#,##0.00", bold: true },
        },
      })),
    };
  },
};
```

`rows` may contain scalars, `CellValue` objects, or
`{ value: CellValue, style?: CellStyle }` wrappers. Hydrated formulas,
references, and styles do not emit user change events. Short pages mark only the
returned rows loaded; malformed ranges emit `datasource-error` and remain
retryable. Resetting or destroying the grid aborts outstanding requests, and a
late page never overwrites a cell edited after that request began.

Dense storage is the default. `{ mode: "paged" }` allocates
power-of-two row chunks only for loaded or locally edited areas; `cacheBytes`
bounds clean cached chunks, while dirty chunks remain pinned until
acknowledgement. Full-sheet queries and exports report incomplete data until all
required pages are loaded. `Store.queryCapability(sheet)` and
`getCellLoadState(addr)` expose that state.
Default chunk/cache values and eviction behavior are listed in [Compatibility and limits](https://sheetwrite.vercel.app/docs/reference/compatibility-limits/#rendering-interaction-and-paged-data).

### Serializable documents

Use `WorkbookSnapshot` plus `validateWorkbookSnapshot()` at persistence
boundaries. `schemaVersion: 1` rejects unsupported future schemas with
structured errors. `DocumentOp` is the exhaustive reducer operation union,
including metadata and sheet lifecycle operations.
Session-only grid options such as `renderer`, `readOnly`, local zoom, selection,
scroll, search, and temporary highlights never belong in a snapshot.

`createGridFromSnapshot(host, snapshot, options)` validates and hydrates every
sheet before mounting. Hydration emits no change event or undo entry.
`grid.exportSnapshot()` uses bulk sheet reads and returns deterministic sparse
blocks. `grid.applyRemoteOperations(operations)` emits a change with
`source: "remote"` while remaining outside local undo history and
`SyncCoordinator`'s outgoing queue. `SyncCoordinator` queues each non-empty local
transaction as an immutable mutation record. Its `serverVersion` option is
required and should come from the loaded snapshot.
`sendNext()` and `retry(id)` are host-controlled; retries retain the original
ID. `subscribe(source)` accepts a transport-neutral callback source and validates
strict version order. Use `MemoryPersistenceAdapter` as an executable,
server-sequenced reference—not as durable storage. Adapter methods accept
`AbortSignal`; transport failures use `PersistenceError`, while version
conflicts are typed commit responses that retain local work.

A `CellRenderer` paints or retains a DOM node for each cell in the rendered
window. When `dom` is present, it owns the cell content (the canvas still paints
the cell background, border, headers, and grid lines):

```ts
interface CellRenderer {
  canvas?(ctx: CanvasRenderingContext2D, c: CellPaintContext): void;
  dom?(c: CellPaintContext): HTMLElement;
  update?(element: HTMLElement, c: CellPaintContext): void;
  destroy?(element: HTMLElement): void;
}
```

`dom` creates an element when a cell enters the bounded rendered window.
`update` receives that same element after values, styles, theme, zoom, size, or
scroll geometry change. `destroy` runs immediately before the element leaves
the window, is replaced by a newly registered renderer, or its grid is reset or
destroyed. Implement `update` to preserve focus and element-local state. A
legacy renderer with only `dom` is recreated when its value, style, theme, or
size changes, but not for a pure scroll.

DOM cells are clipped to the viewport and frozen pane that owns them. A merged
range produces one node for its anchor, not one node per covered cell. Plain
renderer output stays hidden from assistive technology because the compact ARIA
mirror already exposes its cell value. To make a renderer explicitly
interactive, return a native control (or add a non-negative `tabindex`), give it
an accessible name, and set `element.style.pointerEvents = "auto"`. Keyboard
events from that control stay with the control instead of moving the grid.

With `renderer: "worker"`, `canvas` hooks cannot cross the Worker boundary.
`dom`, `update`, and `destroy` still run on the main thread in the retained
overlay.

## GridConfig (toolbar)

Set `config` to show the built-in toolbar. Each flag toggles one control; all
flags **default to `true`** when `config` is present. The one special case is
`toolbar: false`, which suppresses the toolbar entirely.

```ts
createGrid(host, { workbook, config: {} });               // toolbar with every control
createGrid(host, { workbook, config: { sort: false } });  // toolbar, no sort control
createGrid(host, { workbook, config: { toolbar: false } }); // no toolbar
createGrid(host, { workbook });                            // no toolbar (config omitted)
```

| Flag | Type | Default | Control |
| --- | --- | --- | --- |
| `toolbar` | `boolean` | `true`¹ | Master switch. `false` removes the toolbar. |
| `bold` | `boolean` | `true` | Bold toggle. |
| `italic` | `boolean` | `true` | Italic toggle. |
| `align` | `boolean` | `true` | Left / center / right alignment. |
| `textColor` | `boolean` | `true` | Text color picker. |
| `fillColor` | `boolean` | `true` | Fill (background) color picker. |
| `border` | `boolean` | `true` | Border control. |
| `clearFormat` | `boolean` | `true` | Clear formatting. |
| `merge` | `boolean` | `true` | Merge / unmerge selection. |
| `sort` | `boolean` | `true` | Sort the selected column. |
| `export` | `boolean` | `true` | CSV / XLSX export buttons. |
| `undo` | `boolean` | `true` | Undo / redo buttons (also bound to Ctrl+Z / Ctrl+Shift+Z). |

¹ "Default `true`" means: when you supply a `config` object at all. With no
`config` there is no toolbar.

The export flag always enables CSV. Its XLSX button requires an explicit
optional installation and `import "@sheetwrite/xlsx/register"` before use; the
framework packages do not install an XLSX backend.
Direct `grid.exportXlsx(...)` calls reject on failure; built-in toolbar and
context-menu actions report the same failure through one `export-error` event.

Every control acts on the current selection — see [Interaction](https://sheetwrite.vercel.app/docs/guides/interaction/).

### Host-owned command state

Host chrome can use `grid.actions` without duplicating selection/history logic.
Query one command with `grid.getCommandState(name)` or subscribe to the complete
snapshot through `command-state-change` (`onCommandStateChange` in React/Svelte,
`@command-state-change` in Vue):

```ts
const update = (bold: GridCommandState, undo: GridCommandState) => {
  undoButton.disabled = undo.disabled;
  boldButton.disabled = bold.disabled;
  boldButton.setAttribute(
    "aria-pressed",
    bold.activity === "mixed" ? "mixed" : String(bold.activity === "active"),
  );
};

update(grid.getCommandState("bold"), grid.getCommandState("undo"));
const stop = grid.on("command-state-change", ({ states }) => {
  update(states.bold, states.undo);
});

boldButton.addEventListener("click", () => grid.actions.toggleBold());
undoButton.addEventListener("click", () => grid.actions.undo());

// Run during host teardown.
stop();
```

`disabled` accounts for read-only mode, empty selections, and undo/redo history.
Formatting commands report `activity: "inactive" | "active" | "mixed"` across
the current selection. The built-in toolbar uses the same contract, including
native `disabled` and `aria-pressed="mixed"`. Aggregation is bounded; very large
selections conservatively report `mixed` rather than forcing an unbounded cell
walk.

### Feature flags

Three `GridConfig` fields enable behavior that lives outside the toolbar row:

| Field | Type | Default | Effect |
| --- | --- | --- | --- |
| `find` | `boolean` | `true` | Built-in **Ctrl+F** search box, next/previous controls, and live match count. |
| `contextMenu` | `boolean \| ContextMenuItems` | `true` | Built-in right-click menu, disabled menu, static readonly rows, or a context-aware row factory. |
| `icons` | `Partial<Record<ToolbarActionName, ToolbarIcon>>` | `undefined` | Built-in toolbar icon overrides. Strings render as text; a DOM `Node` or `() => Node` supports SVG/HTML without `innerHTML`. |

### Context-menu items

The default menu contains copy, cut, paste, clear contents, row
insert/delete/hide/show/auto-fit, column insert/delete/hide/show/auto-fit,
clear column filter, merge, and unmerge actions, with separators between
groups. `exportCsv` and `exportXlsx` are also valid built-in actions in a
custom list.

`ContextMenuItems` is either a `readonly ContextMenuItem[]` or a factory
evaluated for each `ContextMenuContext`. An item may set a stable `id`,
built-in `action`, visible `label`, `shortcut` hint, and static or
context-aware `visible`/`disabled` policy. The lean context carries only
`cell`, `clientX`, and `clientY`. `onClick(grid, cell)` overrides `action`;
hidden separators are normalized.

```ts
const config = {
  contextMenu: (context) => [
    { id: "copy", action: "copy", label: "Copy value", shortcut: "Ctrl+C" },
    { action: "separator" },
    {
      id: "inspect",
      label: "Inspect cell",
      visible: context.cell !== null,
      disabled: ({ cell }) => cell === null,
      onClick(grid, cell) {
        if (cell !== null) console.log(grid.store.getCell(cell));
      },
    },
    { action: "exportCsv", label: "Download CSV" },
  ],
} satisfies GridConfig;
```

For fully host-owned UI, set `contextMenu: false`, listen for the DOM
`contextmenu` event on the host, call
`grid.getCellAtPoint(event.clientX, event.clientY)`, update selection, and
invoke `grid.actions` from the host menu. Sheetwrite does not prescribe the
host's event lifecycle:

```ts
host.addEventListener("contextmenu", (event) => {
  event.preventDefault();
  const cell = grid.getCellAtPoint(event.clientX, event.clientY);
  if (cell !== null) grid.setSelection({ kind: "cell", addr: cell });
  host.dispatchEvent(
    new CustomEvent("sheetwrite:context-menu", {
      detail: { cell, x: event.clientX, y: event.clientY, actions: grid.actions },
    }),
  );
});
```

See [Interaction → Context menu](https://sheetwrite.vercel.app/docs/guides/interaction/#context-menu),
[Styling](https://sheetwrite.vercel.app/docs/guides/styling/#widget-and-context-menu-styling), and the
generated [`ContextMenuContext`](https://sheetwrite.vercel.app/docs/api/core/context-menu-context/),
[`ContextMenuItems`](https://sheetwrite.vercel.app/docs/api/core/context-menu-items/),
[`ContextMenuItem`](https://sheetwrite.vercel.app/docs/api/core/context-menu-item/), and
[`Grid.getCellAtPoint`](https://sheetwrite.vercel.app/docs/api/core/grid/#getcellatpoint) contracts.

Undo/redo and find are keyboard-driven and work without the toolbar: **Ctrl+Z**
undoes the last edit, **Ctrl+Shift+Z** redoes it, and **Ctrl+F** opens the find
widget (unless `find: false`).

## Grid instance

`createGrid` returns an imperative handle:

```ts
interface Grid {
  readonly store: Store;
  readonly actions: GridActions;
  setActiveSheet(id: SheetId): void;
  scrollToCell(addr: CellAddress): void;
  getSelection(): Selection | null;
  setSelection(sel: Selection | null): void;
  setTheme(theme: Partial<Theme>): void;
  defineCellRenderer(name: string, renderer: CellRenderer): void;
  aggregate(col: number, op: AggregateOp): number;
  sortBy(col: number, ascending?: boolean): void;
  sortByMulti(keys: readonly SortKey[]): void;
  filterBy(col: number, needle: string): void;
  setColumnFilter(col: number, filter: ColumnFilter | null): void;
  getColumnFilters(): ReadonlyMap<number, ColumnFilter>;
  distinctValues(col: number, limit?: number): CellScalar[];
  hideRows(rows: readonly number[]): void;
  showRows(rows?: readonly number[]): void;
  hiddenRows(): readonly number[];
  hideColumns(cols?: readonly number[]): void;
  showColumns(cols?: readonly number[]): void;
  hiddenColumns(): readonly number[];
  groupRows(start: number, end: number): void;
  ungroupRows(start: number, end: number): void;
  setGroupCollapsed(start: number, collapsed: boolean): void;
  rowGroups(): readonly RowGroup[];
  clearView(): void;
  undo(): void;
  redo(): void;
  exportCsv(filename: string): void;
  exportXlsx(filename: string): Promise<void>;
  search(query: string, opts?: SearchOptions): SearchResult;
  findNext(): SearchResult;
  findPrev(): SearchResult;
  clearSearch(): void;
  replaceCurrent(replacement: string): SearchResult;
  replaceAll(replacement: string): ReplaceResult;
  insertRows(at: number, count?: number): void;
  removeRows(at: number, count?: number): void;
  insertColumns(at: number, count?: number): void;
  removeColumns(at: number, count?: number): void;
  highlightCells(ranges: readonly HighlightRange[] | null, color?: string): void;
  styleRange(range: Range, style: Partial<CellStyle> | null): void;
  setValidationRule(rule: DataValidationRule): ApplyTransactionResult;
  removeValidationRule(id: string): ApplyTransactionResult;
  setProtectedRange(range: ProtectedRange): ApplyTransactionResult;
  removeProtectedRange(id: string): ApplyTransactionResult;
  setProtectionResolver(resolver?: ProtectionResolver, mode?: MutationPolicyMode): void;
  setNote(addr: CellAddress, text: string | null): ApplyTransactionResult;
  getNote(addr: CellAddress): string | null;
  beginEdit(row: number, col: number, initial?: string, selectAll?: boolean): void;
  dataEdge(row: number, col: number, dRow: number, dCol: number): number | null;
  setRowHeight(row: number, height: number): void;
  setColumnWidth(col: number, width: number): void;
  autoFitRows(range?: Range): void;
  autoFitColumns(cols?: readonly number[]): void;
  setFrozen(rows: number, cols?: number): void;
  setZoom(zoom: number): void;
  getZoom(): number;
  on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void;
  refresh(): void;
  destroy(): void;
}
```

| Method | Purpose |
| --- | --- |
| `store` | The underlying [`Store`](https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/#the-store-contract) — apply transactions, read cells, subscribe. |
| `actions` | Imperative action surface (`toggleBold()`, `merge()`, `undo()`, `exportCsv()`, …) the toolbar and context menu bind to — use it to wire custom controls. |
| `setActiveSheet(id)` | Switch the visible sheet. |
| `scrollToCell(addr)` | Scroll a cell into view. |
| `getSelection()` / `setSelection(sel)` | Read or set the current [`Selection`](https://sheetwrite.vercel.app/docs/guides/interaction/#selection-model) (`null` clears it). |
| `setTheme(partial)` | Merge a partial theme and repaint. |
| `defineCellRenderer(name, r)` | Register a custom renderer after construction. |
| `aggregate(col, op)` | Column aggregate; see [Data operations](https://sheetwrite.vercel.app/docs/guides/data-operations/#aggregate). |
| `sortBy` / `sortByMulti` | Non-mutating display sorts; see [Data operations](https://sheetwrite.vercel.app/docs/guides/data-operations/#display-views). |
| `filterBy` / `setColumnFilter` / `getColumnFilters` | Column filters that compose with sort, hidden rows, and row groups. |
| `distinctValues(col, limit?)` | First-seen distinct values for building filter menus. |
| `hideRows` / `showRows` / `hiddenRows` | Explicit row visibility separate from sort/filter state. |
| `hideColumns` / `showColumns` / `hiddenColumns` | Bulk-safe persisted column visibility; omitted arguments target the focused column for hide and every column for show. |
| `groupRows` / `ungroupRows` / `setGroupCollapsed` / `rowGroups` | Inclusive data-row groups with collapse state. |
| `clearView()` | Clears sort/filter state; hidden rows and row groups remain. |
| `setFrozen(rows, cols?)` | Pin leading view rows/columns while the body scrolls. |
| `setZoom(z)` / `getZoom()` | Scale grid content between `0.5` and `2` without mutating workbook base sizes. |
| `undo()` / `redo()` | Undo or redo the last recorded cell edit (also bound to Ctrl+Z / Ctrl+Shift+Z). |
| `exportCsv` / `exportXlsx` | Download the active data; see [Data operations](https://sheetwrite.vercel.app/docs/guides/data-operations/#export). |
| `search(query, opts?)` | Find matching cells; highlights them, emits `search`, returns a [`SearchResult`](#search). |
| `findNext()` / `findPrev()` | Step the active match forward / backward and scroll it into view. |
| `clearSearch()` | Drop the current search and clear its highlights. |
| `replaceCurrent()` / `replaceAll()` | Replace literal text/number matches through undoable transactions. |
| `insertRows` / `removeRows` / `insertColumns` / `removeColumns` | Structural edits through undoable patches. |
| `highlightCells(ranges, color?)` | Highlight arbitrary ranges (`null` clears); `color` overrides the theme highlight. |
| `styleRange(range, style)` | Merge or clear store-backed cell styles across a range. |
| `setValidationRule` / `removeValidationRule` | Add, replace, or remove a serializable range validation rule. List and checkbox rules get accessible editors. |
| `setProtectedRange` / `removeProtectedRange` / `setProtectionResolver` | Define protected-range metadata and host-owned local permission policy. This is not server authorization. |
| `setNote` / `getNote` | Set, clear, or read a serializable plain-text cell note. |
| `beginEdit(row, col, initial?, selectAll?)` | Open the inline editor at a view cell. |
| `dataEdge(row, col, dRow, dCol)` | Ctrl+Arrow-style data-run jump target; vertical movement is view-aware under sort/filter. |
| `setRowHeight(row, h)` / `setColumnWidth(col, w)` | Geometry APIs; row height is view-indexed and persists against the underlying data row. |
| `autoFitRows(range?)` / `autoFitColumns(cols?)` | Explicit, undoable geometry fitting from bulk reads; auto-fit never runs during paint. |
| `on(evt, fn)` | Subscribe to an event; returns an unsubscribe function. |
| `refresh()` | Force a re-render (e.g. after mutating the workbook directly). |
| `destroy()` | Tear down listeners, DOM, and ARIA attributes. |

## Search

`grid.search(query, opts?)` scans cells, highlights every match, scrolls the first
match into view, and emits a [`search`](#events) event. `findNext()` / `findPrev()`
move the active match; `clearSearch()` clears the highlights. The built-in **Ctrl+F**
find widget (gated by `config.find`, on by default) drives this same API.

```ts
interface SearchOptions {
  matchCase?: boolean; // case-sensitive match (default false)
  wholeCell?: boolean; // match the whole cell, not a substring (default false)
  sheet?: SheetId;     // restrict to one sheet (default: the active sheet)
  columns?: number[];  // restrict to these column indices (default: all)
}

interface SearchResult {
  query: string;
  matches: CellAddress[]; // matching cells, in row-major order
  active: number;         // index of the active match, or -1 when there are none
}
```

```ts
const result = grid.search("error");
console.log(`${result.matches.length} match(es)`);
grid.findNext();    // advance the active match and scroll to it
grid.clearSearch(); // remove the highlights when done
```

`highlightCells(ranges, color?)` highlights arbitrary ranges independently of
search (pass `null` to clear); `color` overrides the theme highlight color.

## Events

`grid.on(evt, fn)` returns an `off()` you should call to unsubscribe.

| Event | Payload |
| --- | --- |
| `change` | `{ transaction; changes; dirty; commitReason; source: "local" \| "remote"; epoch? }` |
| `selection` | `{ selection: Selection \| null }` |
| `scroll` | `{ scrollTop: number; firstRow: number; lastRow: number }` |
| `edit-begin` | `{ addr: CellAddress }` |
| `edit-commit` | `{ addr: CellAddress; value: CellValue }` |
| `search` | `SearchResult` — `{ query: string; matches: CellAddress[]; active: number }` |

```ts
const sync = new SyncCoordinator(grid, adapter, {
  documentId: "products",
  serverVersion: loadedSnapshot.version ?? 0,
});
const off = sync.on((event) => {
  if (event.type === "conflict") showConflict(event.response);
  if (event.type === "reload-required") requestFreshSnapshot();
});

saveButton.onclick = () => void sync.sendNext();
// later
off();
sync.destroy();
```

### Data operations and export

Source: https://sheetwrite.vercel.app/docs/guides/data-operations/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

Sheetwrite can sort, filter, hide, group, aggregate, import, and export the active
sheet without rewriting the stored row data. Sorts and filters are display views:
the store keeps a row-order permutation/subset and the renderer reads through it.

## Display views

The simple shorthands are still available:

```ts
grid.sortBy(4);            // sort by column 4, ascending
grid.sortBy(4, false);     // descending
grid.filterBy(3, "Tokyo"); // keep rows whose column-3 text contains "Tokyo"
grid.clearView();          // clear sort/filter state only
```

For custom UI, use the composable primitives. All active column filters are ANDed
together, hidden rows and collapsed groups are subtracted, and the remaining rows
are sorted by the active multi-key sort.

```ts
grid.sortByMulti([
  { col: 4, ascending: false }, // primary key
  { col: 0, ascending: true },  // tie-breaker
]);

grid.setColumnFilter(3, { kind: "contains", text: "Tokyo" });
grid.setColumnFilter(2, { kind: "values", values: ["Retail", "Partner"] });
grid.setColumnFilter(5, { kind: "compare", op: "gte", value: 1000 });

const cities = grid.distinctValues(3, 100); // data source for a filter menu

grid.hideRows([1, 7, 9]);
grid.groupRows(10, 25);
grid.setGroupCollapsed(10, true);
```

| Method | Signature | Effect |
| --- | --- | --- |
| `sortBy` | `sortBy(col: number, ascending = true): void` | Reorder displayed rows by one column. |
| `sortByMulti` | `sortByMulti(keys: readonly SortKey[]): void` | Stable multi-key sort; first key is primary. |
| `filterBy` | `filterBy(col: number, needle: string): void` | Shorthand for a case-insensitive `contains` column filter. |
| `setColumnFilter` | `setColumnFilter(col: number, filter: ColumnFilter \| null): void` | Set or clear one column filter. |
| `getColumnFilters` | `getColumnFilters(): ReadonlyMap<number, ColumnFilter>` | Current active column filters. |
| `distinctValues` | `distinctValues(col: number, limit = 1000): CellScalar[]` | First-seen distinct resolved values for a column. |
| `hideRows` / `showRows` | `hideRows(rows)` / `showRows(rows?)` | Hide/show data rows independent of sort/filter state. |
| `hiddenRows` | `hiddenRows(): readonly number[]` | Currently hidden data rows. |
| `groupRows` / `ungroupRows` | `groupRows(start, end)` / `ungroupRows(start, end)` | Create/remove an inclusive data-row group. |
| `setGroupCollapsed` | `setGroupCollapsed(start, collapsed): void` | Collapse or expand the group starting at `start`. |
| `rowGroups` | `rowGroups(): readonly RowGroup[]` | Current row-group definitions. |
| `clearView` | `clearView(): void` | Clears sort/filter state. Hidden rows and row groups are preserved. |

`clearView()` deliberately does **not** unhide rows or expand row groups. This
matches spreadsheet behavior: clearing a filter removes the query, but explicit
hidden rows and collapsed groups remain a separate visibility state. Use
`showRows()` and `setGroupCollapsed(start, false)` to reverse those states.

Because a view reorders or hides rows, two features that depend on a stable
row-to-cell mapping are disabled while a view is active:

- **Merged cells** are not drawn (the layout reports no merges under a view).
- **Drag-to-fill** is unavailable (the fill handle is hidden).

Call `clearView()` to remove sort/filter state; also show hidden rows / expand
row groups if you need the full natural data order.

## Aggregate

`aggregate` computes a column reduction over the active sheet's data and returns a
number:

```ts
type Aggregate = Grid["aggregate"];
```

```ts
const total = grid.aggregate(4, "sum");
const rows = grid.aggregate(0, "count");
```

## Frozen panes and zoom

Frozen panes and zoom are view geometry, not data mutations:

```ts
grid.setFrozen(1, 1); // pin first view row and first column
grid.setFrozen(0, 0); // unfreeze

grid.setZoom(1.25);
console.log(grid.getZoom());
```

`setFrozen(rows, cols?)` pins leading view rows and columns while the body
scrolls. `setZoom(z)` clamps to `0.5`-`2` and scales painted row/column geometry
and fonts; workbook widths/heights remain in base units.

## Export

The grid can download the active sheet directly. CSV is synchronous; XLSX is
async because the optional backend produces bytes asynchronously. Install and
register `@sheetwrite/xlsx` before enabling a framework toolbar export action
or calling `grid.exportXlsx`:

```sh
npm install @sheetwrite/xlsx
```

```ts
import "@sheetwrite/xlsx/register";

grid.exportCsv("sales.csv");
await grid.exportXlsx("sales.xlsx");
```

`grid.exportXlsx(...)` rejects when registration or encoding fails, preserving
the backend error. Built-in toolbar and context-menu actions cannot return that
promise, so the grid emits one `export-error` event with
`{ format: "xlsx", error }` instead:

```ts
grid.on("export-error", ({ format, error }) => {
  console.error(`${format} export failed`, error);
});
```

CSV is written UTF-8 with a BOM and CRLF line endings, and string values are
**injection-hardened** — a value starting with `=`, `+`, `-`, `@`, tab, or CR is
prefixed with a single quote so it cannot become an executable formula when
reopened in a spreadsheet app.

Clipboard formulas and references retain their rich behavior only for a
copy/cut pasted back through the same live Sheetwrite grid controller. Rich
payloads from another controller or application, including spreadsheet HTML,
paste as injection-neutralized text; `pasteValues` uses resolved literals.

### Standalone import/export functions

Sheetwrite exposes two intentionally different XLSX contracts:

- **Table interchange**: `toXlsxTable` / `fromXlsxTable`. This is the active-sheet,
first-row-header API used by `grid.exportXlsx`.
- **Workbook round-trip**: `toXlsxWorkbook` / `fromXlsxWorkbook`. This consumes
and produces the same `WorkbookSnapshot` used by persistence, without adding
a header row.

Register the optional XLSX package once before using either contract:
```ts
import {
  downloadBytes,
  fromCsv,
  fromXlsxTable,
  fromXlsxWorkbook,
  SheetwriteStore,
  toCsv,
  toTsv,
  toXlsxTable,
  toXlsxWorkbook,
} from "@sheetwrite/core";
import "@sheetwrite/xlsx/register";

const dataFromCsv = fromCsv(csvText, columns);
const tableBytes = await toXlsxTable(workbook, store);
const dataFromTable = await fromXlsxTable(tableBytes);

const workbookBytes = await toXlsxWorkbook(store.exportSnapshot(), {
  maxCells: 250_000,
  signal: abortController.signal,
  onWarning: (warning) => console.warn(warning.code, warning.message),
});
const importedSnapshot = await fromXlsxWorkbook(workbookBytes);
const importedStore = SheetwriteStore.fromSnapshot(importedSnapshot);

const csv = toCsv(sheet, store); // string (BOM + CRLF, injection-hardened)
const tsv = toTsv(range, store); // string (Excel/Sheets clipboard TSV)

downloadBytes(csv, "sales.csv", "text/csv");
downloadBytes(
  workbookBytes,
  "workbook.xlsx",
  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
);
```

| Function | Signature |
| --- | --- |
| `fromCsv` | `fromCsv(text: string, columns: readonly Column[]): ColumnarData` |
| `fromXlsxTable` | `(data: ArrayBuffer \| Uint8Array, options?: XlsxWorkbookOptions) => Promise<ColumnarData>` |
| `fromXlsxWorkbook` | `(data: ArrayBuffer \| Uint8Array, options?: XlsxWorkbookOptions) => Promise<WorkbookSnapshot>` |
| `toCsv` | `toCsv(sheet: Sheet, store: Store): string` |
| `toTsv` | `toTsv(range: Range, store: Store): string` |
| `toXlsxTable` | `(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions) => Promise<Uint8Array>` |
| `toXlsxWorkbook` | `(snapshot: WorkbookSnapshot, options?: XlsxWorkbookOptions) => Promise<Uint8Array>` |
| `downloadBytes` | `downloadBytes(bytes: Uint8Array \| string, filename: string, mime: string): void` |

`XlsxWorkbookOptions` is the shared resource contract for every table and
workbook path. `maxCells` bounds logical accepted cells and defaults to
`1_000_000`; `resourceLimits` overrides the remaining input, archive, XML,
dimension, and output budgets, which are checked before decompression and
allocation and reject with a typed `XlsxResourceError`. `signal` is checked
between bounded codec stages, and structured warnings surface through
`onWarning`. Both directions materialize the complete file representation in
memory; there is no streaming mode.

### XLSX compatibility

| Feature | Table API | Workbook API |
| --- | --- | --- |
| Multiple worksheets and order | Active sheet only | Preserved |
| First row | Synthesized column headers | Ordinary row; no header synthesis |
| Formula source, including cross-sheet formulas | Exports resolved scalars | Preserved; workbook requests full recalculation on open |
| Cell styles, borders, number/date formats | Preserved on active-sheet export | Preserved |
| Merges, column widths, row heights | Preserved on active-sheet export | Preserved |
| Frozen panes and active worksheet | Not round-tripped | Preserved |
| Named ranges | Not represented | Preserved |
| Sheetwrite conditional formats and row groups | Not represented | Preserved in Sheetwrite metadata; warning reports that no Excel rule/outline is emitted |
| Boolean literals | Imported by the table reader | Preserved as native booleans |
| Rich text and hyperlinks | Reader-dependent flattening | Display text preserved with a structured warning |
| Sheetwrite validation rules | Not represented | Preserved in Sheetwrite metadata; supported list/numeric/date/text-length rules also emit native Excel validation |
| Protected ranges | Not represented | Preserved in Sheetwrite metadata; no Excel sheet-protection claim is made |
| Cell notes | Not represented | Preserved in Sheetwrite metadata and emitted as native Excel notes |
| External Excel validation, protection, notes, images, tables, auto-filters, conditional formatting, and VBA | Not represented | Features without Sheetwrite metadata are dropped with a structured `unsupported-feature` warning when detected |

Workbook formulas are imported as formula source, not as cached results.
Hydrating the returned snapshot with `SheetwriteStore.fromSnapshot` recompiles
them into the WASM formula engine. No raw formula handles enter the serialized
snapshot.

### XLSX backends

XLSX uses pluggable backends. Calling a table or workbook API without its
backend throws a configuration error that names both remedies: install
`@sheetwrite/xlsx`, then import `@sheetwrite/xlsx/register` before calling the
function. The ordinary core entry never resolves the optional codec, so normal
grid bundles carry no spreadsheet-file code.

`@sheetwrite/xlsx` is the only concrete implementation package. Its root entry
is side-effect free and exports `registerXlsxBackends()` plus the three named
backend instances for explicit registration or wrapping. The `./register`
entry performs idempotent registration:

```ts
import {
  registerXlsxBackends,
  sheetwriteTableExportBackend,
  sheetwriteTableImportBackend,
  sheetwriteWorkbookBackend,
} from "@sheetwrite/xlsx";
import {
  setXlsxTableExportBackend,
  setXlsxTableImportBackend,
  setXlsxWorkbookBackend,
  type XlsxTableExportBackend,
  type XlsxTableImportBackend,
  type XlsxWorkbookBackend,
} from "@sheetwrite/core";

registerXlsxBackends();

// Or compose individual backends explicitly.
setXlsxTableExportBackend(sheetwriteTableExportBackend);
setXlsxTableImportBackend(sheetwriteTableImportBackend);
setXlsxWorkbookBackend(sheetwriteWorkbookBackend);
```

The backends share Sheetwrite's internal bounded OOXML codec, which owns OPC
part resolution, XML tokenization, styles, and worksheet mapping over one
audited compression primitive (`fflate`). It preserves formula source,
worksheets, styles, merges, dimensions, frozen views, and named ranges, and it
enforces the shared resource limits before decompression. The host can replace
any role by implementing `XlsxWorkbookBackend` or the table backend contracts.

## See also

- [Interaction](https://sheetwrite.vercel.app/docs/guides/interaction/) for clipboard TSV and the toolbar sort control.
- [Concepts](https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/#document-protocol-and-storage-transactions) for row/column `DocumentOp` transactions.

### Formulas

Source: https://sheetwrite.vercel.app/docs/guides/formulas/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

Sheetwrite evaluates formulas in the Rust/WASM calculation engine. Formula sources are persisted exactly as document values; evaluated results are cached for rendering, queries, export, and dependent formulas.

Sheetwrite intentionally implements a coherent spreadsheet subset. It does **not** claim full Google Sheets or Excel formula parity.

See the generated [formula function contract](https://sheetwrite.vercel.app/docs/reference/formula-functions/) for the complete inventory-derived function table and the [detailed compatibility results](https://sheetwrite.vercel.app/docs/reference/compatibility-results/) for checked operator, spill, preservation, and unsupported boundaries.

## Authoring formulas

A formula is a `CellValue` with `kind: "formula"`. The leading `=` is optional at the storage API, although UI input conventionally includes it.

```ts
grid.store.applyTransaction({
  patches: [
    {
      op: "set",
      addr: { sheet: "sheet1", row: 5, col: 4 },
      value: { kind: "formula", src: "=SUM(E1:E5)" },
    },
  ],
});
```

`store.getFormula(address)` returns the source. `store.getCell(address).resolved` returns the evaluated scalar or error sentinel. An unsupported function evaluates to `#NAME?`, but its source remains retrievable and persists through snapshots/XLSX round-trips so a later engine can evaluate it.

## Supported formulas

The checked, versioned `sheetwrite.formula-capabilities` contract is the source of truth for function registration. Its generated reference publishes all **100 required-supported target functions plus every incumbent function**, grouped by family, with aliases, exact signature and semantic profiles, implementation/evidence paths, source links, and behavior status. Do not infer support from an Excel, Google Sheets, or OpenFormula function with a similar name.

[Browse the generated formula function contract →](https://sheetwrite.vercel.app/docs/reference/formula-functions/)

Function names are case-insensitive. Commas are the only documented argument separator. Interior omitted optional arguments are preserved (`XLOOKUP(key, keys, results,, 0)`). Locale-specific separators are not accepted.

## Scalars, coercion, and errors

Persisted literals and evaluated formula results use `string | number | boolean | null`. Boolean literals entered as `TRUE`/`FALSE`, formula comparisons, XLSX boolean cells, snapshots, visible windows, clipboard output, and CSV/TSV output remain booleans end to end. Display and text export use uppercase `TRUE` and `FALSE`.

| Sentinel | Meaning |
| --- | --- |
| `#REF!` | Missing sheet/cell reference or invalid reference structure. |
| `#VALUE!` | Wrong value type, malformed formula, invalid arity, or range-shape mismatch. |
| `#DIV/0!` | Division/modulo by zero or an empty criteria average. |
| `#NAME?` | Unknown function or unresolved named range. |
| `#N/A` | Lookup did not find a compatible value. |
| `#NUM!` | Non-finite numeric result, excessive recursion, or an oversized range. |
| `#SPILL!` | A dynamic result intersects content, another spill, a merge, validation/protection metadata, or a sheet boundary. |
| `#CALC!` | A supported array calculation has no result, such as `FILTER` without matches or an empty fallback. |
| `#CYCLE!` | Direct or transitive formula/reference cycle. |
| `#LOADING!` | A formula depends on datasource cells that have not loaded yet. |

Errors are values for display and dependency propagation, not `NaN` or blank rendering. `IFERROR` can replace them. Unsupported or malformed source remains stored even when the result is an error.

Coercion follows these documented rules:

- Arithmetic converts numeric text and booleans (`TRUE = 1`, `FALSE = 0`); nonnumeric text returns `#VALUE!`.
- Direct scalar boolean/text arguments may be coerced by numeric functions. Text/booleans reached through a range are ignored by numeric aggregates, matching common spreadsheet behavior.
- Empty scalar arithmetic behaves as zero. Empty range cells are skipped.
- Comparisons are case-insensitive for text and use spreadsheet type ordering.
- `AND`, `OR`, `NOT`, and `IF` accept booleans, numbers, and the text `TRUE`/`FALSE`.

## LET bindings

`LET(name1, value1, [name2, value2, …], calculation)` supports lexical, case-insensitive local names. A name starts with an ASCII letter or `_`; subsequent characters may also contain ASCII digits or `.`. Inner `LET` bindings shadow outer bindings, and each value expression can see only earlier bindings.

Bindings are lazy. Only names reachable from `calculation` are expanded and evaluated, so an unused cell read, error, or `NOW()` does not become a dependency, error, or volatile marker. A used binding preserves ordinary formula dependency, spill, copy/fill, and structural-reference behavior. `LET(x,1/0,7)` therefore returns `7`, while `LET(x,A1,x+1)` tracks `A1`.

One `LET` admits at most 126 bindings. Expansion admits at most 16,384 AST nodes across reachable bindings. Invalid name/arity/binding structure returns `#VALUE!`; expansion beyond the node ceiling returns `#NUM!`. `LET` does not create callable functions: `LAMBDA` and higher-order execution remain unsupported.

## References, ranges, and named ranges

A1 cells (`A1`, `$B12`, `AA$3`), rectangular ranges (`A1:B3`), and cross-sheet references (`Sales!E2`, `'Sales 2026'!E2:E10`) are supported. Absolute markers affect fill/structural rewriting; they do not change evaluation.

Named ranges are document operations and snapshot metadata:

```ts
store.applyTransaction({
  patches: [
    {
      op: "setNamedRange",
      namedRange: {
        name: "Revenue",
        range: {
          sheet: "data",
          start: { row: 1, col: 4 },
          end: { row: 100, col: 4 },
        },
      },
    },
    {
      op: "setNamedRange",
      namedRange: {
        name: "Revenue",
        scope: "summary",
        range: {
          sheet: "data",
          start: { row: 1, col: 5 },
          end: { row: 100, col: 5 },
        },
      },
    },
  ],
});
```

A formula on `summary` resolves the sheet-scoped `Revenue`; formulas on other sheets resolve the workbook definition. Names are case-insensitive, must be formula-safe identifiers, and cannot look like A1 cells or boolean literals. Row/column insertions, removals, and moves rebase their rectangles. Deleting the complete target or its scope removes the definition; formulas then fall back to a workbook definition or evaluate to `#NAME?`.

## Operators

| Precedence, high to low | Operators | Associativity |
| --- | --- | --- |
| Reference | `:` | — |
| Unary sign | unary `+`, unary `-` | right |
| Percentage | postfix `%` | left |
| Exponentiation | `^` | left |
| Multiplication | `*`, `/` | left |
| Addition | `+`, `-` | left |
| Concatenation | `&` | left |
| Comparison | `=`, `<>`, `<`, `>`, `<=`, `>=` | one comparison |

This deliberately follows Excel's spreadsheet precedence rather than programming-language
conventions: `=-2^2` is `4`, `=2^3^2` is `64`, and `=2^-2` is `0.25`. Parenthesize formulas
when portability to a non-spreadsheet evaluator matters. Percentage divides its operand by
100 and may repeat (`=50%%` is `0.005`). Concatenation formats numbers, booleans, and blanks
as spreadsheet text; arithmetic and comparison bind before `&`.

Comparisons return native booleans. For example, `=IF(A1 >= 100, A1 * 0.9, A1)`.

## Date/time semantics

Dates are numbers: whole days since the spreadsheet epoch, with a fractional day for time. Sheetwrite uses only the Excel 1900 date system on this path:

- serial `0` maps to `1899-12-31`
- `DATE(1900,1,1) = 1`
- serial `60` is retained as the compatibility-only, non-Gregorian date `1900-02-29`
- `DATE(1900,3,1) = 61`
- `DATE` treats 1900 as a leap year for this serial boundary and normalizes month/day overflow; `DATE(2024,13,1)` is 2025-01-01
- `DATEVALUE` is locale-neutral: it accepts the documented ISO `yyyy-mm-dd` form and fixed slash-delimited numeric forms; it never consults the host locale

`TODAY` and `NOW` are volatile, but never consult the clock during paint or ordinary dependency reads. The host captures one absolute instant and triggers a barrier:

```ts
store.recalculateVolatile(new Date("2026-07-13T18:00:00.000Z"));
```

The default captures `new Date()` once. The instant is converted to a UTC serial, so a fixed `Date` produces identical results in every host timezone. `TODAY` returns its whole-day component; `NOW` retains the fraction.

Basic `TEXT` date patterns are `yyyy-mm-dd`, `yyyy/mm/dd`, `mm/dd/yyyy`, `dd/mm/yyyy`, `m/d/yyyy`, `yyyy-mm-dd hh:mm`, `yyyy-mm-dd hh:mm:ss`, `hh:mm`, and `hh:mm:ss`.

Text evaluation is host-locale neutral. Function argument separators stay commas; `VALUE` uses `.` decimal and `,` grouping, and `NUMBERVALUE(text, [decimal_separator], [group_separator])` uses those same defaults unless the separators are supplied explicitly. Case conversion uses Unicode mappings, not browser locale. `LEN`, `LEFT`, `RIGHT`, and `MID` count Unicode scalar values rather than UTF-16 code units. Generated text is capped at 16 MiB and bounded searches at 4,000,000 steps; excess work returns `#NUM!`.

## Criteria semantics and shapes

Criteria strings may begin with `=`, `<>`, `<`, `<=`, `>`, or `>=`. Numeric and boolean operands are parsed before text comparison. Plain text comparisons are case-insensitive. `*` matches zero or more characters, `?` matches one character, and `~` escapes the next wildcard. Wildcards apply to equality/inequality text criteria. Criteria are parsed once per formula evaluation, not once per cell.

Shapes are exact row-by-column dimensions; equal cell counts with different dimensions do not match:

- `COUNTIF(criteria_range, criterion)` accepts one matrix and one scalar criterion.
- `COUNTIFS(criteria_range1, criterion1, …)` requires one or more range/criterion pairs. Every criteria range must have exactly the shape of the first.
- `SUMIF(criteria_range, criterion, [value_range])` and `AVERAGEIF(...)` use `criteria_range` as the value range when the third argument is omitted. When supplied, `value_range` must have exactly the same shape; Sheetwrite does not implement Excel's top-left range extension.
- `SUMIFS(value_range, criteria_range1, criterion1, …)`, `AVERAGEIFS`, `MAXIFS`, and `MINIFS` require one or more pairs after the value range. Every criteria range must exactly match the value range.

A mismatch or malformed pair list returns `#VALUE!`. Matching result-range errors propagate. Text, booleans, and blanks in a numeric result range are ignored. A criteria sum with no numeric matches is `0`; an average is `#DIV/0!`; `MAXIFS`/`MINIFS` return `0`.

## SUMPRODUCT and SUBTOTAL

`SUMPRODUCT(array1, [array2, …])` requires at least one argument. Every argument must have the same exact row-by-column shape; a scalar is a 1×1 shape, and a dimensional mismatch returns `#VALUE!`. It multiplies corresponding cells and sums the products. Text, booleans, and blanks reached through ranges contribute zero; directly supplied numeric text and booleans use ordinary scalar numeric coercion. Errors propagate, and a non-finite product or total returns `#NUM!`.

`SUBTOTAL(function_number, reference1, [reference2, …])` accepts codes `1`–`11`: `AVERAGE`, `COUNT`, `COUNTA`, `MAX`, `MIN`, `PRODUCT`, `STDEV.S`, `STDEV.P`, `SUM`, `VAR.S`, and `VAR.P`. It accepts up to 253 reference arguments and uses the corresponding aggregate's range coercion/error rules. Codes `101`–`111` are deliberately unsupported and return `#VALUE!` pending hidden-row provenance in formula range values. Nested-subtotal and filtered/hidden-row exclusion must not be inferred.

## Financial functions

`PV`, `FV`, `PMT`, `NPV`, `IRR`, `RATE`, `IPMT`, and `PPMT` use binary64 arithmetic, fixed defaults from the generated signatures, and explicit domain errors. `NPV` discounts its first cash flow at period 1 and uses compensated summation. Range cash flows ignore text and blanks; errors propagate.

`IRR` requires at least one positive and one negative cash flow. `IRR` and `RATE` use the caller's guess (default `0.1`), 14 deterministic bracket steps, at most 100 deterministic solve steps, fixed absolute/relative tolerances of `1e-12`, and a finite transformed search domain. Invalid domains or failure to converge return `#NUM!`; no random seed, host locale, wall clock, or platform-specific iteration budget is used.

## Lookup semantics

- `INDEX(range, row, [column])` uses 1-based indices and returns one scalar. Zero/negative indices return `#VALUE!`; array-return row/column projections are not implemented.
- `MATCH(key, range, 0)` is exact. Match type `1` returns the largest value less than or equal to the key from ascending data. `-1` returns the smallest value greater than or equal to the key from descending data. Invalid ordering returns `#N/A` rather than a plausible wrong row.
- `VLOOKUP`/`HLOOKUP` use exact matching when the final argument is false. The omitted/true mode uses correctly ordered approximate data and returns the largest value less than or equal to the key.
- `XLOOKUP` supports exact, next-smaller (`-1`), next-larger (`1`), and wildcard (`2`) match modes; forward/reverse and ordered binary-search modes are accepted. `if_not_found` is optional. If it is omitted—including via an interior empty argument—the result is `#N/A`.

Lookup errors in the scanned range propagate. Approximate modes validate ordering and do not silently return a result from unsorted input.

## Dynamic arrays and spills

`FILTER`, `SORT`, `UNIQUE`, `TRANSPOSE`, `SEQUENCE`, `TAKE`, `DROP`, `CHOOSECOLS`, and `CHOOSEROWS` return rectangular values. A direct range formula such as `=A1:B4` also spills:

- `FILTER(array, include, [if_empty])` accepts a one-column include range matching the array's rows or a one-row include range matching its columns. Shape mismatches are `#VALUE!`. No selected values returns `if_empty`, or `#CALC!` when omitted.
- `SORT(array, [sort_index], [sort_order], [by_col])` defaults to the first column, ascending. `sort_index` selects the row/column key; `sort_order` is `1` or `-1`; `by_col=TRUE` sorts columns instead of rows. Multi-key sorting is unsupported.
- `UNIQUE(array, [by_col], [exactly_once])` preserves first-seen order. `by_col=TRUE` compares columns; `exactly_once=TRUE` keeps only items occurring once. An empty result is `#CALC!`.
- `TRANSPOSE(array)` swaps rows and columns.
- `SEQUENCE(rows, [columns], [start], [step])` requires positive integer dimensions and defaults to one column, start `1`, step `1`; values fill row-major.
- `TAKE`/`DROP(array, rows, [columns])` use positive counts from the start and negative counts from the end. A zero or empty result is `#CALC!`; counts beyond an axis clamp to that axis.
- `CHOOSECOLS`/`CHOOSEROWS(array, index1, …)` use 1-based positive indices and end-relative negative indices. Repeated indices repeat output axes; zero/out-of-range indices return `#VALUE!`.

Errors inside a returned array stay at their corresponding spill children; a mixed result such
as `{1;#N/A;2}` does not collapse to an anchor-only error.

The formula cell is the **anchor** and owns the complete runtime rectangle. Spill children
have no formula source or persisted document identity. `store.getSpillAnchor(address)` returns
the anchor for either the anchor or a child, and returns `null` for an ordinary cell.

Spills publish atomically. Any nonempty destination, another spill, merge, validation or
protected range, unloaded paged cell, or sheet boundary makes the anchor `#SPILL!`; no partial
children remain. Styles, conditional formatting, and hidden rows/columns do not obstruct.
Editing a projected child through canonical core mutations is rejected. Edit or clear the
anchor instead. Structural and metadata changes invalidate ownership and recompute it.

Snapshots and XLSX export serialize only the anchor formula. Children recompute after
hydration. Internal rich copy preserves the anchor formula while treating children as
derived blanks on paste; external TSV receives the displayed spill values. History snapshots
likewise restore the anchor and recompute children, so undo never persists stale projections.
Unsupported OOXML array/data-table formula records remain inert source text with an explicit
warning rather than being silently treated as Sheetwrite spills.

Each array dimension is capped at Excel's row/column limits, one spill is capped at 1,000,000
cells and 64 MiB of bounded value/intermediate storage, and one dynamic recompute pass is
capped at 2,000,000 cell operations. Materialized spill ownership across the complete store is
also capped at 1,000,000 cells and 64 MiB, including per-child error metadata. Installation
checks that cumulative budget atomically; clearing, shrinking, or removing a spill releases its
ownership. Oversized work returns stable `#NUM!` without partial children, while unstable or
colliding shapes return an explicit error rather than truncating.

The admission check happens before materialization when the shape is statically knowable and is repeated before spill ownership is installed. It accounts source/result copies and per-item auxiliary storage; a shape that could exceed a ceiling is rejected rather than optimistically allocated. A recompute either atomically replaces the complete previous spill or leaves no projected children.

## Unsupported categories

Formula evaluation performs no network request and runs no custom JavaScript. Automatic volatile functions beyond the explicit `TODAY`/`NOW` host-clock barrier, network functions, external/live-data providers, arbitrary external workbook references, database functions, cube/OLAP functions, and `LAMBDA` or higher-order array execution are unsupported. Examples include `RAND`, `RANDBETWEEN`, `INDIRECT`, `OFFSET`, `WEBSERVICE`, `GOOGLEFINANCE`, `IMPORT*`, `RTD`, `DSUM`, `CUBEVALUE`, `LAMBDA`, `MAP`, `REDUCE`, and `SCAN`.

Unsupported names evaluate to `#NAME?` while preserving source for snapshots and interchange. There is no compatibility shim or side-effecting fallback. The generated [unsupported-category ledger](https://sheetwrite.vercel.app/docs/reference/formula-functions/#unsupported-categories) is derived from the versioned inventory.

## Performance evidence

No formula throughput or latency number is published from this guide because no checked final formula-performance evidence file is present. Follow the [performance evidence guide](https://sheetwrite.vercel.app/docs/guides/performance-resources/) to capture and freshness-check measurements; do not treat resource ceilings as benchmark results.

## Point mode and reference rewriting

While editing a formula, clicking a cell inserts its A1 reference and dragging inserts a range. Relative references shift during fill; `$`-absolute axes remain fixed. Structural row/column edits rewrite direct and named references while preserving stable sheet identity.

The same `$`-aware utility is public:

```ts
import { shiftA1Refs } from "@sheetwrite/core";

shiftA1Refs("A1 + $B$1", 0, 1); // "B1 + $B$1"
```

A1 address helpers are exported as `cellA1`, `colToA1`, `labelToCol`, and `rangeA1`.

### Keep app rows in your store

Source: https://sheetwrite.vercel.app/docs/guides/host-owned-rows/

Use the row bridge when your app owns the row objects and Sheetwrite owns editing, history, sorting, and filtering. The bridge is optional. Without `getRowId`, `defaultRows` keeps its existing one-time, uncontrolled behavior.

```ts
import { createRowBridge, type RowBridgeProjection } from "@sheetwrite/core";

interface InvoiceRow {
  id: string;
  customer: string;
  total: number;
}

const entities = new Map<string, InvoiceRow>([
  ["invoice-1", { id: "invoice-1", customer: "Ada", total: 120 }],
  ["invoice-2", { id: "invoice-2", customer: "Lin", total: 75 }],
]);
const rows = [...entities.values()];
let nextId = 3;

const bridge = createRowBridge({
  columns: [{ key: "customer" }, { key: "total" }],
  defaultRows: rows,
  getRowId: (row) => row.id,
  createRowId: () => `invoice-${nextId++}`,
});

function applyProjection(projection: RowBridgeProjection<string>) {
  if (projection.status === "rejected" || projection.status === "duplicate") return;
  for (const delta of projection.deltas) {
    if (delta.kind === "cell") {
      const { rowId, columnKey, next } = delta.cell;
      if (rowId === null || columnKey === null || next?.kind !== "literal") continue;
      const row = entities.get(rowId);
      if (row) entities.set(rowId, { ...row, [columnKey]: next.value });
    }
    if (delta.kind === "row-structure" && delta.action === "delete") {
      for (const rowId of delta.removed) if (rowId !== null) entities.delete(rowId);
    }
    if (delta.kind === "row-structure" && delta.action === "insert") {
      for (const rowId of delta.inserted) {
        if (rowId !== null) entities.set(rowId, { id: rowId, customer: "", total: 0 });
      }
    }
  }
}
```

Attach the same bridge and callback in any adapter:

```tsx
import {
  SheetwriteGrid,
  type RowBridge,
  type RowBridgeProjection,
  type SimpleColumn,
} from "@sheetwrite/react";

interface InvoiceRow {
  id: string;
  customer: string;
  total: number;
}

declare const columns: readonly SimpleColumn<InvoiceRow>[];
declare const rows: readonly InvoiceRow[];
declare const bridge: RowBridge<string>;
declare const applyProjection: (projection: RowBridgeProjection<string>) => void;
<SheetwriteGrid
  columns={columns}
  defaultRows={rows}
  rowBridge={bridge}
  onRowDelta={applyProjection}
  height={420}
/>
```

Vue emits `row-delta`; Svelte and the imperative controller use `onRowDelta`. All adapters call the same core bridge. Sorts, filters, and hidden rows only change the visible order, so emitted row IDs still refer to data-space rows.

Remote changes should enter through `grid.applyRemoteOperations(...)`. Their projections have `status: "remote"` and `source: "remote"`. An echoed local transaction is returned as `duplicate` with no deltas. For a server rejection or transformed acceptance, call `bridge.reconcile(...)` with the server result and the canonical applied operations. The bridge does not update your store automatically; your callback remains the only place that changes host rows.

### Interaction and editing

Source: https://sheetwrite.vercel.app/docs/guides/interaction/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

Sheetwrite handles selection, keyboard navigation, inline editing, the clipboard,
the toolbar, merges, and drag-to-fill out of the box. The host element is made
focusable (`tabindex="0"`) so it receives keyboard events. Setting
`readOnly: true` disables every mutating interaction below (editing, clearing,
fill, paste, and restyling) while leaving navigation and selection intact.

## Selection model

A `Selection` is one of five shapes:

```ts
type Selection =
  | { kind: "cell"; addr: CellAddress }
  | { kind: "range"; range: Range }
  | { kind: "row"; sheet: SheetId; row: number }
  | { kind: "column"; sheet: SheetId; col: number }
  | { kind: "multi"; ranges: Range[] };
```

Read or set it imperatively, and subscribe to changes:

```ts
const sel = grid.getSelection();
grid.setSelection({ kind: "cell", addr: { sheet: "sheet1", row: 0, col: 0 } });
grid.setSelection(null); // clear

grid.on("selection", (e) => console.log(e.selection));
```

How selections are made with the mouse (primary button):

| Gesture | Result |
| --- | --- |
| Click a cell | Select that cell. |
| Drag across cells | Extend to a **range**. |
| Shift-click | Extend the range from the current anchor. |
| Ctrl/Cmd-click | Add a region — produces a **multi** selection. |
| Click a column letter (top header) | Select that **column** (Shift extends; Ctrl/Cmd adds). |

Row and full-column selections are part of the model. Column selection is wired to
the top header; **row selection is programmatic only** — there is no row-header
click gesture, so set it via `setSelection({ kind: "row", sheet, row })`.

## Keyboard navigation

When the grid is focused and not editing:

| Key | Action |
| --- | --- |
| Arrow keys | Move the focus one cell. |
| Ctrl/Cmd + Arrow | Jump to the first/last row or column. |
| Page Up / Page Down | Move by a viewport of rows. |
| Home / End | Move to the first / last column of the row. |
| Ctrl/Cmd + Home / End | Move to the sheet's first / last cell. |
| Shift + any of the above | Extend the selection instead of moving. |
| Enter or F2 | Edit the focused cell (F2 selects the existing text). |
| Delete / Backspace | Clear the selected cells. |
| A printable character | Start editing, replacing the cell's content. |
| Ctrl/Cmd + C / X / V | Copy / cut / paste. |
| Ctrl/Cmd + Z | Undo the last edit. |
| Ctrl/Cmd + Shift + Z (or Ctrl/Cmd + Y) | Redo. |
| Ctrl/Cmd + F | Open the find bar (when `config.find` is not `false`). |

## Inline editing

Editing happens in a single real `<textarea>` overlaid on the active cell. It is
never recycled across cells, so **IME composition and focus survive scrolling** —
composing CJK or other input methods is safe. Begin editing by double-clicking,
pressing Enter or F2, or just typing.

Commit and navigation keys:

| Key | Result |
| --- | --- |
| Enter | Commit, move **down**. |
| Tab | Commit, move **right**. |
| Shift + Tab | Commit, move **left**. |
| Shift + Enter | Insert a newline (does not commit). |
| Escape | Cancel the edit. |
| Blur (click away) | Commit in place. |

While the IME is composing, keystrokes belong to the composition and are not
treated as navigation. Editing emits `edit-begin` and `edit-commit` events.

## Clipboard interoperability

Copy and cut always produce injection-hardened TSV and, where the browser exposes
`ClipboardItem`, also write sanitized `text/html` plus Sheetwrite's private
`application/x-sheetwrite+json` payload. The private payload preserves formula
source and cell styles for same-app round-trips. HTML contains only escaped table
markup, plain cell text, safe `data-sheetwrite-formula` attributes, and a bounded
style subset; no pasted HTML is inserted into the document.

Paste prefers the private Sheetwrite payload, then sanitized HTML tables, then
plain TSV. HTML parsing uses an inert `DOMParser` document and accepts only cell
text, safe formula attributes, and supported inline styles. External formulas
containing control characters are treated as text. TSV handles quoted,
multi-line fields, matching Excel and Google Sheets. External text beginning
with `=`, `+`, `-`, `@`, tab, or CR is prefixed with a single quote, so it cannot
become an executable formula.

`paste()` preserves supported formula/style data; `pasteValues()` intentionally
writes resolved literals and drops formulas/styles. Cut clears its source only
after the system clipboard accepts the payload. Paste is disabled when
`readOnly`.

`grid.actions.copy/cut/paste/pasteValues` return
`Promise<ClipboardOutcome>` — `"done" | "unsupported" | "blocked" | "empty"` —
and never reject. A missing API resolves `"unsupported"`; permission or
user-activation rejection resolves `"blocked"`, so custom UI can surface the
outcome without tripping global error monitoring.

## Validation, protection, and notes

`DataValidationRule` covers list, numeric range, date range, text-length, and
checkbox conditions. Rules carry a stable ID, range, `reject` / `warn` / `allow`
policy, optional blank handling, and help text. List rules open a keyboard-
operable `listbox`; checkbox rules open a real ARIA `checkbox`. Arrow keys and
typeahead change a list choice, Space toggles a checkbox, Enter commits, Tab
commits and moves, and Escape cancels. Every mutation ingress—including paste,
fill, clear, and host transactions—passes through the same validation boundary.

`ProtectedRange` is serializable client policy metadata. Local writes are denied
by default and can be allowed by a host `ProtectionResolver`; atomic mode rejects
the whole transaction, while partial mode applies allowed operations and reports
the rest. Remote operations bypass this UX policy. A server must enforce its own
authorization.

Plain-text notes use `setNote(addr, text)` / `getNote(addr)`. The focused cell's
note is exposed as the ARIA description. Notes serialize, rebase with structural
edits, participate in undo/redo, and round-trip through Sheetwrite XLSX metadata.

## Toolbar actions

When you opt into the toolbar via `config`, each control acts on the current
selection. The controls (and the `config` flag that gates each) are:

| Control | Flag |
| --- | --- |
| Bold | `bold` |
| Italic | `italic` |
| Align left / center / right | `align` |
| Text color | `textColor` |
| Fill color | `fillColor` |
| Border | `border` |
| Clear formatting | `clearFormat` |
| Merge / unmerge | `merge` |
| Sort ascending / descending | `sort` |

See [Configuration → GridConfig](https://sheetwrite.vercel.app/docs/guides/configuration/#gridconfig-toolbar).

## Context menu

`GridConfig.contextMenu` is `true` by default, `false` to disable, a static
readonly item list, or a factory evaluated for each right-click context.
Sheetwrite prevents the browser menu, hit-tests the pointer, and selects the
resolved cell before evaluating item visibility/disabled predicates.

Rows may provide `id`, `label`, and `shortcut`; bind a built-in `action` or use
`onClick(grid, cell)`. `visible` and `disabled` accept booleans or predicates
receiving the lean `{ cell, clientX, clientY }` `ContextMenuContext`. Hidden
separators are normalized and disabled rows cannot invoke actions.

The built-in action names are:

| Clipboard/content | Rows | Columns | View/export |
| --- | --- | --- | --- |
| `cut`, `copy`, `paste`, `clearContents` | `insertRowAbove`, `insertRowBelow`, `deleteRow`, `hideRow`, `showAllRows`, `autoFitRow` | `insertColumnLeft`, `insertColumnRight`, `deleteColumn`, `hideColumn`, `showAllColumns`, `autoFitColumn` | `clearFilter`, `merge`, `unmerge`, `exportCsv`, `exportXlsx` |

The default list uses the clipboard/content, row, column, filter, and
merge/unmerge actions; export actions are available for custom lists. XLSX
still requires `@sheetwrite/xlsx/register`.

For fully host-owned menu rendering, disable the bundled menu and bind the host
element's DOM `contextmenu` event. `grid.getCellAtPoint(clientX, clientY)`
resolves the pointer without exposing renderer internals; the host then owns
`preventDefault`, selection, positioning, dismissal, and invoking
`grid.actions`.

See [Configuration → Context-menu items](https://sheetwrite.vercel.app/docs/guides/configuration/#context-menu-items)
for both models and [Styling → Widget and context-menu styling](https://sheetwrite.vercel.app/docs/guides/styling/#widget-and-context-menu-styling)
for the bundled menu CSS hooks.

## Merged cells

Merging combines the selected range into one cell: the top-left value is shown and
the covered cells are hidden, tracked in a per-sheet merge registry. Unmerge
reverses it. Merges are **not drawn while a sort or filter view is active** (the
display order no longer maps cleanly to the merged region); clear the view to see
them again. See [Data operations](https://sheetwrite.vercel.app/docs/guides/data-operations/#display-views).

## Drag-to-fill

A small fill handle sits at the bottom-right corner of the selection. Drag it
**down, up, left, or right** — the dominant axis wins — to fill the source block
across the new region. The source is tiled (repeated) to cover the target.

When the filled cells contain formulas, references are rewritten as they are
copied: **relative** A1 parts shift by the fill offset and **absolute** parts
(prefixed with `$`) stay fixed. For example, filling `=A1 + $B$1` one column right
yields `=B1 + $B$1`. See [Formulas → Point mode and reference rewriting](https://sheetwrite.vercel.app/docs/guides/formulas/#point-mode-and-reference-rewriting).

Drag-to-fill is unavailable while a sort/filter view is active (the handle is
hidden) and when `readOnly`.

## Touch

Grid input runs on Pointer Events, so mouse, touch, and pen share one code
path. For `pointerType: "touch"` the policy is:

| Gesture | Behavior |
| --- | --- |
| Tap on a cell | select the cell (same as a click) |
| Tap on a column header | select the column |
| Drag starting on a plain cell | **native scroll** — the grid neither captures the pointer nor calls `preventDefault` |
| Drag starting on the fill handle | drag-to-fill (pointer captured) |
| Drag starting on a row/column resize boundary | resize (pointer captured) |
| Drag starting on the border of a multi-cell selection (±6px band) | extend the selection (pointer captured) |
| Double-tap on a cell | begin editing (the browser's synthesized `dblclick`) |

Mouse and pen behave classically: any drag from a cell extends the selection,
and hovering a resize boundary shows the resize cursor. A `pointercancel`
(e.g. the browser reclaims the gesture) abandons the drag without committing.
The scroller sets `touch-action: pan-x pan-y`, which keeps native panning but
disables double-tap zoom so captured drags keep receiving `pointermove`.
Long-press → context menu on touch is deferred; when added it must cancel on
move to respect the native-scroll rule.

### Persistence and recovery

Source: https://sheetwrite.vercel.app/docs/guides/persistence/

Sheetwrite supplies contracts, not a database or endpoint. A `PersistenceAdapter` loads a schema-versioned `WorkbookSnapshot` and commits immutable `PendingCommit` records carrying a stable `clientMutationId` and `baseVersion`.

A commit response is `applied`, `duplicate`, or `conflict`. Applied and duplicate acknowledgements advance the server version. A conflict may provide ordered operations since the base or a current snapshot; ambiguous structural or formula conflicts require host UX rather than silent merge.

`IndexedDbPendingCommitStorage` from `@sheetwrite/core/browser` can retain optimistic work across reloads. Its typed errors report blocked upgrades, unsupported schemas, quota, transaction, and abort failures. The core continues without durable browser storage when no pending-storage adapter is supplied.

Document snapshots include workbook/sheet data, formula source, formatting, validation, protection metadata, notes, names, filters, and related document state. Selection, scroll position, caret state, search overlays, host read-only policy, and local zoom remain session state.

- [Collaboration and conservative rebase](https://sheetwrite.vercel.app/docs/guides/collaboration/)
- [Document operations reference](https://sheetwrite.vercel.app/docs/reference/document-operations/)
- [`PersistenceAdapter` and sync API](https://sheetwrite.vercel.app/docs/api/core/persistence-adapter/)
- [`@sheetwrite/core/browser`](https://sheetwrite.vercel.app/docs/api/core-browser/)

### Styling and theming

Source: https://sheetwrite.vercel.app/docs/guides/styling/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

Sheetwrite paints cells on a canvas, so styling has two layers: the **`Theme`**
(colors, fonts, and geometry the renderer uses) and **`CellStyle`** (per-cell and
per-column formatting). A small stylesheet provides the host container chrome and
CSS custom properties.

## Theme

The `Theme` controls the canvas paint. Pass a `Partial<Theme>` as the `theme`
option, or call `grid.setTheme(partial)` at runtime; either is merged over the
defaults.

```ts
interface Theme {
  font: string;
  bg: string;
  fg: string;
  gridLine: string;
  headerBg: string;
  headerFg: string;
  selection: string;
  selectionBorder: string;
  rowHeight: number;
  headerHeight: number;
  rowHeaderWidth: number; // 0 hides the left row-number gutter
  searchMatch: string;       // fill behind a search match
  searchActiveMatch: string; // fill/outline for the active (current) match
  highlight: string;         // fill for cells highlighted via Grid.highlightCells
}
```

`DEFAULT_THEME` (exported from `@sheetwrite/core`):

| Field | Default |
| --- | --- |
| `font` | `"13px system-ui, -apple-system, Segoe UI, Roboto, sans-serif"` |
| `bg` | `"#ffffff"` |
| `fg` | `"#111111"` |
| `gridLine` | `"#eeeeee"` |
| `headerBg` | `"#f4ede1"` |
| `headerFg` | `"#6b4a1f"` |
| `selection` | `"#2563eb22"` |
| `selectionBorder` | `"#2563eb"` |
| `rowHeight` | `28` |
| `headerHeight` | `32` |
| `rowHeaderWidth` | `48` |
| `searchMatch` | `"#ffd54f80"` |
| `searchActiveMatch` | `"#f59e0b"` |
| `highlight` | `"#a7f3d080"` |

Note: the shipped `styles.css` declares different values for the search/highlight
CSS custom properties (`#fff47580`, `#fbbc04`, `#e8f0fe99`); on a host that
imports the stylesheet those win over `DEFAULT_THEME` per the resolution order
below.

Override the search-match colors at runtime via `setTheme`:

```ts
grid.setTheme({ searchMatch: "#fff47580", searchActiveMatch: "#fbbc04" });
```

### Resolution order

The effective theme is computed once at construction and again on `setTheme`:

```text
DEFAULT_THEME  <  --sheetwrite-* CSS custom properties (resolveThemeFromCss)  <  opts.theme / setTheme
```

`resolveThemeFromCss(host)` reads CSS custom properties from the host's computed
style into a partial theme, and `opts.theme` wins last.

Two runtime methods with different semantics:

- `grid.setTheme(partial)` — **imperative patch**: merges into the accumulated
base theme and repaints. Use for incremental tweaks.
- `grid.replaceTheme(partial | undefined)` — **option-level replacement**:
re-runs the construction-time resolution above with the new value;
`undefined` restores the CSS-variable/default resolution. The framework
adapters call this for their `theme` prop, so **the prop is authoritative**:
removing it (or dropping a field) restores defaults instead of leaving stale
merged values behind.
- `grid.getEffectiveTheme()` returns the effective (post-zoom) theme currently
painting.

Tailwind works through the same seam: set `--sheetwrite-*` custom properties on
the host with arbitrary-property utilities (e.g.
`class="[--sheetwrite-bg:#0b0b0c] [--sheetwrite-fg:#e7e7e7]"`) or a `@layer`
rule; construction and `replaceTheme(undefined)` both pick them up from the
computed style.

```ts
const DARK: Partial<Theme> = {
  bg: "#0b0b0c",
  fg: "#e7e7e7",
  gridLine: "#26262a",
  headerBg: "#1a160f",
  headerFg: "#e8c98a",
  selection: "#e8c98a22",
  selectionBorder: "#e8c98a",
};

grid.setTheme(DARK);
```

## CSS custom properties & the stylesheet

Import the stylesheet once. It styles the host container (the grid adds the
`.sheetwrite` class to your host element), declares the `--sheetwrite-*` defaults,
and ships a dark variant under `[data-theme="dark"]` or a `.dark` ancestor class
(the Tailwind convention):

```ts
import "@sheetwrite/core/styles.css";
```

`resolveThemeFromCss` maps these custom properties onto `Theme` fields:

| CSS custom property | Theme field |
| --- | --- |
| `--sheetwrite-bg` | `bg` |
| `--sheetwrite-fg` | `fg` |
| `--sheetwrite-grid-line` | `gridLine` |
| `--sheetwrite-header-bg` | `headerBg` |
| `--sheetwrite-header-fg` | `headerFg` |
| `--sheetwrite-selection` | `selection` |
| `--sheetwrite-selection-border` | `selectionBorder` |
| `--sheetwrite-row-height` | `rowHeight` (parsed as a number) |
| `--sheetwrite-search-match` | `searchMatch` |
| `--sheetwrite-search-active` | `searchActiveMatch` |
| `--sheetwrite-highlight` | `highlight` |
| `--sheetwrite-font` | `font` (a `/ line-height` segment is stripped for the canvas) |

`headerHeight` and `rowHeaderWidth` have no CSS variable — set them through the
`theme` option. An explicit `--sheetwrite-*` value set on the `.sheetwrite`
element itself still wins over either dark selector (same-element beats
ancestor).

### Widget and context-menu styling

The stylesheet exposes widget variables in addition to the canvas theme
mapping:

| CSS custom property | Widget use | Fallback |
| --- | --- | --- |
| `--sheetwrite-widget-border` | Borders and separators for toolbar/find/menu chrome | `--sheetwrite-grid-line` |
| `--sheetwrite-menu-hover` | Context-menu item hover background | `--sheetwrite-grid-line` |
| `--sheetwrite-menu-disabled-opacity` | Disabled context-menu row opacity | `0.5` |

The bundled menu uses the public `.sheetwrite-context-menu` container,
`.sheetwrite-context-menu-item` row, `.sheetwrite-context-menu-item-disabled`
state, `.sheetwrite-context-menu-shortcut` hint, and
`.sheetwrite-context-menu-sep` separator classes. Scope overrides beneath the
grid host rather than replacing positioning, visibility, or disabled behavior:

```css
.sheetwrite {
  --sheetwrite-widget-border: #334155;
  --sheetwrite-menu-hover: #1e293b;
  --sheetwrite-menu-disabled-opacity: 0.45;
}

.sheetwrite .sheetwrite-context-menu-item {
  font-weight: 500;
}
```

The recommended runtime-theming pattern drives both layers together: toggle
`data-theme` on a wrapper so the surrounding CSS-variable chrome flips, and
call `setTheme` so the canvas repaints.

```ts
darkBtn.addEventListener("click", () => {
  grid.setTheme(DARK);
  stage.setAttribute("data-theme", "dark");
});
```

## CellStyle

`CellStyle` formats individual cells. It appears in three places:

- as the `style` on a `set` patch — formatting for that one specific cell;
- as `Column.cellStyle` — a column-wide default the renderer paints under every
body cell of the column;
- as `Column.headerStyle` — the style applied to that column's header cell.

`Column.cellStyle` is a default, not a lock: a per-cell `set` style overrides the
column default for that cell, so a cell paints with its column's `cellStyle` until
its own patch supplies styling.

```ts
interface CellStyle {
  bold?: boolean;
  italic?: boolean;
  underline?: boolean;
  strikethrough?: boolean;
  fontSize?: number;
  color?: string;            // hex text color, e.g. "#111111"
  backgroundColor?: string;  // hex fill, e.g. "#ffffff"
  align?: "left" | "center" | "right";
  wrap?: boolean;
  border?: CellBorders;
}
```

Apply a style to a cell via a transaction (a `set` replaces value + style, so pass
the current value back when only restyling):

```ts
grid.store.applyTransaction({
  patches: [
    {
      op: "set",
      addr: { sheet: "sheet1", row: 0, col: 0 },
      value: { kind: "literal", value: "Total" },
      style: { bold: true, align: "center", backgroundColor: "#eef1f5" },
    },
  ],
});
```

### Borders

Borders are per side. `CellBorders.all` applies to any side not given its own
border:

```ts
interface CellBorders {
  all?: CellBorder;
  top?: CellBorder;
  right?: CellBorder;
  bottom?: CellBorder;
  left?: CellBorder;
}

interface CellBorder {
  color?: string;                          // hex, e.g. "#111111"
  width?: number;
  style?: "solid" | "dashed" | "dotted";
}
```

```ts
const style: CellStyle = {
  border: {
    all: { color: "#cccccc", width: 1, style: "solid" },
    bottom: { color: "#111111", width: 2, style: "solid" },
  },
};
```

## Number formats

A numeric/date column can carry an Excel-style `numberFormat` code and an explicit
BCP 47 `numberLocale`. The same UTC serial value and locale are used by the
canvas renderer, auto-fit measurement, and exported formatter:

```ts
const columns: Column[] = [
  {
    key: "amount",
    header: "Amount",
    width: 140,
    type: "number",
    numberFormat: "#,##0.00",
    numberLocale: "de-DE",
  },
  { key: "day", header: "Day", width: 120, type: "date", numberFormat: "yyyy-mm-dd" },
];
```

`formatNumber(value, code?, locale?)` is exported from `@sheetwrite/core`. It is
a cached renderer for the supported Excel-style families:

| Code | Example output |
| --- | --- |
| _(none)_ | `1234.5` → locale-default `1,234.5` |
| `0` | `1234.5` → `1235` |
| `0.00` | `1234.5` → `1234.50` |
| `#,##0.00` | `1234.5` → `1,234.50` |
| `0%` | `0.5` → `50%` |
| `$#,##0.00` | `1234.5` → `$1,234.50` |
| `0.00E+00` | `12345` → `1.23E+04` |
| `yyyy-mm-dd` | serial `45351` → `2024-02-29` |
| `mmm d, yyyy h:mm:ss AM/PM` | UTC serial → `Jul 4, 2024 3:06:07 PM` |
| `0.00;[Red](0.00);"none";"value: "@` | positive / negative / zero / text sections |

Numeric formats support fixed decimals, optional grouping, percent scaling,
scientific exponents with explicit width, quoted/escaped literals, and currency
prefixes/suffixes. Up to four semicolon sections select positive, negative, zero,
and text output; color directives such as `[Red]` are accepted as formatting
metadata but do not change canvas text color.

Date/time formats support numeric and named month/day fields, 12/24-hour time,
minutes, seconds, and AM/PM. Month/minute disambiguation follows neighboring time
tokens. UTC fields make date rendering deterministic across host timezones.
Locale-specific separators come from `numberLocale`, not ambient browser locale.

Fractions, elapsed-time bracket tokens, and fractional seconds are not supported.
Formula errors are explicit sentinels such as `#DIV/0!` and `#CYCLE!`; they are
not non-finite numbers hidden by the formatter. See
[Formulas](https://sheetwrite.vercel.app/docs/guides/formulas/#scalars-coercion-and-errors).

Native boolean values use the normal cell style model, render as uppercase
`TRUE`/`FALSE`, and default to centered alignment unless `CellStyle.align`
overrides it.

## See also

- [Configuration](https://sheetwrite.vercel.app/docs/guides/configuration/) for `theme`, `renderers`, and the toolbar color controls.
- [Concepts](https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/#headers-letters-vs-field-names) for the styled row-0 field-header pattern.

### Worker rendering

Source: https://sheetwrite.vercel.app/docs/guides/worker-rendering/

[Installation](https://sheetwrite.vercel.app/docs/start/installation/)

By default Sheetwrite paints on the main thread (`renderer: "canvas"`). For sheets
where a busy main thread could stall scrolling, you can move painting onto a Web
Worker with an OffscreenCanvas — same `Renderer` contract, drop-in.

## Enabling it

Set `renderer: "worker"` and point `workerUrl` at the worker module **as the
browser will fetch it**. The worker entry ships at
`@sheetwrite/core/dist/worker.js` (export subpath `@sheetwrite/core/worker`),
but the platform `Worker`/`URL` constructors do not consult package exports —
`new URL("@sheetwrite/core/worker", import.meta.url)` treats the bare
specifier as a relative path and produces a 404 URL unless your bundler
happens to rewrite that exact form. Two reliable recipes:

**Universal (any bundler, no bundler):** the worker entry is an ES module with
relative imports (`./canvas-paint.js`, …), so a single-file copy breaks — copy
the package's whole `dist/` directory into your public/static assets and pass
the served `worker.js` URL (a module worker fetches its sibling imports over
HTTP):

```sh
cp -r node_modules/@sheetwrite/core/dist public/sheetwrite
```

```ts
import { createGrid, initSheetwrite } from "@sheetwrite/core";

await initSheetwrite();

const grid = createGrid(host, {
  workbook,
  datasource,
  renderer: "worker",
  workerUrl: "/sheetwrite/worker.js",
});
```

**Vite dependency-worker import (machine-verified):** Vite bundles the whole
worker graph into one chunk and returns its URL via the `?worker&url` query —
verified by the fixture build in `test/bundler-fixtures/vite`
(`bun run verify:bundlers`):

```ts
import workerUrl from "@sheetwrite/core/worker?worker&url";
```

webpack 5 / Next.js have no equivalent URL-returning dependency-worker import
(webpack only bundles a worker graph for a literal
`new Worker(new URL(...))` expression, which Sheetwrite constructs internally)
— use the public-copy recipe above there.

`workerUrl` accepts a `string | URL`. If you omit it, the worker renderer
resolves `./worker.js` relative to its own module — that only works when your
bundler preserves module URLs (it usually does not after bundling to one file).

## Verify it actually started

A worker that fails to construct falls back to the main-thread canvas renderer
(see below) — verify instead of assuming:

```ts
grid.on("renderer-fallback", ({ error }) => {
  console.warn("Sheetwrite worker renderer unavailable, using canvas:", error);
});

if (grid.rendererKind() !== "worker") {
  // main-thread rendering is active
}
```

## How it works

- On mount the renderer constructs the `Worker`, creates a `<canvas>`, and
transfers control of it to the worker with `transferControlToOffscreen()`. The
worker paints into that `OffscreenCanvas` off the main thread.
- Layout, theme, viewport, and each painted window are posted to the worker as
messages. The window snapshot is the same typed-array-backed `VisibleWindowView`
the store produces, so it is cheap to transfer.
- Painting therefore continues smoothly even when the main thread is busy.

## Automatic fallback

The worker is constructed **first**, before the canvas is transferred. If
construction throws — no `OffscreenCanvas` support, or a bundler/security
restriction on the worker URL — the grid switches to the main-thread
`CanvasRenderer` and emits one `renderer-fallback` event with a
`SheetwriteError`. You still get a working grid; worker rendering is an
enhancement, never a hard requirement.

## Limitation: no custom renderers

Custom cell renderers are functions, and functions can not cross the worker
boundary. Under `renderer: "worker"` the `renderers` option (and
`defineCellRenderer`) have no effect — the worker's renderer registry is always
empty. If you rely on custom [`CellRenderer`](https://sheetwrite.vercel.app/docs/guides/configuration/#gridoptions)s,
use the main-thread `canvas` renderer.

## See also

- [Configuration](https://sheetwrite.vercel.app/docs/guides/configuration/#gridoptions) for `renderer` and `workerUrl`.
- [Concepts](https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/#canvas-rendering-and-the-wasm-columnar-store) for the transferable window snapshot.

### XLSX and export

Source: https://sheetwrite.vercel.app/docs/guides/xlsx-export/

CSV and TSV remain core-only. XLSX is optional so normal grid and framework bundles do not pull spreadsheet-file dependencies into their initial graph.

```sh
bun add @sheetwrite/xlsx
```

Register it once before invoking grid XLSX actions or the core workbook/table functions:

```ts
import "@sheetwrite/xlsx/register";

await grid.exportXlsx("sales.xlsx");
```
All four optional XLSX functions are asynchronous. Missing registration and
codec failures reject with `SheetwriteError`; use `code` rather than matching
the installation message. Resource failures remain `XlsxResourceError`
instances and therefore also satisfy `isSheetwriteError`.

## Table interchange

`toXlsxTable` and `fromXlsxTable` exchange the active rectangular table. They deliberately reduce scope and fidelity — one sheet, synthesized headers, resolved scalars instead of formula source — and, like the workbook APIs, they materialize the complete file in memory rather than streaming it. CSV output is UTF-8 with a BOM and CRLF line endings and prefixes injection-sensitive leading characters in string values.

## Workbook interchange

`toXlsxWorkbook` and `fromXlsxWorkbook` preserve supported worksheets, formula source, styles, merges, dimensions, frozen panes, names, HTTPS/mailto and internal range hyperlinks, ordered conditional formats, and Sheetwrite metadata. Unsupported Excel features are never silently flattened: every dropped native feature is reported through the structured `onWarning` callback (`XlsxWorkbookWarning`), and callers must surface warnings when fidelity matters. Both directions build the complete workbook representation in memory; budget accordingly for large files.

Hyperlinks retain stable IDs in Sheetwrite metadata. Internal destinations use stable sheet IDs, so a sheet rename does not retarget the link; removing the destination removes inbound links atomically, and undo restores them with the sheet. Activation of any stale host-held target still fails closed. External mutation and activation accept only absolute `https://` and `mailto:` targets. `javascript:`, `data:`, `file:`, HTTP, credentials, malformed URLs, and internal OOXML relationship traversal are rejected before document mutation or host activation. Sheetwrite never calls `window.open`: Ctrl/Meta-click and `grid.activateHyperlink()` emit `hyperlink-activate` with a validated target. Set `hyperlinkActivation: "internal-navigation"` to additionally navigate internal targets, or `"disabled"` to suppress activation.

Conditional rules are evaluated in array order. Earlier rules have style precedence, and a matching `stopIfTrue` prevents later rules from entering the main/Worker match mask. Formula predicates are anchored at the rule range's top-left: relative A1 references move per target cell while `$`-absolute components stay fixed. One sheet admits at most 32 rules (the deterministic `u32` renderer mask), and one predicate formula is limited to 8,192 characters. SpreadsheetML `cellIs`, blank/text, and expression rules round-trip with priority and stop behavior. Color scales, data bars, icon sets, and unrepresentable differential styles remain in neither the live model nor the renderer; import emits a deterministic `format-loss` warning naming the exact dropped rule kind.

The [detailed compatibility results](https://sheetwrite.vercel.app/docs/reference/compatibility-results/) distinguish evaluated, preserved, flattened, warning, and unsupported behavior by checked test file and producing application.

## Resource limits

Every table and workbook path shares one resource contract, `XlsxWorkbookOptions`:

- `maxCells` bounds logical accepted cells and defaults to `1_000_000`;
- `resourceLimits` overrides the remaining bounded dimensions, checked before decompression and allocation: input bytes (32 MiB), output bytes (128 MiB), archive entries (1,024), per-entry uncompressed bytes (64 MiB), total uncompressed bytes (256 MiB), compression ratio (×100), sheets (256), rows per sheet (1,048,576), columns per sheet (16,384), merges (100,000), shared strings (1,000,000), style records (65,536), XML elements (2,000,000), XML depth (64), XML attributes per element (128), and XML text bytes (16 MiB);
- `signal` aborts between bounded codec stages.

Crossing any bound rejects with a typed `XlsxResourceError` naming the resource, limit, and observed value — before the codec allocates unsafe data. The defaults are exported as `DEFAULT_XLSX_RESOURCE_LIMITS`.

The optional package implements a bounded OOXML subset internally over one audited compression primitive (`fflate`). Load `@sheetwrite/xlsx/register` on the path that needs XLSX rather than in every application entry.

- [Data operations and XLSX compatibility](https://sheetwrite.vercel.app/docs/guides/data-operations/#xlsx-compatibility)
- [`@sheetwrite/xlsx` API](https://sheetwrite.vercel.app/docs/api/xlsx/)
- [`@sheetwrite/xlsx/register` API](https://sheetwrite.vercel.app/docs/api/xlsx-register/)
- [`toXlsxWorkbook`](https://sheetwrite.vercel.app/docs/api/core/to-xlsx-workbook/)

### Public API contract

Source: https://sheetwrite.vercel.app/docs/reference/api-contract/

Sheetwrite treats each package `exports` map as the public boundary. The release gate builds the packages first, analyzes the emitted declarations with TypeScript, and rejects undocumented, ambiguous, or accidentally exposed symbols before any package can publish.

## Entry-point classifications

Every exported subpath has one explicit classification:

| Classification | Contract |
| --- | --- |
| `supported` | Public application API. Semver and the generated reference apply. |
| `internal` | Required runtime plumbing, such as the WASM loader. Published intentionally but not a general extension surface. |
| `testing-only` | Deterministic harnesses for consumers' tests; never production code. |
| `asset` | CSS, Worker, or WASM bytes rather than a TypeScript symbol surface. |

The [generated API index](https://sheetwrite.vercel.app/docs/api/) lists every package entry point, its classification, and every compiler-visible export. There is no manually maintained symbol inventory beside it.

## What the gate records

For every TypeScript export, the canonical manifest records:

- symbol name and declaration kind;
- normalized primary signature;
- owning declaration files and source location;
- source JSDoc and JSDoc tags;
- documented interface and class members.

Named re-exports preserve documentation from both the export statement and the declaration target. Framework-generated declarations are analyzed from the bytes that packages actually ship.

## Stability and changes

`bun run api:check` hashes the normalized manifest. A changed digest must be reviewed with the declaration diff and accepted explicitly; rebuilding alone cannot rewrite the baseline. This catches additions, removals, signature drift, duplicate declaration merges, missing documentation, and dependency types that leak into the public surface.

The API manifest describes type compatibility. Runtime behavior remains protected by package tests, adapter lifecycle contracts, browser scenarios, canonical tarball checks, and delivery-size budgets.

### Compatibility and limits

Source: https://sheetwrite.vercel.app/docs/reference/compatibility-limits/

| Area | Supported contract | Boundary |
| --- | --- | --- |
| Data | Eager columnar data or cancellable datasource pages; dense and allocation-lazy paged storage | Full-sheet queries and exports are incomplete until required pages load |
| Formulas | Persisted formula source, A1/range references, named ranges, the inventory-derived supported function contract, bounded lexical `LET`, and bounded dynamic-array spills | No blanket Excel/Sheets/OpenFormula claim; external/network/database/cube/LAMBDA categories and automatic volatility beyond the clock barrier are unsupported |
| Protection | Serializable client interaction policy with atomic/partial local mutation behavior | Never server authorization; remote operations bypass local UX policy |
| Collaboration | Host sequencing, stable mutation IDs, durable optimistic edits, ordered remote operations, presence/comments/revisions, conservative rebase | No bundled server, CRDT, or general OT; ambiguous structural/formula conflicts require host UX |
| Worker | OffscreenCanvas rendering with capability/startup fallback | Custom function renderers cannot transfer to the worker |
| XLSX | Table interchange plus supported workbook formulas/styles/merges/dimensions/frozen panes/names and Sheetwrite metadata | Unsupported workbook features are warned, flattened, or dropped; not full Excel fidelity |
| Accessibility | ARIA grid mirror for the visible virtualized window with keyboard-driven updates | The full document is not duplicated into hidden DOM |

Compatibility statements are feature contracts, not claims of Excel or Google Sheets parity.

The [detailed compatibility results](https://sheetwrite.vercel.app/docs/reference/compatibility-results/) link each formula, workbook, clipboard, and XLSX status to its evidence record and exact difference.

The [generated formula function contract](https://sheetwrite.vercel.app/docs/reference/formula-functions/) publishes names, families, signatures, behavior profiles, source links, implementation evidence, and unsupported categories directly from the checked versioned inventory.

The tables below describe the owning source definition, not generated API signatures. Ceilings are inclusive unless a row says otherwise. MiB means 1,048,576 bytes. “Compatibility” identifies an external or product boundary; “resource defense” identifies bounded allocation or retained state; “interaction tuning” identifies a non-failing operational default.

## Rendering, interaction, and paged data

| Owner / resource | Default and unit | Why / evidence class | Behavior at the boundary | Supported override |
| --- | --- | --- | --- | --- |
| `GridOptions.overscan` / `DEFAULT_OVERSCAN` | 6 row and visible-column positions per viewport edge | Interaction tuning: keep the virtual paint and ARIA windows close to the viewport | It is not a document ceiling; the window is clipped to available rows/columns | `GridOptions.overscan` or `grid.setOverscan()`; `0` disables the buffer |
| `measureMaxElementHeight` | Measured browser clamp minus 4,096 CSS px; 15,000,000 CSS px fallback | Compatibility: browser layout and scroll-offset clamps vary | Taller logical sheets use scaled scrolling while the DOM sizer stays at the safe clamp | Not configurable |
| `AUTO_FIT_CHUNK_CELLS` | 16,384 cells per store read | Resource defense: bound one synchronous auto-fit read | Larger scans continue in frame-scheduled chunks and commit after the scan | Not configurable |
| `DEFAULT_COL_WIDTH` | 100 CSS px | Interaction tuning: keep synthesized sheet and padding columns consistent | Used for generated columns; it is not a width ceiling | No global setting; supply or update individual column widths |
| [`DEFAULT_SIMPLE_COLUMN_WIDTH`](https://sheetwrite.vercel.app/docs/api/core-adapter/default-simple-column-width/) | 120 CSS px | Interaction tuning: give adapter-created schemas an explicit usable width | Used only when a simple column omits `width` | `SimpleColumn.width` |
| `DataSourceStorageOptions.chunkRows` / `DEFAULT_PAGE_CHUNK_ROWS` | 4,096 rows per chunk | Resource defense: allocation-lazy page granularity | Chunks allocate on load/edit; a positive non-power-of-two value is rounded up to a power of two | `GridOptions.datasourceStorage.chunkRows` or `SheetwriteStoreOptions.chunkRows` |
| `DataSourceStorageOptions.cacheBytes` / `DEFAULT_PAGED_CACHE_BYTES` | 32 MiB per paged sheet | Resource defense: bound clean cached chunks | Before a new chunk would exceed the budget, the least-recent clean, unpinned chunks are evicted; dirty/visible chunks may exceed it | `GridOptions.datasourceStorage.cacheBytes` or `SheetwriteStoreOptions.cacheBytes`; `0` disables eviction |
| `DataSourceStorageOptions.dirtyCellLimit` / `DEFAULT_PAGED_DIRTY_CELL_LIMIT` | 1,000,000 sparse local cells per paged sheet | Resource defense: bound dirty overlay memory independently of clean cached chunks | A transaction that would add cell 1,000,001 is rejected atomically with a `paged-dirty-cells` resource-limit issue; rewrites of already-dirty cells do not consume more capacity | `GridOptions.datasourceStorage.dirtyCellLimit` or `SheetwriteStoreOptions.dirtyCellLimit` |
| `Grid.distinctValues` | 1,000 distinct values | Resource defense: bound the default filter-menu result | Returns the first 1,000 distinct resolved values in first-seen order | Pass `limit`; `0` requests an uncapped scan |
| `UndoManager` | 200 transactions | Resource defense: bound retained undo resources | Pushing entry 201 disposes the oldest undo entry | Not configurable through the public `Grid` API |

The accessibility mirror uses the same virtual window and overscan as the canvas; it has no separate full-document DOM budget. See [datasource paging and storage](https://sheetwrite.vercel.app/docs/guides/configuration/#datasource-pages), [data operations](https://sheetwrite.vercel.app/docs/guides/data-operations/), and [the visible-window accessibility limit](https://sheetwrite.vercel.app/docs/guides/accessibility/#limitation-the-mirror-reflects-the-visible-window).

## Formula evaluation

| Owner / resource | Default and unit | Why / evidence class | Behavior at the boundary | Supported override |
| --- | --- | --- | --- | --- |
| `PARSE_RECURSION_LIMIT` | 256 nested parser levels | Resource defense: bound recursive formula parsing | Deeper syntax is a malformed formula and resolves to `#VALUE!` | Not configurable |
| `FORMULA_RECURSION_LIMIT` | 256 dependency/evaluation levels | Resource defense: bound recursive dependency evaluation | A deeper dependency or expression resolves to `#NUM!` | Not configurable |
| `RANGE_CELL_LIMIT` | 1,000,000 materialized cells per formula range | Resource defense: bound range/matrix allocation | An oversized range resolves to `#NUM!` | Not configurable |
| `SPILL_MAX_ROWS` / `SPILL_MAX_COLS` | 1,048,576 rows and 16,384 columns per matrix | Compatibility and resource defense: match worksheet axes before allocation | An invalid or oversized dimension resolves to `#NUM!` | Not configurable |
| `SPILL_MAX_CELLS` / `SPILL_MAX_BYTES` | 1,000,000 cells and 64 MiB value/intermediate storage per matrix operation | Resource defense: bound dynamic arrays, criteria matrices, transforms, and spill materialization | Preflight or materialization resolves to `#NUM!`; no truncated matrix is installed | Not configurable |
| `SPILL_MAX_RECOMPUTE_CELLS` | 2,000,000 cell operations per dynamic recompute | Resource defense: bound filtering, sorting, uniqueness comparisons, and transforms | The operation resolves to `#NUM!`; spill publication remains atomic | Not configurable |
| `LET_BINDING_LIMIT` | 126 lexical bindings per `LET` | Resource defense: bound binding state and source expansion | Binding 127 resolves to `#VALUE!` | Not configurable |
| `LET_EXPANDED_NODE_LIMIT` | 16,384 reachable expanded AST nodes | Resource defense: bound lazy substitution, including repeated bindings | The first node above the ceiling resolves to `#NUM!`; unused bindings do not consume expansion work | Not configurable |
| `MAX_TEXT_OUTPUT_BYTES` / `MAX_SEARCH_STEPS` | 16 MiB generated text and 4,000,000 bounded search steps | Resource defense: bound Unicode output and text search/substitution work | Excess work resolves to `#NUM!` | Not configurable |
| Financial root solver | 14 bracket steps, 100 solve steps, fixed `1e-12` tolerances | Determinism and resource defense for `IRR`/`RATE` | Invalid domains or non-convergence resolve to `#NUM!` | Not configurable |

See [formula functions, exact semantics, errors, and compatibility](https://sheetwrite.vercel.app/docs/guides/formulas/) and the [inventory-generated function reference](https://sheetwrite.vercel.app/docs/reference/formula-functions/).

## Transactions and snapshots

[`DEFAULT_TRANSACTION_RESOURCE_LIMITS`](https://sheetwrite.vercel.app/docs/api/core/default-transaction-resource-limits/) owns the atomic mutation defaults. A transaction at the ceiling is accepted; exceeding either ceiling returns a `resource-limit` rejection and applies none of an atomic transaction.

| Owner / resource | Default and unit | Why / evidence class | Behavior above the ceiling | Supported override |
| --- | --- | --- | --- | --- |
| `maxOperations` | 10,000 `DocumentOp` objects per transaction | Resource defense: bound object-heavy validation and dispatch | Transaction is rejected | `GridOptions.transactionResourceLimits`, `SheetwriteStoreOptions.transactionResourceLimits`, or an explicit limit passed to `validateTransactionResources` |
| `maxEncodedBytes` | 8 MiB of UTF-8 JSON per operation array | Resource defense: bound exact payload inspection | Transaction is rejected | Same paths as `maxOperations` |

[`DEFAULT_SNAPSHOT_RESOURCE_LIMITS`](https://sheetwrite.vercel.app/docs/api/core/default-snapshot-resource-limits/) owns validation and allocation defaults. Exceeding one produces a path-qualified validation error or `SnapshotResourceError` before store allocation; an allocation failure within a configured ceiling still surfaces as a resource failure.

| Owner / resource | Default and unit | Why / evidence class | Behavior above the ceiling | Supported override |
| --- | --- | --- | --- | --- |
| `maxSheets` | 256 sheets per workbook | Resource defense: bound sheet-indexed schema/store state | Snapshot or direct workbook construction is rejected | `SnapshotValidationOptions.resourceLimits`, `SheetwriteStoreOptions.snapshotResourceLimits`, or `SnapshotGridOptions.snapshotResourceLimits` |
| `maxRowsPerSheet` | 1,000,000 rows per sheet | Compatibility: million-row allocation-lazy sheet contract | Rejected before allocation | Same snapshot resource-limit paths |
| `maxColumnsPerSheet` | 16,384 columns per sheet | Compatibility: worksheet width shared with XLSX | Rejected before allocation | Same snapshot resource-limit paths |
| `maxMetadataEntries` | 1,000,000 aggregate entries | Resource defense: bound names and sheet metadata collections | Rejected during resource preflight | Same snapshot resource-limit paths |
| `maxSerializedBytes` | 64 MiB of UTF-8 JSON | Resource defense: bound snapshot JSON-safety inspection | Validation returns a resource-limit error | Same snapshot resource-limit paths |
| `maxLogicalCellsPerSheet` | 4,294,967,295 row-by-column cells per sheet | Resource defense: cap logical area even when paged storage defers allocation | Rejected before dense or paged allocation | Same snapshot resource-limit paths |
| `maxDenseCells` | 5,000,000 aggregate cells per dense workbook | Resource defense: bound eager allocation | Dense construction is rejected; paged storage does not consume this budget | Same snapshot resource-limit paths; choose `storage: "paged"` for allocation-lazy data |

See [persistence and recovery](https://sheetwrite.vercel.app/docs/guides/persistence/) and [document operations](https://sheetwrite.vercel.app/docs/reference/document-operations/).

## Delimited text

[`DEFAULT_DELIMITED_TEXT_RESOURCE_LIMITS`](https://sheetwrite.vercel.app/docs/api/core/default-delimited-text-resource-limits/) owns synchronous CSV/TSV defaults. Except for the writer window, exceeding a ceiling throws `DelimitedTextResourceError` before the next oversized parse/encode allocation; no partial string is returned.

| Resource | Default and unit | Why / evidence class | Behavior at or above the boundary | Supported override |
| --- | --- | --- | --- | --- |
| `maxInputBytes` | 32 MiB UTF-8 input | Resource defense: bound the caller-owned string before parser allocations | At the ceiling parses; above it throws | `DelimitedTextOptions.resourceLimits.maxInputBytes` |
| `maxOutputBytes` | 64 MiB UTF-8 output, including BOM | Resource defense: bound the single returned string | At the ceiling returns; above it throws | `DelimitedTextOptions.resourceLimits.maxOutputBytes` |
| `maxRows` | 1,000,000 syntactic records | Compatibility: million-row data contract | Record 1,000,001 throws | `DelimitedTextOptions.resourceLimits.maxRows` |
| `maxColumns` | 16,384 fields in one record | Compatibility: worksheet width | Field 16,385 in one record throws | `DelimitedTextOptions.resourceLimits.maxColumns` |
| `maxCells` | 1,000,000 aggregate fields | Resource defense: bound parser arrays and encoder work | Aggregate field 1,000,001 throws | `DelimitedTextOptions.resourceLimits.maxCells` |
| `maxFieldBytes` | 1 MiB decoded UTF-8 per field | Resource defense: prevent one quoted field dominating memory | One byte above the ceiling throws | `DelimitedTextOptions.resourceLimits.maxFieldBytes` |
| `maxWriterWindowRows` | 4,096 rows per packed store read | Resource defense: bound each synchronous store window | Export continues with the next window; this is not a total-row ceiling | `DelimitedTextOptions.resourceLimits.maxWriterWindowRows` |

The override object accepts positive safe integers. CSV and TSV still return complete in-memory strings; raising byte/cell ceilings is not streaming. See [data import and export](https://sheetwrite.vercel.app/docs/guides/data-operations/#export).

## Synchronization and presence

[`DEFAULT_SYNC_COORDINATOR_LIMITS`](https://sheetwrite.vercel.app/docs/api/core/default-sync-coordinator-limits/) owns remote-input and durable-queue defaults. All fields accept positive safe-integer overrides through `SyncCoordinatorOptions.limits`.

| Resource | Default and unit | Why / evidence class | Behavior at or above the boundary | Supported override |
| --- | --- | --- | --- | --- |
| `maxMutationIdBytes` | 256 UTF-8 bytes per mutation ID | Resource defense: IDs cross transport and persistence boundaries | At the ceiling accepted; an oversized ID is a typed protocol error | `limits.maxMutationIdBytes` |
| `maxOperationsPerVersion` | 10,000 operations per remote version | Resource defense: match one atomic transaction | At the ceiling accepted; above it emits a protocol error and reload requirement | `limits.maxOperationsPerVersion` |
| `maxVersionPayloadBytes` | 8 MiB UTF-8 JSON per remote version | Resource defense: match one atomic transaction payload | At the ceiling accepted; above it emits a protocol error and reload requirement | `limits.maxVersionPayloadBytes` |
| `maxFutureVersionDistance` | 1,024 versions ahead | Recovery bound: avoid retaining an unbounded gap | A greater distance clears the gap buffer and requests reload/recovery | `limits.maxFutureVersionDistance` |
| `maxBufferedVersions` | 256 future versions | Resource defense: bound retained gap count | The next version clears the gap buffer and requests reload/recovery | `limits.maxBufferedVersions` |
| `maxBufferedOperations` | 40,000 aggregate operations | Resource defense: bound retained gap work | The operation that would exceed it clears the gap buffer and requests reload/recovery | `limits.maxBufferedOperations` |
| `maxBufferedBytes` | 32 MiB aggregate UTF-8 JSON | Resource defense: bound retained gap payloads | The operation that would exceed it clears the gap buffer and requests reload/recovery | `limits.maxBufferedBytes` |
| `maxRecentAcknowledgements` | 4,096 mutation IDs | Resource defense: bound echo-deduplication state | The oldest ID expires; a later stale echo is a reload-requiring protocol violation | `limits.maxRecentAcknowledgements` |
| `maxPendingCommits` | 10,000 pending commits | Durability bound: cap retained offline work | At the ceiling capacity is `full`; another local transaction is rejected atomically | `limits.maxPendingCommits` |
| `maxPendingOperations` | 100,000 aggregate pending operations | Durability bound: cap retained offline work | At the ceiling capacity is `full`; a transaction that would exceed it is rejected | `limits.maxPendingOperations` |
| `maxPendingEncodedBytes` | 128 MiB aggregate UTF-8 JSON | Durability bound: cap retained offline payloads | At the ceiling capacity is `full`; a transaction that would exceed it is rejected | `limits.maxPendingEncodedBytes` |

`PresenceCoordinator` owns its independent ephemeral defaults:

| Resource | Default and unit | Why / evidence class | Behavior at the boundary | Supported override |
| --- | --- | --- | --- | --- |
| `heartbeatMs` | 15,000 ms | Interaction tuning: periodic publish and stale pruning | Timer publishes/prunes each interval | `PresenceCoordinatorOptions.heartbeatMs`; `0` disables the timer |
| `timeoutMs` | 45,000 ms | Interaction tuning: three default heartbeat intervals of silence | An actor at or beyond the idle cutoff is expired | `PresenceCoordinatorOptions.timeoutMs` |
| `maxActors` | 32 remote actors | Resource defense: bound overlay state | Receiving a new actor at capacity evicts the oldest actor | `PresenceCoordinatorOptions.maxActors` (minimum 1) |
| `maxRangesPerActor` | 8 selection ranges | Resource defense: bound payload and overlay work | Additional outbound/inbound ranges are truncated | `PresenceCoordinatorOptions.maxRangesPerActor` (minimum 1) |

See [durable commits, version gaps, and presence](https://sheetwrite.vercel.app/docs/guides/collaboration/).

## XLSX codec

[`DEFAULT_XLSX_RESOURCE_LIMITS`](https://sheetwrite.vercel.app/docs/api/core/default-xlsx-resource-limits/) owns every optional codec path. Each ceiling is inclusive; exceeding one throws `XlsxResourceError` and returns no partial workbook. Override `maxCells` through `XlsxWorkbookOptions.maxCells`; override every other field through `XlsxWorkbookOptions.resourceLimits`.

| Resource | Default and unit | Why / evidence class | Behavior above the ceiling | Supported override |
| --- | --- | --- | --- | --- |
| `maxInputBytes` | 32 MiB compressed input | Resource defense: bound caller input | Import throws before ZIP parsing | `resourceLimits.maxInputBytes` |
| `maxOutputBytes` | 128 MiB encoded output | Resource defense: bound the returned byte array | Export throws during preflight or after encoding | `resourceLimits.maxOutputBytes` |
| `maxArchiveEntries` | 1,024 ZIP entries | Resource defense: bound archive fan-out | Import/export throws | `resourceLimits.maxArchiveEntries` |
| `maxEntryUncompressedBytes` | 64 MiB per ZIP entry | Resource defense: bound one inflated/encoded part | Import/export throws | `resourceLimits.maxEntryUncompressedBytes` |
| `maxTotalUncompressedBytes` | 256 MiB aggregate ZIP content | Resource defense: bound total inflated/encoded parts | Import/export throws | `resourceLimits.maxTotalUncompressedBytes` |
| `maxCompressionRatio` | 100:1 uncompressed/compressed | Resource defense: reject zip-bomb-like entries | Import throws | `resourceLimits.maxCompressionRatio` |
| `maxSheets` | 256 worksheets | Resource defense: bound workbook collections | Import/export throws | `resourceLimits.maxSheets` |
| `maxRowsPerSheet` | 1,048,576 rows per worksheet | Compatibility: SpreadsheetML worksheet height | Import/export throws | `resourceLimits.maxRowsPerSheet` |
| `maxColumnsPerSheet` | 16,384 columns per worksheet | Compatibility: SpreadsheetML worksheet width | Import/export throws | `resourceLimits.maxColumnsPerSheet` |
| `maxCells` | 1,000,000 cells accounted by the conversion path | Resource defense: bound conversion work | Import/export throws | Top-level `XlsxWorkbookOptions.maxCells` |
| `maxMerges` | 100,000 aggregate merged ranges | Resource defense: bound merge collections | Import/export throws | `resourceLimits.maxMerges` |
| `maxSharedStrings` | 1,000,000 shared-string entries | Resource defense: bound the shared-string table | Import throws | `resourceLimits.maxSharedStrings` |
| `maxStyles` | 65,536 style-related records | Resource defense: bound style tables | Import/export throws | `resourceLimits.maxStyles` |
| `maxXmlElements` | 2,000,000 elements per XML part | Resource defense: bound parser nodes | Import throws | `resourceLimits.maxXmlElements` |
| `maxXmlDepth` | 64 nested elements per XML part | Resource defense: bound parser nesting | Import throws | `resourceLimits.maxXmlDepth` |
| `maxXmlAttributesPerElement` | 128 attributes per element | Resource defense: bound per-node parsing | Import throws | `resourceLimits.maxXmlAttributesPerElement` |
| `maxXmlTextBytes` | 16 MiB UTF-8 text per element or attribute | Resource defense: bound XML text accumulation | Import/export throws | `resourceLimits.maxXmlTextBytes` |

Table and workbook conversions account cells according to the active path (for example, table export accounts its rectangular table). Raising dimensions does not add fidelity for unsupported workbook features. See [XLSX compatibility](https://sheetwrite.vercel.app/docs/guides/data-operations/#xlsx-compatibility).

## Related guides

- [Supported formulas and formula errors](https://sheetwrite.vercel.app/docs/guides/formulas/#supported-formulas)
- [Datasource pages and allocation-lazy storage](https://sheetwrite.vercel.app/docs/guides/configuration/#datasource-pages)
- [Data operations and export](https://sheetwrite.vercel.app/docs/guides/data-operations/)
- [Accessibility limits](https://sheetwrite.vercel.app/docs/guides/accessibility/)
- [Persistence and recovery](https://sheetwrite.vercel.app/docs/guides/persistence/)
- [Collaboration and presence](https://sheetwrite.vercel.app/docs/guides/collaboration/)
- [Worker fallback](https://sheetwrite.vercel.app/docs/guides/worker-rendering/)

### Document operations

Source: https://sheetwrite.vercel.app/docs/reference/document-operations/

`DocumentOp` is the exhaustive serializable mutation union used by Store/Grid transactions, persistence, sync, undo/redo, and document rebase. Operations address stable sheet IDs and explicit row/column coordinates; structural operations also rebase formula references and related metadata.

## Local transactions

`grid.applyTransaction({ patches })` participates in read-only/protection policy, undo/redo, and committed `change` events. Its `ApplyTransactionResult` is `applied`, `rejected`, `conflict`, or `noop`, with warnings/rejections where applicable. `store.applyTransaction` is the lower-level epoch boundary and intentionally bypasses Grid policy/history.

## Remote input

Apply sequenced host input through the remote operation path so events carry `source: "remote"` and are not re-enqueued as local output. Versions must be contiguous: gaps require reload or an explicit `SyncVersionGapRequest` recovery flow.

## Snapshots and rebase

Validate untrusted JSON with the snapshot validator before hydration. `SnapshotValidationError` identifies the failing path. `rebaseDocumentOperations` accepts only cases it can establish as non-overlapping; conflicts preserve the original pending queue for host resolution.

- [`DocumentOp`](https://sheetwrite.vercel.app/docs/api/core/document-op/)
- [`Grid.applyTransaction`](https://sheetwrite.vercel.app/docs/api/core/grid/#applytransaction)
- [`ApplyTransactionResult`](https://sheetwrite.vercel.app/docs/api/core/apply-transaction-result/)
- [`WorkbookSnapshot`](https://sheetwrite.vercel.app/docs/api/core/workbook-snapshot/)
- [Persistence and recovery](https://sheetwrite.vercel.app/docs/guides/persistence/)

### Error handling

Source: https://sheetwrite.vercel.app/docs/reference/events-errors/

## Event direction

`change` is the committed transaction stream. `ChangeEvent.source` is `local` for user/API output that a host may persist and `remote` for already-persisted input that must not be enqueued again. Selection, search, renderer fallback, and other UI events remain observational.

Framework `onGridChange`/`grid-change` callbacks carry the same committed event. Adapter readiness is `{ grid, generation, reason }`; `reason` distinguishes `initial`, `input-reset`, and `renderer-reset`. The imperative ref, exposed handle, or binding is assigned before readiness and cleared on replacement.

## Stable failure envelope

Every consumer-visible initialization, datasource, renderer, export, persistence,
snapshot, synchronization, collaboration, CSV, and XLSX failure is a
`SheetwriteError`. Use `code` and `operation` for control flow; `message` is
diagnostic text and may become more specific. `context` contains
serialization-safe boundary details, `retryable` is present only when
Sheetwrite can determine it, and `cause` retains the original exception in the
current realm. `toJSON()` omits `cause`.

```ts
import { initSheetwrite, isSheetwriteError } from "@sheetwrite/core";
declare const wasmUrl: URL;
declare const correctedWasmUrl: URL;
declare function showInitializationError(message: string): void;

try {
  await initSheetwrite(wasmUrl);
} catch (error) {
  if (!isSheetwriteError(error) || error.code !== "initialization-failed") throw error;
  showInitializationError(error.message);
  // A failed source does not poison readiness. Retry with corrected input.
  await initSheetwrite(correctedWasmUrl);
}
```

The guard also recognizes validated cross-realm and serialized envelopes. A
serialized envelope is structural; code that requires `Error` identity should
construct or receive a live `SheetwriteError`.

```ts
declare function retryVisibleRows(request: {
  readonly sheet: string;
  readonly start: number;
  readonly end: number;
  readonly revision: number;
}): void;
declare function reportDegradedRendering(code: string): void;
declare function promptToEnableXlsx(): void;

grid.on("datasource-error", ({ request, error }) => {
  if (error.retryable !== false) {
    retryVisibleRows(request);
  }
});

grid.on("renderer-fallback", ({ error }) => {
  reportDegradedRendering(error.code);
  // Canvas rendering is already active; do not remount the Grid.
});

grid.on("export-error", ({ error }) => {
  if (error.code === "optional-backend-unavailable") {
    promptToEnableXlsx();
  }
});
```

Framework initialization callbacks and Grid operational events carry the same
class identity exported by `@sheetwrite/core` and `@sheetwrite/core/adapter`.
Normal mutation denials remain `mutation-rejected` results/events, and
incomplete paged queries retain their explicit capability/result contracts;
they are not converted into generic exceptions.

## Typed error index

Start with [`SheetwriteError`](https://sheetwrite.vercel.app/docs/api/core/sheetwrite-error/) and
[`isSheetwriteError`](https://sheetwrite.vercel.app/docs/api/core/is-sheetwrite-error/). Branch on the stable
`code` and `operation` fields; use the boundary-specific classes below only when
their structured fields are needed.

The complete enums are [`SheetwriteErrorCode`](https://sheetwrite.vercel.app/docs/api/core/sheetwrite-error-code/)
and [`SheetwriteErrorOperation`](https://sheetwrite.vercel.app/docs/api/core/sheetwrite-error-operation/);
their runtime value sets are
[`SHEETWRITE_ERROR_CODES`](https://sheetwrite.vercel.app/docs/api/core/sheetwrite-error-codes/) and
[`SHEETWRITE_ERROR_OPERATIONS`](https://sheetwrite.vercel.app/docs/api/core/sheetwrite-error-operations/).

SnapshotValidationError Malformed workbook snapshot; inspect path-qualified errors. (https://sheetwrite.vercel.app/docs/api/core/snapshot-validation-error/)
SnapshotResourceError Workbook construction exceeded a configured resource ceiling. (https://sheetwrite.vercel.app/docs/api/core/snapshot-resource-error/)
IncompleteDataError A query needs datasource pages that are not loaded yet. (https://sheetwrite.vercel.app/docs/api/core/incomplete-data-error/)
DelimitedTextOptionsError A CSV/TSV resource-limit option is invalid. (https://sheetwrite.vercel.app/docs/api/core/delimited-text-options-error/)
DelimitedTextResourceError CSV/TSV parsing or encoding exceeded a declared limit. (https://sheetwrite.vercel.app/docs/api/core/delimited-text-resource-error/)
XlsxResourceError XLSX import or export exceeded a codec resource ceiling. (https://sheetwrite.vercel.app/docs/api/core/xlsx-resource-error/)
PersistenceError Host load, commit, or recovery failed with a stable persistence code. (https://sheetwrite.vercel.app/docs/api/core/persistence-error/)
IndexedDbPendingCommitStorageError Browser durable-queue storage is unavailable, blocked, aborted, corrupt, or over quota. (https://sheetwrite.vercel.app/docs/api/core-browser/indexed-db-pending-commit-storage-error/)
SyncProtocolError Remote synchronization input is malformed or exceeds a protocol bound. (https://sheetwrite.vercel.app/docs/api/core/sync-protocol-error/)
SyncPendingCapacityError The durable local queue cannot reserve capacity for another transaction. (https://sheetwrite.vercel.app/docs/api/core/sync-pending-capacity-error/)

## Recovery by boundary

- `SnapshotValidationError` rejects malformed workbooks before partial hydration. Inspect its path-qualified `errors`; fix or reject the source instead of retrying unchanged bytes.
- `SnapshotResourceError` reports bounded workbook construction. Reduce the document or explicitly raise the named host-controlled ceiling.
- `DelimitedTextOptionsError` rejects an invalid CSV/TSV ceiling before work starts. Correct the option; retrying the same configuration cannot succeed.
- `DelimitedTextResourceError` and `XlsxResourceError` retain `resource`, `limit`, and `actual`. Reduce the input/output or explicitly change the applicable limit.
- `IncompleteDataError` identifies datasource pages required by the operation. Load those pages or use a visible-window operation; do not treat unloaded cells as empty.
- `PersistenceError` retains the host load/commit `cause`; its code distinguishes aborted work, invalid snapshots, resource limits, missing state, and rejected commits.
- `IndexedDbPendingCommitStorageError` distinguishes unavailable, blocked, aborted, corrupt, and quota-limited browser storage.
- `SyncProtocolError` rejects malformed or resource-violating remote input. Fix the producer; do not replay the same payload.
- `SyncPendingCapacityError` rejects a new local transaction before it can exceed the durable queue ceiling. Drain or reconcile pending work before retrying.

Worker startup and capability failures switch to the canvas renderer and emit `renderer-fallback`; observe `grid.rendererKind` to report the active renderer, not the requested option.

- [`GridEvents`](https://sheetwrite.vercel.app/docs/api/core/grid-events/)
- [`SnapshotValidationError`](https://sheetwrite.vercel.app/docs/api/core/snapshot-validation-error/)
- [`IncompleteDataError`](https://sheetwrite.vercel.app/docs/api/core/incomplete-data-error/)
- [`SheetwriteError`](https://sheetwrite.vercel.app/docs/api/core/sheetwrite-error/)
- [`isSheetwriteError`](https://sheetwrite.vercel.app/docs/api/core/is-sheetwrite-error/)
- [Framework lifecycle](https://sheetwrite.vercel.app/docs/frameworks/lifecycle/)

### Your first grid

Source: https://sheetwrite.vercel.app/docs/start/first-grid/

This complete TypeScript example uses the imperative core. [Install Sheetwrite](https://sheetwrite.vercel.app/docs/start/installation/) first; the framework adapters expose the same `Grid` after their client-only initialization completes.

```ts
import {
  createGrid,
  initSheetwrite,
  type ColumnarData,
  type Workbook,
} from "@sheetwrite/core";
import "@sheetwrite/core/styles.css";

const host = document.querySelector<HTMLElement>("#grid");
if (host === null) throw new Error("Missing #grid host");
host.style.height = "420px";

const workbook: Workbook = {
  activeSheet: "sales",
  sheets: [
    {
      id: "sales",
      name: "Sales",
      rowCount: 3,
      columns: [
        { key: "product", header: "Product", width: 180, type: "text" },
        { key: "amount", header: "Amount", width: 100, type: "number" },
      ],
    },
  ],
};
const data: ColumnarData = {
  rowCount: 3,
  columns: {
    product: ["Notebook", "Pen", "Folder"],
    amount: new Float64Array([12, 4, 9]),
  },
};

await initSheetwrite();
const grid = createGrid(host, { workbook, data });
grid.on("change", ({ transaction }) => {
  console.log(transaction.patches);
});
```

`initSheetwrite()` is re-entrant. Call it before `createGrid`; concurrent calls share initialization and a failed call can be retried. Destroy the returned grid when its host is permanently removed.

## Next steps

- Open the [Vanilla example](https://sheetwrite.vercel.app/vanilla/) to exercise the same lifecycle in a production build.
- Choose a [framework integration](https://sheetwrite.vercel.app/docs/frameworks/lifecycle/).
- Learn when the [`Grid` and `Store` own state](https://sheetwrite.vercel.app/docs/concepts/runtime-ownership/).
- Browse the generated [`@sheetwrite/core` API](https://sheetwrite.vercel.app/docs/api/core/).

### Installation

Source: https://sheetwrite.vercel.app/docs/start/installation/

Choose a framework in the header once. Every framework-aware example uses that preference, including the quick starts below and the lifecycle guide.

**Vanilla**

```sh
npm install @sheetwrite/core
```

```ts
import { createGrid, initSheetwrite } from "@sheetwrite/core";
import "@sheetwrite/core/styles.css";

await initSheetwrite();
const grid = createGrid(document.querySelector("#grid")!, { workbook, data });
```

The host owns initialization and must destroy the returned `Grid` when its DOM lifetime ends.

**React**

```sh
npm install @sheetwrite/react
```

```tsx
import { Sheetwrite } from "@sheetwrite/react";
import "@sheetwrite/react/styles.css";

export function Workbook() {
  return <Sheetwrite columns={columns} defaultRows={rows} height={520} />;
}
```

The adapter initializes WASM after client mount. Use a client component boundary in server-rendered React hosts.

**Vue**

```sh
npm install @sheetwrite/vue
```

```vue
<script setup lang="ts">
import { Sheetwrite } from "@sheetwrite/vue";
import "@sheetwrite/vue/styles.css";
</script>

<template>
  <Sheetwrite :columns="columns" :default-rows="rows" height="520px" />
</template>
```

The adapter initializes WASM after client mount. Use a client-only boundary in Nuxt and other server-rendered Vue hosts.

**Svelte**

```sh
npm install @sheetwrite/svelte
```

```svelte
<script lang="ts">
  import { Sheetwrite } from "@sheetwrite/svelte";
  import "@sheetwrite/svelte/styles.css";
</script>

<Sheetwrite {columns} defaultRows={rows} height="520px" />
```

The adapter initializes WASM after client mount. Use a client-only boundary when a SvelteKit route renders on the server.

## Server-rendered host boundaries

The adapter host, its `Grid`, and WASM initialization are client-owned. Server rendering may produce surrounding layout and fallback content, but it must not instantiate a Sheetwrite component or call `createGrid`.

**Next.js App Router:** put the adapter import and component in a module whose first directive is `"use client"`. Import `@sheetwrite/react/styles.css` once from the root layout. The production fixture builds a static Next route, hydrates it in Chromium, then proves ready, edit, input reset, and unmount using the adapter's zero-argument initializer.

**Nuxt:** render `@sheetwrite/vue` from a `.client.vue` component or inside Nuxt's `<ClientOnly>` boundary, and load `@sheetwrite/vue/styles.css` through the app-level `css` configuration. Nuxt is not currently in the release runtime matrix, so this boundary is required and server-side component execution is not claimed as supported.

**SvelteKit:** make the containing route client-rendered with `export const ssr = false`, or create the adapter only from `onMount` when the rest of the route must stay server-rendered. Import `@sheetwrite/svelte/styles.css` from the client-owned component or app stylesheet. SvelteKit is not currently in the release runtime matrix; direct SSR of the adapter is not claimed as supported.

## Runtime initialization

Zero-argument `initSheetwrite()` is canonical for the imperative package. It is re-entrant: concurrent calls share one initialization, retries work after failure, and repeats after success are no-ops. Framework adapters call the same initializer on mount.

Pass a source only for unsupported bundlers, public-asset policies, or controlled delivery:

```ts
await initSheetwrite(source);
```

Accepted sources are `BufferSource | URL | string | Request | WebAssembly.Module`. The raw binary remains exported as `@sheetwrite/wasm/wasm`.

```ts
// Vite-family URL
import wasmUrl from "@sheetwrite/wasm/wasm?url";
await initSheetwrite(wasmUrl);

// webpack asset URL
await initSheetwrite(new URL("@sheetwrite/wasm/wasm", import.meta.url));

// Public-copy fallback
await initSheetwrite("/sheetwrite_wasm_bg.wasm");
```

webpack and Next.js need no `IgnorePlugin`; package export conditions keep Node filesystem code out of browser graphs.

## Failure UI and retries

React accepts `fallback`; Vue and Svelte use fallback content or slots. Initialization failures reach `onInitializationError` or Vue's `initialization-error`. A changed explicit source or remount can retry after failure.

## Optional feature assets

Worker rendering and XLSX stay explicit. Import the Worker entry from `@sheetwrite/core/worker`. XLSX requires `@sheetwrite/xlsx` plus `import "@sheetwrite/xlsx/register"` before toolbar or programmatic export.

- [Build the first workbook](https://sheetwrite.vercel.app/docs/start/first-grid/)
- [Choose lifecycle ownership](https://sheetwrite.vercel.app/docs/frameworks/lifecycle/)
- [Configure Worker rendering](https://sheetwrite.vercel.app/docs/guides/worker-rendering/)
- [Configure XLSX import and export](https://sheetwrite.vercel.app/docs/guides/xlsx-export/)

## Public API declarations

Every symbol below is compiler-verified from the declaration files the packages ship. Entry-point classification, signatures, and source JSDoc are the complete public surface; anything absent is not public API.

### `@sheetwrite/core`

#### `@sheetwrite/core` — supported

Declaration target: `./dist/index.d.ts`
Source entry: `src/index.ts`
Page: https://sheetwrite.vercel.app/docs/api/core/

##### `AggregateOp` — type

```ts
export type AggregateOp = "sum" | "avg" | "min" | "max" | "count";
```

Column aggregate operation for `Grid.aggregate` / `Store` data ops.

##### `ApplyTransactionResult` — type

```ts
export type ApplyTransactionResult = | { status: "applied"; epoch: number; transaction: Transaction; warnings?: MutationIssue[]; rejections?: MutationIssue[]; } | { status: "conflict"; expectedEpoch: number; actualEpoch: number } | { status: "rejected"; epoch: number; issues: MutationIssue[]; } | { status: "noop"; epoch: number; reason: "empty" | "out-of-bounds" | "incomplete-data" | "read-only"; };
```

Outcome of applying a document transaction, including conflict, rejection, and no-op states.

##### `assertRuntimeResourceSnapshot` — function

```ts
(snapshot: RuntimeResourceSnapshot): void
```

Reject overlap, negative values, and attempts to fold runtime observations into owner totals.

##### `assertWorkbookTables` — function

```ts
(sheets: readonly Sheet[], limits?: Readonly<WorkbookTableResourceLimits>, reservedNames?: readonly string[]): void
```

Reject an invalid or oversized live workbook before table arrays are copied to WASM.

##### `BoundaryDirection` — type

```ts
export type BoundaryDirection = "js-to-wasm" | "wasm-to-js";
```

Direction of a measured JS/WASM boundary crossing.

##### `BoundaryOperationStats` — interface

```ts
export interface BoundaryOperationStats { readonly operation: RuntimeResourceOperation; readonly ffiCalls: number; readonly jsToWasmBytes: number; readonly wasmToJsBytes: number; readonly largestTransferBytes: number; readonly bulkCalls: number; readonly scalarCalls: number; }
```

Fixed-cardinality boundary crossing counters for one operation.

##### `BoundaryTransferKind` — type

```ts
export type BoundaryTransferKind = "bulk" | "scalar";
```

Whether a measured boundary crossing transfers one scalar or a packed batch.

##### `cellA1` — function

```ts
(row: number, col: number): string
```

0-based (row, col) → A1 cell reference (0, 0 → "A1").

##### `CellAddress` — interface

```ts
export interface CellAddress { sheet: SheetId; row: number; col: number; }
```

Zero-based address of one cell on a stable sheet ID.

##### `CellAlign` — type

```ts
export type CellAlign = "left" | "center" | "right";
```

Horizontal text alignment supported by cell styles.

##### `CellBlock` — interface

```ts
export interface CellBlock { startRow: number; startCol: number; rowCount: number; colCount: number; cells: SnapshotCell[]; }
```

Sparse row-major cells bounded by one rectangular block.

##### `CellBorder` — interface

```ts
export interface CellBorder { color?: string; width?: number; style?: "solid" | "dashed" | "dotted"; }
```

Visual border applied to one or more sides of a cell.

Members:
- `color` — hex color, e.g. "#111111"

##### `CellBorders` — interface

```ts
export interface CellBorders { all?: CellBorder; top?: CellBorder; right?: CellBorder; bottom?: CellBorder; left?: CellBorder; }
```

Per-side borders; `all` applies to any side not given its own border.

##### `CellChange` — interface

```ts
export interface CellChange { addr: CellAddress; oldValue: CellValue; newValue: CellValue; oldStyle?: CellStyle; newStyle?: CellStyle; }
```

One committed cell edit, carrying enough to roll back.

##### `CellEditor` — interface

```ts
export interface CellEditor { mount(host: HTMLElement, context: CellEditorContext): CellEditorInstance; }
```

Framework-neutral named editor definition registered through GridOptions.editors.

##### `CellEditorContext` — interface

```ts
export interface CellEditorContext { readonly grid: Grid; readonly address: Readonly<CellAddress>; readonly viewAddress: Readonly<CellAddress>; readonly column: Readonly<Column>; readonly value: CellScalar; readonly text: string; readonly initialInput: string | undefined; readonly selectAll: boolean; readonly label: string; readonly signal: AbortSignal; commit(value: string, navigation?: CellEditorNavigation): void; cancel(): void; }
```

Immutable state and guarded completion callbacks for one mounted editor.

##### `CellEditorInstance` — interface

```ts
export interface CellEditorInstance { update(context: CellEditorContext): void; reposition(rect: CellEditorRect): void; commit(navigation: CellEditorNavigation): string | undefined | Promise<string | undefined>; cancel(): void; destroy(): void; }
```

Retained lifecycle returned by a custom editor's mount method.

##### `CellEditorNavigation` — type

```ts
export type CellEditorNavigation = "down" | "right" | "left" | "none";
```

Selection movement applied after a successful editor commit.

##### `CellEditorRect` — interface

```ts
export interface CellEditorRect { readonly x: number; readonly y: number; readonly width: number; readonly height: number; }
```

Viewport-relative geometry of the cell currently owned by an editor.

##### `CellFormat` — type

```ts
export type CellFormat = "text" | "number" | "date" | "currency";
```

How a column's cells are typed, parsed, and rendered: `text` verbatim, `number`
via its `numberFormat`, `date` as an Excel-style serial (see `date-serial.ts`)
rendered by a date `numberFormat`, and `currency` as a plain number rendered by
a currency `numberFormat` (e.g. `$#,##0.00`).

##### `CellHyperlink` — interface

```ts
export interface CellHyperlink { id: string; range: Range; target: HyperlinkTarget; display?: string; style?: CellStyle; }
```

Bounded serializable hyperlink metadata applied to one cell or range.

Members:
- `display` — Optional accessible/OOXML display label; cell values remain authoritative.
- `id` — Stable identity used by operations, history, and collaboration rebase.
- `style` — Optional override merged over the deterministic blue/underline link style.

##### `CellInputSnapshot` — interface

```ts
export interface CellInputSnapshot { readonly address: CellAddress; readonly text: string; readonly format: CellFormat; }
```

View-aware editable snapshot of one cell, for hosts building a detached
formula bar or cell inspector. `address` is the translated *data* address —
the correct target for `Grid.applyTransaction` even under an active
sort/filter view — while the `(row, col)` inputs of
{@link Grid.getCellInput} are active-sheet view coordinates.

Members:
- `address` — Underlying data address, suitable for a `set` patch.
- `format` — Column input format, for `parseCellInput`.
- `text` — Formula source when the cell is a formula, else the literal display text.

##### `CellLoadState` — type

```ts
export type CellLoadState = "unloaded" | "loaded-empty" | "loaded-value" | "local-edit";
```

Datasource loading state for a resolved cell.

##### `CellNote` — interface

```ts
export interface CellNote { addr: CellAddress; text: string; }
```

Serializable plain-text note anchored to a cell.

##### `CellPaintContext` — interface

```ts
export interface CellPaintContext { value: CellScalar; x: number; y: number; w: number; h: number; theme: Theme; style: CellStyle; }
```

Read-only cell value and screen geometry supplied to a custom renderer.

##### `CellRenderer` — interface

```ts
export interface CellRenderer { canvas?(ctx: CanvasRenderingContext2D, c: CellPaintContext): void; dom?(c: CellPaintContext): HTMLElement; update?(element: HTMLElement, c: CellPaintContext): void; destroy?(element: HTMLElement): void; }
```

Custom cell renderer hooks for the main-thread canvas or retained DOM overlay.

Members:
- `destroy` — Runs immediately before a retained element is removed or replaced.
- `dom` — Creates a fresh, detached element uniquely owned by one retained DOM cell.
- `update` — Updates a retained element after its value, style, theme, or geometry changes.

##### `CellScalar` — type

```ts
export type CellScalar = string | number | boolean | null;
```

A scalar that can be displayed directly.

##### `cellScalarToText` — function

```ts
(value: CellScalar): string
```

Spreadsheet display text for a resolved scalar.

##### `CellStyle` — interface

```ts
export interface CellStyle { bold?: boolean; italic?: boolean; underline?: boolean; strikethrough?: boolean; fontSize?: number; color?: string; backgroundColor?: string; align?: CellAlign; wrap?: boolean; border?: CellBorders; }
```

Serializable formatting applied to a cell or used as a column default.

Members:
- `align` — Horizontal placement of cell text within its column.
- `backgroundColor` — hex color, e.g. "#ffffff"
- `bold` — Uses the bold variant of the theme font.
- `border` — Border overrides for the cell's individual sides.
- `color` — hex color, e.g. "#111111"
- `fontSize` — Font size in unzoomed CSS pixels; zoom is applied during painting.
- `italic` — Uses the italic variant of the theme font.
- `strikethrough` — Draws a line through each rendered text run.
- `underline` — Draws a line beneath each rendered text run.
- `wrap` — Wraps text within the cell width; row auto-fit accounts for the resulting line count.

##### `CellValue` — type

```ts
export type CellValue = | { kind: "literal"; value: CellScalar } | { kind: "ref"; target: CellAddress } | { kind: "formula"; src: string };
```

A cell's persisted input: a literal, a cross-reference, or a formula.
References resolve through the store's reference graph; formulas resolve in
the WASM calculation engine.

##### `ChangeEvent` — interface

```ts
export interface ChangeEvent { transaction: Transaction; changes: CellChange[]; commitReason: CommitReason; source: OperationSource; epoch?: number; }
```

Payload of the `change` event; flows OUT for API submission/reconcile.

Members:
- `changes` — Cell-level before/after effects; empty for commits that only change metadata.
- `commitReason` — What produced this commit — see {@link CommitReason}.
- `epoch` — Store epoch after the commit; emitted store and grid changes include it.
- `source` — Remote input is observable but never belongs in outgoing local persistence.
- `transaction` — Operations that actually committed after policy and bounds filtering.

##### `colToA1` — function

```ts
(col: number): string
```

Column index (0-based) → A1 column label (0 → "A", 26 → "AA").

##### `Column` — interface

```ts
export interface Column { key: string; header: string; width: number; type: CellFormat; numberFormat?: string; numberLocale?: string; headerStyle?: CellStyle; cellStyle?: CellStyle; visible?: boolean; renderer?: string; editor?: string; }
```

Schema and default presentation for one workbook column.

Members:
- `cellStyle` — Base style merged beneath each cell's own style.
- `editor` — Name of a registered custom editor (see `GridOptions.editors`).
- `header` — Schema label used by table exports and data-grid presentation headers.
- `headerStyle` — Overrides theme styling for the painted column header.
- `key` — Non-empty key, unique within the sheet, used to map input and datasource values.
- `numberFormat` — Excel number-format code, e.g. "#,##0.00"
- `numberLocale` — Explicit BCP 47 locale for separators; omitted keeps the deterministic default.
- `renderer` — Name of a registered custom cell renderer (see `Grid.defineCellRenderer`).
- `type` — Controls cell input parsing and default value formatting for this column.
- `visible` — Set to `false` to exclude the column from the live view and table exports.
- `width` — Unzoomed column width in CSS pixels.

##### `ColumnarData` — interface

```ts
export interface ColumnarData { rowCount: number; columns: Record<string, ArrayLike<CellScalar | CellValue>>; }
```

Eager column-oriented values used to initialize a sheet.

##### `ColumnFilter` — type

```ts
export type ColumnFilter = | { kind: "values"; values: readonly CellScalar[] } | { kind: "contains"; text: string; matchCase?: boolean } | { kind: "compare"; op: "gt" | "gte" | "lt" | "lte" | "eq" | "neq"; value: number } | { kind: "empty" } | { kind: "nonEmpty" };
```

One column's filter predicate. All active column filters AND together;
matching is against the cell's resolved value (text or number).

##### `CommentAdapter` — interface

```ts
export interface CommentAdapter { listComments(documentId: string, signal?: AbortSignal): Promise<CommentListResult>; mutateComment(request: CommentMutationRequest): Promise<CommentMutationResponse>; subscribeComments?( documentId: string, listener: (event: VersionedCommentEvent) => void, signal?: AbortSignal, ): undefined | (() => void); }
```

Host persistence contract for versioned comment threads.

##### `CommentAnchor` — type

```ts
export type CommentAnchor = | { kind: "cell"; address: { sheet: string; row: number; col: number } } | { kind: "range"; range: Range };
```

Document location to which a comment thread is attached.

##### `CommentAuthorRef` — interface

```ts
export interface CommentAuthorRef { id: string; displayName?: string; avatarUrl?: string; }
```

Stable host-provided identity displayed on a comment message.

##### `CommentCoordinator` — class

```ts
class CommentCoordinator { constructor(adapter: CommentAdapter, options: CommentCoordinatorOptions); commentThreads: () => readonly CommentThread[]; create: (threadId: string, messageId: string, anchor: CommentAnchor, body: string, clientMutationId: string) => Promise<CommentMutationResponse>; destroy: () => void; load: () => Promise<readonly CommentThread[]>; mutate: (mutation: CommentMutation, clientMutationId: string) => Promise<CommentMutationResponse>; on: (listener: CommentListener) => () => void; reply: (threadId: string, messageId: string, body: string, clientMutationId: string) => Promise<CommentMutationResponse>; resolve: (threadId: string, resolved: boolean, clientMutationId: string) => Promise<CommentMutationResponse>; serverVersion: number }
```

Transport/auth-neutral comment state with server-owned author and timestamp fields.

##### `CommentCoordinatorEvent` — type

```ts
export type CommentCoordinatorEvent = | { type: "loaded"; version: number; threads: readonly CommentThread[] } | { type: "changed"; version: number; thread: CommentThread } | { type: "conflict"; currentVersion: number } | { type: "gap"; expectedVersion: number; receivedVersion: number } | { type: "error"; error: SheetwriteError };
```

State transition emitted by the comment coordinator.

##### `CommentCoordinatorOptions` — interface

```ts
export interface CommentCoordinatorOptions { documentId: string; serverVersion?: number; }
```

Document identity and initial version for comment coordination.

##### `CommentListResult` — interface

```ts
export interface CommentListResult { version: number; threads: readonly CommentThread[]; }
```

Versioned comment-thread listing returned by a host adapter.

##### `CommentMessage` — interface

```ts
export interface CommentMessage { id: string; author: CommentAuthorRef; body: string; createdAt: string; editedAt?: string; }
```

One immutable author message in a comment thread.

##### `CommentMutation` — type

```ts
export type CommentMutation = | { kind: "create"; threadId: string; messageId: string; anchor: CommentAnchor; body: string; } | { kind: "reply"; threadId: string; messageId: string; body: string } | { kind: "resolve"; threadId: string; resolved: boolean };
```

Serializable operation that creates or updates comment state.

##### `CommentMutationRequest` — interface

```ts
export interface CommentMutationRequest { documentId: string; baseVersion: number; clientMutationId: string; mutation: CommentMutation; signal?: AbortSignal; }
```

Versioned comment mutation submitted to a host adapter.

##### `CommentMutationResponse` — type

```ts
export type CommentMutationResponse = | { status: "applied"; version: number; clientMutationId: string; thread: CommentThread; } | { status: "duplicate"; version: number; clientMutationId: string } | { status: "conflict"; currentVersion: number };
```

Applied, duplicate, or conflict acknowledgement for a comment mutation.

##### `CommentThread` — interface

```ts
export interface CommentThread { id: string; documentId: string; anchor: CommentAnchor; version: number; messages: readonly CommentMessage[]; resolved: boolean; resolvedBy?: CommentAuthorRef; resolvedAt?: string; }
```

Versioned discussion anchored to a document location.

##### `CommitReason` — type

```ts
export type CommitReason = | "edit-blur" | "edit-enter" | "edit-tab" | "edit-programmatic" | "paste" | "cut" | "clear" | "fill" | "structure" | "style" | "replace" | "undo" | "redo" | "api";
```

The gesture/operation that produced a committed transaction. Consumers
switching on reasons MUST keep a default branch — the union grows with new
mutation features.

##### `ConditionalFormatPredicate` — type

```ts
export type ConditionalFormatPredicate = | { kind: "greaterThan"; value: number } | { kind: "lessThan"; value: number } | { kind: "equal"; value: CellScalar } | { kind: "contains"; text: string; matchCase?: boolean } | { kind: "formula"; source: string };
```

Predicate used to decide whether a conditional format applies.

##### `ConditionalFormatRule` — interface

```ts
export interface ConditionalFormatRule { range: Range; when: ConditionalFormatPredicate; style: CellStyle; stopIfTrue?: boolean; }
```

Ordered condition and style applied to a cell range.

Members:
- `stopIfTrue` — Stop evaluating lower-precedence rules for a cell when this rule matches.

##### `ContextMenuActionName` — type

```ts
export type ContextMenuActionName = | "cut" | "copy" | "paste" | "clearContents" | "merge" | "unmerge" | "insertRowAbove" | "insertRowBelow" | "deleteRow" | "insertColumnLeft" | "insertColumnRight" | "deleteColumn" | "hideRow" | "showAllRows" | "autoFitRow" | "hideColumn" | "showAllColumns" | "autoFitColumn" | "clearFilter" | "exportCsv" | "exportXlsx" | "separator";
```

Built-in action names accepted by custom context-menu rows.

##### `ContextMenuContext` — interface

```ts
export interface ContextMenuContext { readonly cell: CellAddress | null; readonly clientX: number; readonly clientY: number; }
```

Cell and viewport coordinates resolved for one bundled context-menu opening.

Members:
- `cell` — Right-clicked cell, or null when the pointer is outside the cell body.
- `clientX` — Viewport-relative browser pointer coordinate.
- `clientY` — Viewport-relative browser pointer coordinate.

##### `ContextMenuItem` — interface

```ts
export interface ContextMenuItem { id?: string; action?: ContextMenuActionName; onClick?: (grid: Grid, cell: CellAddress | null) => void; label?: string; shortcut?: string; visible?: boolean | ((context: ContextMenuContext) => boolean); disabled?: boolean | ((context: ContextMenuContext) => boolean); }
```

Built-in, separator, or custom callback row in the right-click menu.

Members:
- `action` — Built-in action to bind (or "separator"). Omit when supplying `onClick`.
- `disabled` — Static or context-aware disabled state.
- `id` — Stable host identifier, exposed as `data-context-menu-item`.
- `label` — Menu row text. Defaults per action.
- `onClick` — Custom click handler; receives the grid and the right-clicked cell (null if none).
- `shortcut` — Optional shortcut hint rendered beside the label.
- `visible` — Static or request-aware visibility. Hidden separators are normalized.

##### `ContextMenuItems` — type

```ts
export type ContextMenuItems = | readonly ContextMenuItem[] | ((context: ContextMenuContext) => readonly ContextMenuItem[]);
```

Static rows or a context-aware factory evaluated each time the menu opens.

##### `createGrid` — function

```ts
(host: HTMLElement, opts: GridOptions): Grid
```

Creates and mounts an imperative Grid in the supplied host element.

##### `createGridFromSnapshot` — function

```ts
(host: HTMLElement, snapshot: unknown, options?: SnapshotGridOptions): Grid
```

Mount a grid over a validated, non-dirty snapshot. The grid owns and disposes
the hydrated store just like one created through `createGrid`.

##### `createRowBridge` — function

```ts
<Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId>(options: RowBridgeOptions<Row, Id>): RowBridge<Id>
```

Create a typed bridge while preserving row and identity inference.

##### `createRuntimeResourceSnapshot` — function

```ts
(input: { operation: RuntimeResourceOperation; phase: RuntimeResourcePhase; wasm: StoreMemoryBreakdown; jsOwners?: readonly ResourceOwnerBytes[]; boundary?: readonly BoundaryOperationStats[]; runtime?: RuntimeMemoryObservation; }): RuntimeResourceSnapshot
```

Build and validate one operation-phase snapshot without double-counting runtime observations.

##### `DataCell` — type

```ts
export type DataCell = CellScalar | CellValue | { value: CellValue; style?: CellStyle };
```

Datasource cell value with optional cell-specific styling.

##### `DataSource` — interface

```ts
export interface DataSource { readonly capabilities: DataSourceCapabilities; getRows(request: DataSourceRequest): Promise<DataSourcePage>; }
```

Host callback that asynchronously loads cancellable rectangular pages.

Members:
- `getRows` — Loads the requested rows and columns; implementations should stop work when its signal aborts.

##### `DataSourceCapabilities` — interface

```ts
export interface DataSourceCapabilities { protocol: 2; columns: "windowed" | "full-width"; }
```

Declares whether a source can load only the requested column runs.

##### `DataSourceColumnBand` — interface

```ts
export interface DataSourceColumnBand { start: number; end: number; keys: readonly string[]; }
```

One half-open run of workbook columns, in stable sheet order.

Members:
- `end` — Exclusive workbook column index after the last key.
- `keys` — Stable workbook column keys for every index in `[start, end)`.
- `start` — Zero-based workbook column index of the first key.

##### `DataSourcePage` — interface

```ts
export interface DataSourcePage { protocol: 2; start: number; columns: readonly DataSourceColumnBand[]; rows: RowData[]; revision?: string | number; }
```

One resolved rectangular page returned by a DataSource.

Members:
- `columns` — Exact column runs represented by every returned row.
- `protocol` — Paging contract version.
- `start` — Inclusive row index of the first returned row.

##### `DataSourceRequest` — interface

```ts
export interface DataSourceRequest { protocol: 2; sheet: SheetId; start: number; end: number; columns: readonly DataSourceColumnBand[]; signal: AbortSignal; revision: number; }
```

Cancellable sheet rectangle requested from a DataSource.

Members:
- `columns` — Exact visible, frozen, or prefetched column runs required by the Grid.
- `end` — Exclusive row index.
- `protocol` — Paging contract version.
- `start` — Inclusive row index.

##### `DataSourceStorageOptions` — interface

```ts
export interface DataSourceStorageOptions { mode?: "dense" | "paged"; chunkRows?: number; cacheBytes?: number; dirtyCellLimit?: number; }
```

Dense or allocation-lazy paged storage policy for datasource cells.

Members:
- `cacheBytes` — Per-sheet clean-chunk cache budget; defaults to 32 MiB. Sparse local edits are accounted separately; dirty and visible chunks may exceed it.
- `chunkRows` — Paged row chunk size; defaults to 4,096 and is normalized to a power of two.
- `dirtyCellLimit` — Maximum sparse local edits retained outside the clean page cache. Defaults to 1,000,000.
- `mode` — Storage engine. Dense is the default.

##### `DataValidationComparison` — type

```ts
export type DataValidationComparison = | { operator: "between" | "notBetween"; min: number; max: number } | { operator: | "equal" | "notEqual" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual"; value: number; };
```

Native comparison semantics for numeric, date-serial, and text-length validation.
Interval operands are inclusive; `notBetween` accepts values outside that interval.

##### `DataValidationCondition` — type

```ts
export type DataValidationCondition = | { kind: "list"; values: readonly CellScalar[]; allowCustom?: boolean } | { kind: "number"; min?: number; max?: number; integer?: boolean; comparison?: DataValidationComparison; } | { kind: "date"; min?: number; max?: number; comparison?: DataValidationComparison } | { kind: "textLength"; min?: number; max?: number; comparison?: DataValidationComparison } | { kind: "checkbox"; checkedValue?: CellScalar; uncheckedValue?: CellScalar; };
```

Serializable condition enforced by a data-validation rule.

`min` and `max` remain inclusive legacy bounds. Use `comparison` when the
operator itself is significant; comparison and legacy bounds are mutually exclusive.

##### `DataValidationRule` — interface

```ts
export interface DataValidationRule { id: string; range: Range; condition: DataValidationCondition; policy: ValidationPolicy; allowBlank?: boolean; helpText?: string; }
```

One stable, range-scoped data-entry rule. Blank cells are allowed unless disabled.

##### `dateToSerial` — function

```ts
(date: Date): number
```

Convert a real UTC `Date` to the Excel 1900-system serial. It is the inverse
of {@link serialToDate} except for synthetic serial 60, which JavaScript
cannot represent as a Date. Construct calendar dates with `Date.UTC(...)`
(or via {@link parseDateInput}) to avoid host-timezone shifts.

##### `decodeStoreMemoryStats` — function

```ts
(encoded: ArrayLike<number>, wasmCommittedBytes: number | null): StoreMemoryBreakdown
```

Decode the flat Rust protocol and fail closed on version/order/total drift.

##### `DEFAULT_DELIMITED_TEXT_RESOURCE_LIMITS` — variable

```ts
Readonly<DelimitedTextResourceLimits>
```

Synchronous operations return one in-memory string, so byte/cell ceilings
bound allocation while sheet-compatible dimensions remain independently valid.

##### `DEFAULT_SNAPSHOT_RESOURCE_LIMITS` — variable

```ts
Readonly<SnapshotResourceLimits>
```

Conservative defaults that retain the million-row paged-sheet contract.

##### `DEFAULT_SYNC_COORDINATOR_LIMITS` — variable

```ts
Readonly<SyncCoordinatorLimits>
```

Security and durability defaults bound hostile remote versions, recovery
buffers, acknowledgement memory, and the offline pending queue independently.

##### `DEFAULT_THEME` — variable

```ts
Theme
```

Default canvas theme used before CSS and explicit theme overrides.

##### `DEFAULT_TRANSACTION_RESOURCE_LIMITS` — variable

```ts
Readonly<TransactionResourceLimits>
```

Inclusive defaults for every atomic document transaction accepted by a
Store or Grid. The count bounds object-heavy validation and dispatch; the
exact UTF-8 JSON size bounds hostile or accidentally oversized payloads.

##### `DEFAULT_WORKBOOK_TABLE_RESOURCE_LIMITS` — variable

```ts
Readonly<WorkbookTableResourceLimits>
```

Independent metadata ceilings enforced before table arrays cross the WASM boundary.

##### `DEFAULT_XLSX_RESOURCE_LIMITS` — variable

```ts
Readonly<XlsxResourceLimits>
```

Codec defaults combine SpreadsheetML worksheet dimensions with independent
ZIP/XML and aggregate-work ceilings for untrusted in-memory conversion.

##### `DelimitedTextOperation` — type

```ts
export type DelimitedTextOperation = "parse" | "import" | "encode" | "export";
```

Phase reported by a typed delimited-text resource failure.

##### `DelimitedTextOptions` — interface

```ts
export interface DelimitedTextOptions { resourceLimits?: Partial<DelimitedTextResourceLimits>; }
```

Optional resource ceilings for an in-memory delimited-text operation.

Members:
- `resourceLimits` — Positive safe-integer overrides merged over `DEFAULT_DELIMITED_TEXT_RESOURCE_LIMITS`.

##### `DelimitedTextOptionsError` — class

```ts
class DelimitedTextOptionsError extends SheetwriteError { constructor(resource: keyof DelimitedTextResourceLimits, value: unknown); name: "DelimitedTextOptionsError"; resource: keyof DelimitedTextResourceLimits; value: unknown }
```

Stable invalid-option failure for a delimited-text resource ceiling.

##### `DelimitedTextResourceError` — class

```ts
class DelimitedTextResourceError extends SheetwriteError { constructor(resource: keyof DelimitedTextResourceLimits, limit: number, actual: number, operation: DelimitedTextOperation); actual: number; limit: number; name: "DelimitedTextResourceError"; resource: keyof DelimitedTextResourceLimits }
```

Stable resource-limit failure raised before the next oversized parse or encode allocation.

##### `DelimitedTextResourceLimits` — interface

```ts
export interface DelimitedTextResourceLimits { maxInputBytes: number; maxOutputBytes: number; maxRows: number; maxColumns: number; maxCells: number; maxFieldBytes: number; maxWriterWindowRows: number; }
```

Resource ceilings shared by synchronous CSV and TSV parsing and encoding.

Members:
- `maxCells` — Aggregate fields across all records; defaults to 1,000,000.
- `maxColumns` — Fields in any one record; defaults to 16,384.
- `maxFieldBytes` — Decoded UTF-8 bytes in one field; defaults to 1 MiB.
- `maxInputBytes` — Input string size in UTF-8 bytes; defaults to 32 MiB.
- `maxOutputBytes` — Output string size in UTF-8 bytes, including a BOM; defaults to 64 MiB.
- `maxRows` — Syntactically present records; defaults to 1,000,000.
- `maxWriterWindowRows` — Rows fetched by an export writer in one packed store read; defaults to 4,096.

##### `diffRuntimeResourcePhases` — function

```ts
(before: RuntimeResourceSnapshot, after: RuntimeResourceSnapshot): RuntimeResourcePhaseDelta
```

Diff two validated phases of the same operation by exclusive resource owner.

##### `DocumentOp` — type

```ts
export type DocumentOp = | { op: "set"; addr: CellAddress; value: CellValue; style?: CellStyle } | { op: "setRange"; range: Range; cells: SnapshotCell[] } | { op: "setBlock"; range: Range; block: PackedCellBlock } | { op: "setRangeStyle"; range: Range; style: Partial<CellStyle> | null } | { op: "clearRange"; range: Range; contents?: boolean; style?: boolean } | { op: "addRows"; sheet: SheetId; at: number; count: number } | { op: "removeRows"; sheet: SheetId; at: number; count: number } | { op: "moveRows"; sheet: SheetId; from: number; count: number; to: number } | { op: "addColumns"; sheet: SheetId; at: number; columns: Column[] } | { op: "removeColumns"; sheet: SheetId; at: number; count: number } | { op: "moveColumns"; sheet: SheetId; from: number; count: number; to: number } | { op: "setColumn"; sheet: SheetId; col: number; patch: Partial<Column> } | { op: "setRowMeta"; sheet: SheetId; row: number; meta: RowMetadata | null } | { op: "addMerge"; sheet: SheetId; merge: MergeRange } | { op: "removeMerge"; sheet: SheetId; merge: MergeRange } | { op: "addSheet"; sheet: SheetSnapshot } | { op: "removeSheet"; sheet: SheetId } | { op: "renameSheet"; sheet: SheetId; name: string } | { op: "moveSheet"; sheet: SheetId; to: number } | { op: "setSheetVisibility"; sheet: SheetId; visibility: SheetVisibility } | { op: "addTable"; table: WorkbookTable } | { op: "updateTable"; sheet: SheetId; tableId: string; patch: WorkbookTablePatch } | { op: "removeTable"; sheet: SheetId; tableId: string } | { op: "setSheetMeta"; sheet: SheetId; patch: { frozenRows?: number; frozenCols?: number; conditionalFormats?: ConditionalFormatRule[]; rowGroups?: RowGroup[]; sortKeys?: SortKey[]; filters?: Array<[col: number, filter: ColumnFilter]>; }; } | { op: "setValidationRule"; sheet: SheetId; rule: DataValidationRule } | { op: "removeValidationRule"; sheet: SheetId; id: string } | { op: "setHyperlink"; sheet: SheetId; hyperlink: CellHyperlink } | { op: "removeHyperlink"; sheet: SheetId; id: string } | { op: "setProtectedRange"; sheet: SheetId; protectedRange: ProtectedRange } | { op: "removeProtectedRange"; sheet: SheetId; id: string } | { op: "setNote"; addr: CellAddress; text: string | null } | { op: "setNamedRange"; namedRange: NamedRangeSnapshot } | { op: "removeNamedRange"; name: string; scope?: SheetId };
```

Exhaustive serializable operation union for workbook mutations.

##### `documentOpTarget` — function

```ts
(operation: DocumentOp): string
```

Exhaustive stable target identity used by persistence/logging layers.

##### `DocumentRebaseResult` — type

```ts
export type DocumentRebaseResult = | { status: "rebased"; operations: readonly DocumentOp[] } | { status: "conflict"; conflict: RebaseConflict };
```

Successful rebased operations or a conservative rebase conflict.

##### `DocumentValidationError` — interface

```ts
export interface DocumentValidationError { path: string; code: | "unsupported-schema" | "invalid-value" | "duplicate-id" | "missing-reference" | "out-of-bounds" | "overlapping-merge" | "non-serializable" | "resource-limit"; message: string; }
```

Path-qualified validation failure for a document operation.

##### `DocumentValidationResult` — type

```ts
export type DocumentValidationResult = | { ok: true; value: WorkbookSnapshot } | { ok: false; errors: DocumentValidationError[] };
```

Success or structured errors returned by document validation.

##### `downloadBytes` — function

```ts
(bytes: Uint8Array | string, filename: string, mime: string): void
```

Trigger a browser download from in-memory bytes. The temporary anchor is
removed and its object URL is scheduled for revocation even when DOM append or
click throws.

##### `emptyStoreMemoryStats` — function

```ts
(wasmCommittedBytes: number | null): StoreMemoryBreakdown
```

Construct a zero-owner store report when no WASM store is available.

##### `formatNumber` — function

```ts
(value: number | string, code?: string, locale?: string): string
```

Deterministic Excel-style number/date formatter. Supports explicit locale
separators, percent/scientific notation, UTC date/time tokens, four-section
positive/negative/zero/text codes, quoted literals, and backslash escapes.

##### `fromCsv` — function

```ts
(text: string, columns: readonly Column[], options?: DelimitedTextOptions): ColumnarData
```

Parse CSV into `ColumnarData`. The first record is consumed as a positional
header. Input fields project onto declared visible columns; hidden declared
columns are initialized to `null`, matching the visible-column CSV export.
Extra fields are ignored and missing fields become `null`. The returned
columnar table is fully materialized in memory.

##### `fromXlsxTable` — function

```ts
(data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions): Promise<ColumnarData>
```

Parse the first sheet of `.xlsx` bytes into `ColumnarData`. The first parsed
row is treated as the header and its cell text becomes each column's key.
Numbers stay numbers, date cells use the date-serial convention, strings are
verbatim, and empty cells become `null`.

##### `fromXlsxWorkbook` — function

```ts
(data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions): Promise<WorkbookSnapshot>
```

Formula-preserving, multi-sheet workbook import through the optional XLSX backend.

##### `Grid` — interface

```ts
export interface Grid { readonly store: Store; readonly actions: GridActions; getRuntimeResourceSnapshot( operation: RuntimeResourceOperation, phase: RuntimeResourcePhase, runtime?: RuntimeMemoryObservation, ): RuntimeResourceSnapshot; getCommandState(command: GridCommandName): GridCommandState; setActiveSheet(id: SheetId): void; scrollToCell(addr: CellAddress): void; getCellAtPoint(clientX: number, clientY: number): CellAddress | null; getActiveSheet(): SheetId; getCellInput(row: number, col: number): CellInputSnapshot | null; getSelection(): Selection | null; setSelection(sel: Selection | null): void; setTheme(theme: Partial<Theme>): void; replaceTheme(theme: Partial<Theme> | undefined): void; getEffectiveTheme(): Theme; setReadOnly(readOnly: boolean): void; setConfig(config: GridConfig | undefined): void; applyTransaction(transaction: GridTransaction): ApplyTransactionResult; exportSnapshot(): WorkbookSnapshot; applyRemoteOperations( operations: readonly DocumentOp[], options?: RemoteOperationOptions, ): ApplyTransactionResult; defineCellRenderer(name: string, renderer: CellRenderer): void; aggregate(col: number, op: AggregateOp): number; sortBy(col: number, ascending?: boolean): void; sortByMulti(keys: readonly SortKey[]): void; filterBy(col: number, needle: string): void; setColumnFilter(col: number, filter: ColumnFilter | null): void; setSort(keys: readonly SortKey[]): ApplyTransactionResult; getColumnFilters(): ReadonlyMap<number, ColumnFilter>; distinctValues(col: number, limit?: number): CellScalar[]; hideRows(rows: readonly number[]): void; showRows(rows?: readonly number[]): void; hiddenRows(): readonly number[]; hideColumns(cols?: readonly number[]): void; showColumns(cols?: readonly number[]): void; hiddenColumns(): readonly number[]; groupRows(start: number, end: number): void; ungroupRows(start: number, end: number): void; setGroupCollapsed(start: number, collapsed: boolean): void; rowGroups(): readonly RowGroup[]; clearView(): void; undo(): void; redo(): void; exportCsv(filename: string): void; exportXlsx(filename: string): Promise<void>; search(query: string, opts?: SearchOptions): SearchResult; findNext(): SearchResult; findPrev(): SearchResult; clearSearch(): void; replaceCurrent(replacement: string): SearchResult; replaceAll(replacement: string): ReplaceResult; insertRows(at: number, count?: number): void; removeRows(at: number, count?: number): void; insertColumns(at: number, count?: number): void; removeColumns(at: number, count?: number): void; addSheet(input: AddSheetInput): SheetLifecycleResult; removeSheet(id: SheetId): SheetLifecycleResult; renameSheet(id: SheetId, name: string): SheetLifecycleResult; moveSheet(id: SheetId, toIndex: number): SheetLifecycleResult; setSheetVisibility(id: SheetId, visibility: SheetVisibility): SheetLifecycleResult; setConditionalFormats(rules: readonly ConditionalFormatRule[]): void; setHyperlink(hyperlink: CellHyperlink): ApplyTransactionResult; removeHyperlink(id: string): ApplyTransactionResult; getHyperlink(addr: CellAddress): CellHyperlink | null; activateHyperlink(addr: CellAddress): boolean; setValidationRule(rule: DataValidationRule): ApplyTransactionResult; removeValidationRule(id: string): ApplyTransactionResult; setProtectedRange(protectedRange: ProtectedRange): ApplyTransactionResult; removeProtectedRange(id: string): ApplyTransactionResult; setProtectionResolver(resolver: ProtectionResolver | undefined, mode?: MutationPolicyMode): void; setNote(addr: CellAddress, text: string | null): ApplyTransactionResult; getNote(addr: CellAddress): string | null; setOverscan(overscan?: number): void; setMinColumns(minColumns?: number): void; highlightCells(ranges: readonly HighlightRange[] | null, color?: string): void; setPresenceOverlays(overlays: readonly PresenceOverlay[] | null): void; styleRange(range: Range, style: Partial<CellStyle> | null): void; beginEdit(row: number, col: number, initial?: string, selectAll?: boolean): void; dataEdge(row: number, col: number, dRow: number, dCol: number): number | null; setRowHeight(row: number, height: number): void; setColumnWidth(col: number, width: number): void; autoFitRows(range?: Range): void; autoFitColumns(cols?: readonly number[]): void; setFrozen(rows: number, cols?: number): void; setZoom(zoom: number): void; getZoom(): number; rendererKind(): "canvas" | "worker"; on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void; refresh(): void; destroy(): void; }
```

Imperative grid handle for document commands, events, rendering, and teardown.

Members:
- `actions` — Imperative action surface for binding custom toolbars/menus.
- `activateHyperlink` — Validate and emit a host-owned activation event. External targets are never
opened by Sheetwrite; internal navigation occurs only under the explicit policy.
- `addSheet` — Add a sheet with a stable ID and return its actionable transaction outcome.
- `aggregate` — Column aggregate over the active sheet's data.
- `applyRemoteOperations` — Apply host-supplied operations without undo history or outgoing dirty state.
The resulting change event has `source: "remote"`.
- `applyTransaction` — Apply arbitrary patches as one undoable Grid commit. No-op when read-only.
Use `Store.applyTransaction` only for low-level writes that intentionally
bypass Grid history and policy.
- `autoFitColumns` — Explicitly resize columns from a bulk worksheet read.
- `autoFitRows` — Explicitly resize rows to fit wrapped content; never runs during paint.
- `beginEdit` — Open the cell editor at a view cell, optionally seeding text / selecting all.
- `clearSearch` — Clear the current search and its highlights.
- `clearView` — Clear any active sort/filter view.
- `dataEdge` — Ctrl+Arrow-style jump target: the data-run edge from (row, col) on the
moved axis (row for vertical moves, col for horizontal), or null when the
store is not columnar. Under an active sort/filter view, `row` is a view
position and vertical moves return view positions. For hosts building
their own keymaps (`config.keyboard`).
- `distinctValues` — Distinct resolved values of a column in first-seen order. Defaults to
1,000 values for bounded filter menus; pass 0 to request an uncapped scan.
- `exportSnapshot` — Deterministically export the complete authoritative workbook document.
- `filterBy` — Filter the displayed rows to those whose column text contains `needle`.
- `findNext` — Move the active match to the next match and scroll it into view.
- `findPrev` — Move the active match to the previous match and scroll it into view.
- `getActiveSheet` — Id of the currently visible sheet.
- `getCellAtPoint` — Resolve browser viewport coordinates to an active-sheet cell for host-owned
menus and interactions. Returns null outside the cell body.
- `getCellInput` — Editable snapshot of the cell at a view position on the active sheet, or
null when out of bounds. See {@link CellInputSnapshot}.
- `getColumnFilters` — Active column filters on the active sheet, keyed by column index.
- `getCommandState` — Query undo/redo availability and formatting active/mixed/disabled state.
- `getEffectiveTheme` — The effective (post-zoom) theme the renderer is currently painting with.
- `getRuntimeResourceSnapshot` — Versioned coarse runtime ownership snapshot, including datasource state.
- `groupRows` — Define a collapsible row group over a data-row range (end-inclusive).
- `hiddenColumns` — Currently hidden columns on the active sheet.
- `hiddenRows` — Currently hidden data rows on the active sheet.
- `hideColumns` — Hide columns through one bulk-safe metadata transaction.
- `hideRows` — Hide the given data rows (composes with filters/sort).
- `highlightCells` — Highlight arbitrary cell ranges (null clears). Per-range `color` wins over the call color.
- `redo` — Redo the last undone cell edit.
- `removeSheet` — Remove a sheet while preserving at least one visible worksheet.
- `rendererKind` — Which renderer is actually active: `"worker"` when the OffscreenCanvas
worker constructed successfully, `"canvas"` otherwise (including after a
`renderer-fallback`).
- `replaceAll` — Replace every current match in a single undoable transaction (one
`undo()` restores them all), then re-scan. Formula/ref cells are skipped
and not counted. No-op when read-only.
- `replaceCurrent` — Replace the active match with `replacement`, then advance to the next match
(re-scanning against the new data). Only literal text/number cells are
eligible; formula and ref cells are skipped (formula source is never
rewritten). Honors the active {@link SearchOptions} (matchCase; `wholeCell`
swaps the entire cell). The write flows through the grid's commit path as
one undoable step. No-op when read-only or when there is no active match.
- `replaceTheme` — Option-level replacement: re-run construction-time resolution
(`DEFAULT_THEME < CSS custom properties < theme`) with the new partial.
`undefined` restores the CSS-variable/default resolution. Adapters call
this for their declarative `theme` prop; imperative patching stays on
{@link setTheme}.
- `rowGroups` — Row groups on the active sheet.
- `search` — Find cells matching `query`; highlights matches, emits `search`, returns the result.
- `setColumnFilter` — Set or clear (null) one column's filter. All column filters AND together
and compose with the active sort and hidden rows.
- `setColumnWidth` — Set one column's width via an undoable `setColumn` patch.
- `setConfig` — Reconfigure built-in chrome and keyboard handling without replacing the
Grid or clearing selection/history. Construction-bound GridOptions are not
accepted here.
- `setFrozen` — Pin the first `rows` view rows and `cols` columns; they stay visible while
the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.
- `setGroupCollapsed` — Collapse/expand a row group; collapsing hides its rows.
- `setMinColumns` — Live-update the minimum rendered column count. Increasing the minimum
silently extends presentation padding; `undefined` restores the default.
- `setOverscan` — Live-update the render window overscan (row/column positions painted past
each edge); `undefined` restores the default of 6.
- `setPresenceOverlays` — Replace ephemeral remote-presence overlays; null clears every collaborator.
- `setReadOnly` — Update editability without replacing the Grid or clearing session state.
- `setRowHeight` — Set one row's persistent display height through document history.
- `setSheetVisibility` — Set host-visible worksheet state; stock UI never offers `veryHidden`.
- `setSort` — Persisted multi-key sort of the active sheet.
- `setTheme` — Imperative patch: merge `theme` into the accumulated base theme.
- `setZoom` — Content zoom factor (0.5–2): scales row/column geometry and fonts.
- `showColumns` — Show columns through one bulk-safe metadata transaction.
- `showRows` — Show the given data rows again, or every hidden row when omitted.
- `sortBy` — Sort the displayed rows by a column (does not mutate stored data).
- `sortByMulti` — Multi-key sort of the displayed rows (first key primary; stable).
- `styleRange` — Merge `style` into every cell of `range` (null clears cell styles) as one
undoable transaction. Styles land in the store and paint in the canvas —
unlike {@link highlightCells}, which draws a translucent overlay above it.
- `undo` — Undo the last recorded cell edit.
- `ungroupRows` — Remove a row group (rows become visible if the group was collapsed).

##### `GridActions` — interface

```ts
export interface GridActions { toggleBold(): void; toggleItalic(): void; toggleUnderline(): void; toggleStrikethrough(): void; setAlign(align: CellAlign): void; setTextColor(color: string): void; setFillColor(color: string): void; toggleBorder(): void; clearFormat(): void; merge(): void; unmerge(): void; sort(ascending: boolean): void; insertRowAbove(): void; insertRowBelow(): void; deleteRow(): void; insertColumnLeft(): void; insertColumnRight(): void; deleteColumn(): void; hideRows(rows?: readonly number[]): void; showRows(rows?: readonly number[]): void; autoFitRows(): void; hideColumns(cols?: readonly number[]): void; showColumns(cols?: readonly number[]): void; autoFitColumns(cols?: readonly number[]): void; clearFilter(col?: number): void; copy(): Promise<ClipboardOutcome>; cut(): Promise<ClipboardOutcome>; paste(): Promise<ClipboardOutcome>; pasteValues(): Promise<ClipboardOutcome>; clearContents(): void; exportCsv(filename?: string): void; exportXlsx(filename?: string): void; undo(): void; redo(): void; }
```

Imperative operations the toolbar and context menu bind to; also exposed as `Grid.actions`.

Members:
- `copy` — Copy the focused rectangle to the system clipboard. Never rejects.
- `cut` — Copy + clear the source (after the clipboard accepted). Never rejects.
- `paste` — Paste at the focus cell. Never rejects.
- `pasteValues` — Paste keeping only resolved values — no formulas, no styles (Ctrl+Shift+V). Never rejects.

##### `GridCommandName` — type

```ts
export type GridCommandName = Exclude<ToolbarActionName, "separator">;
```

Built-in command names accepted by state queries and change events.

##### `GridCommandState` — interface

```ts
export interface GridCommandState { readonly disabled: boolean; readonly activity: "inactive" | "active" | "mixed"; }
```

Observable availability and selection-derived activity for one command.

##### `GridCommandStateChangeEvent` — interface

```ts
export interface GridCommandStateChangeEvent { readonly states: Readonly<Record<GridCommandName, GridCommandState>>; }
```

Complete command-state snapshot emitted whenever availability or activity can change.

##### `GridConfig` — interface

```ts
export interface GridConfig { toolbar?: boolean | ToolbarItem[]; bold?: boolean; italic?: boolean; align?: boolean; textColor?: boolean; fillColor?: boolean; border?: boolean; clearFormat?: boolean; merge?: boolean; sort?: boolean; export?: boolean; icons?: Partial<Record<ToolbarActionName, ToolbarIcon>>; contextMenu?: boolean | ContextMenuItems; undo?: boolean; find?: boolean; tabs?: boolean; keyboard?: boolean | ((e: KeyboardEvent, grid: Grid) => boolean); }
```

Toolbar / feature configuration. When `config` is set the built-in toolbar is
shown; control flags default to `true` except the opt-in `export` flag.

Members:
- `align` — Show left, center, and right alignment controls (default true).
- `bold` — Show the bold control in the default toolbar (default true).
- `border` — Show the border control in the default toolbar (default true).
- `clearFormat` — Show the clear-format control in the default toolbar (default true).
- `contextMenu` — Built-in menu, disabled menu, static rows, or a request-aware row factory.
- `export` — Show CSV/XLSX export controls in the default toolbar (default false).
- `fillColor` — Show the fill-color control in the default toolbar (default true).
- `find` — Built-in Ctrl+F find widget: enabled (true, default) or disabled (false).
- `icons` — Override built-in toolbar icons by action name. Strings render as plain text; DOM nodes/factories support SVG/HTML icons.
- `italic` — Show the italic control in the default toolbar (default true).
- `keyboard` — Built-in keyboard handling. `true` (default) keeps the stock Sheets-style
bindings (navigation, type-to-edit, clipboard, undo/redo, find). `false`
disables ALL of them — the host owns key events and drives `grid.actions`,
selection, editing, and search primitives itself. A function is consulted
first and consumes the event by returning `true`; returning `false` falls
through to the stock bindings.
- `merge` — Show merge and unmerge controls in the default toolbar (default true).
- `sort` — Show ascending and descending sort controls in the default toolbar (default true).
- `tabs` — Bottom sheet-tab bar for multi-sheet workbooks (default true).
- `textColor` — Show the text-color control in the default toolbar (default true).
- `toolbar` — Show the built-in toolbar (true), hide it (false), or supply a custom item list.
- `undo` — Show undo/redo controls in the built-in toolbar (default true).

##### `GridEvents` — interface

```ts
export interface GridEvents { change: ChangeEvent; selection: { selection: Selection | null }; scroll: { scrollTop: number; firstRow: number; lastRow: number; scrollLeft: number; firstVisibleColumn: number | null; lastVisibleColumn: number | null; }; "edit-begin": { addr: CellAddress }; "edit-commit": { addr: CellAddress; value: CellValue }; search: SearchResult; "command-state-change": GridCommandStateChangeEvent; "mutation-rejected": { issues: MutationIssue[] }; "active-sheet": { sheet: SheetId }; "hyperlink-activate": HyperlinkActivationEvent; "renderer-fallback": { requested: "worker"; error: SheetwriteError }; "datasource-error": { request: Omit<DataSourceRequest, "signal">; error: SheetwriteError; }; "export-error": { format: "xlsx"; error: SheetwriteError }; }
```

Payload map for events emitted by a Grid.

Members:
- `active-sheet` — Emitted after the visible sheet changes (direct call or cross-sheet scroll).
- `command-state-change` — Command availability or formatting activity changed.
- `export-error` — Built-in toolbar/context-menu export failed after its action was dispatched.
- `renderer-fallback` — Emitted once when the worker renderer could not be constructed and the
grid fell back to the main-thread canvas renderer.

##### `GridOptions` — interface

```ts
export interface GridOptions { workbook: Workbook; data?: ColumnarData; datasource?: DataSource; datasourceStorage?: DataSourceStorageOptions; renderer?: "canvas" | "worker"; workerUrl?: string | URL; presentation?: GridPresentation; theme?: Partial<Theme>; readOnly?: boolean; hyperlinkActivation?: "event-only" | "internal-navigation" | "disabled"; protectionResolver?: ProtectionResolver; mutationPolicy?: MutationPolicyMode; transactionResourceLimits?: Partial<TransactionResourceLimits>; renderers?: Record<string, CellRenderer>; editors?: Record<string, CellEditor>; overscan?: number; minColumns?: number; config?: GridConfig; }
```

Workbook, data, rendering, policy, and built-in UI options used to create a Grid.

Members:
- `config` — Built-in UI controls; providing an object enables the toolbar unless `toolbar` is false.
- `data` — Eager column-major values loaded into `workbook.activeSheet`; use instead of `datasource`.
- `datasource` — Lazy row provider requested for visible windows; use instead of eager `data`.
- `datasourceStorage` — Allocation and cache policy for datasource-backed cell storage.
- `editors` — Named custom editors resolved from each column's `editor` field.
- `hyperlinkActivation` — Hyperlink activation never opens a browser URL. `event-only` (default)
emits a safe resolved target; `internal-navigation` additionally moves to
stable internal destinations; `disabled` rejects every activation request.
- `minColumns` — Render at least this many columns (empty padding columns past the data, like a spreadsheet).
- `mutationPolicy` — Atomic rejects the transaction; partial skips denied operation objects.
- `overscan` — Extra row and visible-column positions painted on each viewport edge.
Defaults to 6; use 0 to disable the buffer.
- `presentation` — Header presentation. Spreadsheet mode (default) paints positional A/B/C
labels; data-grid mode paints each column's semantic `header`. Cell
addressing, row indices, clipboard values, formulas, and exports are
unchanged in both modes.
- `protectionResolver` — Host-owned client UX permission check. Servers must independently authorize
every submitted operation; this resolver is not an authentication boundary.
- `readOnly` — Disables mutating interactions while preserving navigation and selection.
- `renderer` — Paint backend; defaults to main-thread `canvas` and falls back there if a worker fails.
- `renderers` — Custom cell renderers registered up front; also see `Grid.defineCellRenderer`.
- `theme` — Overrides merged over the default theme and host CSS custom properties.
- `transactionResourceLimits` — Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
- `workbook` — Live workbook schema adopted by the store and updated by document operations.
- `workerUrl` — URL of the worker renderer module (`renderer: "worker"`), as served to the
BROWSER — the platform `Worker` constructor does not consult package
exports, so a bare specifier like `new URL("@sheetwrite/core/worker",
import.meta.url)` is NOT reliable. Either copy
`@sheetwrite/core/dist/worker.js` to your public assets and pass its URL
string (works everywhere), or use your bundler's dependency-worker import
if it has one (see `/docs/guides/worker-rendering/`). If omitted or the worker
can't be constructed, the grid falls back to the main-thread canvas
renderer and emits `renderer-fallback` once.

##### `GridPresentation` — type

```ts
export type GridPresentation = "spreadsheet" | "data-grid";
```

Header semantics used by the retained canvas and accessibility mirror.

##### `GridTransaction` — interface

```ts
export interface GridTransaction { patches: DocumentOp[]; }
```

An undoable transaction submitted through a Grid.

Grid transactions deliberately have no epoch: optimistic reconciliation is
a low-level Store concern, while Grid commits are normal host-driven edits
that participate in read-only policy and undo/redo history.

##### `HighlightRange` — interface

```ts
export interface HighlightRange { color?: string; sheet: SheetId; start: { row: number; col: number }; end: { row: number; col: number }; }
```

A highlight target: a range plus an optional per-range color override.

Members:
- `color` — Overrides the call-level `color` / theme highlight for this range only.

##### `hyperlinkAt` — function

```ts
(workbook: Workbook, address: CellAddress): CellHyperlink | null
```

Return the first validated hyperlink covering an address, or null when none does.

##### `HyperlinkTarget` — type

```ts
export type HyperlinkTarget = | { kind: "external"; url: string } | { kind: "internal"; range: Range };
```

Browser-safe external target or stable workbook-internal range target.

##### `IncompleteDataError` — class

```ts
class IncompleteDataError extends SheetwriteError { constructor(sheet: SheetId, capability: Extract<QueryCapability, { status: "incomplete"; }>); capability: { status: "incomplete"; loadedCells: number; totalCells: number; }; name: "IncompleteDataError" }
```

Error thrown when an operation requires datasource cells that are not loaded.

##### `initSheetwrite` — function

```ts
(source?: BufferSource | URL | string | Request | WebAssembly.Module): Promise<void>
```

Load the WASM data engine once. Must be awaited before `createGrid`.

##### `isSafeExternalHyperlink` — function

```ts
(url: string): boolean
```

Validate, but never activate or fetch, an external hyperlink target.

##### `isSheetwriteError` — function

```ts
(value: unknown): value is SheetwriteErrorEnvelope
```

Narrow same-realm errors, cross-realm errors, and serialized failure envelopes.

##### `isSheetwriteReady` — function

```ts
(): boolean
```

Whether `initSheetwrite` has completed — the single readiness source.

##### `isValidCellHyperlink` — function

```ts
(value: unknown): value is CellHyperlink
```

Shape/security validation shared by mutation, snapshot, clipboard, and activation barriers.

##### `isValidHyperlinkId` — function

```ts
(id: string): boolean
```

Whether an identifier is bounded, non-empty, trimmed, and free of control characters.

##### `labelToCol` — function

```ts
(label: string): number
```

A1 column label → 0-based column index (inverse of {@link colToA1}).

##### `legacyFullWidthDataSource` — function

```ts
(loadRows: LegacyRowLoader): DataSource
```

Adapts a row loader to protocol 2; full-width loading is horizontally non-scalable.

##### `LegacyRowLoader` — type

```ts
export type LegacyRowLoader = ( request: DataSourceRequest, ) => Promise<LegacyRowPage> | LegacyRowPage;
```

Loads one row-only page for the full-width compatibility adapter.

##### `LegacyRowPage` — interface

```ts
export interface LegacyRowPage { readonly start: number; readonly rows: readonly RowData[]; }
```

Row-only page shape accepted by the full-width compatibility adapter.

##### `MAX_CONDITIONAL_FORMAT_FORMULA_LENGTH` — variable

```ts
8192
```

Maximum serialized formula predicate source; parsing/evaluation stays bounded per visible cell.

##### `MAX_CONDITIONAL_FORMAT_RULES` — variable

```ts
32
```

Maximum ordered conditional-format rules admitted per worksheet and encoded in one u32 match mask.

##### `MAX_HYPERLINK_DISPLAY_LENGTH` — variable

```ts
32767
```

Optional display text ceiling used by SpreadsheetML shared-string implementations.

##### `MAX_HYPERLINK_ID_LENGTH` — variable

```ts
128
```

Serialized identifier ceiling; IDs remain stable across history and snapshots.

##### `MAX_HYPERLINK_TARGET_LENGTH` — variable

```ts
2048
```

External target ceiling, aligned with the bounded private clipboard payload.

##### `MAX_HYPERLINKS_PER_SHEET` — variable

```ts
4096
```

Renderer/codec ceiling for one sheet's hyperlink metadata.

##### `MemoryPersistenceAdapter` — class

```ts
class MemoryPersistenceAdapter implements PersistenceAdapter { constructor(...snapshots: readonly WorkbookSnapshot[]); commit: (request: PersistenceCommitRequest) => Promise<PersistenceCommitResponse>; load: (documentId: string, signal?: AbortSignal) => Promise<WorkbookSnapshot> }
```

Executable database-neutral reference adapter for tests, demos, and local workflows.

##### `MergeRange` — interface

```ts
export interface MergeRange { r0: number; c0: number; r1: number; c1: number; }
```

Inclusive merged-cell rectangle in data-row/column coordinates.

##### `MutationIssue` — type

```ts
export type MutationIssue = | { kind: "validation"; severity: "error" | "warning"; ruleId: string; addr: CellAddress; value: CellValue; message: string; operationIndex: number; } | { kind: "protection"; severity: "error"; protectedRangeId: string; range: Range; operationIndex: number; message: string; } | { kind: "invalid-operation"; severity: "error"; operationIndex: number; message: string; } | { kind: "resource-limit"; severity: "error"; resource: | "operations" | "encoded-bytes" | "pending-commits" | "pending-operations" | "pending-encoded-bytes" | "paged-dirty-cells" | "paged-reference-simulation"; actual: number; max: number; message: string; } | { kind: "sheet-lifecycle"; severity: "error"; code: SheetLifecycleIssueCode; sheet?: SheetId; operationIndex: number; message: string; };
```

Structured warning or rejection produced while applying an operation.

##### `MutationPolicyMode` — type

```ts
export type MutationPolicyMode = "atomic" | "partial";
```

Atomic or partial handling for locally denied operations.

##### `NamedRangeSnapshot` — interface

```ts
export interface NamedRangeSnapshot { name: string; scope?: SheetId; range: Range; }
```

Workbook-global or sheet-scoped named range used by formulas and persistence.

Members:
- `scope` — Formula-context sheet whose local definition shadows the workbook definition.

##### `observeRuntimeMemory` — function

```ts
(): RuntimeMemoryObservation
```

Observe runtime memory buckets available in the current JS host without fabricating missing data.

##### `OperationSource` — type

```ts
export type OperationSource = "local" | "remote";
```

Whether a committed change originated locally or from remote host input.

##### `PackedCellBlock` — interface

```ts
export interface PackedCellBlock { rowCount: number; colCount: number; values: CellScalar[]; formulas?: Array<[offset: number, source: string]>; refs?: Array<[offset: number, target: CellAddress]>; styleTable?: CellStyle[]; styleIds?: number[]; }
```

Dense row-major mutation payload. Primitive arrays keep large paste/fill
operations JSON-safe without allocating one operation object per cell.
Formula/reference tuples are sparse exceptions keyed by row-major offset.

##### `PagedStoreStats` — interface

```ts
export interface PagedStoreStats { chunks: number; loadedCells: number; dirtyCells: number; allocatedBytes: number; dirtyAllocatedBytes: number; fullyLoaded: boolean; }
```

Allocation and load statistics for one paged datasource sheet.

Members:
- `dirtyAllocatedBytes` — Sparse local-edit overlay bytes, excluded from the clean chunk cache budget.

##### `parseCellInput` — function

```ts
(raw: string, type: CellFormat): CellValue
```

Coerce raw text input into a {@link CellValue}, following spreadsheet
input-bar conventions:

- blank (after trimming) clears the cell to a `null` literal;
- text longer than one character beginning with `=` becomes a formula;
- in a `number` column a finite numeric string becomes a number literal;
- in a `date` column a recognized date string ({@link parseDateInput}) becomes
 its serial-number literal;
- in a `currency` column a currency string ({@link parseCurrencyInput}) becomes
 a plain number literal;
- anything else is stored verbatim as a text literal (the untrimmed `raw`).

Shared by the grid's inline editor and any host-built formula bar, so input
parsing is identical everywhere instead of re-derived per consumer.

##### `parseCellLiteralInput` — function

```ts
(raw: string, type: CellFormat): CellScalar
```

Parse imported text as a literal using the same boolean, number, date, and
currency rules as {@link parseCellInput}. Unlike interactive entry, a leading
`=` remains inert text. Declared date columns also accept an existing finite
date serial so delimited export/import preserves numeric dates.

##### `parseCsv` — function

```ts
(text: string, options?: DelimitedTextOptions): string[][]
```

Parse the fixed comma dialect: quoted delimiters/newlines, doubled quotes,
bare CR, LF, or CRLF records, Unicode, trailing empty fields, and one optional
leading UTF-8 BOM. The synchronous API consumes an existing in-memory string
and returns an in-memory grid; it does not claim streaming. Scanning enforces
resource ceilings before materializing the next oversized field or record.

##### `parseCurrencyInput` — function

```ts
(raw: string): number | null
```

Parse a currency-formatted string into a plain number, or `null` when the
remaining text is not numeric. Strips currency symbols (`$ € £ ¥ ¤`), thousands
grouping (`,`), and whitespace, and reads accounting-style parentheses
(`(1,234.50)`) as a negative amount. Grouping/decimals follow the US locale the
renderer uses.

##### `parseDateInput` — function

```ts
(raw: string): number | null
```

Parse a user-typed date string into a serial, or `null` when it is not a date.
Accepted forms:

- ISO `yyyy-mm-dd` (e.g. `2026-07-06`);
- ISO date-time `yyyy-mm-dd hh:mm` or `yyyy-mm-dd hh:mm:ss` (a `T` separator is
 also accepted); the fractional serial carries the time;
- slash `dd/mm/yyyy` and `mm/dd/yyyy`, disambiguated **conservatively**: if one
 component exceeds 12 it must be the day and the layout is unambiguous; when
 both are ≤ 12 the value is ambiguous (e.g. `04/05/2026`) and is read as
 **mm/dd** — Google Sheets' default (US) locale. Both > 12 is rejected.

Anything else (bare numbers, free text) returns `null` so callers can fall back
to a text literal.

##### `PendingCommit` — interface

```ts
export interface PendingCommit { documentId: string; baseVersion: number; clientMutationId: string; readonly operations: readonly DocumentOp[]; }
```

Immutable local operation batch awaiting a host acknowledgement.

##### `PendingCommitLoadOptions` — interface

```ts
export interface PendingCommitLoadOptions { signal?: AbortSignal; maxRecords: number; maxOperations: number; maxBytes: number; }
```

Mandatory bounds for one durable pending-commit restore.

Members:
- `maxBytes` — Maximum aggregate UTF-8 bytes of the JSON-encoded operation arrays.
- `maxOperations` — Maximum aggregate operation count returned for one document queue.
- `maxRecords` — Maximum records returned for one document queue.

##### `PendingCommitStorage` — interface

```ts
export interface PendingCommitStorage { load(documentId: string, options: PendingCommitLoadOptions): Promise<readonly PendingCommit[]>; put(commit: PendingCommit, signal?: AbortSignal): Promise<void>; remove(documentId: string, clientMutationId: string, signal?: AbortSignal): Promise<void>; replace( documentId: string, expectedClientMutationIds: readonly string[], commits: readonly PendingCommit[], signal?: AbortSignal, ): Promise<void>; }
```

Host-owned durable queue. Browser storage lives in the optional `./browser` entrypoint.

Members:
- `replace` — Atomically replaces one document queue only if its ordered IDs still match
the caller's expected view.

##### `PersistenceAdapter` — interface

```ts
export interface PersistenceAdapter { load(documentId: string, signal?: AbortSignal): Promise<WorkbookSnapshot>; commit(request: PersistenceCommitRequest): Promise<PersistenceCommitResponse>; }
```

Host load and commit contract for versioned workbook persistence.

##### `PersistenceCommitRequest` — interface

```ts
export interface PersistenceCommitRequest { signal?: AbortSignal; documentId: string; baseVersion: number; clientMutationId: string; readonly operations: readonly DocumentOp[]; }
```

Cancellable pending commit submitted to a persistence adapter.

##### `PersistenceCommitResponse` — type

```ts
export type PersistenceCommitResponse = | { status: "applied"; version: number; clientMutationId: string } | { status: "duplicate"; version: number; clientMutationId: string } | { status: "conflict"; currentVersion: number; operationsSinceBase?: readonly VersionedOperation[]; snapshot?: WorkbookSnapshot; };
```

Applied, duplicate, or conflict acknowledgement from persistence. `applied`
confirms the submitted operations unchanged; normalization must conflict.

##### `PersistenceError` — class

```ts
class PersistenceError extends SheetwriteError { constructor(code: PersistenceErrorCode, message: string, options?: ErrorOptions); name: "PersistenceError" }
```

Typed failure raised by persistence and synchronization flows.

##### `PersistenceErrorCode` — type

```ts
export type PersistenceErrorCode = | "aborted" | "invalid-snapshot" | "resource-limit" | "not-found" | "commit-rejected";
```

Stable category for a persistence failure.

##### `PresenceActor` — interface

```ts
export interface PresenceActor { id: string; displayName?: string; color?: string; }
```

Public collaborator identity attached to presence updates.

##### `PresenceCoordinator` — class

```ts
class PresenceCoordinator { constructor(grid: Grid, transport: PresenceTransport, options: PresenceCoordinatorOptions); destroy: () => void; on: (listener: PresenceListener) => () => void; pruneStale: () => void; publishNow: () => Promise<void>; remotePresence: () => readonly PresenceMessage[] }
```

Ephemeral presence lifecycle; it never calls a document mutation API.

##### `PresenceCoordinatorEvent` — type

```ts
export type PresenceCoordinatorEvent = | { type: "published"; message: PresenceMessage } | { type: "updated"; actorId: string } | { type: "expired"; actorId: string } | { type: "error"; error: SheetwriteError };
```

Connection or actor transition emitted by presence coordination.

##### `PresenceCoordinatorOptions` — interface

```ts
export interface PresenceCoordinatorOptions { actor: PresenceActor; privacy?: PresencePrivacyOptions; heartbeatMs?: number; timeoutMs?: number; maxActors?: number; maxRangesPerActor?: number; now?: () => number; }
```

Identity, privacy, and timing options for presence coordination.

Members:
- `heartbeatMs` — Publish/prune interval in milliseconds; defaults to 15,000. Use 0 to disable the timer.
- `maxActors` — Remote actors retained at once; defaults to 32 and is clamped to at least 1.
- `maxRangesPerActor` — Selection ranges sent or accepted per actor; defaults to 8 and is clamped to at least 1.
- `timeoutMs` — Idle receipt time before a remote actor expires; defaults to 45,000 milliseconds.

##### `PresenceMessage` — interface

```ts
export interface PresenceMessage { actor: PresenceActor; activeSheet: string; selections: readonly Range[]; sentAt: number; }
```

Ephemeral collaborator selection and activity update.

##### `PresenceOverlay` — interface

```ts
export interface PresenceOverlay { actorId: string; displayName?: string; color: string; activeSheet: SheetId; ranges: readonly Range[]; }
```

Ephemeral collaborator selection rendered above the grid. Presence never
enters document operations, snapshots, dirty state, or undo history.

##### `PresencePrivacyOptions` — interface

```ts
export interface PresencePrivacyOptions { shareDisplayName?: boolean; shareSelection?: boolean; receivePresence?: boolean; allowActor?: (actor: Readonly<PresenceActor>) => boolean; }
```

Controls which ephemeral collaborator details may be transmitted.

##### `PresenceTransport` — interface

```ts
export interface PresenceTransport { publish(message: PresenceMessage, signal?: AbortSignal): void | Promise<void>; subscribe( listener: (message: PresenceMessage) => void, signal?: AbortSignal, ): undefined | (() => void); }
```

Host transport contract for ephemeral presence messages.

##### `ProtectedRange` — interface

```ts
export interface ProtectedRange { id: string; range: Range; label?: string; permissionKey?: string; }
```

Serializable client UX policy. A host resolver decides whether a local mutation may proceed.

##### `ProtectionRequest` — interface

```ts
export interface ProtectionRequest { protectedRange: Readonly<ProtectedRange>; operation: Readonly<DocumentOp>; commitReason: CommitReason; }
```

Local operation and protected-range context supplied to the host policy.

##### `ProtectionResolver` — type

```ts
export type ProtectionResolver = (request: ProtectionRequest) => "allow" | "deny";
```

Host-owned client UX permission callback for protected mutations.

##### `QueryCapability` — type

```ts
export type QueryCapability = | { status: "complete" } | { status: "incomplete"; loadedCells: number; totalCells: number };
```

Whether a query is complete for the currently loaded datasource pages.

##### `Range` — interface

```ts
export interface Range { sheet: SheetId; start: { row: number; col: number }; end: { row: number; col: number }; }
```

Inclusive rectangular cell range on a stable sheet ID.

##### `rangeA1` — function

```ts
(a: CellRef, b: CellRef): string
```

Two cell corners → A1 range ("A1:B3"), collapsing to a single ref when equal.

##### `RebaseConflict` — interface

```ts
export interface RebaseConflict { code: RebaseConflictCode; localOperationIndex: number; remoteOperationIndex: number; message: string; }
```

Reason and affected operations for an unsafe document rebase.

##### `RebaseConflictCode` — type

```ts
export type RebaseConflictCode = | "overlapping-edit" | "sheet-removed" | "sheet-lifecycle" | "formula-structural" | "structural-overlap" | "unsupported-structural";
```

Stable conservative-rebase conflict category.

##### `rebaseDocumentOperations` — function

```ts
(localOperations: readonly DocumentOp[], remoteOperations: readonly DocumentOp[]): DocumentRebaseResult
```

Conservative server-ordered rebase for pending offline work. Non-overlapping
literal edits are shifted across row/column insertion and deletion. Ambiguous
formula, overlapping, sheet-lifecycle, and move cases become explicit
conflicts instead of lossy guesses. This is the collaboration design gate;
no CRDT dependency is required for the supported cases.

##### `REF_CYCLE` — variable

```ts
"#CYCLE!"
```

Sentinel shown for a reference that participates in a cycle.

##### `RemoteOperationOptions` — interface

```ts
export interface RemoteOperationOptions { commitReason?: CommitReason; localReplay?: boolean; }
```

Classification metadata for host-supplied remote operations.

Members:
- `localReplay` — Reapply a durable local mutation as dirty pending state rather than authoritative remote data.

##### `RemoteOperationSource` — interface

```ts
export interface RemoteOperationSource { subscribe( listener: (operation: VersionedOperation) => void | Promise<void>, signal?: AbortSignal, ): undefined | (() => void); }
```

Host subscription contract for ordered versioned operations. Sources that
can pause intake should await the listener promise to preserve backpressure.

##### `ReplaceResult` — interface

```ts
export interface ReplaceResult { replaced: number; result: SearchResult; }
```

Replacement count and refreshed search state returned by replace-all.

Members:
- `replaced` — How many cells were rewritten.
- `result` — Search state after the replacement (matches re-scanned against the new data).

##### `ResolvedCell` — interface

```ts
export interface ResolvedCell { resolved: CellScalar; style: CellStyle; }
```

Authoritative source value, evaluated value, style, and load state for a cell.

##### `ResolvedHyperlinkTarget` — type

```ts
export type ResolvedHyperlinkTarget = | { readonly kind: "external"; readonly href: string } | { readonly kind: "internal"; readonly address: CellAddress };
```

Host-safe target resolved immediately before hyperlink activation.

##### `resolveHyperlinkTarget` — function

```ts
(workbook: Workbook, target: HyperlinkTarget): ResolvedHyperlinkTarget
```

Revalidate at the final activation boundary; hosts never receive an unsafe URL.

##### `resolveThemeFromCss` — function

```ts
(el: HTMLElement): Partial<Theme>
```

Read `--sheetwrite-*` CSS custom properties into a partial theme.

##### `resolveTransactionResourceLimits` — function

```ts
(overrides?: Partial<TransactionResourceLimits>): Readonly<TransactionResourceLimits>
```

Validate and merge transaction ceiling overrides without retaining the
caller-owned object. Every ceiling is an inclusive non-negative safe integer.

##### `ResourceOwnerBytes` — interface

```ts
export interface ResourceOwnerBytes { readonly owner: string; readonly logicalBytes: number; readonly allocatedBytes: number; readonly entries: number; readonly measurement: | "exact-capacity" | "hash-capacity-v1" | "typed-array-byte-length" | "utf16-upper-bound" | "entry-count-only"; }
```

Retained logical payload and allocated capacity attributed to one exclusive owner.

Members:
- `allocatedBytes` — Container capacity owned exclusively by this owner.
- `logicalBytes` — Bytes containing live logical payload. Never includes runtime observations.

##### `RevisionAdapter` — interface

```ts
export interface RevisionAdapter { listRevisions(documentId: string, signal?: AbortSignal): Promise<readonly RevisionSummary[]>; loadRevision(documentId: string, version: number, signal?: AbortSignal): Promise<unknown>; restoreRevision(request: RevisionRestoreRequest): Promise<RevisionRestoreResponse>; }
```

Host persistence contract for revision history and restore.

Members:
- `restoreRevision` — Must create a new auditable server version; never rewind storage in place.

##### `RevisionCoordinator` — class

```ts
class RevisionCoordinator { constructor(adapter: RevisionAdapter, options: RevisionCoordinatorOptions); destroy: () => void; list: () => Promise<readonly RevisionSummary[]>; on: (listener: RevisionListener) => () => void; preview: (host: HTMLElement, version: number, options?: SnapshotGridOptions) => Promise<Grid>; restore: (targetVersion: number, clientMutationId: string) => Promise<RevisionRestoreResponse>; serverVersion: number }
```

Coordinates listing and restoring host-owned workbook revisions.

##### `RevisionCoordinatorEvent` — type

```ts
export type RevisionCoordinatorEvent = | { type: "restored"; targetVersion: number; version: number } | { type: "conflict"; targetVersion: number; currentVersion: number } | { type: "error"; error: SheetwriteError };
```

State or restore transition emitted by revision coordination.

##### `RevisionCoordinatorOptions` — interface

```ts
export interface RevisionCoordinatorOptions { documentId: string; serverVersion: number; migrateSnapshot?: (snapshot: unknown) => unknown; }
```

Document identity and version options for revision coordination.

##### `RevisionRestoreRequest` — interface

```ts
export interface RevisionRestoreRequest { documentId: string; targetVersion: number; baseVersion: number; clientMutationId: string; signal?: AbortSignal; }
```

Versioned restore request submitted to a revision adapter.

##### `RevisionRestoreResponse` — type

```ts
export type RevisionRestoreResponse = | { status: "applied"; version: number; clientMutationId: string; snapshot: WorkbookSnapshot; } | { status: "duplicate"; version: number; clientMutationId: string } | { status: "conflict"; currentVersion: number };
```

Applied or conflict acknowledgement for a revision restore.

##### `RevisionSummary` — interface

```ts
export interface RevisionSummary { version: number; createdAt: string; actor?: PresenceActor; label?: string; }
```

Host-provided metadata describing a saved workbook revision.

##### `RowBridge` — class

```ts
class RowBridge { constructor<Id extends RowBridgeId = RowBridgeId, Row extends Record<string, CellScalar> = Record<string, CellScalar>>(options: RowBridgeOptions<Row, Id>); columnKeys: (sheet?: SheetId) => readonly string[]; project: (event: ChangeEvent, requestedOperations?: readonly DocumentOp[], transactionId?: string) => RowBridgeProjection<Id>; reconcile: (input: RowBridgeReconciliationInput<Id>) => RowBridgeProjection<Id>; rowIds: (sheet?: SheetId) => readonly (Id | null)[] }
```

Projects canonical document transactions into host-owned row changes.

The bridge only owns compact data-space identity arrays. It never writes to
`defaultRows`, never renders, and never creates a second document store.

Members:
- `columnKeys` — Current semantic column keys in canonical column order.
- `project` — Project an applied Grid change as an accepted, transformed, or remote result.
- `reconcile` — Reconcile a canonical transaction response without synchronizing host rows implicitly.
- `rowIds` — Current data-space row identities; visual sort and filters do not affect this order.

##### `RowBridgeCell` — interface

```ts
export interface RowBridgeCell<Id extends RowBridgeId = RowBridgeId> { readonly sheet: SheetId; readonly row: number; readonly rowId: Id | null; readonly col: number; readonly columnKey: string | null; readonly previous: CellValue | undefined; readonly next: CellValue | undefined; }
```

A cell effect with semantic column and host row identity.

##### `RowBridgeClearDelta` — interface

```ts
export interface RowBridgeClearDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "clear"; readonly range: Range; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A clearRange effect expanded to its exact changed cells.

##### `RowBridgeColumn` — interface

```ts
export interface RowBridgeColumn<Row extends Record<string, CellScalar>> { readonly key: keyof Row & string; }
```

Semantic column key accepted by the row bridge.

##### `RowBridgeDelta` — type

```ts
export type RowBridgeDelta<Id extends RowBridgeId = RowBridgeId> = | RowBridgeCellDelta<Id> | RowBridgeRangeDelta<Id> | RowBridgeClearDelta<Id> | RowBridgePasteDelta<Id> | RowBridgeFillDelta<Id> | RowBridgeRowStructureDelta<Id> | RowBridgeMetadataDelta<Id> | RowBridgeHostActionDelta<Id> | RowBridgeUnprojectableDelta<Id>;
```

Every possible projection produced by a row bridge.

##### `RowBridgeFillDelta` — interface

```ts
export interface RowBridgeFillDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "fill"; readonly range: Range | null; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A fill-series transaction effect.

##### `RowBridgeHandler` — type

```ts
export type RowBridgeHandler<Id extends RowBridgeId = RowBridgeId> = ( projection: RowBridgeProjection<Id>, ) => void;
```

Callback accepted by imperative and framework adapters.

##### `RowBridgeHostActionDelta` — interface

```ts
export interface RowBridgeHostActionDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "host-action"; readonly action: | "add-sheet" | "remove-sheet" | "rename-sheet" | "move-sheet" | "set-sheet-visibility"; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A document operation that needs a host-side action rather than row mutation.

##### `RowBridgeId` — type

```ts
export type RowBridgeId = string | number;
```

A stable host identity for one data-space row.

##### `RowBridgeInsertContext` — interface

```ts
export interface RowBridgeInsertContext { readonly sheet: SheetId; readonly at: number; readonly offset: number; readonly transactionId: string; }
```

Context supplied when a canonical row insertion needs a host identity.

##### `RowBridgeMetadataDelta` — interface

```ts
export interface RowBridgeMetadataDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "metadata"; readonly metadata: | "column" | "row" | "sheet" | "merge" | "table" | "validation" | "hyperlink" | "protected-range" | "note" | "named-range"; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A document operation that changes workbook or column metadata.

##### `RowBridgeOptions` — interface

```ts
export interface RowBridgeOptions< Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId, > { readonly columns: readonly RowBridgeColumn<Row>[]; readonly defaultRows: readonly Row[]; readonly getRowId: (row: Row, index: number) => Id; readonly sheet?: SheetId; readonly createRowId?: (context: RowBridgeInsertContext) => Id; }
```

Options for the framework-neutral, opt-in row bridge.

Members:
- `createRowId` — Optional identity factory for rows created by an addRows operation.
- `sheet` — Sheet identity used by the simple data-first adapter. Defaults to `sheet1`.

##### `RowBridgePasteDelta` — interface

```ts
export interface RowBridgePasteDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "paste"; readonly range: Range | null; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A paste transaction effect. A paste can contain multiple canonical patches.

##### `RowBridgeProjection` — interface

```ts
export interface RowBridgeProjection<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transaction: RowBridgeTransaction; readonly deltas: readonly RowBridgeDelta<Id>[]; }
```

Result of projection or reconciliation.

##### `RowBridgeRangeDelta` — interface

```ts
export interface RowBridgeRangeDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "range"; readonly range: Range; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A setRange/setBlock effect expanded to its exact changed cells.

##### `RowBridgeReconciliationInput` — interface

```ts
export interface RowBridgeReconciliationInput<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transactionId?: string; readonly source?: OperationSource; readonly version?: number; readonly operations?: readonly DocumentOp[]; readonly requestedOperations?: readonly DocumentOp[]; readonly event?: ChangeEvent; readonly commitReason?: CommitReason; readonly _type?: Id; }
```

Input to {@link RowBridge.reconcile}.

Members:
- `operations` — Canonical operations applied by the document engine.
- `requestedOperations` — Original host operations, used to identify a transformed acceptance.

##### `RowBridgeReconciliationStatus` — type

```ts
export type RowBridgeReconciliationStatus = | "accepted" | "transformed" | "rejected" | "out-of-order" | "duplicate" | "remote";
```

Reconciliation status for a canonical transaction response.

##### `RowBridgeRowStructureDelta` — interface

```ts
export interface RowBridgeRowStructureDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "row-structure"; readonly action: "insert" | "delete" | "move"; readonly sheet: SheetId; readonly at: number; readonly count: number; readonly from?: number; readonly to?: number; readonly inserted: readonly (Id | null)[]; readonly removed: readonly (Id | null)[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

Stable row identity effects for insert, delete, and move operations.

##### `RowBridgeTransaction` — interface

```ts
export interface RowBridgeTransaction { readonly id: string; readonly source: OperationSource; readonly commitReason: CommitReason; readonly epoch: number | undefined; readonly patches: readonly DocumentOp[]; }
```

The canonical transaction identity carried by each projected delta.

##### `rowBridgeTransactionId` — function

```ts
(transaction: Pick<Transaction, "patches" | "epoch">): string
```

Compute a deterministic identity for a canonical transaction.

##### `RowBridgeUnprojectableDelta` — interface

```ts
export interface RowBridgeUnprojectableDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "unprojectable"; readonly reason: string; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

An explicit projection record for an operation with no row-space meaning.

##### `RowData` — type

```ts
export type RowData = Record<string, DataCell>;
```

Object-shaped datasource row keyed by workbook column keys.

##### `RowGroup` — interface

```ts
export interface RowGroup { start: number; end: number; collapsed: boolean; }
```

A collapsible row group (data-row range, end-inclusive), Sheets-style.

##### `RowMetadata` — interface

```ts
export interface RowMetadata { height?: number; hidden?: boolean; }
```

Persistent display and grouping metadata for one document row.

##### `RUNTIME_RESOURCE_SCHEMA_VERSION` — variable

```ts
2
```

Stable protocol for runtime ownership and operation-cost reports.

##### `RuntimeMemoryObservation` — interface

```ts
export interface RuntimeMemoryObservation { readonly usedJSHeapSize: number | null; readonly arrayBufferBytes: number | null; readonly externalBytes: number | null; readonly browserBackingStoreBytes: number | null; }
```

Available runtime-level memory observations, kept separate from retained owner totals.

##### `RuntimeResourceOperation` — type

```ts
export type RuntimeResourceOperation = | "startup" | "scroll" | "ingest" | "edit" | "dirty-clear" | "formula-recompute" | "auto-fit" | "export" | "snapshot" | "persistence" | "teardown";
```

User-visible operation whose retained and transient resource costs are measured.

##### `RuntimeResourcePhase` — type

```ts
export type RuntimeResourcePhase = "before" | "peak" | "settled" | "after-destroy";
```

Measurement point within one resource-accounted operation.

##### `RuntimeResourcePhaseDelta` — interface

```ts
export interface RuntimeResourcePhaseDelta { readonly schemaVersion: typeof RUNTIME_RESOURCE_SCHEMA_VERSION; readonly operation: RuntimeResourceOperation; readonly from: RuntimeResourcePhase; readonly to: RuntimeResourcePhase; readonly owners: readonly ResourceOwnerDelta[]; readonly runtime: { readonly usedJSHeapSize: number | null; readonly arrayBufferBytes: number | null; readonly externalBytes: number | null; readonly browserBackingStoreBytes: number | null; }; }
```

Owner and runtime deltas between two phases of the same operation.

##### `RuntimeResourceSnapshot` — interface

```ts
export interface RuntimeResourceSnapshot { readonly schemaVersion: typeof RUNTIME_RESOURCE_SCHEMA_VERSION; readonly operation: RuntimeResourceOperation; readonly phase: RuntimeResourcePhase; readonly wasm: StoreMemoryBreakdown; readonly jsOwners: readonly ResourceOwnerBytes[]; readonly boundary: readonly BoundaryOperationStats[]; readonly runtime: RuntimeMemoryObservation; readonly totals: { readonly logicalLiveBytes: number; readonly allocatedCapacityBytes: number; }; }
```

Complete retained-resource and boundary snapshot for one operation phase.

##### `sanitizeCellHyperlink` — function

```ts
(value: unknown): CellHyperlink | null
```

Sanitize one untrusted clipboard/snapshot value without cloning its object graph.

##### `sanitizeHyperlinkStyle` — function

```ts
(value: unknown): CellStyle | null
```

Convert an untrusted style into one bounded, plain renderer-safe value.

##### `SearchOptions` — interface

```ts
export interface SearchOptions { matchCase?: boolean; wholeCell?: boolean; sheet?: SheetId; columns?: number[]; }
```

Case, whole-cell, sheet, and column constraints for grid search.

Members:
- `columns` — Restrict to these column indices (defaults to all columns).
- `matchCase` — Case-sensitive match (default false).
- `sheet` — Restrict to a sheet (defaults to the active sheet).
- `wholeCell` — Match only when the whole cell text equals the query (default false: substring).

##### `SearchResult` — interface

```ts
export interface SearchResult { query: string; matches: CellAddress[]; active: number; }
```

Ordered matches and active index produced by a grid search.

Members:
- `active` — Index of the active match within `matches`, or -1 when there are none.
- `matches` — Matching cells in row-major order.
- `query` — Query string retained for navigation and subsequent replacement.

##### `Selection` — type

```ts
export type Selection = | { kind: "cell"; addr: CellAddress; } | { kind: "range"; range: Range; } | { kind: "row"; sheet: SheetId; row: number; } | { kind: "column"; sheet: SheetId; col: number; } | { kind: "multi"; ranges: Range[]; };
```

Current cell, range, row, column, or multi-range selection.

##### `serialToDate` — function

```ts
(serial: number): Date
```

Convert a date serial back to a `Date`. Read the result with the UTC accessors
(`getUTCFullYear`, `getUTCMonth`, …) — which is what the renderer does — so the
calendar fields are stable regardless of the host time zone.

##### `setXlsxTableExportBackend` — function

```ts
(next: XlsxTableExportBackend): void
```

Registers the optional table XLSX export implementation used by core.

##### `setXlsxTableImportBackend` — function

```ts
(next: XlsxTableImportBackend): void
```

Registers the optional table XLSX import implementation used by core.

##### `setXlsxWorkbookBackend` — function

```ts
(next: XlsxWorkbookBackend): void
```

Registers the optional workbook XLSX implementation used by core.

##### `Sheet` — interface

```ts
export interface Sheet { id: SheetId; name: string; visibility?: SheetVisibility; columns: Column[]; rowCount: number; rowHeights?: Map<number, number>; hiddenRows?: Set<number>; rowGroups?: RowGroup[]; conditionalFormats?: ConditionalFormatRule[]; hyperlinks?: CellHyperlink[]; validationRules?: DataValidationRule[]; protectedRanges?: ProtectedRange[]; notes?: CellNote[]; sortKeys?: SortKey[]; filters?: Array<[col: number, filter: ColumnFilter]>; merges?: MergeRange[]; frozenRows?: number; frozenCols?: number; tables?: WorkbookTable[]; }
```

Workbook sheet schema used when creating a live grid.

Members:
- `columns` — Ordered schema; array positions are the zero-based column coordinates.
- `conditionalFormats` — Conditional styles folded into the bulk render-window style dictionary.
- `filters` — Persisted column filters as JSON-safe index/value tuples.
- `frozenCols` — Leading columns pinned left of the scrolling body (0/undefined = none).
- `frozenRows` — Leading view rows pinned above the scrolling body (0/undefined = none).
- `hiddenRows` — Persisted hidden data rows; runtime form is sparse and non-JSON.
- `hyperlinks` — Stable, serializable range hyperlinks; external URLs pass the shared safety policy.
- `id` — Stable identifier, unique within the workbook and used by every cell address.
- `merges` — Persisted merged-cell regions; covered cells render/export from the anchor.
- `name` — User-facing sheet name shown in tabs and workbook exports.
- `notes` — Simple cell notes. Discussion threads live outside the document model.
- `protectedRanges` — Client-side protected-range policy metadata; never server authorization.
- `rowCount` — Row count for both in-memory and datasource-backed sheets.
- `rowGroups` — Persisted collapsible row groups.
- `rowHeights` — Sparse per-row height overrides; default comes from the theme.
- `sortKeys` — Persisted sort keys for the sheet's view.
- `tables` — Native workbook tables anchored to this stable worksheet identity.
- `validationRules` — Serializable data-entry rules evaluated at the local mutation barrier.
- `visibility` — Hidden worksheets remain addressable but are omitted from the tab strip.

##### `SheetId` — type

```ts
export type SheetId = string;
```

Stable identifier used to address a workbook sheet.

##### `SheetLifecycleIssueCode` — type

```ts
export type SheetLifecycleIssueCode = | SheetNameIssueCode | "duplicate-sheet-id" | "sheet-not-found" | "invalid-sheet" | "invalid-position" | "last-visible-sheet";
```

Stable lifecycle rejection codes suitable for inline sheet-management UI.

##### `SheetLifecycleResult` — type

```ts
export type SheetLifecycleResult = ApplyTransactionResult & { readonly sheet: SheetId };
```

Actionable transaction outcome for a stable sheet lifecycle target.

##### `SheetNameIssueCode` — type

```ts
export type SheetNameIssueCode = | "blank" | "too-long" | "forbidden-character" | "edge-apostrophe" | "duplicate";
```

Stable reason codes returned by worksheet-name validation.

##### `sheetNameKey` — function

```ts
(name: string): string
```

NFC and locale-independent Unicode lowercase key used for worksheet-name identity.

##### `SheetNameValidationResult` — type

```ts
export type SheetNameValidationResult = | { readonly ok: true; readonly name: string; readonly key: string; } | { readonly ok: false; readonly code: SheetNameIssueCode; readonly name: string; readonly key: string; };
```

Successful canonical name or an actionable validation failure.

##### `SheetSnapshot` — interface

```ts
export interface SheetSnapshot { id: SheetId; name: string; order: number; visibility?: SheetVisibility; rowCount: number; columns: Column[]; frozenRows?: number; frozenCols?: number; rowMeta?: Array<[row: number, meta: RowMetadata]>; merges?: MergeRange[]; conditionalFormats?: ConditionalFormatRule[]; hyperlinks?: CellHyperlink[]; validationRules?: DataValidationRule[]; protectedRanges?: ProtectedRange[]; notes?: CellNote[]; sortKeys?: SortKey[]; filters?: Array<[col: number, filter: ColumnFilter]>; rowGroups?: RowGroup[]; tables?: WorkbookTable[]; cells: CellBlock[]; }
```

Serializable complete state for one workbook sheet.

Members:
- `columns` — Keys are stable, unique document column identities as well as datasource keys.
- `visibility` — Hidden worksheets remain in the workbook and retain formulas/references.

##### `SheetVisibility` — type

```ts
export type SheetVisibility = "visible" | "hidden" | "veryHidden";
```

Native worksheet visibility preserved across workbook snapshots and tab rendering.

##### `SHEETWRITE_CLIPBOARD_MIME` — variable

```ts
"application/x-sheetwrite+json"
```

Private-format MIME type used for rich Sheetwrite clipboard payloads.

##### `SHEETWRITE_ERROR_CODES` — variable

```ts
readonly ["initialization-failed", "initialization-required", "datasource-request-failed", "renderer-fallback", "export-failed", "xlsx-import-failed", "optional-backend-unavailable", "delimited-text-resource-limit", "delimited-text-invalid-limit", "xlsx-resource-limit", "resource-limit", "invalid-snapshot", "aborted", "not-found", "commit-rejected", "unavailable", "blocked", "quota", "unsupported-schema", "transaction", "conflict", "limit", "invalid-limits", "invalid-version", "invalid-id", "invalid-operations", "operation-limit", "payload-limit", "response-id-mismatch", "future-distance-limit", "buffer-count-limit", "buffer-operation-limit", "buffer-byte-limit", "pending-count-limit", "pending-operation-limit", "pending-byte-limit", "late-echo", "remote-operations-rejected", "pending-capacity", "presence-failed", "revision-failed", "comment-failed", "sync-failed", "sync-storage-failed", "incomplete-data", "xlsx-invalid-options", "unsafe-hyperlink"]
```

Stable public failure codes. Messages are diagnostic and are not API contracts.

##### `SHEETWRITE_ERROR_OPERATIONS` — variable

```ts
readonly ["initialize", "create-grid", "datasource-request", "renderer-worker", "export-xlsx", "xlsx-import", "xlsx-export", "delimited-parse", "delimited-import", "delimited-encode", "delimited-export", "delimited-options", "snapshot-validate", "snapshot-allocate", "persistence", "pending-storage", "synchronize", "presence", "revision", "comments", "query", "hyperlink-activate"]
```

Stable operations at which a consumer-visible failure can surface.

##### `SheetwriteError` — class

```ts
class SheetwriteError extends Error implements SheetwriteErrorEnvelope { constructor(code: SheetwriteErrorCode, operation: SheetwriteErrorOperation, message: string, options?: SheetwriteErrorOptions); code: "aborted" | "blocked" | "buffer-byte-limit" | "buffer-count-limit" | "buffer-operation-limit" | "comment-failed" | "commit-rejected" | "conflict" | "datasource-request-failed" | "delimited-text-invalid-limit" | "delimited-text-resource-limit" | "export-failed" | "future-distance-limit" | "incomplete-data" | "initialization-failed" | "initialization-required" | "invalid-id" | "invalid-limits" | "invalid-operations" | "invalid-snapshot" | "invalid-version" | "late-echo" | "limit" | "not-found" | "operation-limit" | "optional-backend-unavailable" | "payload-limit" | "pending-byte-limit" | "pending-capacity" | "pending-count-limit" | "pending-operation-limit" | "presence-failed" | "quota" | "remote-operations-rejected" | "renderer-fallback" | "resource-limit" | "response-id-mismatch" | "revision-failed" | "sync-failed" | "sync-storage-failed" | "transaction" | "unavailable" | "unsafe-hyperlink" | "unsupported-schema" | "xlsx-import-failed" | "xlsx-invalid-options" | "xlsx-resource-limit"; context?: Readonly<Record<string, SheetwriteErrorContextValue>> | undefined; name: string; operation: "comments" | "create-grid" | "datasource-request" | "delimited-encode" | "delimited-export" | "delimited-import" | "delimited-options" | "delimited-parse" | "export-xlsx" | "hyperlink-activate" | "initialize" | "pending-storage" | "persistence" | "presence" | "query" | "renderer-worker" | "revision" | "snapshot-allocate" | "snapshot-validate" | "synchronize" | "xlsx-export" | "xlsx-import"; retryable?: boolean | undefined; toJSON: () => SheetwriteErrorEnvelope }
```

Canonical envelope for thrown and callback-delivered Sheetwrite failures.

##### `SheetwriteErrorCode` — type

```ts
export type SheetwriteErrorCode = (typeof SHEETWRITE_ERROR_CODES)[number];
```

Exhaustive stable discriminator for consumer-visible Sheetwrite failures.

##### `SheetwriteErrorContext` — type

```ts
export type SheetwriteErrorContext = Readonly<Record<string, SheetwriteErrorContextValue>>;
```

Stable, serialization-safe diagnostic context.

##### `SheetwriteErrorContextValue` — type

```ts
export type SheetwriteErrorContextValue = | null | string | number | boolean | readonly SheetwriteErrorContextValue[] | { readonly [key: string]: SheetwriteErrorContextValue };
```

JSON-safe values accepted in a public failure context.

##### `SheetwriteErrorEnvelope` — interface

```ts
export interface SheetwriteErrorEnvelope { readonly name: string; readonly message: string; readonly code: SheetwriteErrorCode; readonly operation: SheetwriteErrorOperation; readonly context?: SheetwriteErrorContext; readonly retryable?: boolean; }
```

Structural form preserved across realms and JSON serialization.

##### `SheetwriteErrorOperation` — type

```ts
export type SheetwriteErrorOperation = (typeof SHEETWRITE_ERROR_OPERATIONS)[number];
```

Exhaustive stable operation discriminator for consumer-visible failures.

##### `SheetwriteErrorOptions` — interface

```ts
export interface SheetwriteErrorOptions extends ErrorOptions { context?: SheetwriteErrorContext; retryable?: boolean; }
```

Optional cause, diagnostic context, and boundary-known retryability.

Members:
- `retryable` — Present only when Sheetwrite can determine retryability from the boundary itself.

##### `SheetwriteStore` — class

```ts
class SheetwriteStore implements Store { constructor(workbook: Workbook, data?: ColumnarData, options?: SheetwriteStoreOptions); acknowledgeOperations: (operations: readonly DocumentOp[], storageRevision?: bigint) => void; aggregate: (sheet: SheetId, col: number, op: AggregateOp) => number; applyTransaction: (tx: Transaction, reasonOrOptions?: CommitReason | TransactionApplicationOptions) => ApplyTransactionResult; areColumnsFullyLoaded: (sheet: SheetId, startRow: number, endRow: number, columns: readonly number[]) => boolean; canApplyLocally: (patch: DocumentOp) => boolean; captureRangeHistory: (input: Range) => CompactRangeHistory | null; clearView: (sheet: SheetId) => void; columnFilters: (sheet: SheetId) => ReadonlyMap<number, ColumnFilter>; dataEdge: (sheet: SheetId, row: number, col: number, dRow: number, dCol: number) => number; dataRowAt: (sheet: SheetId, viewRow: number) => number; dispose: () => void; distinctValues: (sheet: SheetId, col: number, limit?: number) => CellScalar[]; ensureColumns: (sheet: SheetId, columns: readonly Column[]) => void; exportSnapshot: () => WorkbookSnapshot; filterBy: (sheet: SheetId, col: number, needle: string) => void; getCell: (addr: CellAddress) => ResolvedCell; getCellLoadState: (addr: CellAddress) => CellLoadState; getClipboardWindow: (sheet: SheetId, viewRows: { start: number; end: number; }, cols: readonly number[]) => ClipboardWindowView; getDataWindow: (sheet: SheetId, rows: { start: number; end: number; }, cols: readonly number[]) => VisibleWindowView; getFormula: (addr: CellAddress) => string | null; getFormulaMatrixResourcePeak: () => TransientResourcePeak; getPagedStats: (sheet: SheetId) => PagedStoreStats; getRangeMutationAllocationStats: () => RangeMutationAllocationStats; getRefTarget: (addr: CellAddress) => CellAddress | null; getRuntimeResourceSnapshot: (operation: RuntimeResourceOperation, phase: RuntimeResourcePhase, runtime?: RuntimeMemoryObservation) => RuntimeResourceSnapshot; getSpillAnchor: (addr: CellAddress) => CellAddress | null; getVisibleWindow: (sheet: SheetId, rows: { start: number; end: number; }, cols: readonly number[]) => VisibleWindowView; getWorkbook: () => Workbook; groupRows: (sheet: SheetId, start: number, end: number) => void; hasView: (sheet: SheetId) => boolean; hiddenRows: (sheet: SheetId) => number[]; hideRows: (sheet: SheetId, rows: readonly number[]) => void; isPaged: (sheet: SheetId) => boolean; isRangeFullyLoaded: (input: Range) => boolean; loadPage: (sheet: SheetId, start: number, columns: readonly DataSourceColumnBand[], rows: readonly RowData[], protect?: (addr: CellAddress) => boolean) => void; on: (_evt: "change", fn: ChangeListener) => () => void; queryCapability: (sheet: SheetId) => QueryCapability; recalculateVolatile: (now?: Date) => void; removeSheetFormulaIdentity: (sheet: SheetId) => boolean; renameSheetFormulaIdentity: (sheet: SheetId, name: string) => boolean; resetFormulaMatrixResourcePeak: () => void; resetRangeMutationAllocationStats: () => void; resetRuntimeResourceAccounting: () => void; rowGroups: (sheet: SheetId) => readonly RowGroup[]; searchCells: (sheet: SheetId, query: string, opts?: { matchCase?: boolean; wholeCell?: boolean; columns?: number[]; }) => CellAddress[]; searchCellsFlat: (sheet: SheetId, query: string, opts?: { matchCase?: boolean; wholeCell?: boolean; columns?: number[]; }) => Uint32Array; setColumnFilter: (sheet: SheetId, col: number, filter: ColumnFilter | null) => void; setDetailedChangeCapture: (enabled: boolean) => void; setGroupCollapsed: (sheet: SheetId, start: number, collapsed: boolean) => void; setProtectionResolver: (resolver: ProtectionResolver | undefined, mode?: MutationPolicyMode) => void; showRows: (sheet: SheetId, rows?: readonly number[]) => void; sortBy: (sheet: SheetId, col: number, ascending: boolean) => void; sortByMulti: (sheet: SheetId, keys: readonly SortKey[]) => void; ungroupRows: (sheet: SheetId, start: number, end: number) => void; viewRowCount: (sheet: SheetId) => number; viewRowOf: (sheet: SheetId, dataRow: number) => number | null; withResourceOperation: <T>(operation: RuntimeResourceOperation, run: () => T) => T; static fromSnapshot: (input: unknown, options?: SheetwriteStoreOptions) => SheetwriteStore }
```

Stable public facade and the sole transaction, epoch, policy, and event barrier.

Members:
- `acknowledgeOperations` — Release sparse paged edits after server acknowledgement.
- `applyTransaction` — Apply a low-level storage transaction.

This bypasses Grid read-only checks and Grid undo/redo history. Use
`Grid.applyTransaction` for normal host-driven edits.
Queued and flushed at a barrier — never reentrant.
- `ensureColumns` — Ensure a sheet can address at least `columns.length` columns without
producing user changes or dirty patches. Used for presentation padding.
- `exportSnapshot` — Deterministic, JSON-safe authoritative runtime document.
- `getCell` — Single-cell read for interactions, API reads, and tests.
NOT for the render hot path — renderers use `getVisibleWindow`.
- `getCellLoadState` — Loaded/empty/local state; dense stores always return a loaded state.
- `getClipboardWindow` — Optional packed clipboard read. Custom stores may omit it; the controller
preserves the per-cell Store fallback contract.
- `getDataWindow` — Optional packed canonical data-row window used by file export. Unlike
`getVisibleWindow`, sort/filter state never remaps `rows`.
- `getFormula` — Formula source at `addr`, or null when the cell is not a formula.
- `getRefTarget` — Plain-reference target at `addr`, or null when the cell is not a ref.
- `getSpillAnchor` — Owning dynamic-array formula cell, or null when `addr` is not spilled.
- `getVisibleWindow` — Bulk read of a visible window; the only read a renderer should use per frame.
- `queryCapability` — Explicit partial-data state for paged datasource stores.
- `recalculateVolatile` — Recompute volatile formulas (`TODAY`/`NOW`) from one captured instant.
The supplied Date is interpreted as an absolute UTC instant.
- `setDetailedChangeCapture` — Opt in to per-cell before/after capture for packed and clear operations.
- `setProtectionResolver` — Configure host-owned protected-range permissions. The resolver is synchronous
so every local mutation ingress shares one atomic commit barrier.
- `viewRowCount` — Displayed row count after any active sort/filter view.

##### `SheetwriteStoreOptions` — interface

```ts
export interface SheetwriteStoreOptions { snapshotResourceLimits?: Partial<SnapshotResourceLimits>; transactionResourceLimits?: Partial<TransactionResourceLimits>; storage?: "dense" | "paged"; chunkRows?: number; cacheBytes?: number; dirtyCellLimit?: number; referenceSimulationLimit?: number; protectionResolver?: ProtectionResolver; mutationPolicy?: MutationPolicyMode; }
```

Storage layout plus snapshot and transaction resource ceilings for one store.

Members:
- `cacheBytes` — Per-sheet clean-chunk budget; defaults to 32 MiB. Dirty and pinned chunks may exceed it.
- `chunkRows` — Paged row chunk size; defaults to 4,096 and is normalized to a power of two.
- `dirtyCellLimit` — Maximum sparse local edits retained outside the clean page cache. Defaults to 1,000,000 cells; further edits reject atomically.
- `referenceSimulationLimit` — Maximum clean references retained for exact multi-operation remove-sheet simulation.
- `snapshotResourceLimits` — Overrides canonical snapshot/workbook allocation ceilings before construction.
- `storage` — Storage engine; defaults to eager `dense` allocation.
- `transactionResourceLimits` — Overrides inclusive operation-count and encoded-byte ceilings for every transaction.

##### `shiftA1Refs` — function

```ts
(src: string, dRow: number, dCol: number): string
```

Shift relative A1 references in a formula by (dRow, dCol) — used when a
formula is filled into other cells. Absolute parts ($A, A$1) stay fixed, and
tokens preceded by an alphanumeric (function names, identifiers) are skipped.

##### `SnapshotCell` — interface

```ts
export interface SnapshotCell { rowOffset: number; colOffset: number; value: CellValue; style?: CellStyle; }
```

Serializable cell value and optional style inside a snapshot block.

##### `SnapshotGridOptions` — type

```ts
export type SnapshotGridOptions = Omit<GridOptions, "workbook" | "data"> & { snapshotResourceLimits?: Partial<SnapshotResourceLimits>; };
```

Grid creation options accepted when hydrating a validated snapshot.

##### `SnapshotResourceError` — class

```ts
class SnapshotResourceError extends SheetwriteError { constructor(resource: keyof SnapshotResourceLimits, limit: number, actual: number, options?: ErrorOptions); actual: number; limit: number; name: "SnapshotResourceError"; resource: keyof SnapshotResourceLimits }
```

Stable resource failure raised by direct workbook construction paths.

##### `SnapshotResourceLimits` — interface

```ts
export interface SnapshotResourceLimits { maxSheets: number; maxRowsPerSheet: number; maxColumnsPerSheet: number; maxMetadataEntries: number; maxSerializedBytes: number; maxLogicalCellsPerSheet: number; maxDenseCells: number; }
```

Resource ceilings applied before snapshot normalization or store allocation.

Members:
- `maxColumnsPerSheet` — Columns in any sheet; defaults to 16,384.
- `maxDenseCells` — Aggregate cells allocated by dense storage; defaults to 5,000,000.
- `maxLogicalCellsPerSheet` — Logical row-by-column cells in any sheet; defaults to 4,294,967,295.
- `maxMetadataEntries` — Aggregate workbook/sheet metadata array entries; defaults to 1,000,000.
- `maxRowsPerSheet` — Rows in any sheet; defaults to 1,000,000.
- `maxSerializedBytes` — UTF-8 JSON bytes inspected while validating a snapshot; defaults to 64 MiB.
- `maxSheets` — Workbook sheets; defaults to 256.

##### `SnapshotStorageMode` — type

```ts
export type SnapshotStorageMode = "dense" | "paged";
```

Allocation mode used when enforcing snapshot construction capacity.

##### `SnapshotValidationError` — class

```ts
class SnapshotValidationError extends SheetwriteError { constructor(errors: readonly DocumentValidationError[]); errors: readonly DocumentValidationError[]; name: "SnapshotValidationError" }
```

Path-qualified schema failure found while validating an untrusted snapshot.

##### `SnapshotValidationOptions` — interface

```ts
export interface SnapshotValidationOptions { storage?: SnapshotStorageMode; resourceLimits?: Partial<SnapshotResourceLimits>; }
```

Validation and allocation policy for an untrusted workbook snapshot.

Members:
- `resourceLimits` — Non-negative safe-integer overrides merged over `DEFAULT_SNAPSHOT_RESOURCE_LIMITS`.
- `storage` — Allocation model used for capacity checks; defaults to `dense`.

##### `SortKey` — interface

```ts
export interface SortKey { col: number; ascending: boolean; }
```

One key of a multi-column sort, applied in array order (first = primary).

##### `Store` — interface

```ts
export interface Store { getWorkbook(): Workbook; getCell(addr: CellAddress): ResolvedCell; getFormula(addr: CellAddress): string | null; getSpillAnchor(addr: CellAddress): CellAddress | null; getRefTarget(addr: CellAddress): CellAddress | null; recalculateVolatile(now?: Date): void; getVisibleWindow( sheet: SheetId, rows: { start: number; end: number }, cols: readonly number[], ): VisibleWindowView; getDataWindow?( sheet: SheetId, rows: { start: number; end: number }, cols: readonly number[], ): VisibleWindowView; getClipboardWindow?( sheet: SheetId, viewRows: { start: number; end: number }, cols: readonly number[], ): ClipboardWindowView; ensureColumns(sheet: SheetId, columns: readonly Column[]): void; applyTransaction( tx: Transaction, options?: TransactionApplicationOptions, ): ApplyTransactionResult; setProtectionResolver?(resolver: ProtectionResolver | undefined, mode?: MutationPolicyMode): void; on(evt: "change", fn: (event: ChangeEvent) => void): () => void; setDetailedChangeCapture?(enabled: boolean): void; queryCapability?(sheet: SheetId): QueryCapability; getCellLoadState?(addr: CellAddress): CellLoadState; acknowledgeOperations?(operations: readonly DocumentOp[], storageRevision?: bigint): void; exportSnapshot?(): WorkbookSnapshot; viewRowCount(sheet: SheetId): number; }
```

Columnar workbook storage, query, transaction, and subscription contract.

Members:
- `acknowledgeOperations` — Release sparse paged edits after server acknowledgement.
- `applyTransaction` — Apply a low-level storage transaction.

This bypasses Grid read-only checks and Grid undo/redo history. Use
`Grid.applyTransaction` for normal host-driven edits.
Queued and flushed at a barrier — never reentrant.
- `ensureColumns` — Ensure a sheet can address at least `columns.length` columns without
producing user changes or dirty patches. Used for presentation padding.
- `exportSnapshot` — Deterministic, JSON-safe authoritative runtime document.
- `getCell` — Single-cell read for interactions, API reads, and tests.
NOT for the render hot path — renderers use `getVisibleWindow`.
- `getCellLoadState` — Loaded/empty/local state; dense stores always return a loaded state.
- `getClipboardWindow` — Optional packed clipboard read. Custom stores may omit it; the controller
preserves the per-cell Store fallback contract.
- `getDataWindow` — Optional packed canonical data-row window used by file export. Unlike
`getVisibleWindow`, sort/filter state never remaps `rows`.
- `getFormula` — Formula source at `addr`, or null when the cell is not a formula.
- `getRefTarget` — Plain-reference target at `addr`, or null when the cell is not a ref.
- `getSpillAnchor` — Owning dynamic-array formula cell, or null when `addr` is not spilled.
- `getVisibleWindow` — Bulk read of a visible window; the only read a renderer should use per frame.
- `queryCapability` — Explicit partial-data state for paged datasource stores.
- `recalculateVolatile` — Recompute volatile formulas (`TODAY`/`NOW`) from one captured instant.
The supplied Date is interpreted as an absolute UTC instant.
- `setDetailedChangeCapture` — Opt in to per-cell before/after capture for packed and clear operations.
- `setProtectionResolver` — Configure host-owned protected-range permissions. The resolver is synchronous
so every local mutation ingress shares one atomic commit barrier.
- `viewRowCount` — Displayed row count after any active sort/filter view.

##### `STORE_MEMORY_HASH_ESTIMATE_VERSION` — variable

```ts
1
```

Version of the deterministic hash-table capacity estimate used by store owners.

##### `STORE_MEMORY_PROTOCOL_VERSION` — variable

```ts
3
```

Flat WASM store-memory protocol version; decoders reject any mismatch.

##### `StoreMemoryBreakdown` — interface

```ts
export interface StoreMemoryBreakdown { readonly protocolVersion: typeof STORE_MEMORY_PROTOCOL_VERSION; readonly hashTableEstimateVersion: typeof STORE_MEMORY_HASH_ESTIMATE_VERSION; readonly owners: readonly ResourceOwnerBytes[]; readonly logicalLiveBytes: number; readonly allocatedCapacityBytes: number; readonly wasmCommittedBytes: number | null; readonly allocatorMarginBytes: number | null; readonly unaccountedBytes: number; }
```

Decoded, fail-closed retained-memory ownership report from the WASM store.

Members:
- `allocatorMarginBytes` — Allocator internals are intentionally not fabricated from `size_of_val`.
- `wasmCommittedBytes` — Linear-memory pages are a runtime observation and are never summed into live payload.

##### `SyncActivityState` — type

```ts
export type SyncActivityState = | "hydrating" | "idle" | "persisting" | "pending" | "sending" | "conflict" | "error" | "destroyed";
```

Current persistence activity reported by a sync coordinator.

##### `SyncConnectionState` — type

```ts
export type SyncConnectionState = "offline" | "connecting" | "online" | "error" | "destroyed";
```

Host-controlled online state reported by synchronization.

##### `SyncCoordinator` — class

```ts
class SyncCoordinator { constructor(grid: Grid, adapter: PersistenceAdapter, options: SyncCoordinatorOptions); applyVersionedOperation: (operation: VersionedOperation) => Promise<void>; destroy: () => void; flush: () => Promise<readonly PersistenceCommitResponse[]>; handleResponse: (response: PersistenceCommitResponse, requestedMutationId?: string) => Promise<void>; on: (listener: SyncListener) => () => void; pendingCommits: () => readonly SyncMutationRecord[]; pendingCount: number; ready: () => Promise<void>; resumeAfterReload: (snapshot: WorkbookSnapshot) => Promise<void>; retry: (clientMutationId: string) => Promise<PersistenceCommitResponse | null>; retryPersistence: (clientMutationId: string) => Promise<boolean>; send: (clientMutationId: string) => Promise<PersistenceCommitResponse | null>; sendNext: () => Promise<PersistenceCommitResponse | null>; serverVersion: number; setOnline: (online: boolean) => void; state: SyncStateSnapshot; subscribe: (source: RemoteOperationSource | AsyncIterable<VersionedOperation>) => () => void }
```

Deterministic, transport-neutral optimistic sync. Local rendering is never
blocked: changes queue immediately, while hosts explicitly call `sendNext`
or `retry` to perform network work.

Members:
- `handleResponse` — Public for transports that deliver responses independently of send promises.
- `ready` — Resolves after durable work is restored and every startup commit is visible locally.
- `resumeAfterReload` — Resume only after the host remounted/reloaded document state and reapplied
retained local operations. No lossy structural merge is attempted here.
- `retry` — Explicit retry; the original mutation ID and durable record are retained.
- `setOnline` — Update connectivity. Reconnection drains durable work in order; going
offline aborts in-flight requests so retries retain their mutation IDs.

##### `SyncCoordinatorEvent` — type

```ts
export type SyncCoordinatorEvent = | { type: "state"; state: SyncStateSnapshot } | { type: "restored"; pending: readonly SyncMutationRecord[] } | { type: "persisting"; mutation: SyncMutationRecord } | { type: "pending"; mutation: SyncMutationRecord } | { type: "sending"; mutation: SyncMutationRecord } | { type: "acknowledged"; clientMutationId: string; version: number; duplicate: boolean; } | { type: "conflict"; mutation: SyncMutationRecord; response: Extract<PersistenceCommitResponse, { status: "conflict" }>; } | { type: "remote-applied"; operation: VersionedOperation } | { type: "reload-required"; expectedVersion: number; receivedVersion: number; snapshot?: WorkbookSnapshot; } | { type: "reloaded"; serverVersion: number; pending: readonly SyncMutationRecord[] } | { type: "storage-error"; error: SheetwriteError; clientMutationId?: string } | { type: "error"; error: SheetwriteError; clientMutationId?: string };
```

Queue, version, connection, or error transition emitted by synchronization.

##### `SyncCoordinatorLimits` — interface

```ts
export interface SyncCoordinatorLimits { maxMutationIdBytes: number; maxOperationsPerVersion: number; maxVersionPayloadBytes: number; maxFutureVersionDistance: number; maxBufferedVersions: number; maxBufferedOperations: number; maxBufferedBytes: number; maxRecentAcknowledgements: number; maxPendingCommits: number; maxPendingOperations: number; maxPendingEncodedBytes: number; }
```

Resource ceilings applied independently to remote collaboration input and local durability.

Members:
- `maxBufferedBytes` — Aggregate encoded bytes retained in the gap buffer; defaults to 32 MiB.
- `maxBufferedOperations` — Aggregate operations retained in the gap buffer; defaults to 40,000.
- `maxBufferedVersions` — Remote future versions retained in the gap buffer; defaults to 256.
- `maxFutureVersionDistance` — Version distance allowed ahead of the contiguous head; defaults to 1,024.
- `maxMutationIdBytes` — UTF-8 bytes in a remote or pending mutation ID; defaults to 256.
- `maxOperationsPerVersion` — Operations accepted in one remote version; defaults to 10,000.
- `maxPendingCommits` — Pending local commits, including synchronous reservations; defaults to 10,000.
- `maxPendingEncodedBytes` — Aggregate UTF-8 bytes across pending operation arrays; defaults to 128 MiB.
- `maxPendingOperations` — Aggregate DocumentOp count across pending commits; defaults to 100,000.
- `maxRecentAcknowledgements` — Recently acknowledged mutation IDs retained for echo deduplication;
defaults to 4,096. Once an ID expires, a stale operation carrying it is a
reload-requiring protocol violation and its operations are never reapplied.
- `maxVersionPayloadBytes` — Encoded operation bytes accepted in one remote version; defaults to 8 MiB.

##### `SyncCoordinatorOptions` — interface

```ts
export interface SyncCoordinatorOptions { documentId: string; serverVersion: number; createMutationId?: () => string; pendingStorage?: PendingCommitStorage; initialConnection?: "offline" | "online"; recoverVersionGap?: ( request: SyncVersionGapRequest, ) => Promise<readonly VersionedOperation[] | WorkbookSnapshot>; limits?: Partial<SyncCoordinatorLimits>; }
```

Document, version, durability, and online options for synchronization.

Members:
- `limits` — Positive safe-integer overrides merged over `DEFAULT_SYNC_COORDINATOR_LIMITS`.
- `recoverVersionGap` — Optional host recovery hook. Return the missing ordered operations, or a
snapshot for the host to remount before calling `resumeAfterReload`.

##### `SyncMutationRecord` — interface

```ts
export interface SyncMutationRecord { status: SyncMutationStatus; documentId: string; baseVersion: number; clientMutationId: string; readonly operations: readonly DocumentOp[]; }
```

Pending commit paired with its current synchronization status.

##### `SyncMutationStatus` — type

```ts
export type SyncMutationStatus = | "persisting" | "pending" | "sending" | "conflicted" | "storage-error";
```

Lifecycle state of one local mutation in the synchronization queue.

##### `SyncPendingCapacityError` — class

```ts
class SyncPendingCapacityError extends SheetwriteError { constructor(issue: Extract<MutationIssue, { kind: "resource-limit"; }>); issue: { kind: "resource-limit"; severity: "error"; resource: "operations" | "encoded-bytes" | "pending-commits" | "pending-operations" | "pending-encoded-bytes" | "paged-dirty-cells" | "paged-reference-simulation"; actual: number; max: number; message: string; }; name: "SyncPendingCapacityError" }
```

Typed local transaction rejection produced when the durable queue cannot reserve capacity.

##### `SyncPendingCapacityState` — type

```ts
export type SyncPendingCapacityState = | "hydrating" | "available" | "full" | "restore-error" | "destroyed";
```

Whether the durable local queue can currently admit another transaction.

##### `SyncPendingQueueLimits` — interface

```ts
export interface SyncPendingQueueLimits { maxPendingCommits: number; maxPendingOperations: number; maxPendingEncodedBytes: number; }
```

Aggregate ceilings for local commits retained until durable acknowledgement.

Members:
- `maxPendingCommits` — Pending local commits, including synchronous reservations; defaults to 10,000.
- `maxPendingEncodedBytes` — Aggregate UTF-8 bytes across pending operation arrays; defaults to 128 MiB.
- `maxPendingOperations` — Aggregate DocumentOp count across pending commits; defaults to 100,000.

##### `SyncProtocolError` — class

```ts
class SyncProtocolError extends SheetwriteError { constructor(code: SyncProtocolErrorCode, message: string); name: "SyncProtocolError" }
```

Typed rejection of malformed or resource-exhausting synchronization input.

##### `SyncProtocolErrorCode` — type

```ts
export type SyncProtocolErrorCode = | "invalid-limits" | "invalid-version" | "invalid-id" | "invalid-operations" | "operation-limit" | "payload-limit" | "response-id-mismatch" | "future-distance-limit" | "buffer-count-limit" | "buffer-operation-limit" | "buffer-byte-limit" | "pending-count-limit" | "pending-operation-limit" | "pending-byte-limit" | "late-echo" | "remote-operations-rejected";
```

Stable category identifying which synchronization protocol bound was violated.

##### `SyncStateSnapshot` — interface

```ts
export interface SyncStateSnapshot { connection: SyncConnectionState; activity: SyncActivityState; pendingCount: number; pendingOperations: number; pendingEncodedBytes: number; pendingCapacity: SyncPendingCapacityState; serverVersion: number; }
```

Immutable observable synchronization state.

Members:
- `pendingCapacity` — Current local transaction admission state.
- `pendingCount` — Pending local commits, including synchronous pre-commit reservations.
- `pendingEncodedBytes` — Aggregate UTF-8 bytes of pending JSON-encoded operation arrays.
- `pendingOperations` — Aggregate DocumentOp count, including synchronous pre-commit reservations.
- `serverVersion` — Last accepted contiguous remote server version.

##### `SyncVersionGapRequest` — interface

```ts
export interface SyncVersionGapRequest { documentId: string; expectedVersion: number; receivedVersion: number; signal: AbortSignal; }
```

Contiguous-version recovery request produced when remote input skips ahead.

##### `Theme` — interface

```ts
export interface Theme { font: string; bg: string; fg: string; gridLine: string; headerBg: string; headerFg: string; selection: string; selectionBorder: string; rowHeight: number; headerHeight: number; rowHeaderWidth: number; searchMatch: string; searchActiveMatch: string; highlight: string; }
```

Resolved canvas colors, typography, and geometry used for painting.

Members:
- `bg` — CSS color painted behind body cells.
- `fg` — CSS color used for unstyled cell text.
- `font` — Canvas font shorthand used for unstyled cells.
- `gridLine` — CSS color used for cell grid lines.
- `headerBg` — CSS color painted behind column and row headers.
- `headerFg` — CSS color used for column letters and row numbers.
- `headerHeight` — Column-header height in unzoomed CSS pixels.
- `highlight` — Fill for cells highlighted via Grid.highlightCells.
- `rowHeaderWidth` — Width of the left row-number gutter (0 hides it).
- `rowHeight` — Default data-row height in unzoomed CSS pixels.
- `searchActiveMatch` — Fill/outline for the active (current) search match.
- `searchMatch` — Fill behind a search match.
- `selection` — CSS color painted over the selected region.
- `selectionBorder` — CSS color used for the active selection outline.

##### `toCsv` — function

```ts
(sheet: Sheet, store: Store, options?: DelimitedTextOptions): string
```

Export the current visible CSV view (UTF-8 BOM, CRLF): visible columns and
view-ordered rows surviving sort, filter, hidden-row, and group state. String
values beginning with `= + - @ \t \r` are prefixed with `'`. The synchronous
API returns one in-memory string, but fetches at most
`maxWriterWindowRows` view rows from the store per read.

##### `ToolbarActionName` — type

```ts
export type ToolbarActionName = | "bold" | "italic" | "underline" | "strikethrough" | "alignLeft" | "alignCenter" | "alignRight" | "textColor" | "fillColor" | "border" | "clearFormat" | "merge" | "unmerge" | "sortAsc" | "sortDesc" | "exportCsv" | "exportXlsx" | "undo" | "redo" | "separator";
```

Built-in action names accepted by custom toolbar items.

##### `ToolbarIcon` — type

```ts
export type ToolbarIcon = string | Node | (() => Node);
```

Text, DOM node, or node factory used as toolbar icon content.

##### `ToolbarItem` — interface

```ts
export interface ToolbarItem { action?: ToolbarActionName; onClick?: (grid: Grid) => void; icon?: ToolbarIcon; title?: string; }
```

Built-in, separator, or custom callback item in the grid toolbar.

Members:
- `action` — Built-in action to bind (or "separator"). Omit when supplying `onClick`.
- `icon` — Button icon/content. Strings render as plain text; pass a DOM `Node` or a
factory returning one for SVG/HTML icons without using `innerHTML`.
- `onClick` — Custom click handler; receives the grid handle. Overrides `action`.
- `title` — Accessible tooltip.

##### `toTsv` — function

```ts
(range: Range, store: Store, options?: DelimitedTextOptions): string
```

Export a canonical data-space range as clipboard-compatible TSV (CRLF, no
BOM). Reversed corners are normalized; active sort and filter views do not
remap the supplied row coordinates. Values are injection-hardened. The
synchronous API returns one in-memory string and fetches at most
`maxWriterWindowRows` canonical rows per packed store read.

##### `toXlsxTable` — function

```ts
(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions): Promise<Uint8Array>
```

Exports a table model through the registered optional XLSX backend.

##### `toXlsxWorkbook` — function

```ts
(input: WorkbookSnapshot | Pick<Grid, "exportSnapshot">, options?: XlsxWorkbookOptions): Promise<Uint8Array>
```

Formula-preserving, multi-sheet workbook export through the optional XLSX backend.

##### `Transaction` — interface

```ts
export interface Transaction { patches: DocumentOp[]; epoch?: number; }
```

Low-level Store transaction. `epoch` provides optional optimistic
concurrency at the storage boundary.

Calling `Store.applyTransaction` bypasses Grid read-only checks and Grid
undo/redo history. Host-driven edits should use `Grid.applyTransaction`.

Members:
- `epoch` — Expected current store epoch; a mismatch returns a conflict without applying patches.
- `patches` — Ordered document operations submitted as one store commit.

##### `TransactionApplicationOptions` — interface

```ts
export interface TransactionApplicationOptions { source?: OperationSource; commitReason?: CommitReason; localReplay?: boolean; }
```

Source and commit classification used when applying a transaction.

Members:
- `commitReason` — Event classification; defaults to `api`.
- `localReplay` — Internal durable-queue replay: bypass remote hydration while retaining remote event semantics.
- `source` — Distinguishes host persistence input from local user/API output.

##### `TransactionResourceLimits` — interface

```ts
export interface TransactionResourceLimits { maxOperations: number; maxEncodedBytes: number; }
```

Public ceilings shared by transaction producers, persistence, transport,
and replay. Limits measure the submitted operation array itself, not the
logical cell area covered by compact operations.

Members:
- `maxEncodedBytes` — UTF-8 bytes in the JSON-encoded DocumentOp array; defaults to 8 MiB.
- `maxOperations` — DocumentOp objects in one atomic transaction; defaults to 10,000.

##### `TransactionResourceValidationResult` — type

```ts
export type TransactionResourceValidationResult = | { ok: true; operationCount: number; encodedBytes: number; } | { ok: false; issue: Extract<MutationIssue, { kind: "resource-limit" } | { kind: "invalid-operation" }>; };
```

Successful byte/count inspection or one structured transaction rejection.

##### `TransientResourcePeak` — interface

```ts
export interface TransientResourcePeak { readonly owner: string; readonly peakBytes: number; readonly allocations: number; readonly measurement: "instrumented-operation-peak"; }
```

Operation-scoped transient peak, excluded from retained owner totals.

##### `validateSheetName` — function

```ts
(name: string, existingNames?: readonly string[]): SheetNameValidationResult
```

Validate and canonicalize a SpreadsheetML worksheet name.

##### `validateTransactionResources` — function

```ts
(operations: readonly DocumentOp[], limits?: Readonly<TransactionResourceLimits>): TransactionResourceValidationResult
```

Incrementally validate the operation count and exact encoded payload size
without constructing a JSON string. Compact operation ranges are measured by
their serialized fields; their logical cell area is deliberately irrelevant.

##### `validateWorkbookSnapshot` — function

```ts
(input: unknown, options?: SnapshotValidationOptions): DocumentValidationResult
```

Validate and canonically order a schema-1 snapshot without hydrating runtime state.

##### `validateWorkbookTableName` — function

```ts
(input: string, existingNames?: readonly string[], maxLength?: number): WorkbookTableNameValidationResult
```

Validate and NFC-normalize an ECMA-compatible structured-reference name.

##### `ValidationPolicy` — type

```ts
export type ValidationPolicy = "reject" | "warn" | "allow";
```

Reject-or-warn policy attached to a data-validation rule.

##### `validWorkbookTable` — function

```ts
(table: WorkbookTable, sheet: Sheet, existing: readonly WorkbookTable[], limits?: Readonly<WorkbookTableResourceLimits>): boolean
```

Validate one canonical table against sheet bounds and workbook-global identities.

##### `VersionedCommentEvent` — interface

```ts
export interface VersionedCommentEvent { version: number; thread: CommentThread; clientMutationId?: string; }
```

Comment mutation paired with its assigned server version.

##### `VersionedOperation` — interface

```ts
export interface VersionedOperation { version: number; readonly operations: readonly DocumentOp[]; clientMutationId?: string; }
```

Remote document operations paired with a contiguous server version.

##### `VisibleWindowView` — interface

```ts
export interface VisibleWindowView { sheet: SheetId; rows: { start: number; end: number }; cols: readonly number[]; values: ArrayLike<CellScalar>; styleIds: Uint32Array; styles: readonly CellStyle[]; valueKinds?: Uint8Array; numberValues?: Float64Array; stringPoolIds?: Uint32Array; stringLocalIds?: Int32Array; stringPoolUpdateIds?: Uint32Array; stringPoolUpdateValues?: readonly string[]; localStrings?: readonly string[]; ffiCalls?: number; ffiBoundaryCalls?: number; ffiInputBytes?: number; ffiOutputBytes?: number; ffiLargestTransferBytes?: number; }
```

One rectangular window of resolved cells, returned by `Store.getVisibleWindow`
in a single call. The renderer paints from this view and MUST NOT call
`Store.getCell` per cell. `styleIds` are view-local indices into this view's
compact `styles` dictionary; on the worker renderer path, `styleIds.buffer` is
transferred during paint, so main-thread code must not read it after `paint`.

Lifetime: valid until the next store mutation or window refresh.

Members:
- `cols` — visible column indices, in paint order
- `ffiBoundaryCalls` — Every wasm-bindgen method/accessor/free crossing used by diagnostics.
- `ffiCalls` — Internal count of WASM boundary calls used to produce this window.
- `ffiInputBytes` — Exact copied input bytes for this packed boundary operation.
- `ffiLargestTransferBytes` — Largest individual copied buffer/string payload in this operation.
- `ffiOutputBytes` — Exact copied output bytes for this packed boundary operation.
- `localStrings` — Local non-pooled strings, currently formula error sentinels.
- `numberValues` — Raw numeric payloads for worker transfer; internal fast path.
- `rows` — end-exclusive row range
- `stringLocalIds` — Raw local-string indices for formula errors; `-1` means none.
- `stringPoolIds` — Raw global string-pool ids for worker transfer; `0xffffffff` means none.
- `stringPoolUpdateIds` — String-pool ids resolved by this window and safe for worker cache updates.
- `stringPoolUpdateValues` — String values parallel to `stringPoolUpdateIds`.
- `styleIds` — row-major view-local style ids, same length as `values`
- `styles` — compact window style dictionary indexed by `styleIds`
- `valueKinds` — Raw cell tags for worker transfer; internal fast path.
- `values` — row-major resolved values, length `(end-start) * cols.length`

##### `WASM_MEMORY_OWNERS` — variable

```ts
readonly ["wasm.dense.kinds", "wasm.dense.payloads", "wasm.dense.styles", "wasm.paged.kinds", "wasm.paged.payloads", "wasm.paged.styles", "wasm.paged.loaded-bitmaps", "wasm.paged.dirty-bitmaps", "wasm.paged.indexes", "wasm.string-pool.utf8", "wasm.string-pool.spans", "wasm.string-index", "wasm.formulas", "wasm.dependency-nodes", "wasm.dependency-edges", "wasm.sheet-indexes-metadata", "wasm.spill-ranges", "wasm.spill-owners", "wasm.spill-blockers"]
```

Stable ordered owner list encoded by the WASM store-memory protocol.

##### `WasmMemoryOwner` — type

```ts
export type WasmMemoryOwner = (typeof WASM_MEMORY_OWNERS)[number];
```

One retained-memory owner reported by the WASM cell store.

##### `Workbook` — interface

```ts
export interface Workbook { sheets: Sheet[]; activeSheet: SheetId; namedRanges?: NamedRangeSnapshot[]; }
```

Live workbook schema containing ordered sheets and the active sheet ID.

Members:
- `activeSheet` — Active sheet ID and initial tab presented when the grid is created.
- `namedRanges` — Formula names shared by the workbook or shadowed within a sheet scope.
- `sheets` — Sheets in display/tab order.

##### `WORKBOOK_SCHEMA_VERSION` — variable

```ts
1
```

Current workbook snapshot schema version accepted by Sheetwrite.

##### `WorkbookSnapshot` — interface

```ts
export interface WorkbookSnapshot { schemaVersion: 1; documentId?: string; version?: number; workbook: { activeSheet: SheetId; namedRanges?: NamedRangeSnapshot[]; }; sheets: SheetSnapshot[]; }
```

Schema-versioned serializable workbook document.

##### `WorkbookTable` — interface

```ts
export interface WorkbookTable { id: WorkbookTableId; name: string; range: Range; columns: WorkbookTableColumn[]; headerRow: boolean; totalsRow: boolean; style?: WorkbookTableStyle; unsupportedFeatures?: WorkbookTableUnsupportedFeature[]; }
```

Serializable canonical workbook table. Its range includes header/totals rows.

Members:
- `columns` — Ordered stable columns; length is exactly the table rectangle width.
- `headerRow` — Whether the first range row is the structured-reference header row.
- `name` — Workbook-global, case-insensitively unique structured-reference name.
- `range` — Inclusive table rectangle on one stable sheet ID.
- `totalsRow` — Whether the last range row is the structured-reference totals row.

##### `WorkbookTableColumn` — interface

```ts
export interface WorkbookTableColumn { id: string; name: string; totalsRowLabel?: string; }
```

Stable identity and display metadata for one ordered table column.

Members:
- `name` — Case-insensitively unique within the table.
- `totalsRowLabel` — Optional text written in the totals row. Formula cells remain authoritative cell sources.

##### `WorkbookTableId` — type

```ts
export type WorkbookTableId = string;
```

Stable identity for a workbook table. Names may change; IDs never do.

##### `WorkbookTableNameIssueCode` — type

```ts
export type WorkbookTableNameIssueCode = | "empty" | "too-long" | "invalid-characters" | "cell-reference" | "duplicate";
```

Stable reason code returned when a workbook table name is rejected.

##### `workbookTableNameKey` — function

```ts
(name: string): string
```

Locale-independent key used for table and table-column collision checks.

##### `WorkbookTableNameValidationResult` — type

```ts
export type WorkbookTableNameValidationResult = | { ok: true; name: string } | { ok: false; code: WorkbookTableNameIssueCode };
```

Result of validating and NFC-normalizing a workbook table name.

##### `WorkbookTablePatch` — interface

```ts
export interface WorkbookTablePatch { name?: string; range?: Range; columns?: WorkbookTableColumn[]; headerRow?: boolean; totalsRow?: boolean; style?: WorkbookTableStyle | null; unsupportedFeatures?: WorkbookTableUnsupportedFeature[]; }
```

Mutable table fields accepted by the explicit update operation.

##### `WorkbookTableResourceLimits` — interface

```ts
export interface WorkbookTableResourceLimits { maxTables: number; maxColumnsPerTable: number; maxNameLength: number; maxIdLength: number; maxStyleNameLength: number; maxUnsupportedFeaturesPerTable: number; }
```

Resource ceilings for canonical workbook-table metadata and identifiers.

##### `WorkbookTableStyle` — interface

```ts
export interface WorkbookTableStyle { name?: string; showFirstColumn?: boolean; showLastColumn?: boolean; showRowStripes?: boolean; showColumnStripes?: boolean; }
```

Bounded native subset of ECMA-376 table style information.

##### `WorkbookTableUnsupportedFeature` — type

```ts
export type WorkbookTableUnsupportedFeature = | "auto-filter" | "sort-state" | "calculated-columns" | "totals-functions" | "query-table" | "external-data" | "extensions";
```

OOXML table features deliberately retained as explicit loss metadata rather
than silently flattened into an ordinary range.

##### `XlsxResourceError` — class

```ts
class XlsxResourceError extends SheetwriteError { constructor(resource: keyof XlsxResourceLimits, limit: number, actual: number, operation: "import" | "export"); actual: number; limit: number; name: "XlsxResourceError"; resource: keyof XlsxResourceLimits }
```

Stable resource-limit failure surfaced before an XLSX codec allocates unsafe data.

##### `XlsxResourceLimits` — interface

```ts
export interface XlsxResourceLimits { maxInputBytes: number; maxOutputBytes: number; maxArchiveEntries: number; maxEntryUncompressedBytes: number; maxTotalUncompressedBytes: number; maxCompressionRatio: number; maxSheets: number; maxRowsPerSheet: number; maxColumnsPerSheet: number; maxCells: number; maxMerges: number; maxSharedStrings: number; maxStyles: number; maxXmlElements: number; maxXmlDepth: number; maxXmlAttributesPerElement: number; maxXmlTextBytes: number; }
```

Resource dimensions bounded by every XLSX import and export path.

Members:
- `maxArchiveEntries` — ZIP archive entries; defaults to 1,024.
- `maxCells` — Cells accounted by the active conversion path; defaults to 1,000,000.
- `maxColumnsPerSheet` — Columns in any worksheet; defaults to 16,384.
- `maxCompressionRatio` — Uncompressed-to-compressed ratio for one ZIP entry; defaults to 100.
- `maxEntryUncompressedBytes` — Uncompressed bytes in any one ZIP entry; defaults to 64 MiB.
- `maxInputBytes` — Compressed workbook input bytes; defaults to 32 MiB.
- `maxMerges` — Aggregate merged ranges; defaults to 100,000.
- `maxOutputBytes` — Encoded workbook output bytes; defaults to 128 MiB.
- `maxRowsPerSheet` — Rows in any worksheet; defaults to 1,048,576.
- `maxSharedStrings` — Shared-string table entries; defaults to 1,000,000.
- `maxSheets` — Workbook worksheets; defaults to 256.
- `maxStyles` — Style-related records; defaults to 65,536.
- `maxTotalUncompressedBytes` — Aggregate uncompressed ZIP entry bytes; defaults to 256 MiB.
- `maxXmlAttributesPerElement` — Attributes on any one XML element; defaults to 128.
- `maxXmlDepth` — Element nesting depth in any one XML part; defaults to 64.
- `maxXmlElements` — Elements in any one XML part; defaults to 2,000,000.
- `maxXmlTextBytes` — UTF-8 text bytes in one XML element or attribute; defaults to 16 MiB.

##### `XlsxTableExportBackend` — interface

```ts
export interface XlsxTableExportBackend { name: string; toXlsxTable(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions): Promise<Uint8Array>; }
```

Pluggable first-row-header, first-sheet table export backend.

##### `XlsxTableImportBackend` — interface

```ts
export interface XlsxTableImportBackend { name: string; fromXlsxTable( data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions, ): Promise<ColumnarData>; }
```

Pluggable table import backend. Parses raw `.xlsx` bytes into the same
`ColumnarData` shape `fromCsv` returns, so host ingestion code can stay
format-agnostic.

##### `XlsxWorkbookBackend` — interface

```ts
export interface XlsxWorkbookBackend { name: string; toXlsxWorkbook(snapshot: WorkbookSnapshot, options?: XlsxWorkbookOptions): Promise<Uint8Array>; fromXlsxWorkbook( data: ArrayBuffer | Uint8Array, options?: XlsxWorkbookOptions, ): Promise<WorkbookSnapshot>; }
```

Optional backend contract for complete workbook XLSX interchange.

##### `XlsxWorkbookOptions` — interface

```ts
export interface XlsxWorkbookOptions { signal?: AbortSignal; maxCells?: number; resourceLimits?: Partial<Omit<XlsxResourceLimits, "maxCells">>; onWarning?: (warning: XlsxWorkbookWarning) => void; }
```

Shared options passed to every registered table and workbook XLSX backend.

Members:
- `maxCells` — Cells accounted by the active conversion path; defaults to 1,000,000.
- `resourceLimits` — Positive overrides for every XLSX resource dimension except `maxCells`.
- `signal` — Abort before or between bounded codec operations.

##### `XlsxWorkbookWarning` — interface

```ts
export interface XlsxWorkbookWarning { code: | "boolean-literal" | "rich-text" | "hyperlink" | "unsupported-cell-value" | "unsupported-feature" | "external-relationship" | "external-formula" | "format-loss" | "validation-loss" | "invalid-metadata"; message: string; sheet?: string; cell?: string; part?: string; }
```

Structured fidelity warning emitted during XLSX conversion.

#### `@sheetwrite/core/adapter` — supported

Declaration target: `./dist/adapter.d.ts`
Source entry: `src/adapter.ts`
Page: https://sheetwrite.vercel.app/docs/api/core-adapter/

##### `applyChangedLiveGridOptions` — function

```ts
(controller: GridController, previous: GridOptions, next: GridOptions): void
```

Applies live-updatable adapter option changes to an existing Grid.

##### `createGridController` — function

```ts
<Id extends RowBridgeId = RowBridgeId>(host: HTMLElement, options: GridOptions, handlers: GridControllerHandlers<Id>, rowBridge?: RowBridge<Id>): GridController
```

Create a grid and wire its lifecycle once, so the React/Vue/Svelte adapters
(and any plain host) share a single, drift-free implementation instead of
each re-deriving the same create → subscribe → teardown behavior.

`initSheetwrite()` MUST already have been awaited; {@link createGrid} throws
otherwise.

### Live handlers
`handlers` is held **by reference**, not copied. Every event reads the
object's *current* fields (`handlers.onGridChange?.(…)`), so a host may swap
callbacks without rebuilding the grid. Framework adapters must mutate the
shared object only from their commit lifecycle; mutating it during render can
expose callbacks from work that never commits.

##### `createRowBridge` — function

```ts
<Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId>(options: RowBridgeOptions<Row, Id>): RowBridge<Id>
```

Create a typed bridge while preserving row and identity inference.

##### `createSimpleGridInput` — function

```ts
<Row extends Record<string, CellScalar>>(options: SimpleSheetwriteOptions<Row>): SimpleGridInput
```

Converts simple columns and row objects into canonical workbook and columnar input.

##### `createSimpleRowBridge` — function

```ts
<Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId>(options: SimpleSheetwriteOptions<Row, Id>): RowBridgeInstance<Id> | undefined
```

Creates the optional row bridge for a simple data-first input.

##### `DEFAULT_SIMPLE_COLUMN_WIDTH` — variable

```ts
120
```

Default pixel width assigned to simple adapter columns.

##### `extractGridOptions` — function

```ts
(source: Record<string, unknown>): GridOptions
```

Extracts advanced GridOptions from framework adapter props.

##### `getGridResetReason` — function

```ts
(previous: GridOptions, next: GridOptions): GridResetReason | null
```

Returns the first reset-sensitive adapter input that changed, if any.

##### `GRID_OPTION_POLICY` — variable

```ts
{ readonly workbook: "reset"; readonly data: "reset"; readonly datasource: "reset"; readonly datasourceStorage: "reset"; readonly renderer: "reset"; readonly workerUrl: "reset"; readonly presentation: "reset"; readonly renderers: "reset"; readonly editors: "reset"; readonly protectionResolver: "reset"; readonly mutationPolicy: "reset"; readonly transactionResourceLimits: "reset"; readonly hyperlinkActivation: "reset"; readonly theme: "live"; readonly readOnly: "live"; readonly config: "live"; readonly overscan: "live"; readonly minColumns: "live"; }
```

Classification of adapter options as live-updatable or reset-sensitive.

##### `GridAdapterEventHandlers` — interface

```ts
export interface GridAdapterEventHandlers<Id extends RowBridgeId = RowBridgeId> { onGridChange?: (event: ChangeEvent) => void; onRowDelta?: RowBridgeHandler<Id>; onSelectionChange?: (selection: Selection | null) => void; onViewportChange?: (event: GridEvents["scroll"]) => void; onEditBegin?: (event: GridEvents["edit-begin"]) => void; onEditCommit?: (event: GridEvents["edit-commit"]) => void; onSearch?: (result: GridEvents["search"]) => void; onActiveSheetChange?: (event: GridEvents["active-sheet"]) => void; onCommandStateChange?: (event: GridEvents["command-state-change"]) => void; onMutationRejected?: (event: GridEvents["mutation-rejected"]) => void; onRendererFallback?: (event: GridEvents["renderer-fallback"]) => void; onDatasourceError?: (event: GridEvents["datasource-error"]) => void; onExportError?: (event: GridEvents["export-error"]) => void; onReady?: (event: GridReadyEvent) => void; onInitializationError?: (error: SheetwriteError) => void; }
```

Framework-neutral readiness, change, and error callbacks shared by adapters.

Members:
- `onActiveSheetChange` — Fires after the visible sheet changes.
- `onCommandStateChange` — Receives observable undo/redo and formatting command state.
- `onDatasourceError` — Receives failed datasource requests and their errors.
- `onEditBegin` — Fires when cell editing begins.
- `onEditCommit` — Fires after an edit commits its parsed cell value.
- `onExportError` — Receives failures from built-in XLSX export actions.
- `onGridChange` — Receives every committed Grid change, including its applied transaction.
- `onInitializationError` — Receives a WASM initialization failure while the adapter remains mounted.
- `onMutationRejected` — Receives structured issues when a Grid mutation is rejected.
- `onReady` — Fires after the adapter publishes a ready Grid generation.
- `onRendererFallback` — Fires when worker rendering falls back to the main-thread canvas renderer.
- `onRowDelta` — Receives projected host-row effects when a row bridge is attached.
- `onSearch` — Receives refreshed search matches and active-match index.
- `onSelectionChange` — Receives the current selection, or `null` after it is cleared.
- `onViewportChange` — Receives visible row bounds and vertical scroll offset after scrolling.

##### `GridController` — interface

```ts
export interface GridController { readonly grid: Grid; setTheme(theme: Partial<Theme> | undefined): void; setReadOnly(readOnly: boolean): void; setConfig(config: GridConfig | undefined): void; setOverscan(overscan: number | undefined): void; setMinColumns(minColumns: number | undefined): void; destroy(): void; }
```

The lifecycle handle returned by {@link createGridController}: the live grid,
a theme passthrough, and a single teardown that detaches every subscription
and destroys the grid.

Members:
- `destroy` — Detach every event subscription and destroy the grid. Call exactly once.
- `grid` — The imperative core grid this controller owns.
- `setConfig` — Update built-in chrome and keyboard configuration without replacing the grid.
- `setMinColumns` — Live-update the minimum rendered column count without emitting user edits.
- `setOverscan` — Live-update the render overscan without replacing the grid; `undefined`
restores the default.
- `setReadOnly` — Update editability without replacing the owned grid.
- `setTheme` — Apply the host's declarative theme prop: option-level replacement via
{@link Grid.replaceTheme}; `undefined` restores CSS/default resolution.

##### `GridControllerHandlers` — interface

```ts
export interface GridControllerHandlers<Id extends RowBridgeId = RowBridgeId> { onGridChange?(event: ChangeEvent): void; onRowDelta?(projection: Parameters<RowBridgeHandler<Id>>[0]): void; onSelectionChange?(selection: Selection | null): void; onViewportChange?(event: GridEvents["scroll"]): void; onEditBegin?(event: GridEvents["edit-begin"]): void; onEditCommit?(event: GridEvents["edit-commit"]): void; onSearch?(result: GridEvents["search"]): void; onCommandStateChange?(event: GridEvents["command-state-change"]): void; onActiveSheetChange?(event: GridEvents["active-sheet"]): void; onMutationRejected?(event: GridEvents["mutation-rejected"]): void; onRendererFallback?(event: GridEvents["renderer-fallback"]): void; onDatasourceError?(event: GridEvents["datasource-error"]): void; onExportError?(event: GridEvents["export-error"]): void; }
```

Event callbacks a host (a framework adapter, or any plain app) hangs off a
grid's lifecycle.

The controller reads these fields **live** on every event — see
{@link createGridController} — so a host may swap any callback at any time by
mutating the fields of the object it passed in, without recreating the grid.
Every field is optional; a missing callback simply drops that event.

Members:
- `onActiveSheetChange` — Forwarded after the visible sheet changes.
- `onCommandStateChange` — Forwarded whenever command availability or formatting activity changes.
- `onDatasourceError` — Forwarded when a datasource request fails.
- `onEditBegin` — Forwarded when a cell editor opens.
- `onEditCommit` — Forwarded after a cell editor commits.
- `onExportError` — Forwarded when a built-in XLSX export action fails.
- `onGridChange` — Forwarded from the grid's `change` event (a committed transaction).
- `onMutationRejected` — Forwarded when a Grid mutation is rejected.
- `onRendererFallback` — Forwarded when worker rendering falls back to the main-thread canvas renderer.
- `onRowDelta` — Forwarded as a typed host-row projection when a bridge is attached.
- `onSearch` — Forwarded whenever the active search result changes.
- `onSelectionChange` — Forwarded from the grid's `selection` event; `null` when nothing is selected.
- `onViewportChange` — Forwarded from the grid's `scroll` event.

##### `GridReadyEvent` — interface

```ts
export interface GridReadyEvent { grid: Grid; generation: number; reason: GridReadyReason; }
```

Grid handle, generation, and reason published after adapter initialization.

Members:
- `generation` — One-based adapter generation, incremented whenever a Grid is replaced.
- `grid` — Live handle just published by the adapter; replaced on the next reset generation.
- `reason` — Whether readiness followed first initialization, an input reset, or a renderer reset.

##### `GridReadyReason` — type

```ts
export type GridReadyReason = "initial" | GridResetReason;
```

Reason an adapter published a ready Grid generation.

##### `GridResetReason` — type

```ts
export type GridResetReason = "input-reset" | "renderer-reset";
```

Reset-sensitive input change that requires an adapter to replace its Grid.

##### `GridSizeProps` — type

```ts
export type GridSizeProps = | { height: number | string; fill?: never; } | { fill: true; height?: never; };
```

Explicit width and height accepted by framework adapters.

##### `gridSizeStyle` — function

```ts
(size: OptionalGridSizeProps): Record<string, string>
```

Converts adapter size props into a host element style object.

##### `isSheetwriteError` — function

```ts
(value: unknown): value is SheetwriteErrorEnvelope
```

Narrow same-realm errors, cross-realm errors, and serialized failure envelopes.

##### `OptionalGridSizeProps` — interface

```ts
export interface OptionalGridSizeProps { height?: number | string; fill?: true; }
```

Optional width and height accepted by advanced framework adapters.

##### `RowBridge` — class

```ts
class RowBridge { constructor<Id extends RowBridgeId = RowBridgeId, Row extends Record<string, CellScalar> = Record<string, CellScalar>>(options: RowBridgeOptions<Row, Id>); columnKeys: (sheet?: SheetId) => readonly string[]; project: (event: ChangeEvent, requestedOperations?: readonly DocumentOp[], transactionId?: string) => RowBridgeProjection<Id>; reconcile: (input: RowBridgeReconciliationInput<Id>) => RowBridgeProjection<Id>; rowIds: (sheet?: SheetId) => readonly (Id | null)[] }
```

Projects canonical document transactions into host-owned row changes.

The bridge only owns compact data-space identity arrays. It never writes to
`defaultRows`, never renders, and never creates a second document store.

Members:
- `columnKeys` — Current semantic column keys in canonical column order.
- `project` — Project an applied Grid change as an accepted, transformed, or remote result.
- `reconcile` — Reconcile a canonical transaction response without synchronizing host rows implicitly.
- `rowIds` — Current data-space row identities; visual sort and filters do not affect this order.

##### `RowBridgeCell` — interface

```ts
export interface RowBridgeCell<Id extends RowBridgeId = RowBridgeId> { readonly sheet: SheetId; readonly row: number; readonly rowId: Id | null; readonly col: number; readonly columnKey: string | null; readonly previous: CellValue | undefined; readonly next: CellValue | undefined; }
```

A cell effect with semantic column and host row identity.

##### `RowBridgeClearDelta` — interface

```ts
export interface RowBridgeClearDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "clear"; readonly range: Range; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A clearRange effect expanded to its exact changed cells.

##### `RowBridgeColumn` — interface

```ts
export interface RowBridgeColumn<Row extends Record<string, CellScalar>> { readonly key: keyof Row & string; }
```

Semantic column key accepted by the row bridge.

##### `RowBridgeDelta` — type

```ts
export type RowBridgeDelta<Id extends RowBridgeId = RowBridgeId> = | RowBridgeCellDelta<Id> | RowBridgeRangeDelta<Id> | RowBridgeClearDelta<Id> | RowBridgePasteDelta<Id> | RowBridgeFillDelta<Id> | RowBridgeRowStructureDelta<Id> | RowBridgeMetadataDelta<Id> | RowBridgeHostActionDelta<Id> | RowBridgeUnprojectableDelta<Id>;
```

Every possible projection produced by a row bridge.

##### `RowBridgeFillDelta` — interface

```ts
export interface RowBridgeFillDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "fill"; readonly range: Range | null; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A fill-series transaction effect.

##### `RowBridgeHandler` — type

```ts
export type RowBridgeHandler<Id extends RowBridgeId = RowBridgeId> = ( projection: RowBridgeProjection<Id>, ) => void;
```

Callback accepted by imperative and framework adapters.

##### `RowBridgeHostActionDelta` — interface

```ts
export interface RowBridgeHostActionDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "host-action"; readonly action: | "add-sheet" | "remove-sheet" | "rename-sheet" | "move-sheet" | "set-sheet-visibility"; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A document operation that needs a host-side action rather than row mutation.

##### `RowBridgeId` — type

```ts
export type RowBridgeId = string | number;
```

A stable host identity for one data-space row.

##### `RowBridgeInsertContext` — interface

```ts
export interface RowBridgeInsertContext { readonly sheet: SheetId; readonly at: number; readonly offset: number; readonly transactionId: string; }
```

Context supplied when a canonical row insertion needs a host identity.

##### `RowBridgeMetadataDelta` — interface

```ts
export interface RowBridgeMetadataDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "metadata"; readonly metadata: | "column" | "row" | "sheet" | "merge" | "table" | "validation" | "hyperlink" | "protected-range" | "note" | "named-range"; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A document operation that changes workbook or column metadata.

##### `RowBridgeOptions` — interface

```ts
export interface RowBridgeOptions< Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId, > { readonly columns: readonly RowBridgeColumn<Row>[]; readonly defaultRows: readonly Row[]; readonly getRowId: (row: Row, index: number) => Id; readonly sheet?: SheetId; readonly createRowId?: (context: RowBridgeInsertContext) => Id; }
```

Options for the framework-neutral, opt-in row bridge.

Members:
- `createRowId` — Optional identity factory for rows created by an addRows operation.
- `sheet` — Sheet identity used by the simple data-first adapter. Defaults to `sheet1`.

##### `RowBridgePasteDelta` — interface

```ts
export interface RowBridgePasteDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "paste"; readonly range: Range | null; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A paste transaction effect. A paste can contain multiple canonical patches.

##### `RowBridgeProjection` — interface

```ts
export interface RowBridgeProjection<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transaction: RowBridgeTransaction; readonly deltas: readonly RowBridgeDelta<Id>[]; }
```

Result of projection or reconciliation.

##### `RowBridgeRangeDelta` — interface

```ts
export interface RowBridgeRangeDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "range"; readonly range: Range; readonly cells: readonly RowBridgeCell<Id>[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

A setRange/setBlock effect expanded to its exact changed cells.

##### `RowBridgeReconciliationInput` — interface

```ts
export interface RowBridgeReconciliationInput<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transactionId?: string; readonly source?: OperationSource; readonly version?: number; readonly operations?: readonly DocumentOp[]; readonly requestedOperations?: readonly DocumentOp[]; readonly event?: ChangeEvent; readonly commitReason?: CommitReason; readonly _type?: Id; }
```

Input to {@link RowBridge.reconcile}.

Members:
- `operations` — Canonical operations applied by the document engine.
- `requestedOperations` — Original host operations, used to identify a transformed acceptance.

##### `RowBridgeReconciliationStatus` — type

```ts
export type RowBridgeReconciliationStatus = | "accepted" | "transformed" | "rejected" | "out-of-order" | "duplicate" | "remote";
```

Reconciliation status for a canonical transaction response.

##### `RowBridgeRowStructureDelta` — interface

```ts
export interface RowBridgeRowStructureDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "row-structure"; readonly action: "insert" | "delete" | "move"; readonly sheet: SheetId; readonly at: number; readonly count: number; readonly from?: number; readonly to?: number; readonly inserted: readonly (Id | null)[]; readonly removed: readonly (Id | null)[]; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

Stable row identity effects for insert, delete, and move operations.

##### `RowBridgeTransaction` — interface

```ts
export interface RowBridgeTransaction { readonly id: string; readonly source: OperationSource; readonly commitReason: CommitReason; readonly epoch: number | undefined; readonly patches: readonly DocumentOp[]; }
```

The canonical transaction identity carried by each projected delta.

##### `rowBridgeTransactionId` — function

```ts
(transaction: Pick<Transaction, "patches" | "epoch">): string
```

Compute a deterministic identity for a canonical transaction.

##### `RowBridgeUnprojectableDelta` — interface

```ts
export interface RowBridgeUnprojectableDelta<Id extends RowBridgeId = RowBridgeId> { readonly kind: "unprojectable"; readonly reason: string; readonly transaction: RowBridgeTransaction; readonly transactionId: string; readonly source: OperationSource; readonly previous: unknown; readonly next: unknown; readonly operation: DocumentOp; readonly rowIds: readonly (Id | null)[]; }
```

An explicit projection record for an operation with no row-space meaning.

##### `SHEETWRITE_ERROR_CODES` — variable

```ts
readonly ["initialization-failed", "initialization-required", "datasource-request-failed", "renderer-fallback", "export-failed", "xlsx-import-failed", "optional-backend-unavailable", "delimited-text-resource-limit", "delimited-text-invalid-limit", "xlsx-resource-limit", "resource-limit", "invalid-snapshot", "aborted", "not-found", "commit-rejected", "unavailable", "blocked", "quota", "unsupported-schema", "transaction", "conflict", "limit", "invalid-limits", "invalid-version", "invalid-id", "invalid-operations", "operation-limit", "payload-limit", "response-id-mismatch", "future-distance-limit", "buffer-count-limit", "buffer-operation-limit", "buffer-byte-limit", "pending-count-limit", "pending-operation-limit", "pending-byte-limit", "late-echo", "remote-operations-rejected", "pending-capacity", "presence-failed", "revision-failed", "comment-failed", "sync-failed", "sync-storage-failed", "incomplete-data", "xlsx-invalid-options", "unsafe-hyperlink"]
```

Stable public failure codes. Messages are diagnostic and are not API contracts.

##### `SHEETWRITE_ERROR_OPERATIONS` — variable

```ts
readonly ["initialize", "create-grid", "datasource-request", "renderer-worker", "export-xlsx", "xlsx-import", "xlsx-export", "delimited-parse", "delimited-import", "delimited-encode", "delimited-export", "delimited-options", "snapshot-validate", "snapshot-allocate", "persistence", "pending-storage", "synchronize", "presence", "revision", "comments", "query", "hyperlink-activate"]
```

Stable operations at which a consumer-visible failure can surface.

##### `SheetwriteError` — class

```ts
class SheetwriteError extends Error implements SheetwriteErrorEnvelope { constructor(code: SheetwriteErrorCode, operation: SheetwriteErrorOperation, message: string, options?: SheetwriteErrorOptions); code: "aborted" | "blocked" | "buffer-byte-limit" | "buffer-count-limit" | "buffer-operation-limit" | "comment-failed" | "commit-rejected" | "conflict" | "datasource-request-failed" | "delimited-text-invalid-limit" | "delimited-text-resource-limit" | "export-failed" | "future-distance-limit" | "incomplete-data" | "initialization-failed" | "initialization-required" | "invalid-id" | "invalid-limits" | "invalid-operations" | "invalid-snapshot" | "invalid-version" | "late-echo" | "limit" | "not-found" | "operation-limit" | "optional-backend-unavailable" | "payload-limit" | "pending-byte-limit" | "pending-capacity" | "pending-count-limit" | "pending-operation-limit" | "presence-failed" | "quota" | "remote-operations-rejected" | "renderer-fallback" | "resource-limit" | "response-id-mismatch" | "revision-failed" | "sync-failed" | "sync-storage-failed" | "transaction" | "unavailable" | "unsafe-hyperlink" | "unsupported-schema" | "xlsx-import-failed" | "xlsx-invalid-options" | "xlsx-resource-limit"; context?: Readonly<Record<string, SheetwriteErrorContextValue>> | undefined; name: string; operation: "comments" | "create-grid" | "datasource-request" | "delimited-encode" | "delimited-export" | "delimited-import" | "delimited-options" | "delimited-parse" | "export-xlsx" | "hyperlink-activate" | "initialize" | "pending-storage" | "persistence" | "presence" | "query" | "renderer-worker" | "revision" | "snapshot-allocate" | "snapshot-validate" | "synchronize" | "xlsx-export" | "xlsx-import"; retryable?: boolean | undefined; toJSON: () => SheetwriteErrorEnvelope }
```

Canonical envelope for thrown and callback-delivered Sheetwrite failures.

##### `SheetwriteErrorCode` — type

```ts
export type SheetwriteErrorCode = (typeof SHEETWRITE_ERROR_CODES)[number];
```

Exhaustive stable discriminator for consumer-visible Sheetwrite failures.

##### `SheetwriteErrorContext` — type

```ts
export type SheetwriteErrorContext = Readonly<Record<string, SheetwriteErrorContextValue>>;
```

Stable, serialization-safe diagnostic context.

##### `SheetwriteErrorEnvelope` — interface

```ts
export interface SheetwriteErrorEnvelope { readonly name: string; readonly message: string; readonly code: SheetwriteErrorCode; readonly operation: SheetwriteErrorOperation; readonly context?: SheetwriteErrorContext; readonly retryable?: boolean; }
```

Structural form preserved across realms and JSON serialization.

##### `SheetwriteErrorOperation` — type

```ts
export type SheetwriteErrorOperation = (typeof SHEETWRITE_ERROR_OPERATIONS)[number];
```

Exhaustive stable operation discriminator for consumer-visible failures.

##### `SheetwriteInitializationProps` — interface

```ts
export interface SheetwriteInitializationProps { wasmSource?: BufferSource | URL | string | Request | WebAssembly.Module; onInitializationError?: (error: SheetwriteError) => void; }
```

Optional explicit WASM source and initialization error callback for adapters.

Members:
- `onInitializationError` — Called when WASM initialization fails while the adapter is mounted.
- `wasmSource` — Explicit source passed to process-wide WASM initialization; concurrent initialization is first-source-wins.

##### `SimpleColumn` — interface

```ts
export interface SimpleColumn<Row extends Record<string, CellScalar>> { key: keyof Row & string; title: string; width?: number; type?: CellFormat; numberFormat?: string; headerStyle?: CellStyle; editor?: string; cellStyle?: CellStyle; visible?: boolean; }
```

Column definition accepted by the adapters’ simple row-object API.

Members:
- `cellStyle` — Base style merged beneath cell-specific styles.
- `editor` — Name of a custom editor registered through `GridOptions.editors`.
- `headerStyle` — Style applied to the painted column header.
- `key` — Non-empty row-object key, unique within the column list.
- `numberFormat` — Excel number-format code used for number, date, or currency display.
- `title` — Semantic title painted in data-grid mode and written by table exports.
- `type` — Input and formatting type; defaults to `text`.
- `visible` — Set to `false` to exclude the column from the live view and table exports.
- `width` — Unzoomed width in CSS pixels; defaults to 120.

##### `SimpleGridInput` — interface

```ts
export interface SimpleGridInput { workbook: Workbook; data: ColumnarData; presentation: "data-grid"; }
```

Normalized workbook and columnar data produced from simple adapter props.

Members:
- `presentation` — Simple row-object input always opts into semantic data-grid presentation.

##### `SimpleSheetwriteOptions` — interface

```ts
export interface SimpleSheetwriteOptions< Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId, > { columns: readonly SimpleColumn<Row>[]; defaultRows: readonly Row[]; sheetName?: string; getRowId?: (row: Row, index: number) => Id; createRowId?: RowBridgeOptions<Row, Id>["createRowId"]; }
```

Framework-neutral simple columns, rows, sizing, and grid options.

Members:
- `createRowId` — Optional identity factory for rows inserted by the Grid.
- `getRowId` — Opt-in stable data-row identity extractor.

#### `@sheetwrite/core/browser` — supported

Declaration target: `./dist/indexeddb.d.ts`
Source entry: `src/indexeddb.ts`
Page: https://sheetwrite.vercel.app/docs/api/core-browser/

##### `IndexedDbPendingCommitStorage` — class

```ts
class IndexedDbPendingCommitStorage implements PendingCommitStorage { constructor(options?: IndexedDbPendingCommitStorageOptions); close: () => void; load: (documentId: string, options: PendingCommitLoadOptions) => Promise<readonly PendingCommit[]>; put: (commit: PendingCommit, signal?: AbortSignal) => Promise<void>; remove: (documentId: string, clientMutationId: string, signal?: AbortSignal) => Promise<void>; replace: (documentId: string, expectedClientMutationIds: readonly string[], commits: readonly PendingCommit[], signal?: AbortSignal) => Promise<void> }
```

Browser-only durable pending queue. Import it from `@sheetwrite/core/browser`;
the package's root entrypoint never evaluates IndexedDB globals.

Members:
- `replace` — Atomically replaces one document queue only if its ordered IDs still match
the caller's expected view.

##### `IndexedDbPendingCommitStorageError` — class

```ts
class IndexedDbPendingCommitStorageError extends SheetwriteError { constructor(code: IndexedDbPendingCommitStorageErrorCode, message: string, options?: ErrorOptions); name: "IndexedDbPendingCommitStorageError" }
```

Typed IndexedDB failure raised by durable pending-commit storage.

##### `IndexedDbPendingCommitStorageErrorCode` — type

```ts
export type IndexedDbPendingCommitStorageErrorCode = | "unavailable" | "blocked" | "aborted" | "quota" | "unsupported-schema" | "transaction" | "conflict" | "limit";
```

Stable category for an IndexedDB pending-storage failure.

##### `IndexedDbPendingCommitStorageOptions` — interface

```ts
export interface IndexedDbPendingCommitStorageOptions { databaseName?: string; storeName?: string; }
```

Database and store naming options for durable pending commits.

#### `@sheetwrite/core/shell` — supported

Declaration target: `./dist/shell.d.ts`
Source entry: `src/shell.ts`
Page: https://sheetwrite.vercel.app/docs/api/core-shell/

##### `createFormulaBar` — function

```ts
(host: HTMLElement, grid: Grid, options?: FormulaBarOptions): FormulaBarPiece
```

Detached formula bar: mirrors the focused cell's editable text (exact
formula source, else literal text) and commits on Enter through the grid's
undoable transaction path, targeting the data address captured with the
draft — correct even under an active sort/filter view. A focused, dirty
draft is never overwritten by selection/change events; Escape restores the
last stable text.

##### `createNameBox` — function

```ts
(host: HTMLElement, grid: Grid, options?: NameBoxOptions): ShellPiece
```

A1 jump box: shows the focused cell's reference and navigates on Enter.
Invalid or out-of-bounds references set `aria-invalid` and make no grid
calls; Escape restores the displayed reference.

##### `createSelectionStatus` — function

```ts
(host: HTMLElement, grid: Grid): ShellPiece
```

`<output role="status">` that follows the grid's selection. Text nodes only;
polite live region so screen readers announce changes without interrupting.

##### `createSpreadsheetShell` — function

```ts
(host: HTMLElement, options: SpreadsheetShellOptions): SpreadsheetShell
```

Mount a complete spreadsheet shell into `host`: toolbar row, formula row
(name box + formula bar), the grid, and a bottom row with sheet tabs and a
selection status. The host must have a real size; the shell fills it. Returns
the shell handle; `destroy` tears down every piece, the grid, and the shell
DOM, and is safe to call twice.

##### `createToolbar` — function

```ts
(host: HTMLElement, grid: Grid, options?: ToolbarOptions): ShellPiece
```

Mount a toolbar bound to `grid.actions` (custom items receive the grid).
Mouse clicks never steal grid focus; keyboard users get local
Left/Right/Home/End movement across the controls while the toolbar has
focus. Returns the mounted piece with an idempotent `destroy`.

##### `describeSelection` — function

```ts
(selection: Selection | null): string
```

Human phrase for a selection's geometry; blank for null/single-cell.

##### `FormulaBarOptions` — interface

```ts
export interface FormulaBarOptions { focusGrid?: () => void; label?: string; }
```

Host elements and callbacks used to bind a formula bar to a Grid.

Members:
- `focusGrid` — Called after Enter commits or Escape cancels, so the grid regains focus.
- `label` — Accessible label (default "Formula bar").

##### `FormulaBarPiece` — interface

```ts
export interface FormulaBarPiece { setReadOnly(readOnly: boolean): void; readonly element: HTMLElement; destroy(): void; }
```

A formula bar piece; `setReadOnly` blocks commits without unmounting.

##### `NameBoxOptions` — interface

```ts
export interface NameBoxOptions { focusGrid?: () => void; label?: string; }
```

Host elements and callbacks used to bind a name box to a Grid.

Members:
- `focusGrid` — Called after a successful Enter navigation so the grid regains focus.
- `label` — Accessible label (default "Cell reference").

##### `ShellPiece` — interface

```ts
export interface ShellPiece { readonly element: HTMLElement; destroy(): void; }
```

A mounted shell piece: its root element plus an idempotent teardown.

##### `SpreadsheetShell` — interface

```ts
export interface SpreadsheetShell { readonly grid: Grid; readonly element: HTMLElement; setTheme(theme: Partial<Theme>): void; setReadOnly(readOnly: boolean): void; setGridConfig(config: GridConfig | undefined): void; setActiveSheet(id: SheetId): void; destroy(): void; }
```

Disposable controller for the framework-neutral spreadsheet shell.

Members:
- `element` — The shell's root element (already appended to the mount host).
- `grid` — The single grid the shell owns; use it for data, search, and actions.
- `setGridConfig` — Reconfigure the grid; the shell keeps its own toolbar/tabs suppressed.

##### `SpreadsheetShellOptions` — interface

```ts
export interface SpreadsheetShellOptions { grid: GridOptions; toolbar?: readonly ToolbarItem[]; onChange?: (event: ChangeEvent) => void; onSelectionChange?: (selection: Selection | null) => void; onReady?: (grid: Grid) => void; }
```

Host elements and feature options used to create a spreadsheet shell.

Members:
- `grid` — Options for the single grid the shell owns. `initSheetwrite` must already be awaited.
- `onChange` — Event callbacks forwarded from the owned grid.
- `toolbar` — Toolbar items (default: the full built-in action set).

##### `ToolbarOptions` — interface

```ts
export interface ToolbarOptions { items?: readonly ToolbarItem[]; icons?: Partial<Record<ToolbarActionName, ToolbarIcon>>; label?: string; }
```

Host element and configuration used to create the built-in toolbar.

Members:
- `icons` — Per-action icon overrides, exactly like `GridConfig.icons`.
- `items` — Items to render; defaults to the full built-in action set.
- `label` — Accessible toolbar label (default "Spreadsheet formatting").

#### `@sheetwrite/core/shell.css` — asset

Declaration target: `./shell.css`
Page: https://sheetwrite.vercel.app/docs/api/core-shell-css/

#### `@sheetwrite/core/styles.css` — asset

Declaration target: `./styles.css`
Page: https://sheetwrite.vercel.app/docs/api/core-styles-css/

#### `@sheetwrite/core/testing` — test-only

Declaration target: `./dist/testing.d.ts`
Source entry: `src/testing.ts`
Page: https://sheetwrite.vercel.app/docs/api/core-testing/

##### `CanvasTestStubOptions` — interface

```ts
export interface CanvasTestStubOptions { width?: number; height?: number; }
```

Layout dimensions installed by {@link installCanvasTestStubs} in DOM test environments.

Members:
- `height` — Stubbed `clientHeight` for every element. Default 400.
- `width` — Stubbed `clientWidth` for every element (happy-dom/jsdom have no layout). Default 800.

##### `installCanvasTestStubs` — function

```ts
(options?: CanvasTestStubOptions): () => void
```

Install the canvas + layout stubs a DOM test environment (jsdom/happy-dom)
needs before `createGrid` can mount — without them the renderer throws
`"Sheetwrite: 2D canvas context is unavailable"`. Returns a restore
function that undoes every patch.

The installed `getContext("2d")` returns a per-canvas
{@link RecordingContext2D}; re-request it from a mounted canvas to assert
paint activity. Nothing is painted — assert grid STATE, not pixels.
Test-only: never import from production code.

##### `installDatasourceClockForTest` — function

```ts
(now: () => number): () => void
```

Installs a deterministic monotonic clock through the public testing entrypoint.

##### `RecordingContext2D` — interface

```ts
export interface RecordingContext2D { readonly calls: Record<string, number>; fillStyle: string; strokeStyle: string; font: string; textAlign: string; textBaseline: string; lineWidth: number; [method: string]: unknown; }
```

The stub 2D context the canvas test stubs install: every method is a no-op
that counts its invocations in `calls`, so tests can assert paint activity
(e.g. `ctx.calls.fillText > 0`) without a real canvas.

Members:
- `calls` — Per-method invocation counts, keyed by the 2D-context method name.

#### `@sheetwrite/core/worker` — supported

Declaration target: `./dist/worker.d.ts`
Source entry: `src/worker.ts`
Page: https://sheetwrite.vercel.app/docs/api/core-worker/

##### `createWorkerMessageHandler` — function

```ts
(postAcknowledgement: (message: WorkerAcknowledgement) => void): (message: unknown) => void
```

Build the worker-side protocol handler. Keeping the mutable render state
inside the returned closure lets tests exercise the real message contract
without booting a browser Worker.

##### `WorkerAcknowledgement` — type

```ts
export type WorkerAcknowledgement = | { type: "ready" } | { type: "fatal"; reason: string } | { type: "painted" };
```

Lifecycle and frame acknowledgements posted back to the sender.

### `@sheetwrite/react`

#### `@sheetwrite/react` — supported

Declaration target: `./dist/index.d.ts`
Source entry: `src/index.tsx`
Page: https://sheetwrite.vercel.app/docs/api/react/

##### `CellEditor` — interface

```ts
export interface CellEditor { mount(host: HTMLElement, context: CellEditorContext): CellEditorInstance; }
```

Framework-neutral named editor definition registered through GridOptions.editors.

##### `CellEditorContext` — interface

```ts
export interface CellEditorContext { readonly grid: Grid; readonly address: Readonly<CellAddress>; readonly viewAddress: Readonly<CellAddress>; readonly column: Readonly<Column>; readonly value: CellScalar; readonly text: string; readonly initialInput: string | undefined; readonly selectAll: boolean; readonly label: string; readonly signal: AbortSignal; commit(value: string, navigation?: CellEditorNavigation): void; cancel(): void; }
```

Immutable state and guarded completion callbacks for one mounted editor.

##### `CellEditorInstance` — interface

```ts
export interface CellEditorInstance { update(context: CellEditorContext): void; reposition(rect: CellEditorRect): void; commit(navigation: CellEditorNavigation): string | undefined | Promise<string | undefined>; cancel(): void; destroy(): void; }
```

Retained lifecycle returned by a custom editor's mount method.

##### `CellEditorNavigation` — type

```ts
export type CellEditorNavigation = "down" | "right" | "left" | "none";
```

Selection movement applied after a successful editor commit.

##### `CellScalar` — type

```ts
export type CellScalar = string | number | boolean | null;
```

A scalar that can be displayed directly.

##### `Grid` — interface

```ts
export interface Grid { readonly store: Store; readonly actions: GridActions; getRuntimeResourceSnapshot(operation: RuntimeResourceOperation, phase: RuntimeResourcePhase, runtime?: RuntimeMemoryObservation): RuntimeResourceSnapshot; getCommandState(command: GridCommandName): GridCommandState; setActiveSheet(id: SheetId): void; scrollToCell(addr: CellAddress): void; getCellAtPoint(clientX: number, clientY: number): CellAddress | null; getActiveSheet(): SheetId; getCellInput(row: number, col: number): CellInputSnapshot | null; getSelection(): Selection | null; setSelection(sel: Selection | null): void; setTheme(theme: Partial<Theme>): void; replaceTheme(theme: Partial<Theme> | undefined): void; getEffectiveTheme(): Theme; setReadOnly(readOnly: boolean): void; setConfig(config: GridConfig | undefined): void; applyTransaction(transaction: GridTransaction): ApplyTransactionResult; exportSnapshot(): WorkbookSnapshot; applyRemoteOperations(operations: readonly DocumentOp[], options?: RemoteOperationOptions): ApplyTransactionResult; defineCellRenderer(name: string, renderer: CellRenderer): void; aggregate(col: number, op: AggregateOp): number; sortBy(col: number, ascending?: boolean): void; sortByMulti(keys: readonly SortKey[]): void; filterBy(col: number, needle: string): void; setColumnFilter(col: number, filter: ColumnFilter | null): void; setSort(keys: readonly SortKey[]): ApplyTransactionResult; getColumnFilters(): ReadonlyMap<number, ColumnFilter>; distinctValues(col: number, limit?: number): CellScalar[]; hideRows(rows: readonly number[]): void; showRows(rows?: readonly number[]): void; hiddenRows(): readonly number[]; hideColumns(cols?: readonly number[]): void; showColumns(cols?: readonly number[]): void; hiddenColumns(): readonly number[]; groupRows(start: number, end: number): void; ungroupRows(start: number, end: number): void; setGroupCollapsed(start: number, collapsed: boolean): void; rowGroups(): readonly RowGroup[]; clearView(): void; undo(): void; redo(): void; exportCsv(filename: string): void; exportXlsx(filename: string): Promise<void>; search(query: string, opts?: SearchOptions): SearchResult; findNext(): SearchResult; findPrev(): SearchResult; clearSearch(): void; replaceCurrent(replacement: string): SearchResult; replaceAll(replacement: string): ReplaceResult; insertRows(at: number, count?: number): void; removeRows(at: number, count?: number): void; insertColumns(at: number, count?: number): void; removeColumns(at: number, count?: number): void; addSheet(input: AddSheetInput): SheetLifecycleResult; removeSheet(id: SheetId): SheetLifecycleResult; renameSheet(id: SheetId, name: string): SheetLifecycleResult; moveSheet(id: SheetId, toIndex: number): SheetLifecycleResult; setSheetVisibility(id: SheetId, visibility: SheetVisibility): SheetLifecycleResult; setConditionalFormats(rules: readonly ConditionalFormatRule[]): void; setHyperlink(hyperlink: CellHyperlink): ApplyTransactionResult; removeHyperlink(id: string): ApplyTransactionResult; getHyperlink(addr: CellAddress): CellHyperlink | null; activateHyperlink(addr: CellAddress): boolean; setValidationRule(rule: DataValidationRule): ApplyTransactionResult; removeValidationRule(id: string): ApplyTransactionResult; setProtectedRange(protectedRange: ProtectedRange): ApplyTransactionResult; removeProtectedRange(id: string): ApplyTransactionResult; setProtectionResolver(resolver: ProtectionResolver | undefined, mode?: MutationPolicyMode): void; setNote(addr: CellAddress, text: string | null): ApplyTransactionResult; getNote(addr: CellAddress): string | null; setOverscan(overscan?: number): void; setMinColumns(minColumns?: number): void; highlightCells(ranges: readonly HighlightRange[] | null, color?: string): void; setPresenceOverlays(overlays: readonly PresenceOverlay[] | null): void; styleRange(range: Range, style: Partial<CellStyle> | null): void; beginEdit(row: number, col: number, initial?: string, selectAll?: boolean): void; dataEdge(row: number, col: number, dRow: number, dCol: number): number | null; setRowHeight(row: number, height: number): void; setColumnWidth(col: number, width: number): void; autoFitRows(range?: Range): void; autoFitColumns(cols?: readonly number[]): void; setFrozen(rows: number, cols?: number): void; setZoom(zoom: number): void; getZoom(): number; rendererKind(): "canvas" | "worker"; on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void; refresh(): void; destroy(): void; }
```

Imperative grid handle for document commands, events, rendering, and teardown.

Members:
- `actions` — Imperative action surface for binding custom toolbars/menus.
- `activateHyperlink` — Validate and emit a host-owned activation event. External targets are never
opened by Sheetwrite; internal navigation occurs only under the explicit policy.
- `addSheet` — Add a sheet with a stable ID and return its actionable transaction outcome.
- `aggregate` — Column aggregate over the active sheet's data.
- `applyRemoteOperations` — Apply host-supplied operations without undo history or outgoing dirty state.
The resulting change event has `source: "remote"`.
- `applyTransaction` — Apply arbitrary patches as one undoable Grid commit. No-op when read-only.
Use `Store.applyTransaction` only for low-level writes that intentionally
bypass Grid history and policy.
- `autoFitColumns` — Explicitly resize columns from a bulk worksheet read.
- `autoFitRows` — Explicitly resize rows to fit wrapped content; never runs during paint.
- `beginEdit` — Open the cell editor at a view cell, optionally seeding text / selecting all.
- `clearSearch` — Clear the current search and its highlights.
- `clearView` — Clear any active sort/filter view.
- `dataEdge` — Ctrl+Arrow-style jump target: the data-run edge from (row, col) on the
moved axis (row for vertical moves, col for horizontal), or null when the
store is not columnar. Under an active sort/filter view, `row` is a view
position and vertical moves return view positions. For hosts building
their own keymaps (`config.keyboard`).
- `distinctValues` — Distinct resolved values of a column in first-seen order. Defaults to
1,000 values for bounded filter menus; pass 0 to request an uncapped scan.
- `exportSnapshot` — Deterministically export the complete authoritative workbook document.
- `filterBy` — Filter the displayed rows to those whose column text contains `needle`.
- `findNext` — Move the active match to the next match and scroll it into view.
- `findPrev` — Move the active match to the previous match and scroll it into view.
- `getActiveSheet` — Id of the currently visible sheet.
- `getCellAtPoint` — Resolve browser viewport coordinates to an active-sheet cell for host-owned
menus and interactions. Returns null outside the cell body.
- `getCellInput` — Editable snapshot of the cell at a view position on the active sheet, or
null when out of bounds. See {@link CellInputSnapshot}.
- `getColumnFilters` — Active column filters on the active sheet, keyed by column index.
- `getCommandState` — Query undo/redo availability and formatting active/mixed/disabled state.
- `getEffectiveTheme` — The effective (post-zoom) theme the renderer is currently painting with.
- `getRuntimeResourceSnapshot` — Versioned coarse runtime ownership snapshot, including datasource state.
- `groupRows` — Define a collapsible row group over a data-row range (end-inclusive).
- `hiddenColumns` — Currently hidden columns on the active sheet.
- `hiddenRows` — Currently hidden data rows on the active sheet.
- `hideColumns` — Hide columns through one bulk-safe metadata transaction.
- `hideRows` — Hide the given data rows (composes with filters/sort).
- `highlightCells` — Highlight arbitrary cell ranges (null clears). Per-range `color` wins over the call color.
- `redo` — Redo the last undone cell edit.
- `removeSheet` — Remove a sheet while preserving at least one visible worksheet.
- `rendererKind` — Which renderer is actually active: `"worker"` when the OffscreenCanvas
worker constructed successfully, `"canvas"` otherwise (including after a
`renderer-fallback`).
- `replaceAll` — Replace every current match in a single undoable transaction (one
`undo()` restores them all), then re-scan. Formula/ref cells are skipped
and not counted. No-op when read-only.
- `replaceCurrent` — Replace the active match with `replacement`, then advance to the next match
(re-scanning against the new data). Only literal text/number cells are
eligible; formula and ref cells are skipped (formula source is never
rewritten). Honors the active {@link SearchOptions} (matchCase; `wholeCell`
swaps the entire cell). The write flows through the grid's commit path as
one undoable step. No-op when read-only or when there is no active match.
- `replaceTheme` — Option-level replacement: re-run construction-time resolution
(`DEFAULT_THEME < CSS custom properties < theme`) with the new partial.
`undefined` restores the CSS-variable/default resolution. Adapters call
this for their declarative `theme` prop; imperative patching stays on
{@link setTheme}.
- `rowGroups` — Row groups on the active sheet.
- `search` — Find cells matching `query`; highlights matches, emits `search`, returns the result.
- `setColumnFilter` — Set or clear (null) one column's filter. All column filters AND together
and compose with the active sort and hidden rows.
- `setColumnWidth` — Set one column's width via an undoable `setColumn` patch.
- `setConfig` — Reconfigure built-in chrome and keyboard handling without replacing the
Grid or clearing selection/history. Construction-bound GridOptions are not
accepted here.
- `setFrozen` — Pin the first `rows` view rows and `cols` columns; they stay visible while
the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.
- `setGroupCollapsed` — Collapse/expand a row group; collapsing hides its rows.
- `setMinColumns` — Live-update the minimum rendered column count. Increasing the minimum
silently extends presentation padding; `undefined` restores the default.
- `setOverscan` — Live-update the render window overscan (row/column positions painted past
each edge); `undefined` restores the default of 6.
- `setPresenceOverlays` — Replace ephemeral remote-presence overlays; null clears every collaborator.
- `setReadOnly` — Update editability without replacing the Grid or clearing session state.
- `setRowHeight` — Set one row's persistent display height through document history.
- `setSheetVisibility` — Set host-visible worksheet state; stock UI never offers `veryHidden`.
- `setSort` — Persisted multi-key sort of the active sheet.
- `setTheme` — Imperative patch: merge `theme` into the accumulated base theme.
- `setZoom` — Content zoom factor (0.5–2): scales row/column geometry and fonts.
- `showColumns` — Show columns through one bulk-safe metadata transaction.
- `showRows` — Show the given data rows again, or every hidden row when omitted.
- `sortBy` — Sort the displayed rows by a column (does not mutate stored data).
- `sortByMulti` — Multi-key sort of the displayed rows (first key primary; stable).
- `styleRange` — Merge `style` into every cell of `range` (null clears cell styles) as one
undoable transaction. Styles land in the store and paint in the canvas —
unlike {@link highlightCells}, which draws a translucent overlay above it.
- `undo` — Undo the last recorded cell edit.
- `ungroupRows` — Remove a row group (rows become visible if the group was collapsed).

##### `GridCommandName` — type

```ts
export type GridCommandName = Exclude<ToolbarActionName, "separator">;
```

Built-in command names accepted by state queries and change events.

##### `GridCommandState` — interface

```ts
export interface GridCommandState { readonly disabled: boolean; readonly activity: "inactive" | "active" | "mixed"; }
```

Observable availability and selection-derived activity for one command.

##### `GridReadyEvent` — interface

```ts
export interface GridReadyEvent { grid: Grid; generation: number; reason: GridReadyReason; }
```

Grid handle, generation, and reason published after adapter initialization.

Members:
- `generation` — One-based adapter generation, incremented whenever a Grid is replaced.
- `grid` — Live handle just published by the adapter; replaced on the next reset generation.
- `reason` — Whether readiness followed first initialization, an input reset, or a renderer reset.

##### `RowBridge` — class

```ts
class RowBridge { constructor<Id extends RowBridgeId = RowBridgeId, Row extends Record<string, CellScalar> = Record<string, CellScalar>>(options: RowBridgeOptions<Row, Id>); columnKeys: (sheet?: SheetId) => readonly string[]; project: (event: ChangeEvent, requestedOperations?: readonly DocumentOp[], transactionId?: string) => RowBridgeProjection<Id>; reconcile: (input: RowBridgeReconciliationInput<Id>) => RowBridgeProjection<Id>; rowIds: (sheet?: SheetId) => readonly (Id | null)[] }
```

Projects canonical document transactions into host-owned row changes.

The bridge only owns compact data-space identity arrays. It never writes to
`defaultRows`, never renders, and never creates a second document store.

Members:
- `columnKeys` — Current semantic column keys in canonical column order.
- `project` — Project an applied Grid change as an accepted, transformed, or remote result.
- `reconcile` — Reconcile a canonical transaction response without synchronizing host rows implicitly.
- `rowIds` — Current data-space row identities; visual sort and filters do not affect this order.

##### `RowBridgeDelta` — type

```ts
export type RowBridgeDelta<Id extends RowBridgeId = RowBridgeId> = RowBridgeCellDelta<Id> | RowBridgeRangeDelta<Id> | RowBridgeClearDelta<Id> | RowBridgePasteDelta<Id> | RowBridgeFillDelta<Id> | RowBridgeRowStructureDelta<Id> | RowBridgeMetadataDelta<Id> | RowBridgeHostActionDelta<Id> | RowBridgeUnprojectableDelta<Id>;
```

Every possible projection produced by a row bridge.

##### `RowBridgeHandler` — type

```ts
export type RowBridgeHandler<Id extends RowBridgeId = RowBridgeId> = (projection: RowBridgeProjection<Id>) => void;
```

Callback accepted by imperative and framework adapters.

##### `RowBridgeId` — type

```ts
export type RowBridgeId = string | number;
```

A stable host identity for one data-space row.

##### `RowBridgeProjection` — interface

```ts
export interface RowBridgeProjection<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transaction: RowBridgeTransaction; readonly deltas: readonly RowBridgeDelta<Id>[]; }
```

Result of projection or reconciliation.

##### `Sheetwrite` — variable

```ts
<Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId>(props: SheetwriteProps<Row, Id> & { ref?: ForwardedRef<Grid>; }): ReactElement
```

Convenience component for local object rows. It derives a single-sheet workbook from
`columns`, `defaultRows`, and `sheetName`, initializes Sheetwrite, and owns the `Grid`
through prop-driven resets and unmount cleanup. Pass a `ref` to access the live `Grid`;
use `SheetwriteGrid` when the host already owns a workbook or datasource.

##### `SheetwriteGrid` — variable

```ts
<Id extends RowBridgeId = RowBridgeId>(props: SheetwriteGridProps<Id> & { ref?: ForwardedRef<Grid>; }): ReactElement
```

Advanced framework component with inferred row-bridge identity.

##### `SheetwriteGridProps` — interface

```ts
export interface SheetwriteGridProps<Id extends RowBridgeId = RowBridgeId> { rowBridge?: RowBridge<Id>; onRowDelta?: RowBridgeHandler<Id>; onMutationRejected?: GridAdapterEventHandlers["onMutationRejected"]; onRendererFallback?: GridAdapterEventHandlers["onRendererFallback"]; onDatasourceError?: GridAdapterEventHandlers["onDatasourceError"]; onExportError?: GridAdapterEventHandlers["onExportError"]; onReady?: GridAdapterEventHandlers["onReady"]; className?: string; style?: CSSProperties; fallback?: ReactNode; height?: number | string; fill?: true; onGridChange?: (event: ChangeEvent) => void; onSelectionChange?: (selection: Selection | null) => void; workbook: Workbook; data?: ColumnarData; datasource?: DataSource; datasourceStorage?: DataSourceStorageOptions; renderer?: "canvas" | "worker"; workerUrl?: string | URL; presentation?: GridPresentation; theme?: Partial<Theme>; readOnly?: boolean; hyperlinkActivation?: "event-only" | "internal-navigation" | "disabled"; protectionResolver?: ProtectionResolver; mutationPolicy?: MutationPolicyMode; transactionResourceLimits?: Partial<TransactionResourceLimits>; renderers?: Record<string, CellRenderer>; editors?: Record<string, CellEditor>; overscan?: number; minColumns?: number; config?: GridConfig; onViewportChange?: (event: GridEvents["scroll"]) => void; onEditBegin?: (event: GridEvents["edit-begin"]) => void; onEditCommit?: (event: GridEvents["edit-commit"]) => void; onSearch?: (result: GridEvents["search"]) => void; onActiveSheetChange?: (event: GridEvents["active-sheet"]) => void; onCommandStateChange?: (event: GridEvents["command-state-change"]) => void; onInitializationError?: (error: SheetwriteError) => void; wasmSource?: BufferSource | URL | string | Request | WebAssembly.Module; }
```

Advanced framework adapter props for workbook data or datasource ownership.

Members:
- `aria-activedescendant` — Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
- `aria-atomic` — Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute.
- `aria-autocomplete` — Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be
presented if they are made.
- `aria-braillelabel` — Defines a string value that labels the current element, which is intended to be converted into Braille.
- `aria-brailleroledescription` — Defines a human-readable, author-localized abbreviated description for the role of an element, which is intended to be converted into Braille.
- `aria-checked` — Indicates the current "checked" state of checkboxes, radio buttons, and other widgets.
- `aria-colcount` — Defines the total number of columns in a table, grid, or treegrid.
- `aria-colindex` — Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid.
- `aria-colindextext` — Defines a human readable text alternative of aria-colindex.
- `aria-colspan` — Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
- `aria-controls` — Identifies the element (or elements) whose contents or presence are controlled by the current element.
- `aria-current` — Indicates the element that represents the current item within a container or set of related elements.
- `aria-describedby` — Identifies the element (or elements) that describes the object.
- `aria-description` — Defines a string value that describes or annotates the current element.
- `aria-details` — Identifies the element that provides a detailed, extended description for the object.
- `aria-disabled` — Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.
- `aria-dropeffect` — Indicates what functions can be performed when a dragged object is released on the drop target.
- `aria-errormessage` — Identifies the element that provides an error message for the object.
- `aria-expanded` — Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
- `aria-flowto` — Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion,
allows assistive technology to override the general default of reading in document source order.
- `aria-grabbed` — Indicates an element's "grabbed" state in a drag-and-drop operation.
- `aria-haspopup` — Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
- `aria-hidden` — Indicates whether the element is exposed to an accessibility API.
- `aria-invalid` — Indicates the entered value does not conform to the format expected by the application.
- `aria-keyshortcuts` — Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.
- `aria-label` — Defines a string value that labels the current element.
- `aria-labelledby` — Identifies the element (or elements) that labels the current element.
- `aria-level` — Defines the hierarchical level of an element within a structure.
- `aria-live` — Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.
- `aria-modal` — Indicates whether an element is modal when displayed.
- `aria-multiline` — Indicates whether a text box accepts multiple lines of input or only a single line.
- `aria-multiselectable` — Indicates that the user may select more than one item from the current selectable descendants.
- `aria-orientation` — Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
- `aria-owns` — Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship
between DOM elements where the DOM hierarchy cannot be used to represent the relationship.
- `aria-placeholder` — Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value.
A hint could be a sample value or a brief description of the expected format.
- `aria-posinset` — Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM.
- `aria-pressed` — Indicates the current "pressed" state of toggle buttons.
- `aria-readonly` — Indicates that the element is not editable, but is otherwise operable.
- `aria-relevant` — Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified.
- `aria-required` — Indicates that user input is required on the element before a form may be submitted.
- `aria-roledescription` — Defines a human-readable, author-localized description for the role of an element.
- `aria-rowcount` — Defines the total number of rows in a table, grid, or treegrid.
- `aria-rowindex` — Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid.
- `aria-rowindextext` — Defines a human readable text alternative of aria-rowindex.
- `aria-rowspan` — Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.
- `aria-selected` — Indicates the current "selected" state of various widgets.
- `aria-setsize` — Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM.
- `aria-sort` — Indicates if items in a table or grid are sorted in ascending or descending order.
- `aria-valuemax` — Defines the maximum allowed value for a range widget.
- `aria-valuemin` — Defines the minimum allowed value for a range widget.
- `aria-valuenow` — Defines the current value for a range widget.
- `aria-valuetext` — Defines the human readable text alternative of aria-valuenow for a range widget.
- `className` — Additional class appended to the required `sheetwrite` host class.
- `config` — Built-in UI controls; providing an object enables the toolbar unless `toolbar` is false.
- `data` — Eager column-major values loaded into `workbook.activeSheet`; use instead of `datasource`.
- `datasource` — Lazy row provider requested for visible windows; use instead of eager `data`.
- `datasourceStorage` — Allocation and cache policy for datasource-backed cell storage.
- `editors` — Named custom editors resolved from each column's `editor` field.
- `fallback` — Content shown while WASM is loading or after initialization fails.
- `fill` — Fills the parent's available width and height, taking precedence over `height`.
- `height` — Host height in CSS pixels for numbers or any CSS length string.
- `hyperlinkActivation` — Hyperlink activation never opens a browser URL. `event-only` (default)
emits a safe resolved target; `internal-navigation` additionally moves to
stable internal destinations; `disabled` rejects every activation request.
- `inputMode` — Hints at the type of data that might be entered by the user while editing the element or its contents
- `is` — Specify that a standard HTML element should behave like a defined custom built-in element
- `minColumns` — Render at least this many columns (empty padding columns past the data, like a spreadsheet).
- `mutationPolicy` — Atomic rejects the transaction; partial skips denied operation objects.
- `onActiveSheetChange` — Fires after the visible sheet changes.
- `onCommandStateChange` — Receives observable undo/redo and formatting command state.
- `onDatasourceError` — Receives failed datasource requests and their errors.
- `onEditBegin` — Fires when cell editing begins.
- `onEditCommit` — Fires after an edit commits its parsed cell value.
- `onExportError` — Receives failures from built-in XLSX export actions.
- `onGridChange` — Receives every committed Grid change, including its applied transaction.
- `onInitializationError` — Receives a WASM initialization failure while the adapter remains mounted.
- `onMutationRejected` — Receives structured issues when a Grid mutation is rejected.
- `onReady` — Fires after the adapter publishes a ready Grid generation.
- `onRendererFallback` — Fires when worker rendering falls back to the main-thread canvas renderer.
- `onRowDelta` — Receives one accepted or reconciled row projection.
- `onSearch` — Receives refreshed search matches and active-match index.
- `onSelectionChange` — Receives the current selection, or `null` after it is cleared.
- `onViewportChange` — Receives visible row bounds and vertical scroll offset after scrolling.
- `overscan` — Extra row and visible-column positions painted on each viewport edge.
Defaults to 6; use 0 to disable the buffer.
- `presentation` — Header presentation. Spreadsheet mode (default) paints positional A/B/C
labels; data-grid mode paints each column's semantic `header`. Cell
addressing, row indices, clipboard values, formulas, and exports are
unchanged in both modes.
- `protectionResolver` — Host-owned client UX permission check. Servers must independently authorize
every submitted operation; this resolver is not an authentication boundary.
- `readOnly` — Disables mutating interactions while preserving navigation and selection.
- `renderer` — Paint backend; defaults to main-thread `canvas` and falls back there if a worker fails.
- `renderers` — Custom cell renderers registered up front; also see `Grid.defineCellRenderer`.
- `rowBridge` — Projects canonical changes to host-owned row identities.
- `style` — Host styles merged before adapter sizing styles.
- `theme` — Overrides merged over the default theme and host CSS custom properties.
- `transactionResourceLimits` — Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
- `wasmSource` — Explicit source passed to process-wide WASM initialization; concurrent initialization is first-source-wins.
- `workbook` — Live workbook schema adopted by the store and updated by document operations.
- `workerUrl` — URL of the worker renderer module (`renderer: "worker"`), as served to the
BROWSER — the platform `Worker` constructor does not consult package
exports, so a bare specifier like `new URL("@sheetwrite/core/worker",
import.meta.url)` is NOT reliable. Either copy
`@sheetwrite/core/dist/worker.js` to your public assets and pass its URL
string (works everywhere), or use your bundler's dependency-worker import
if it has one (see `/docs/guides/worker-rendering/`). If omitted or the worker
can't be constructed, the grid falls back to the main-thread canvas
renderer and emits `renderer-fallback` once.

##### `SheetwriteProps` — type

```ts
export type SheetwriteProps< Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId, > = Omit< SheetwriteGridProps<Id>, "workbook" | "data" | "datasource" | "height" | "fill" | "rowBridge" > & GridSizeProps & { columns: readonly SimpleColumn<Row>[]; defaultRows: readonly Row[]; sheetName?: string; getRowId?: (row: Row, index: number) => Id; createRowId?: Parameters<typeof createSimpleRowBridge<Row, Id>>[0]["createRowId"]; };
```

Simple framework adapter props for columns and default row objects.

##### `SimpleColumn` — interface

```ts
export interface SimpleColumn<Row extends Record<string, CellScalar>> { key: keyof Row & string; title: string; width?: number; type?: CellFormat; numberFormat?: string; headerStyle?: CellStyle; editor?: string; cellStyle?: CellStyle; visible?: boolean; }
```

Column definition accepted by the adapters’ simple row-object API.

Members:
- `cellStyle` — Base style merged beneath cell-specific styles.
- `editor` — Name of a custom editor registered through `GridOptions.editors`.
- `headerStyle` — Style applied to the painted column header.
- `key` — Non-empty row-object key, unique within the column list.
- `numberFormat` — Excel number-format code used for number, date, or currency display.
- `title` — Semantic title painted in data-grid mode and written by table exports.
- `type` — Input and formatting type; defaults to `text`.
- `visible` — Set to `false` to exclude the column from the live view and table exports.
- `width` — Unzoomed width in CSS pixels; defaults to 120.

#### `@sheetwrite/react/styles.css` — asset

Declaration target: `./styles.css`
Page: https://sheetwrite.vercel.app/docs/api/react-styles-css/

### `@sheetwrite/svelte`

#### `@sheetwrite/svelte` — supported

Declaration target: `./src/index.ts`
Source entry: `src/index.ts`
Page: https://sheetwrite.vercel.app/docs/api/svelte/

##### `CellEditor` — interface

```ts
export interface CellEditor { mount(host: HTMLElement, context: CellEditorContext): CellEditorInstance; }
```

Framework-neutral named editor definition registered through GridOptions.editors.

##### `CellEditorContext` — interface

```ts
export interface CellEditorContext { readonly grid: Grid; readonly address: Readonly<CellAddress>; readonly viewAddress: Readonly<CellAddress>; readonly column: Readonly<Column>; readonly value: CellScalar; readonly text: string; readonly initialInput: string | undefined; readonly selectAll: boolean; readonly label: string; readonly signal: AbortSignal; commit(value: string, navigation?: CellEditorNavigation): void; cancel(): void; }
```

Immutable state and guarded completion callbacks for one mounted editor.

##### `CellEditorInstance` — interface

```ts
export interface CellEditorInstance { update(context: CellEditorContext): void; reposition(rect: CellEditorRect): void; commit(navigation: CellEditorNavigation): string | undefined | Promise<string | undefined>; cancel(): void; destroy(): void; }
```

Retained lifecycle returned by a custom editor's mount method.

##### `CellEditorNavigation` — type

```ts
export type CellEditorNavigation = "down" | "right" | "left" | "none";
```

Selection movement applied after a successful editor commit.

##### `CellScalar` — type

```ts
export type CellScalar = string | number | boolean | null;
```

A scalar that can be displayed directly.

##### `Grid` — interface

```ts
export interface Grid { readonly store: Store; readonly actions: GridActions; getRuntimeResourceSnapshot(operation: RuntimeResourceOperation, phase: RuntimeResourcePhase, runtime?: RuntimeMemoryObservation): RuntimeResourceSnapshot; getCommandState(command: GridCommandName): GridCommandState; setActiveSheet(id: SheetId): void; scrollToCell(addr: CellAddress): void; getCellAtPoint(clientX: number, clientY: number): CellAddress | null; getActiveSheet(): SheetId; getCellInput(row: number, col: number): CellInputSnapshot | null; getSelection(): Selection | null; setSelection(sel: Selection | null): void; setTheme(theme: Partial<Theme>): void; replaceTheme(theme: Partial<Theme> | undefined): void; getEffectiveTheme(): Theme; setReadOnly(readOnly: boolean): void; setConfig(config: GridConfig | undefined): void; applyTransaction(transaction: GridTransaction): ApplyTransactionResult; exportSnapshot(): WorkbookSnapshot; applyRemoteOperations(operations: readonly DocumentOp[], options?: RemoteOperationOptions): ApplyTransactionResult; defineCellRenderer(name: string, renderer: CellRenderer): void; aggregate(col: number, op: AggregateOp): number; sortBy(col: number, ascending?: boolean): void; sortByMulti(keys: readonly SortKey[]): void; filterBy(col: number, needle: string): void; setColumnFilter(col: number, filter: ColumnFilter | null): void; setSort(keys: readonly SortKey[]): ApplyTransactionResult; getColumnFilters(): ReadonlyMap<number, ColumnFilter>; distinctValues(col: number, limit?: number): CellScalar[]; hideRows(rows: readonly number[]): void; showRows(rows?: readonly number[]): void; hiddenRows(): readonly number[]; hideColumns(cols?: readonly number[]): void; showColumns(cols?: readonly number[]): void; hiddenColumns(): readonly number[]; groupRows(start: number, end: number): void; ungroupRows(start: number, end: number): void; setGroupCollapsed(start: number, collapsed: boolean): void; rowGroups(): readonly RowGroup[]; clearView(): void; undo(): void; redo(): void; exportCsv(filename: string): void; exportXlsx(filename: string): Promise<void>; search(query: string, opts?: SearchOptions): SearchResult; findNext(): SearchResult; findPrev(): SearchResult; clearSearch(): void; replaceCurrent(replacement: string): SearchResult; replaceAll(replacement: string): ReplaceResult; insertRows(at: number, count?: number): void; removeRows(at: number, count?: number): void; insertColumns(at: number, count?: number): void; removeColumns(at: number, count?: number): void; addSheet(input: AddSheetInput): SheetLifecycleResult; removeSheet(id: SheetId): SheetLifecycleResult; renameSheet(id: SheetId, name: string): SheetLifecycleResult; moveSheet(id: SheetId, toIndex: number): SheetLifecycleResult; setSheetVisibility(id: SheetId, visibility: SheetVisibility): SheetLifecycleResult; setConditionalFormats(rules: readonly ConditionalFormatRule[]): void; setHyperlink(hyperlink: CellHyperlink): ApplyTransactionResult; removeHyperlink(id: string): ApplyTransactionResult; getHyperlink(addr: CellAddress): CellHyperlink | null; activateHyperlink(addr: CellAddress): boolean; setValidationRule(rule: DataValidationRule): ApplyTransactionResult; removeValidationRule(id: string): ApplyTransactionResult; setProtectedRange(protectedRange: ProtectedRange): ApplyTransactionResult; removeProtectedRange(id: string): ApplyTransactionResult; setProtectionResolver(resolver: ProtectionResolver | undefined, mode?: MutationPolicyMode): void; setNote(addr: CellAddress, text: string | null): ApplyTransactionResult; getNote(addr: CellAddress): string | null; setOverscan(overscan?: number): void; setMinColumns(minColumns?: number): void; highlightCells(ranges: readonly HighlightRange[] | null, color?: string): void; setPresenceOverlays(overlays: readonly PresenceOverlay[] | null): void; styleRange(range: Range, style: Partial<CellStyle> | null): void; beginEdit(row: number, col: number, initial?: string, selectAll?: boolean): void; dataEdge(row: number, col: number, dRow: number, dCol: number): number | null; setRowHeight(row: number, height: number): void; setColumnWidth(col: number, width: number): void; autoFitRows(range?: Range): void; autoFitColumns(cols?: readonly number[]): void; setFrozen(rows: number, cols?: number): void; setZoom(zoom: number): void; getZoom(): number; rendererKind(): "canvas" | "worker"; on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void; refresh(): void; destroy(): void; }
```

Imperative grid handle for document commands, events, rendering, and teardown.

Members:
- `actions` — Imperative action surface for binding custom toolbars/menus.
- `activateHyperlink` — Validate and emit a host-owned activation event. External targets are never
opened by Sheetwrite; internal navigation occurs only under the explicit policy.
- `addSheet` — Add a sheet with a stable ID and return its actionable transaction outcome.
- `aggregate` — Column aggregate over the active sheet's data.
- `applyRemoteOperations` — Apply host-supplied operations without undo history or outgoing dirty state.
The resulting change event has `source: "remote"`.
- `applyTransaction` — Apply arbitrary patches as one undoable Grid commit. No-op when read-only.
Use `Store.applyTransaction` only for low-level writes that intentionally
bypass Grid history and policy.
- `autoFitColumns` — Explicitly resize columns from a bulk worksheet read.
- `autoFitRows` — Explicitly resize rows to fit wrapped content; never runs during paint.
- `beginEdit` — Open the cell editor at a view cell, optionally seeding text / selecting all.
- `clearSearch` — Clear the current search and its highlights.
- `clearView` — Clear any active sort/filter view.
- `dataEdge` — Ctrl+Arrow-style jump target: the data-run edge from (row, col) on the
moved axis (row for vertical moves, col for horizontal), or null when the
store is not columnar. Under an active sort/filter view, `row` is a view
position and vertical moves return view positions. For hosts building
their own keymaps (`config.keyboard`).
- `distinctValues` — Distinct resolved values of a column in first-seen order. Defaults to
1,000 values for bounded filter menus; pass 0 to request an uncapped scan.
- `exportSnapshot` — Deterministically export the complete authoritative workbook document.
- `filterBy` — Filter the displayed rows to those whose column text contains `needle`.
- `findNext` — Move the active match to the next match and scroll it into view.
- `findPrev` — Move the active match to the previous match and scroll it into view.
- `getActiveSheet` — Id of the currently visible sheet.
- `getCellAtPoint` — Resolve browser viewport coordinates to an active-sheet cell for host-owned
menus and interactions. Returns null outside the cell body.
- `getCellInput` — Editable snapshot of the cell at a view position on the active sheet, or
null when out of bounds. See {@link CellInputSnapshot}.
- `getColumnFilters` — Active column filters on the active sheet, keyed by column index.
- `getCommandState` — Query undo/redo availability and formatting active/mixed/disabled state.
- `getEffectiveTheme` — The effective (post-zoom) theme the renderer is currently painting with.
- `getRuntimeResourceSnapshot` — Versioned coarse runtime ownership snapshot, including datasource state.
- `groupRows` — Define a collapsible row group over a data-row range (end-inclusive).
- `hiddenColumns` — Currently hidden columns on the active sheet.
- `hiddenRows` — Currently hidden data rows on the active sheet.
- `hideColumns` — Hide columns through one bulk-safe metadata transaction.
- `hideRows` — Hide the given data rows (composes with filters/sort).
- `highlightCells` — Highlight arbitrary cell ranges (null clears). Per-range `color` wins over the call color.
- `redo` — Redo the last undone cell edit.
- `removeSheet` — Remove a sheet while preserving at least one visible worksheet.
- `rendererKind` — Which renderer is actually active: `"worker"` when the OffscreenCanvas
worker constructed successfully, `"canvas"` otherwise (including after a
`renderer-fallback`).
- `replaceAll` — Replace every current match in a single undoable transaction (one
`undo()` restores them all), then re-scan. Formula/ref cells are skipped
and not counted. No-op when read-only.
- `replaceCurrent` — Replace the active match with `replacement`, then advance to the next match
(re-scanning against the new data). Only literal text/number cells are
eligible; formula and ref cells are skipped (formula source is never
rewritten). Honors the active {@link SearchOptions} (matchCase; `wholeCell`
swaps the entire cell). The write flows through the grid's commit path as
one undoable step. No-op when read-only or when there is no active match.
- `replaceTheme` — Option-level replacement: re-run construction-time resolution
(`DEFAULT_THEME < CSS custom properties < theme`) with the new partial.
`undefined` restores the CSS-variable/default resolution. Adapters call
this for their declarative `theme` prop; imperative patching stays on
{@link setTheme}.
- `rowGroups` — Row groups on the active sheet.
- `search` — Find cells matching `query`; highlights matches, emits `search`, returns the result.
- `setColumnFilter` — Set or clear (null) one column's filter. All column filters AND together
and compose with the active sort and hidden rows.
- `setColumnWidth` — Set one column's width via an undoable `setColumn` patch.
- `setConfig` — Reconfigure built-in chrome and keyboard handling without replacing the
Grid or clearing selection/history. Construction-bound GridOptions are not
accepted here.
- `setFrozen` — Pin the first `rows` view rows and `cols` columns; they stay visible while
the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.
- `setGroupCollapsed` — Collapse/expand a row group; collapsing hides its rows.
- `setMinColumns` — Live-update the minimum rendered column count. Increasing the minimum
silently extends presentation padding; `undefined` restores the default.
- `setOverscan` — Live-update the render window overscan (row/column positions painted past
each edge); `undefined` restores the default of 6.
- `setPresenceOverlays` — Replace ephemeral remote-presence overlays; null clears every collaborator.
- `setReadOnly` — Update editability without replacing the Grid or clearing session state.
- `setRowHeight` — Set one row's persistent display height through document history.
- `setSheetVisibility` — Set host-visible worksheet state; stock UI never offers `veryHidden`.
- `setSort` — Persisted multi-key sort of the active sheet.
- `setTheme` — Imperative patch: merge `theme` into the accumulated base theme.
- `setZoom` — Content zoom factor (0.5–2): scales row/column geometry and fonts.
- `showColumns` — Show columns through one bulk-safe metadata transaction.
- `showRows` — Show the given data rows again, or every hidden row when omitted.
- `sortBy` — Sort the displayed rows by a column (does not mutate stored data).
- `sortByMulti` — Multi-key sort of the displayed rows (first key primary; stable).
- `styleRange` — Merge `style` into every cell of `range` (null clears cell styles) as one
undoable transaction. Styles land in the store and paint in the canvas —
unlike {@link highlightCells}, which draws a translucent overlay above it.
- `undo` — Undo the last recorded cell edit.
- `ungroupRows` — Remove a row group (rows become visible if the group was collapsed).

##### `GridCommandName` — type

```ts
export type GridCommandName = Exclude<ToolbarActionName, "separator">;
```

Built-in command names accepted by state queries and change events.

##### `GridCommandState` — interface

```ts
export interface GridCommandState { readonly disabled: boolean; readonly activity: "inactive" | "active" | "mixed"; }
```

Observable availability and selection-derived activity for one command.

##### `GridReadyEvent` — interface

```ts
export interface GridReadyEvent { grid: Grid; generation: number; reason: GridReadyReason; }
```

Grid handle, generation, and reason published after adapter initialization.

Members:
- `generation` — One-based adapter generation, incremented whenever a Grid is replaced.
- `grid` — Live handle just published by the adapter; replaced on the next reset generation.
- `reason` — Whether readiness followed first initialization, an input reset, or a renderer reset.

##### `RowBridge` — class

```ts
class RowBridge { constructor<Id extends RowBridgeId = RowBridgeId, Row extends Record<string, CellScalar> = Record<string, CellScalar>>(options: RowBridgeOptions<Row, Id>); columnKeys: (sheet?: SheetId) => readonly string[]; project: (event: ChangeEvent, requestedOperations?: readonly DocumentOp[], transactionId?: string) => RowBridgeProjection<Id>; reconcile: (input: RowBridgeReconciliationInput<Id>) => RowBridgeProjection<Id>; rowIds: (sheet?: SheetId) => readonly (Id | null)[] }
```

Projects canonical document transactions into host-owned row changes.

The bridge only owns compact data-space identity arrays. It never writes to
`defaultRows`, never renders, and never creates a second document store.

Members:
- `columnKeys` — Current semantic column keys in canonical column order.
- `project` — Project an applied Grid change as an accepted, transformed, or remote result.
- `reconcile` — Reconcile a canonical transaction response without synchronizing host rows implicitly.
- `rowIds` — Current data-space row identities; visual sort and filters do not affect this order.

##### `RowBridgeDelta` — type

```ts
export type RowBridgeDelta<Id extends RowBridgeId = RowBridgeId> = RowBridgeCellDelta<Id> | RowBridgeRangeDelta<Id> | RowBridgeClearDelta<Id> | RowBridgePasteDelta<Id> | RowBridgeFillDelta<Id> | RowBridgeRowStructureDelta<Id> | RowBridgeMetadataDelta<Id> | RowBridgeHostActionDelta<Id> | RowBridgeUnprojectableDelta<Id>;
```

Every possible projection produced by a row bridge.

##### `RowBridgeHandler` — type

```ts
export type RowBridgeHandler<Id extends RowBridgeId = RowBridgeId> = (projection: RowBridgeProjection<Id>) => void;
```

Callback accepted by imperative and framework adapters.

##### `RowBridgeId` — type

```ts
export type RowBridgeId = string | number;
```

A stable host identity for one data-space row.

##### `RowBridgeProjection` — interface

```ts
export interface RowBridgeProjection<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transaction: RowBridgeTransaction; readonly deltas: readonly RowBridgeDelta<Id>[]; }
```

Result of projection or reconciliation.

##### `Sheetwrite` — variable

```ts
(this: void, internals: ComponentInternals, props: SheetwriteProps<Record<string, CellScalar>>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<SheetwriteProps<Record<string, CellScalar>>>): void; }
```

Convenience component for local object rows. Bind `grid` to access the live `Grid`.

Owns a sheet derived from `columns` and `defaultRows`. Bind `grid` for imperative access; it clears on reset or unmount.

##### `SheetwriteGrid` — variable

```ts
(this: void, internals: ComponentInternals, props: SheetwriteGridProps<RowBridgeId>): { $on?(type: string, callback: (e: any) => void): () => void; $set?(props: Partial<SheetwriteGridProps<RowBridgeId>>): void; }
```

Advanced framework component for workbook data or datasource input.

##### `SheetwriteGridProps` — interface

```ts
export interface SheetwriteGridProps<Id extends RowBridgeId = RowBridgeId> extends Omit<HTMLAttributes<HTMLDivElement>, keyof GridAdapterEventHandlers<Id> | "children"> { workbook: GridOptions["workbook"]; data?: GridOptions["data"]; rowBridge?: RowBridge<Id>; datasource?: GridOptions["datasource"]; datasourceStorage?: GridOptions["datasourceStorage"]; renderer?: GridOptions["renderer"]; workerUrl?: GridOptions["workerUrl"]; presentation?: GridOptions["presentation"]; theme?: GridOptions["theme"]; readOnly?: GridOptions["readOnly"]; protectionResolver?: GridOptions["protectionResolver"]; mutationPolicy?: GridOptions["mutationPolicy"]; transactionResourceLimits?: GridOptions["transactionResourceLimits"]; hyperlinkActivation?: GridOptions["hyperlinkActivation"]; renderers?: GridOptions["renderers"]; editors?: GridOptions["editors"]; overscan?: GridOptions["overscan"]; minColumns?: GridOptions["minColumns"]; config?: GridOptions["config"]; height?: number | string; fill?: true; fallback?: Snippet; grid?: Grid; onGridChange?: (event: ChangeEvent) => void; onRowDelta?: RowBridgeHandler<Id>; onSelectionChange?: (selection: Selection | null) => void; onViewportChange?: (event: GridEvents["scroll"]) => void; onEditBegin?: (event: GridEvents["edit-begin"]) => void; onEditCommit?: (event: GridEvents["edit-commit"]) => void; onSearch?: (result: GridEvents["search"]) => void; onActiveSheetChange?: (event: GridEvents["active-sheet"]) => void; onCommandStateChange?: (event: GridEvents["command-state-change"]) => void; onMutationRejected?: (event: GridEvents["mutation-rejected"]) => void; onRendererFallback?: (event: GridEvents["renderer-fallback"]) => void; onDatasourceError?: (event: GridEvents["datasource-error"]) => void; onExportError?: (event: GridEvents["export-error"]) => void; onReady?: (event: GridReadyEvent) => void; onInitializationError?: (error: SheetwriteError) => void; wasmSource?: BufferSource | URL | string | Request | WebAssembly.Module; }
```

Advanced Svelte adapter props with inferred host row identity.

Members:
- `aria-activedescendant` — Identifies the currently active element when DOM focus is on a composite widget, textbox, group, or application.
- `aria-atomic` — Indicates whether assistive technologies will present all, or only parts of, the changed region based on the change notifications defined by the aria-relevant attribute.
- `aria-autocomplete` — Indicates whether inputting text could trigger display of one or more predictions of the user's intended value for an input and specifies how predictions would be
presented if they are made.
- `aria-busy` — Indicates an element is being modified and that assistive technologies MAY want to wait until the modifications are complete before exposing them to the user.
- `aria-checked` — Indicates the current "checked" state of checkboxes, radio buttons, and other widgets.
- `aria-colcount` — Defines the total number of columns in a table, grid, or treegrid.
- `aria-colindex` — Defines an element's column index or position with respect to the total number of columns within a table, grid, or treegrid.
- `aria-colspan` — Defines the number of columns spanned by a cell or gridcell within a table, grid, or treegrid.
- `aria-controls` — Identifies the element (or elements) whose contents or presence are controlled by the current element.
- `aria-current` — Indicates the element that represents the current item within a container or set of related elements.
- `aria-describedby` — Identifies the element (or elements) that describes the object.
- `aria-details` — Identifies the element that provides a detailed, extended description for the object.
- `aria-disabled` — Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.
- `aria-dropeffect` — Indicates what functions can be performed when a dragged object is released on the drop target.
- `aria-errormessage` — Identifies the element that provides an error message for the object.
- `aria-expanded` — Indicates whether the element, or another grouping element it controls, is currently expanded or collapsed.
- `aria-flowto` — Identifies the next element (or elements) in an alternate reading order of content which, at the user's discretion,
allows assistive technology to override the general default of reading in document source order.
- `aria-grabbed` — Indicates an element's "grabbed" state in a drag-and-drop operation.
- `aria-haspopup` — Indicates the availability and type of interactive popup element, such as menu or dialog, that can be triggered by an element.
- `aria-hidden` — Indicates whether the element is exposed to an accessibility API.
- `aria-invalid` — Indicates the entered value does not conform to the format expected by the application.
- `aria-keyshortcuts` — Indicates keyboard shortcuts that an author has implemented to activate or give focus to an element.
- `aria-label` — Defines a string value that labels the current element.
- `aria-labelledby` — Identifies the element (or elements) that labels the current element.
- `aria-level` — Defines the hierarchical level of an element within a structure.
- `aria-live` — Indicates that an element will be updated, and describes the types of updates the user agents, assistive technologies, and user can expect from the live region.
- `aria-modal` — Indicates whether an element is modal when displayed.
- `aria-multiline` — Indicates whether a text box accepts multiple lines of input or only a single line.
- `aria-multiselectable` — Indicates that the user may select more than one item from the current selectable descendants.
- `aria-orientation` — Indicates whether the element's orientation is horizontal, vertical, or unknown/ambiguous.
- `aria-owns` — Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship
between DOM elements where the DOM hierarchy cannot be used to represent the relationship.
- `aria-placeholder` — Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value.
A hint could be a sample value or a brief description of the expected format.
- `aria-posinset` — Defines an element's number or position in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM.
- `aria-pressed` — Indicates the current "pressed" state of toggle buttons.
- `aria-readonly` — Indicates that the element is not editable, but is otherwise operable.
- `aria-relevant` — Indicates what notifications the user agent will trigger when the accessibility tree within a live region is modified.
- `aria-required` — Indicates that user input is required on the element before a form may be submitted.
- `aria-roledescription` — Defines a human-readable, author-localized description for the role of an element.
- `aria-rowcount` — Defines the total number of rows in a table, grid, or treegrid.
- `aria-rowindex` — Defines an element's row index or position with respect to the total number of rows within a table, grid, or treegrid.
- `aria-rowspan` — Defines the number of rows spanned by a cell or gridcell within a table, grid, or treegrid.
- `aria-selected` — Indicates the current "selected" state of various widgets.
- `aria-setsize` — Defines the number of items in the current set of listitems or treeitems. Not required if all elements in the set are present in the DOM.
- `aria-sort` — Indicates if items in a table or grid are sorted in ascending or descending order.
- `aria-valuemax` — Defines the maximum allowed value for a range widget.
- `aria-valuemin` — Defines the minimum allowed value for a range widget.
- `aria-valuenow` — Defines the current value for a range widget.
- `aria-valuetext` — Defines the human readable text alternative of aria-valuenow for a range widget.
- `bind:innerHTML` — Elements with the contenteditable attribute support `innerHTML`, `textContent` and `innerText` bindings.
- `bind:innerText` — Elements with the contenteditable attribute support `innerHTML`, `textContent` and `innerText` bindings.
- `bind:textContent` — Elements with the contenteditable attribute support `innerHTML`, `textContent` and `innerText` bindings.
- `config` — Built-in UI control configuration.
- `data` — Eager values for the active sheet.
- `datasource` — Lazy visible-row provider.
- `datasourceStorage` — Datasource storage policy.
- `editors` — Named custom cell editors.
- `fallback` — Content shown until initialization succeeds.
- `fill` — Fills the parent's available size.
- `grid` — Bindable live Grid, cleared on reset or unmount.
- `height` — Host height as pixels or a CSS length.
- `hyperlinkActivation` — Controls link activation: emit an event, also navigate internally, or disable it.
- `inputmode` — Hints at the type of data that might be entered by the user while editing the element or its contents
- `is` — Specify that a standard HTML element should behave like a defined custom built-in element
- `minColumns` — Minimum column count with padding.
- `mutationPolicy` — Atomic or partial denial policy.
- `onActiveSheetChange` — Fires after the visible sheet changes.
- `onCommandStateChange` — Receives observable undo/redo and formatting command state.
- `onDatasourceError` — Receives failed datasource requests and their errors.
- `onEditBegin` — Fires when cell editing begins.
- `onEditCommit` — Fires after an edit commits its parsed cell value.
- `onExportError` — Receives failures from built-in XLSX export actions.
- `onGridChange` — Receives every committed Grid change, including its applied transaction.
- `onInitializationError` — Receives a WASM initialization failure while the adapter remains mounted.
- `onMutationRejected` — Receives structured issues when a Grid mutation is rejected.
- `onReady` — Fires after the adapter publishes a ready Grid generation.
- `onRendererFallback` — Fires when worker rendering falls back to the main-thread canvas renderer.
- `onRowDelta` — Receives projected host-row effects when a row bridge is attached.
- `onSearch` — Receives refreshed search matches and active-match index.
- `onSelectionChange` — Receives the current selection, or `null` after it is cleared.
- `onViewportChange` — Receives visible row bounds and vertical scroll offset after scrolling.
- `overscan` — Extra rows painted around the viewport.
- `presentation` — Positional spreadsheet or semantic data-grid headers.
- `protectionResolver` — Client protected-range check.
- `readOnly` — Disables mutations, not navigation.
- `renderer` — Canvas or worker paint backend.
- `renderers` — Named custom cell renderers.
- `rowBridge` — Optional canonical-to-host row projection.
- `theme` — Live resolved-theme overrides.
- `transactionResourceLimits` — Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
- `wasmSource` — Explicit source passed to process-wide WASM initialization; concurrent initialization is first-source-wins.
- `workbook` — Live workbook schema adopted by the Grid.
- `workerUrl` — Browser-fetchable worker module URL.

##### `SheetwriteProps` — type

```ts
export type SheetwriteProps< Row extends Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId, > = Omit< SheetwriteGridProps<Id>, "workbook" | "data" | "datasource" | "height" | "fill" | "rowBridge" > & GridSizeProps & { columns: readonly SimpleColumn<Row>[]; defaultRows: readonly Row[]; sheetName?: string; getRowId?: (row: Row, index: number) => Id; createRowId?: (context: RowBridgeInsertContext) => Id; };
```

Simple framework adapter props for columns and default row objects.

##### `SimpleColumn` — interface

```ts
export interface SimpleColumn<Row extends Record<string, CellScalar>> { key: keyof Row & string; title: string; width?: number; type?: CellFormat; numberFormat?: string; headerStyle?: CellStyle; editor?: string; cellStyle?: CellStyle; visible?: boolean; }
```

Column definition accepted by the adapters’ simple row-object API.

Members:
- `cellStyle` — Base style merged beneath cell-specific styles.
- `editor` — Name of a custom editor registered through `GridOptions.editors`.
- `headerStyle` — Style applied to the painted column header.
- `key` — Non-empty row-object key, unique within the column list.
- `numberFormat` — Excel number-format code used for number, date, or currency display.
- `title` — Semantic title painted in data-grid mode and written by table exports.
- `type` — Input and formatting type; defaults to `text`.
- `visible` — Set to `false` to exclude the column from the live view and table exports.
- `width` — Unzoomed width in CSS pixels; defaults to 120.

#### `@sheetwrite/svelte/styles.css` — asset

Declaration target: `./styles.css`
Page: https://sheetwrite.vercel.app/docs/api/svelte-styles-css/

### `@sheetwrite/vue`

#### `@sheetwrite/vue` — supported

Declaration target: `./dist/index.d.ts`
Source entry: `src/index.ts`
Page: https://sheetwrite.vercel.app/docs/api/vue/

##### `CellEditor` — interface

```ts
export interface CellEditor { mount(host: HTMLElement, context: CellEditorContext): CellEditorInstance; }
```

Framework-neutral named editor definition registered through GridOptions.editors.

##### `CellEditorContext` — interface

```ts
export interface CellEditorContext { readonly grid: Grid; readonly address: Readonly<CellAddress>; readonly viewAddress: Readonly<CellAddress>; readonly column: Readonly<Column>; readonly value: CellScalar; readonly text: string; readonly initialInput: string | undefined; readonly selectAll: boolean; readonly label: string; readonly signal: AbortSignal; commit(value: string, navigation?: CellEditorNavigation): void; cancel(): void; }
```

Immutable state and guarded completion callbacks for one mounted editor.

##### `CellEditorInstance` — interface

```ts
export interface CellEditorInstance { update(context: CellEditorContext): void; reposition(rect: CellEditorRect): void; commit(navigation: CellEditorNavigation): string | undefined | Promise<string | undefined>; cancel(): void; destroy(): void; }
```

Retained lifecycle returned by a custom editor's mount method.

##### `CellEditorNavigation` — type

```ts
export type CellEditorNavigation = "down" | "right" | "left" | "none";
```

Selection movement applied after a successful editor commit.

##### `CellScalar` — type

```ts
export type CellScalar = string | number | boolean | null;
```

A scalar that can be displayed directly.

##### `Grid` — interface

```ts
export interface Grid { readonly store: Store; readonly actions: GridActions; getRuntimeResourceSnapshot(operation: RuntimeResourceOperation, phase: RuntimeResourcePhase, runtime?: RuntimeMemoryObservation): RuntimeResourceSnapshot; getCommandState(command: GridCommandName): GridCommandState; setActiveSheet(id: SheetId): void; scrollToCell(addr: CellAddress): void; getCellAtPoint(clientX: number, clientY: number): CellAddress | null; getActiveSheet(): SheetId; getCellInput(row: number, col: number): CellInputSnapshot | null; getSelection(): Selection | null; setSelection(sel: Selection | null): void; setTheme(theme: Partial<Theme>): void; replaceTheme(theme: Partial<Theme> | undefined): void; getEffectiveTheme(): Theme; setReadOnly(readOnly: boolean): void; setConfig(config: GridConfig | undefined): void; applyTransaction(transaction: GridTransaction): ApplyTransactionResult; exportSnapshot(): WorkbookSnapshot; applyRemoteOperations(operations: readonly DocumentOp[], options?: RemoteOperationOptions): ApplyTransactionResult; defineCellRenderer(name: string, renderer: CellRenderer): void; aggregate(col: number, op: AggregateOp): number; sortBy(col: number, ascending?: boolean): void; sortByMulti(keys: readonly SortKey[]): void; filterBy(col: number, needle: string): void; setColumnFilter(col: number, filter: ColumnFilter | null): void; setSort(keys: readonly SortKey[]): ApplyTransactionResult; getColumnFilters(): ReadonlyMap<number, ColumnFilter>; distinctValues(col: number, limit?: number): CellScalar[]; hideRows(rows: readonly number[]): void; showRows(rows?: readonly number[]): void; hiddenRows(): readonly number[]; hideColumns(cols?: readonly number[]): void; showColumns(cols?: readonly number[]): void; hiddenColumns(): readonly number[]; groupRows(start: number, end: number): void; ungroupRows(start: number, end: number): void; setGroupCollapsed(start: number, collapsed: boolean): void; rowGroups(): readonly RowGroup[]; clearView(): void; undo(): void; redo(): void; exportCsv(filename: string): void; exportXlsx(filename: string): Promise<void>; search(query: string, opts?: SearchOptions): SearchResult; findNext(): SearchResult; findPrev(): SearchResult; clearSearch(): void; replaceCurrent(replacement: string): SearchResult; replaceAll(replacement: string): ReplaceResult; insertRows(at: number, count?: number): void; removeRows(at: number, count?: number): void; insertColumns(at: number, count?: number): void; removeColumns(at: number, count?: number): void; addSheet(input: AddSheetInput): SheetLifecycleResult; removeSheet(id: SheetId): SheetLifecycleResult; renameSheet(id: SheetId, name: string): SheetLifecycleResult; moveSheet(id: SheetId, toIndex: number): SheetLifecycleResult; setSheetVisibility(id: SheetId, visibility: SheetVisibility): SheetLifecycleResult; setConditionalFormats(rules: readonly ConditionalFormatRule[]): void; setHyperlink(hyperlink: CellHyperlink): ApplyTransactionResult; removeHyperlink(id: string): ApplyTransactionResult; getHyperlink(addr: CellAddress): CellHyperlink | null; activateHyperlink(addr: CellAddress): boolean; setValidationRule(rule: DataValidationRule): ApplyTransactionResult; removeValidationRule(id: string): ApplyTransactionResult; setProtectedRange(protectedRange: ProtectedRange): ApplyTransactionResult; removeProtectedRange(id: string): ApplyTransactionResult; setProtectionResolver(resolver: ProtectionResolver | undefined, mode?: MutationPolicyMode): void; setNote(addr: CellAddress, text: string | null): ApplyTransactionResult; getNote(addr: CellAddress): string | null; setOverscan(overscan?: number): void; setMinColumns(minColumns?: number): void; highlightCells(ranges: readonly HighlightRange[] | null, color?: string): void; setPresenceOverlays(overlays: readonly PresenceOverlay[] | null): void; styleRange(range: Range, style: Partial<CellStyle> | null): void; beginEdit(row: number, col: number, initial?: string, selectAll?: boolean): void; dataEdge(row: number, col: number, dRow: number, dCol: number): number | null; setRowHeight(row: number, height: number): void; setColumnWidth(col: number, width: number): void; autoFitRows(range?: Range): void; autoFitColumns(cols?: readonly number[]): void; setFrozen(rows: number, cols?: number): void; setZoom(zoom: number): void; getZoom(): number; rendererKind(): "canvas" | "worker"; on<E extends keyof GridEvents>(evt: E, fn: (e: GridEvents[E]) => void): () => void; refresh(): void; destroy(): void; }
```

Imperative grid handle for document commands, events, rendering, and teardown.

Members:
- `actions` — Imperative action surface for binding custom toolbars/menus.
- `activateHyperlink` — Validate and emit a host-owned activation event. External targets are never
opened by Sheetwrite; internal navigation occurs only under the explicit policy.
- `addSheet` — Add a sheet with a stable ID and return its actionable transaction outcome.
- `aggregate` — Column aggregate over the active sheet's data.
- `applyRemoteOperations` — Apply host-supplied operations without undo history or outgoing dirty state.
The resulting change event has `source: "remote"`.
- `applyTransaction` — Apply arbitrary patches as one undoable Grid commit. No-op when read-only.
Use `Store.applyTransaction` only for low-level writes that intentionally
bypass Grid history and policy.
- `autoFitColumns` — Explicitly resize columns from a bulk worksheet read.
- `autoFitRows` — Explicitly resize rows to fit wrapped content; never runs during paint.
- `beginEdit` — Open the cell editor at a view cell, optionally seeding text / selecting all.
- `clearSearch` — Clear the current search and its highlights.
- `clearView` — Clear any active sort/filter view.
- `dataEdge` — Ctrl+Arrow-style jump target: the data-run edge from (row, col) on the
moved axis (row for vertical moves, col for horizontal), or null when the
store is not columnar. Under an active sort/filter view, `row` is a view
position and vertical moves return view positions. For hosts building
their own keymaps (`config.keyboard`).
- `distinctValues` — Distinct resolved values of a column in first-seen order. Defaults to
1,000 values for bounded filter menus; pass 0 to request an uncapped scan.
- `exportSnapshot` — Deterministically export the complete authoritative workbook document.
- `filterBy` — Filter the displayed rows to those whose column text contains `needle`.
- `findNext` — Move the active match to the next match and scroll it into view.
- `findPrev` — Move the active match to the previous match and scroll it into view.
- `getActiveSheet` — Id of the currently visible sheet.
- `getCellAtPoint` — Resolve browser viewport coordinates to an active-sheet cell for host-owned
menus and interactions. Returns null outside the cell body.
- `getCellInput` — Editable snapshot of the cell at a view position on the active sheet, or
null when out of bounds. See {@link CellInputSnapshot}.
- `getColumnFilters` — Active column filters on the active sheet, keyed by column index.
- `getCommandState` — Query undo/redo availability and formatting active/mixed/disabled state.
- `getEffectiveTheme` — The effective (post-zoom) theme the renderer is currently painting with.
- `getRuntimeResourceSnapshot` — Versioned coarse runtime ownership snapshot, including datasource state.
- `groupRows` — Define a collapsible row group over a data-row range (end-inclusive).
- `hiddenColumns` — Currently hidden columns on the active sheet.
- `hiddenRows` — Currently hidden data rows on the active sheet.
- `hideColumns` — Hide columns through one bulk-safe metadata transaction.
- `hideRows` — Hide the given data rows (composes with filters/sort).
- `highlightCells` — Highlight arbitrary cell ranges (null clears). Per-range `color` wins over the call color.
- `redo` — Redo the last undone cell edit.
- `removeSheet` — Remove a sheet while preserving at least one visible worksheet.
- `rendererKind` — Which renderer is actually active: `"worker"` when the OffscreenCanvas
worker constructed successfully, `"canvas"` otherwise (including after a
`renderer-fallback`).
- `replaceAll` — Replace every current match in a single undoable transaction (one
`undo()` restores them all), then re-scan. Formula/ref cells are skipped
and not counted. No-op when read-only.
- `replaceCurrent` — Replace the active match with `replacement`, then advance to the next match
(re-scanning against the new data). Only literal text/number cells are
eligible; formula and ref cells are skipped (formula source is never
rewritten). Honors the active {@link SearchOptions} (matchCase; `wholeCell`
swaps the entire cell). The write flows through the grid's commit path as
one undoable step. No-op when read-only or when there is no active match.
- `replaceTheme` — Option-level replacement: re-run construction-time resolution
(`DEFAULT_THEME < CSS custom properties < theme`) with the new partial.
`undefined` restores the CSS-variable/default resolution. Adapters call
this for their declarative `theme` prop; imperative patching stays on
{@link setTheme}.
- `rowGroups` — Row groups on the active sheet.
- `search` — Find cells matching `query`; highlights matches, emits `search`, returns the result.
- `setColumnFilter` — Set or clear (null) one column's filter. All column filters AND together
and compose with the active sort and hidden rows.
- `setColumnWidth` — Set one column's width via an undoable `setColumn` patch.
- `setConfig` — Reconfigure built-in chrome and keyboard handling without replacing the
Grid or clearing selection/history. Construction-bound GridOptions are not
accepted here.
- `setFrozen` — Pin the first `rows` view rows and `cols` columns; they stay visible while
the body scrolls (0 = unfreeze that axis). Persisted on the active sheet.
- `setGroupCollapsed` — Collapse/expand a row group; collapsing hides its rows.
- `setMinColumns` — Live-update the minimum rendered column count. Increasing the minimum
silently extends presentation padding; `undefined` restores the default.
- `setOverscan` — Live-update the render window overscan (row/column positions painted past
each edge); `undefined` restores the default of 6.
- `setPresenceOverlays` — Replace ephemeral remote-presence overlays; null clears every collaborator.
- `setReadOnly` — Update editability without replacing the Grid or clearing session state.
- `setRowHeight` — Set one row's persistent display height through document history.
- `setSheetVisibility` — Set host-visible worksheet state; stock UI never offers `veryHidden`.
- `setSort` — Persisted multi-key sort of the active sheet.
- `setTheme` — Imperative patch: merge `theme` into the accumulated base theme.
- `setZoom` — Content zoom factor (0.5–2): scales row/column geometry and fonts.
- `showColumns` — Show columns through one bulk-safe metadata transaction.
- `showRows` — Show the given data rows again, or every hidden row when omitted.
- `sortBy` — Sort the displayed rows by a column (does not mutate stored data).
- `sortByMulti` — Multi-key sort of the displayed rows (first key primary; stable).
- `styleRange` — Merge `style` into every cell of `range` (null clears cell styles) as one
undoable transaction. Styles land in the store and paint in the canvas —
unlike {@link highlightCells}, which draws a translucent overlay above it.
- `undo` — Undo the last recorded cell edit.
- `ungroupRows` — Remove a row group (rows become visible if the group was collapsed).

##### `GridCommandName` — type

```ts
export type GridCommandName = Exclude<ToolbarActionName, "separator">;
```

Built-in command names accepted by state queries and change events.

##### `GridCommandState` — interface

```ts
export interface GridCommandState { readonly disabled: boolean; readonly activity: "inactive" | "active" | "mixed"; }
```

Observable availability and selection-derived activity for one command.

##### `GridReadyEvent` — interface

```ts
export interface GridReadyEvent { grid: Grid; generation: number; reason: GridReadyReason; }
```

Grid handle, generation, and reason published after adapter initialization.

Members:
- `generation` — One-based adapter generation, incremented whenever a Grid is replaced.
- `grid` — Live handle just published by the adapter; replaced on the next reset generation.
- `reason` — Whether readiness followed first initialization, an input reset, or a renderer reset.

##### `RowBridge` — class

```ts
class RowBridge { constructor<Id extends RowBridgeId = RowBridgeId, Row extends Record<string, CellScalar> = Record<string, CellScalar>>(options: RowBridgeOptions<Row, Id>); columnKeys: (sheet?: SheetId) => readonly string[]; project: (event: ChangeEvent, requestedOperations?: readonly DocumentOp[], transactionId?: string) => RowBridgeProjection<Id>; reconcile: (input: RowBridgeReconciliationInput<Id>) => RowBridgeProjection<Id>; rowIds: (sheet?: SheetId) => readonly (Id | null)[] }
```

Projects canonical document transactions into host-owned row changes.

The bridge only owns compact data-space identity arrays. It never writes to
`defaultRows`, never renders, and never creates a second document store.

Members:
- `columnKeys` — Current semantic column keys in canonical column order.
- `project` — Project an applied Grid change as an accepted, transformed, or remote result.
- `reconcile` — Reconcile a canonical transaction response without synchronizing host rows implicitly.
- `rowIds` — Current data-space row identities; visual sort and filters do not affect this order.

##### `RowBridgeDelta` — type

```ts
export type RowBridgeDelta<Id extends RowBridgeId = RowBridgeId> = RowBridgeCellDelta<Id> | RowBridgeRangeDelta<Id> | RowBridgeClearDelta<Id> | RowBridgePasteDelta<Id> | RowBridgeFillDelta<Id> | RowBridgeRowStructureDelta<Id> | RowBridgeMetadataDelta<Id> | RowBridgeHostActionDelta<Id> | RowBridgeUnprojectableDelta<Id>;
```

Every possible projection produced by a row bridge.

##### `RowBridgeHandler` — type

```ts
export type RowBridgeHandler<Id extends RowBridgeId = RowBridgeId> = (projection: RowBridgeProjection<Id>) => void;
```

Callback accepted by imperative and framework adapters.

##### `RowBridgeId` — type

```ts
export type RowBridgeId = string | number;
```

A stable host identity for one data-space row.

##### `RowBridgeProjection` — interface

```ts
export interface RowBridgeProjection<Id extends RowBridgeId = RowBridgeId> { readonly status: RowBridgeReconciliationStatus; readonly transaction: RowBridgeTransaction; readonly deltas: readonly RowBridgeDelta<Id>[]; }
```

Result of projection or reconciliation.

##### `Sheetwrite` — variable

```ts
SheetwriteComponentConstructor<SheetwriteProps<Record<string, CellScalar>, RowBridgeId>, SheetwriteGridEmits<RowBridgeId>, object>
```

Convenience component for local object rows with live option updates.

##### `SheetwriteComponentConstructor` — type

```ts
export type SheetwriteComponentConstructor<Props, Emits, Expose = object> = new () => Expose & ComponentPublicInstance & { $props: AllowedComponentProps & Props & VNodeProps & { [EventName in keyof Emits & string as `on${Capitalize<EventName>}`]?: ( payload: Emits[EventName], ) => void; }; };
```

Vue constructor type for Sheetwrite components: Sheetwrite-owned props,
emitted events exposed as `on*` listener props, and the exposed instance
surface reachable through a template ref.

##### `SheetwriteGrid` — variable

```ts
SheetwriteComponentConstructor<SheetwriteGridProps<RowBridgeId>, SheetwriteGridEmits<RowBridgeId>, SheetwriteGridExpose>
```

Advanced framework component for workbook data or datasource input.

##### `SheetwriteGridEmits` — interface

```ts
export interface SheetwriteGridEmits<Id extends RowBridgeId = RowBridgeId> { "row-delta": Parameters<RowBridgeHandler<Id>>[0]; "grid-change": ChangeEvent; "selection-change": Selection | null; "viewport-change": GridEvents["scroll"]; "edit-begin": GridEvents["edit-begin"]; "edit-commit": GridEvents["edit-commit"]; search: GridEvents["search"]; "command-state-change": GridEvents["command-state-change"]; "active-sheet-change": GridEvents["active-sheet"]; "mutation-rejected": GridEvents["mutation-rejected"]; "renderer-fallback": GridEvents["renderer-fallback"]; "datasource-error": GridEvents["datasource-error"]; "export-error": GridEvents["export-error"]; ready: GridReadyEvent; "initialization-error": SheetwriteError; }
```

Event payloads emitted by the Vue components, keyed by template event name.

Members:
- `active-sheet-change` — The visible sheet changed.
- `command-state-change` — Command availability or formatting activity changed.
- `datasource-error` — A datasource request failed.
- `edit-begin` — Cell editing began.
- `edit-commit` — An edit committed its parsed cell value.
- `export-error` — A built-in XLSX export action failed.
- `grid-change` — Committed Grid change, including its applied transaction.
- `initialization-error` — WASM initialization failed while the component stayed mounted.
- `mutation-rejected` — A Grid mutation was rejected.
- `ready` — The adapter published a ready Grid generation.
- `renderer-fallback` — Worker rendering fell back to the main-thread canvas renderer.
- `row-delta` — Projected host-row changes.
- `search` — Refreshed search matches and active-match index.
- `selection-change` — Current selection, or `null` after it is cleared.
- `viewport-change` — Visible row bounds and vertical scroll offset after scrolling.

##### `SheetwriteGridExpose` — interface

```ts
export interface SheetwriteGridExpose { grid: Grid | null; }
```

Imperative Grid handle exposed by the Vue advanced component.

Members:
- `grid` — Live Grid after readiness, or `null` before initialization and during teardown.

##### `SheetwriteGridProps` — interface

```ts
export interface SheetwriteGridProps<Id extends RowBridgeId = RowBridgeId> { workbook: Workbook; data?: ColumnarData; datasource?: DataSource; datasourceStorage?: DataSourceStorageOptions; rowBridge?: RowBridge<Id>; renderer?: GridOptions["renderer"]; workerUrl?: GridOptions["workerUrl"]; presentation?: GridOptions["presentation"]; theme?: Partial<Theme>; readOnly?: boolean; protectionResolver?: GridOptions["protectionResolver"]; mutationPolicy?: GridOptions["mutationPolicy"]; transactionResourceLimits?: GridOptions["transactionResourceLimits"]; hyperlinkActivation?: GridOptions["hyperlinkActivation"]; renderers?: Record<string, CellRenderer>; editors?: GridOptions["editors"]; overscan?: number; minColumns?: number; config?: GridOptions["config"]; wasmSource?: SheetwriteInitializationProps["wasmSource"]; height?: number | string; fill?: boolean; }
```

Advanced Vue adapter props for workbook data or datasource ownership.

Members:
- `config` — Built-in toolbar, menu, keyboard, find, and tab controls.
- `data` — Eager column-major values for the active sheet.
- `datasource` — Lazy row provider requested for visible windows.
- `datasourceStorage` — Allocation and cache policy for datasource storage.
- `editors` — Named custom editors registered when the Grid is created.
- `fill` — Fills the parent's available width and height.
- `height` — Host height in CSS pixels for numbers or any CSS length string.
- `hyperlinkActivation` — Controls link activation: emit an event, also navigate internally, or disable it.
- `minColumns` — Minimum rendered column count, including empty padding columns.
- `mutationPolicy` — Atomic or partial handling for denied local operations.
- `overscan` — Extra rows painted above and below the viewport.
- `presentation` — Positional spreadsheet or semantic data-grid headers.
- `protectionResolver` — Host-owned client permission check for protected ranges.
- `readOnly` — Disables mutation while preserving navigation and selection.
- `renderer` — Paint backend; defaults to main-thread canvas.
- `renderers` — Named custom renderers registered when the Grid is created.
- `rowBridge` — Optional projection from canonical data-space operations to host row IDs.
- `theme` — Live overrides merged into the resolved Grid theme.
- `transactionResourceLimits` — Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
- `wasmSource` — Explicit source passed to process-wide WASM initialization.
- `workbook` — Live workbook schema adopted by the Grid.
- `workerUrl` — Browser-fetchable worker module URL.

##### `SheetwriteProps` — interface

```ts
export interface SheetwriteProps< Row extends Record<string, CellScalar> = Record<string, CellScalar>, Id extends RowBridgeId = RowBridgeId, > extends Omit<SheetwriteGridProps<Id>, "workbook" | "data" | "datasource" | "rowBridge"> { columns: readonly SimpleColumn<Row>[]; defaultRows: readonly Row[]; sheetName?: string; getRowId?: (row: Row, index: number) => Id; createRowId?: Parameters<typeof createSimpleRowBridge<Row, Id>>[0]["createRowId"]; }
```

Simple Vue adapter props for columns and default row objects.

Members:
- `columns` — Ordered schema used to derive the component-owned sheet.
- `config` — Built-in toolbar, menu, keyboard, find, and tab controls.
- `createRowId` — Creates stable identities for Grid-inserted rows.
- `datasourceStorage` — Allocation and cache policy for datasource storage.
- `defaultRows` — Rows converted to initial columnar data; missing keys become `null`.
- `editors` — Named custom editors registered when the Grid is created.
- `fill` — Fills the parent's available width and height.
- `getRowId` — Opt-in stable identity for each host row.
- `height` — Host height in CSS pixels for numbers or any CSS length string.
- `hyperlinkActivation` — Controls link activation: emit an event, also navigate internally, or disable it.
- `minColumns` — Minimum rendered column count, including empty padding columns.
- `mutationPolicy` — Atomic or partial handling for denied local operations.
- `overscan` — Extra rows painted above and below the viewport.
- `presentation` — Positional spreadsheet or semantic data-grid headers.
- `protectionResolver` — Host-owned client permission check for protected ranges.
- `readOnly` — Disables mutation while preserving navigation and selection.
- `renderer` — Paint backend; defaults to main-thread canvas.
- `renderers` — Named custom renderers registered when the Grid is created.
- `sheetName` — Generated sheet name; defaults to `Sheet 1`.
- `theme` — Live overrides merged into the resolved Grid theme.
- `transactionResourceLimits` — Overrides inclusive operation-count and encoded-byte ceilings for every atomic mutation.
- `wasmSource` — Explicit source passed to process-wide WASM initialization.
- `workerUrl` — Browser-fetchable worker module URL.

##### `SimpleColumn` — interface

```ts
export interface SimpleColumn<Row extends Record<string, CellScalar>> { key: keyof Row & string; title: string; width?: number; type?: CellFormat; numberFormat?: string; headerStyle?: CellStyle; editor?: string; cellStyle?: CellStyle; visible?: boolean; }
```

Column definition accepted by the adapters’ simple row-object API.

Members:
- `cellStyle` — Base style merged beneath cell-specific styles.
- `editor` — Name of a custom editor registered through `GridOptions.editors`.
- `headerStyle` — Style applied to the painted column header.
- `key` — Non-empty row-object key, unique within the column list.
- `numberFormat` — Excel number-format code used for number, date, or currency display.
- `title` — Semantic title painted in data-grid mode and written by table exports.
- `type` — Input and formatting type; defaults to `text`.
- `visible` — Set to `false` to exclude the column from the live view and table exports.
- `width` — Unzoomed width in CSS pixels; defaults to 120.

#### `@sheetwrite/vue/styles.css` — asset

Declaration target: `./styles.css`
Page: https://sheetwrite.vercel.app/docs/api/vue-styles-css/

### `@sheetwrite/wasm`

#### `@sheetwrite/wasm` — internal

Declaration target: `./loader.d.ts`
Source entry: `loader.d.ts`
Page: https://sheetwrite.vercel.app/docs/api/wasm/

##### `CellOut` — class

```ts
class CellOut { free: () => void; kind: number; num: number; string: string | undefined; style: number }
```

Result of a single-cell read.

##### `CellStore` — class

```ts
class CellStore { acknowledgeRevision: (revision: bigint) => void; addPagedSheet: (n_cols: number, row_count: number, chunk_rows: number, byte_budget: number, max_dirty_cells: number) => number; addRows: (sheet: number, at: number, count: number) => void; addSheet: (n_cols: number, row_count: number) => number; aggregate: (sheet: number, col: number, op: number) => number; beginMutation: () => bigint; beginPageLoad: () => void; canDirtyCell: (sheet: number, row: number, col: number) => boolean; captureRange: (sheet: number, r0: number, c0: number, rows: number, cols: number) => RangeSnapshot | undefined; captureReferences: (sheet: number, max_entries: number) => SourceSnapshot | undefined; captureSources: (sheet: number, r0: number, c0: number, rows: number, cols: number) => SourceSnapshot | undefined; captureSourcesForRows: (sheet: number, rows: Uint32Array, cols: Uint32Array) => SourceSnapshot | undefined; cellState: (sheet: number, row: number, col: number) => number; clearCell: (sheet: number, row: number, col: number, style: number) => void; clearRange: (sheet: number, r0: number, c0: number, r1: number, c1: number, contents: boolean, style: boolean) => boolean; colCount: (sheet: number) => number; columnsFullyLoaded: (sheet: number, start_row: number, end_row: number, cols: Uint32Array) => boolean; compactStringStorage: () => void; dataEdge: (sheet: number, row: number, col: number, d_row: number, d_col: number) => number; dataEdgeOrdered: (sheet: number, order: Uint32Array, row: number, col: number, d_row: number, d_col: number) => number; dirtyRevision: (sheet: number, row: number, col: number) => bigint; distinctValues: (sheet: number, col: number, limit: number) => DistinctColumn; endMutation: () => void; endPageLoad: () => void; filterRows: (sheet: number, col: number, needle: string) => Uint32Array; filterRowsMulti: (sheet: number, cols: Uint32Array, kinds: Uint8Array, flags: Uint8Array, nums: Float64Array, num_counts: Uint32Array, text_counts: Uint32Array, value_nums: Float64Array, value_texts: string[]) => Uint32Array; formulaMatrixResourceStats: () => Float64Array; formulaSource: (sheet: number, row: number, col: number) => string | undefined; free: () => void; getCell: (sheet: number, row: number, col: number) => CellOut; getWindow: (sheet: number, row_start: number, row_end: number, cols: Uint32Array) => WindowView; getWindowRows: (sheet: number, rows: Uint32Array, cols: Uint32Array) => WindowView; hydratePageNumbers: (sheet: number, col: number, start_row: number, values: Float64Array, style: number, protected_offsets: Uint32Array) => void; hydratePageStringsPacked: (sheet: number, col: number, start_row: number, buf: string, utf16_lens: Uint32Array, style: number, protected_offsets: Uint32Array) => void; insertCols: (sheet: number, at: number, count: number) => void; isFullyLoaded: (sheet: number) => boolean; isPaged: (sheet: number) => boolean; isSheetAlive: (sheet: number) => boolean; markCellCleanRevision: (sheet: number, row: number, col: number, revision: bigint) => boolean; markRangeClean: (sheet: number, start_row: number, end_row: number, start_col: number, end_col: number) => void; memoryStats: () => Float64Array; pagedDirtyCoordinates: (sheet: number) => Float64Array; pagedStats: (sheet: number) => Float64Array; persistedCellData: (sheet: number) => Float64Array; pinRange: (sheet: number, start_row: number, end_row: number, cols: Uint32Array) => void; poolStrings: (ids: Uint32Array) => string[]; queryResourceStats: () => Float64Array; rangeFullyLoaded: (sheet: number, r0: number, c0: number, r1: number, c1: number) => boolean; rangeStyleIds: (sheet: number, r0: number, c0: number, r1: number, c1: number) => Uint32Array; recompute: (sheet: number) => void; recomputeChanged: () => void; recomputeVolatile: (serial: number) => boolean; referenceTarget: (sheet: number, row: number, col: number) => Uint32Array | undefined; referencesTargeting: (target_sheet: number, max_entries: number) => Uint32Array | undefined; remapRangeStyles: (sheet: number, r0: number, c0: number, r1: number, c1: number, old_ids: Uint32Array, new_ids: Uint32Array) => boolean; removeCols: (sheet: number, at: number, count: number) => void; removeNamedRange: (name: string, scope: number) => boolean; removeRows: (sheet: number, at: number, count: number) => void; removeSheet: (sheet: number) => boolean; removeTable: (id: string) => boolean; renameSheet: (sheet: number, id: string, name: string) => boolean; resetFormulaMatrixResourceStats: () => void; resetQueryResourceStats: () => void; restoreRange: (sheet: number, r0: number, c0: number, snapshot: RangeSnapshot) => boolean; rowCount: (sheet: number) => number; search: (sheet: number, cols: Uint32Array, query: string, case_insensitive: boolean, whole_cell: boolean) => Uint32Array; setBlock: (sheet: number, start_row: number, start_col: number, rows: number, cols: number, kinds: Uint8Array, numbers: Float64Array, texts: string[], styles: Uint32Array, formula_offsets: Uint32Array, formula_sources: string[], reference_offsets: Uint32Array, reference_targets: Uint32Array) => number; setBool: (sheet: number, row: number, col: number, value: boolean, style: number) => void; setColumnNumbers: (sheet: number, col: number, start_row: number, values: Float64Array, style: number) => void; setColumnStrings: (sheet: number, col: number, start_row: number, values: string[], style: number) => void; setColumnStringsPacked: (sheet: number, col: number, start_row: number, buf: string, utf16_lens: Uint32Array, style: number) => void; setConditionalRules: (sheet: number, kinds: Uint8Array, bounds: Uint32Array, nums: Float64Array, strs: string[], flags: Uint8Array) => void; setFormula: (sheet: number, row: number, col: number, src: string, style: number) => number; setNamedRange: (name: string, scope: number, sheet: number, row_start: number, col_start: number, row_end: number, col_end: number) => boolean; setNumber: (sheet: number, row: number, col: number, value: number, style: number) => void; setSheetName: (sheet: number, id: string, name: string) => void; setSparseBlock: (sheet: number, start_row: number, start_col: number, rows: number, cols: number, offsets: Uint32Array, kinds: Uint8Array, numbers: Float64Array, texts: string[], styles: Uint32Array, formula_offsets: Uint32Array, formula_sources: string[], reference_offsets: Uint32Array, reference_targets: Uint32Array) => number; setSpillBlockers: (sheet: number, bounds: Uint32Array) => boolean; setString: (sheet: number, row: number, col: number, value: string, style: number) => void; setTable: (id: string, name: string, sheet: number, row_start: number, col_start: number, row_end: number, col_end: number, header_row: boolean, totals_row: boolean, column_ids: string[], column_names: string[]) => boolean; snapshotNumbers: (snapshot: RangeSnapshot) => Float64Array; snapshotTexts: (snapshot: RangeSnapshot) => string[]; sortRows: (sheet: number, col: number, ascending: boolean) => Uint32Array; sortRowsMulti: (sheet: number, cols: Uint32Array, ascending: Uint8Array, candidates: Uint32Array) => Uint32Array; spillAnchorCol: (sheet: number, row: number, col: number) => number; spillAnchorRow: (sheet: number, row: number, col: number) => number; spillDerivedMask: (sheet: number, row_start: number, row_end: number, cols: Uint32Array) => Uint8Array; spillOwnerCoordinates: (sheet: number, row_start: number, row_end: number, cols: Uint32Array) => Uint32Array; styleIdAt: (sheet: number, row: number, col: number) => number; wasmCommittedBytes: () => number }
```

The workbook-wide store: every sheet, one string pool.

Members:
- `addPagedSheet` — Allocate a logical sheet whose cell chunks materialize on page load or edit.
- `addSheet` — Allocate a sheet grid and return its numeric handle.
- `aggregate` — Column aggregate over numeric cells. op: 0 sum, 1 avg, 2 min, 3 max, 4 count.
- `captureRange` — Capture a dense rectangle into an opaque store-local history resource.
- `captureReferences` — Capture only persisted references for one sheet. The explicit entry cap
bounds allocation for host-side structural admission simulation.
- `captureSources` — Capture only persisted formula/reference sources in a rectangle. The
returned opaque object is compact in source cardinality, not cell count.
- `captureSourcesForRows` — Capture persisted formula/reference sources and derived-spill identity
for arbitrary row/column coordinates in one boundary crossing. Offsets
follow the caller's row-major coordinate order.
- `cellState` — 0 unloaded, 1 loaded-empty, 2 loaded-value, 3 dirty local edit.
- `clearRange` — Clear a rectangle while independently controlling contents and style.
- `compactStringStorage` — Release geometric growth slack after a bounded bulk ingest.
- `dataEdge` — Ctrl+Arrow destination: from `(row, col)` stepping by `(d_row, d_col)`
(exactly one of them ±1), return the destination row (vertical moves) or
column (horizontal moves), Google Sheets semantics:

- current and adjacent cell non-empty → end of the contiguous non-empty
 run;
- otherwise → the next non-empty cell in that direction;
- nothing ahead → the sheet edge.
- `filterRows` — Data-row indices whose column text contains `needle` (case-insensitive).
- `formulaMatrixResourceStats` — Benchmark diagnostic: `[current matrix bytes, peak matrix bytes, allocations]`.
- `getCell` — Single-cell read for interactions/tests — never the render hot path.
- `getWindow` — One bulk read of a rectangular window for the renderer. Returns
contiguous packed cell data (row-major over `rows x cols`) plus the
unique strings referenced by the window, so the host paints without
crossing the boundary per cell.
- `getWindowRows` — Bulk read of an explicit row list (sorted/filtered views) — same output
shape as `get_window`, rows taken from `rows` rather than a range.
- `hydratePageNumbers` — Hydrate one datasource page column while retaining local dirty cells and
request-revision exceptions. `protected_offsets` is sorted and relative
to `start_row`.
- `hydratePageStringsPacked` — Packed-string counterpart to [`CellStore::hydrate_page_numbers`].
- `pagedStats` — `[chunks, loaded cells, dirty cells, clean chunk bytes, fully loaded, dirty bytes]`.
- `persistedCellData` — Sparse persisted-cell records. Each record starts with
`[row, col, kind, number, style, string_id, source_kind, source_length]`.
Formula UTF-8 is packed into little-endian u32 words; references append
one `[sheet, row, col]` triple. The allocation scales with serialized
cells and source bytes, never the logical sheet rectangle.
- `queryResourceStats` — `[contains cache constructions, owned distinct strings]`.
- `rangeStyleIds` — Unique style ids present in a rectangle; cost stays inside WASM.
- `recompute` — Recompute formulas affected by cells changed since the last call.

The pass first grows the dirty cell set through formula read-sets to find
all dependent formulas. It then evaluates only those formulas, using a
per-pass memo table so each formula cell is evaluated at most once even
when many downstream formulas reference it.
- `recomputeChanged` — Recompute the union of every dirty sheet once at the host transaction
barrier, including cross-sheet formula and plain-reference dependents.
- `recomputeVolatile` — Explicit volatile barrier. `serial` is a UTC spreadsheet serial using
the 1899-12-30 epoch; only TODAY/NOW formulas and their dependents dirty.
- `referencesTargeting` — Return packed `[source_sheet, source_row, source_col, ...]` references
targeting one sheet, bounded before crossing into the host.
- `remapRangeStyles` — Remap styles over a rectangle using parallel old/new id tables.
- `removeSheet` — Tombstone a stable sheet handle and invalidate every formula reference to it.
- `renameSheet` — Rename a live stable sheet handle and rewrite every resolved formula AST reference.
- `restoreRange` — Restore a captured block at a destination of the same dimensions.
- `search` — Cell coordinates whose text matches `query`, as a flat `[row, col, ...]`
list. Scans the requested columns column-major (cache-local), then sorts
row-major so search navigation runs top-to-bottom, left-to-right.
- `setBlock` — Atomically write one row-major mixed literal/formula/reference block.
Formula/reference offsets are sparse row-major exceptions. Reference
targets are packed `[sheet_handle, row, col]` triples. The compact
status is `0` success, `1` invalid shape/bounds, `2` invalid or duplicate
source metadata, and `3` paged dirty-capacity rejection.
- `setColumnNumbers` — Bulk-load one column with numbers starting at `start_row`.
- `setColumnStrings` — Bulk-load one column with strings starting at `start_row`.
- `setColumnStringsPacked` — Bulk-load one column of strings from a single concatenated buffer plus
per-row lengths in UTF-16 code units (the JS `string.length` unit).
One boundary decode and one Rust allocation for the whole column,
instead of one per row — the dominant ingest cost for text columns.
- `setConditionalRules` — Replace a sheet's conditional-format rules. Packed columnar encoding,
one entry per rule: `kinds` 0 gt / 1 lt / 2 eqNum / 3 eqStr / 4 eqEmpty /
5 contains / 6 boolean formula; `bounds` = normalized `[r0, c0, r1, c1]`
per rule; `nums` carries the numeric operand; `strs` the text/formula
operand; `flags` bit 0 = match-case for `contains`, bit 1 = stop-if-true.
Formula strings are parsed once here, never once per visible cell.
- `setFormula` — Parse and store an arithmetic formula at `(row, col)`.

Setters only mark cells dirty; they do not recompute formulas. The host
calls `recompute(sheet)` once at the transaction barrier so a multi-cell
edit performs one dependency-scoped pass instead of one full-sheet pass
per setter. The returned value is the previous cached value until that
barrier recompute runs, and the store facade ignores it for batched edits.
- `setSparseBlock` — Write one sparse mixed transaction/page/snapshot block without
allocating by logical rectangle size. Inside `beginPageLoad`, dirty
paged cells are skipped; otherwise the whole sparse write is preflighted.
- `setSpillBlockers` — Replace the host-owned merge/protection collision ranges. Packed as
`[row_start, col_start, row_end, col_end, ...]`; invalid input fails
without weakening the old gate.
- `sortRows` — Stable row order sorted by a column. Returns a data-row permutation.
- `spillAnchorRow` — Stable spill owner coordinate, or `u32::MAX` when `cell` is not part of
a materialized spill.
- `spillDerivedMask` — Row-major mask aligned with render-window layout; `1` marks a derived
spill cell and deliberately excludes the anchor.
- `spillOwnerCoordinates` — Packed row-major `[anchor_row, anchor_col, ...]` owner coordinates.
- `styleIdAt` — Current style-dictionary id at a cell; `0` when out of bounds. Used by
the host to write derived (reference-shadow) values without disturbing
the cell's style.

##### `DistinctColumn` — class

```ts
class DistinctColumn { free: () => void; takeKinds: () => Uint8Array; takeNumbers: () => Float64Array; takeTexts: () => string[] }
```

Distinct-value scan result for one column: parallel kind/number/text
arrays whose buffers are surrendered once through the `take*` accessors.

Members:
- `takeKinds` — Surrenders the per-value kind tags (number/string/boolean codes); the
column keeps an empty buffer afterwards.
- `takeNumbers` — Surrenders the numeric values aligned with the `takeKinds` tags.
- `takeTexts` — Surrenders the distinct strings aligned with the `takeKinds` tags.

##### `InitInput` — type

```ts
export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
```

Sources accepted by asynchronous initialization: a fetchable URL/request/response, raw module bytes, or a precompiled `WebAssembly.Module`.

##### `InitOutput` — interface

```ts
export interface InitOutput { readonly memory: WebAssembly.Memory; readonly __wbg_cellout_free: (a: number, b: number) => void; readonly __wbg_cellstore_free: (a: number, b: number) => void; readonly __wbg_distinctcolumn_free: (a: number, b: number) => void; readonly __wbg_rangesnapshot_free: (a: number, b: number) => void; readonly __wbg_sourcesnapshot_free: (a: number, b: number) => void; readonly __wbg_windowview_free: (a: number, b: number) => void; readonly cellout_kind: (a: number) => number; readonly cellout_num: (a: number) => number; readonly cellout_string: (a: number) => [number, number]; readonly cellout_style: (a: number) => number; readonly cellstore_acknowledgeRevision: (a: number, b: bigint) => void; readonly cellstore_addPagedSheet: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_addRows: (a: number, b: number, c: number, d: number) => void; readonly cellstore_addSheet: (a: number, b: number, c: number) => number; readonly cellstore_aggregate: (a: number, b: number, c: number, d: number) => number; readonly cellstore_beginMutation: (a: number) => bigint; readonly cellstore_beginPageLoad: (a: number) => void; readonly cellstore_canDirtyCell: (a: number, b: number, c: number, d: number) => number; readonly cellstore_captureRange: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_captureReferences: (a: number, b: number, c: number) => number; readonly cellstore_captureSources: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_captureSourcesForRows: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_cellState: (a: number, b: number, c: number, d: number) => number; readonly cellstore_clearCell: (a: number, b: number, c: number, d: number, e: number) => void; readonly cellstore_clearRange: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number; readonly cellstore_colCount: (a: number, b: number) => number; readonly cellstore_columnsFullyLoaded: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_compactStringStorage: (a: number) => void; readonly cellstore_dataEdge: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_dataEdgeOrdered: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => number; readonly cellstore_dirtyRevision: (a: number, b: number, c: number, d: number) => bigint; readonly cellstore_distinctValues: (a: number, b: number, c: number, d: number) => number; readonly cellstore_endMutation: (a: number) => void; readonly cellstore_endPageLoad: (a: number) => void; readonly cellstore_filterRows: (a: number, b: number, c: number, d: number, e: number) => [number, number]; readonly cellstore_filterRowsMulti: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number) => [number, number]; readonly cellstore_formulaMatrixResourceStats: (a: number) => [number, number]; readonly cellstore_formulaSource: (a: number, b: number, c: number, d: number) => [number, number]; readonly cellstore_getCell: (a: number, b: number, c: number, d: number) => number; readonly cellstore_getWindow: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_getWindowRows: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_hydratePageNumbers: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void; readonly cellstore_hydratePageStringsPacked: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number) => void; readonly cellstore_insertCols: (a: number, b: number, c: number, d: number) => void; readonly cellstore_isFullyLoaded: (a: number, b: number) => number; readonly cellstore_isPaged: (a: number, b: number) => number; readonly cellstore_isSheetAlive: (a: number, b: number) => number; readonly cellstore_markCellCleanRevision: (a: number, b: number, c: number, d: number, e: bigint) => number; readonly cellstore_markRangeClean: (a: number, b: number, c: number, d: number, e: number, f: number) => void; readonly cellstore_memoryStats: (a: number) => [number, number]; readonly cellstore_new: () => number; readonly cellstore_pagedDirtyCoordinates: (a: number, b: number) => [number, number]; readonly cellstore_pagedStats: (a: number, b: number) => [number, number]; readonly cellstore_persistedCellData: (a: number, b: number) => [number, number]; readonly cellstore_pinRange: (a: number, b: number, c: number, d: number, e: number, f: number) => void; readonly cellstore_poolStrings: (a: number, b: number, c: number) => [number, number]; readonly cellstore_queryResourceStats: (a: number) => [number, number]; readonly cellstore_rangeFullyLoaded: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_rangeStyleIds: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number]; readonly cellstore_recompute: (a: number, b: number) => void; readonly cellstore_recomputeChanged: (a: number) => void; readonly cellstore_recomputeVolatile: (a: number, b: number) => number; readonly cellstore_referenceTarget: (a: number, b: number, c: number, d: number) => [number, number]; readonly cellstore_referencesTargeting: (a: number, b: number, c: number) => [number, number]; readonly cellstore_remapRangeStyles: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => number; readonly cellstore_removeCols: (a: number, b: number, c: number, d: number) => void; readonly cellstore_removeNamedRange: (a: number, b: number, c: number, d: number) => number; readonly cellstore_removeRows: (a: number, b: number, c: number, d: number) => void; readonly cellstore_removeSheet: (a: number, b: number) => number; readonly cellstore_removeTable: (a: number, b: number, c: number) => number; readonly cellstore_renameSheet: (a: number, b: number, c: number, d: number, e: number, f: number) => number; readonly cellstore_resetFormulaMatrixResourceStats: (a: number) => void; readonly cellstore_resetQueryResourceStats: (a: number) => void; readonly cellstore_restoreRange: (a: number, b: number, c: number, d: number, e: number) => number; readonly cellstore_rowCount: (a: number, b: number) => number; readonly cellstore_search: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number]; readonly cellstore_setBlock: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number, s: number, t: number, u: number, v: number) => number; readonly cellstore_setBool: (a: number, b: number, c: number, d: number, e: number, f: number) => void; readonly cellstore_setColumnNumbers: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void; readonly cellstore_setColumnStrings: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void; readonly cellstore_setColumnStringsPacked: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void; readonly cellstore_setConditionalRules: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number) => void; readonly cellstore_setFormula: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => number; readonly cellstore_setNamedRange: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => number; readonly cellstore_setNumber: (a: number, b: number, c: number, d: number, e: number, f: number) => void; readonly cellstore_setSheetName: (a: number, b: number, c: number, d: number, e: number, f: number) => void; readonly cellstore_setSparseBlock: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number, q: number, r: number, s: number, t: number, u: number, v: number, w: number, x: number) => number; readonly cellstore_setSpillBlockers: (a: number, b: number, c: number, d: number) => number; readonly cellstore_setString: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void; readonly cellstore_setTable: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number, k: number, l: number, m: number, n: number, o: number, p: number) => number; readonly cellstore_snapshotNumbers: (a: number, b: number) => [number, number]; readonly cellstore_snapshotTexts: (a: number, b: number) => [number, number]; readonly cellstore_sortRows: (a: number, b: number, c: number, d: number) => [number, number]; readonly cellstore_sortRowsMulti: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number]; readonly cellstore_spillAnchorCol: (a: number, b: number, c: number, d: number) => number; readonly cellstore_spillAnchorRow: (a: number, b: number, c: number, d: number) => number; readonly cellstore_spillDerivedMask: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number]; readonly cellstore_spillOwnerCoordinates: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number]; readonly cellstore_styleIdAt: (a: number, b: number, c: number, d: number) => number; readonly cellstore_wasmCommittedBytes: (a: number) => number; readonly distinctcolumn_takeKinds: (a: number) => [number, number]; readonly distinctcolumn_takeNumbers: (a: number) => [number, number]; readonly distinctcolumn_takeTexts: (a: number) => [number, number]; readonly rangesnapshot_byteLength: (a: number) => number; readonly rangesnapshot_formulaOffsets: (a: number) => [number, number]; readonly rangesnapshot_formulaSources: (a: number) => [number, number]; readonly rangesnapshot_kinds: (a: number) => [number, number]; readonly rangesnapshot_referenceOffsets: (a: number) => [number, number]; readonly rangesnapshot_referenceTargets: (a: number) => [number, number]; readonly rangesnapshot_styleIds: (a: number) => [number, number]; readonly sourcesnapshot_byteLength: (a: number) => number; readonly sourcesnapshot_formulaOffsets: (a: number) => [number, number]; readonly sourcesnapshot_formulaSources: (a: number) => [number, number]; readonly sourcesnapshot_referenceOffsets: (a: number) => [number, number]; readonly sourcesnapshot_referenceTargets: (a: number) => [number, number]; readonly sourcesnapshot_spillDerived: (a: number) => [number, number]; readonly windowview_nCols: (a: number) => number; readonly windowview_takeStrings: (a: number) => [number, number]; readonly windowview_takePacked: (a: number) => [number, number]; readonly windowview_nRows: (a: number) => number; readonly __wbindgen_malloc: (a: number, b: number) => number; readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number; readonly __wbindgen_externrefs: WebAssembly.Table; readonly __wbindgen_free: (a: number, b: number, c: number) => void; readonly __externref_table_alloc: () => number; readonly __externref_drop_slice: (a: number, b: number) => void; readonly __wbindgen_start: () => void; }
```

Result of module initialization: the instantiated exports plus the shared linear memory.

##### `initSync` — function

```ts
(module: { module: SyncInitInput; } | SyncInitInput): InitOutput
```

Instantiates the given `module`, which can either be bytes or
a precompiled `WebAssembly.Module`.

##### `isLoaded` — function

```ts
(): boolean
```

Whether the WASM module has finished initializing.

##### `load` — function

```ts
(source?: BufferSource | URL | string | Request | WebAssembly.Module): Promise<void>
```

Initialize the WASM module. Idempotent and re-entrant: concurrent
same-source callers share one in-flight init; a concurrent different-source
call rejects; a different-source call after success warns and no-ops; a
rejected init is retryable. When `source` is omitted the loader picks the
right strategy for the runtime.

##### `RangeSnapshot` — class

```ts
class RangeSnapshot { byteLength: () => number; formulaOffsets: () => Uint32Array; formulaSources: () => string[]; free: () => void; kinds: () => Uint8Array; referenceOffsets: () => Uint32Array; referenceTargets: () => Uint32Array; styleIds: () => Uint32Array }
```

Opaque, store-local history payload for one dense rectangular cell block.

The host may retain this object in undo history, but it is deliberately not
part of the serialized document protocol. String payloads remain interned in
the owning `CellStore`, so snapshots must only be restored into that store.

##### `SourceSnapshot` — class

```ts
class SourceSnapshot { byteLength: () => number; formulaOffsets: () => Uint32Array; formulaSources: () => string[]; free: () => void; referenceOffsets: () => Uint32Array; referenceTargets: () => Uint32Array; spillDerived: () => Uint8Array }
```

Compact serializable projection of persisted derived-cell sources and spill
identity in one range. Offsets are row-major and sorted; reference targets
are packed `[sheet_handle, row, col]` triples.

##### `SyncInitInput` — type

```ts
export type SyncInitInput = BufferSource | WebAssembly.Module;
```

Sources accepted by synchronous initialization: raw module bytes or a precompiled `WebAssembly.Module`.

##### `WindowView` — class

```ts
class WindowView { free: () => void; nCols: number; nRows: number; takePacked: () => Uint8Array; takeStrings: () => string[] }
```

A bulk window of resolved cells, row-major over `n_rows x n_cols`.

Members:
- `takePacked` — Consume the complete fixed-width window payload. The returned
`Uint8Array` is copied by wasm-bindgen into JS-owned memory.
- `takeStrings` — Consume formula-error sentinel strings referenced by the packed data.

#### `@sheetwrite/wasm/wasm` — asset

Declaration target: `./pkg/sheetwrite_wasm_bg.wasm`
Page: https://sheetwrite.vercel.app/docs/api/wasm-wasm/

### `@sheetwrite/xlsx`

#### `@sheetwrite/xlsx` — supported

Declaration target: `./dist/index.d.ts`
Source entry: `src/index.ts`
Page: https://sheetwrite.vercel.app/docs/api/xlsx/

##### `buildXlsxModel` — function

```ts
(workbook: Workbook, store: Store, options?: XlsxWorkbookOptions): XlsxModel | null
```

Build the active-sheet table model used by the bounded OOXML writer.

##### `registerXlsxBackends` — function

```ts
(): void
```

Register all concrete XLSX backends with the backend-neutral core contracts.

##### `sheetwriteTableExportBackend` — variable

```ts
XlsxTableExportBackend
```

Default bounded first-sheet table export backend.

##### `sheetwriteTableImportBackend` — variable

```ts
XlsxTableImportBackend
```

Default bounded first-sheet table import backend.

##### `sheetwriteWorkbookBackend` — variable

```ts
XlsxWorkbookBackend
```

Deterministic optional OOXML workbook backend implemented by Sheetwrite.

##### `XlsxModel` — interface

```ts
export interface XlsxModel { sheetName: string; columnWidths: number[]; rowHeights: (number | undefined)[]; rows: (XlsxModelCell | null)[][]; }
```

Implementation-neutral first-sheet table export model.

##### `XlsxModelCell` — interface

```ts
export interface XlsxModelCell { value: CellScalar; style?: CellStyle; numberFormat?: string; columnSpan?: number; rowSpan?: number; }
```

Implementation-neutral cell in the first-sheet table export model.

#### `@sheetwrite/xlsx/register` — supported

Declaration target: `./dist/register.d.ts`
Source entry: `src/register.ts`
Page: https://sheetwrite.vercel.app/docs/api/xlsx-register/

##### `registerXlsxBackends` — function

```ts
(): void
```

Register all concrete XLSX backends with the backend-neutral core contracts.