@aiquants/spreadsheet 0.8.0

package/README.md

@@ -0,0 +1,817 @@
+# @aiquants/spreadsheet
+
+Excel-grade spreadsheet grid for React: multi-cell selection, TSV/HTML clipboard round-trips (Excel / Google Sheets interop with a lossless own payload since v0.8), in-place editing with IME support and formula reference pointing, drag-to-resize headers with hide/unhide and autofit, a fill handle,
+declarative rich cells (formats / notes / comments / links / validation / conditional formats), rebindable Sheets-style command shortcuts and a popover layer — built on `@aiquants/virtualscroll`'s `VirtualGrid` and proven live on a 1,000,000 × 16,384 sheet plus a 1,000,000 × **10,000,000**
+deep-reach proof route.
+
+## Features
+
+- ⚡ **1M rows × 10M columns**: both axes virtualized by `VirtualGrid` (v0.4 — quantized column anchor + residual transform, so layout coordinates never approach the browser's ~2^25 px LayoutUnit wall); DOM holds only visible cells + overscan, independent of selection size and data volume; a 10,000,000-column deep jump lands cells within ±1px
+- 🖱️ **Excel selection semantics**: drag ranges, Shift/Ctrl extend & append, Ctrl+click/drag **subtraction** (deselect cells inside a selection), header row/column selection with Ctrl+click toggle-off, corner select-all, Ctrl/Shift+Space column/row banding, Tab/Enter cycling **across all selected ranges**, auto-scroll at viewport edges
+- 📐 **Drag-to-resize headers, hide/unhide, autofit**: 6px boundary strips with a live guideline, drag-to-zero hides a track, 3px double-line markers restore hidden runs (including a hidden column A), double-click autofit, fan-out over full row/column selections
+- 🖊️ **Fill handle (autofill)**: corner handle on single-range selections, bounding-box drag (single-axis bands or one-gesture diagonal L-fills) with dashed preview, Excel-compatible cyclic copy fill in one `applyEdits` transaction
+- 📋 **Real clipboard, Excel-compatible TSV**: only cells containing tabs/newlines are quoted (a literal `"hi"` survives untouched), dual `text/plain` + `text/html` payloads (`mso-data-placement:same-cell`), tiling paste onto integer-multiple ranges, cut-move — and **both copy and cut arm an animated marching-ants marquee** (Excel-style; a copy's ants survive paste for repeated pasting, Escape or editing dismisses them; static under `prefers-reduced-motion`)
+- ✏️ **In-place editing**: F2 / double-click (caret lands on the clicked character in real browsers) / type-to-replace, Alt+Enter multiline, full IME composition support (Safari and Chrome event orders both handled)
+- 🧮 **Consumer-owned data**: a 4-member adapter (`rowCount` / `colCount` / `getCellText` / `applyEdits`) is the whole data contract — bring your own store, undo stack, and validation; an optional `findDataEdge` capability unlocks Excel Ctrl+Arrow data-edge jumps, and an optional `getCellFormat` capability (v0.7) adds built-in, totally fail-soft display formats —
+  value-aware auto-alignment (values that actually parse go right, labels stay left) plus number/currency/percent/scientific/date value formats over the display string (exact-decimal Intl formatting, interned formatters, timezone-proof pure-calendar dates), editing and copy still carrying the raw value — without a `renderCell`
+
+- 🕳️ **Hidden tracks are first-class**: zero-size rows/columns render nothing, arrows and Shift-arrows jump a hidden run in one keystroke, Home/End land on visible tracks, and rendering stays fast across 100,000-column hidden runs
+- 🛡️ **Never silently freezes**: every bulk operation (copy / cut / delete / paste / fill / resize fan-out / autofit) is size-estimated **before** any expansion and rejected past its `maxOperationCells`-derived ceiling with a typed callback
+- ♿ **Screen-reader announcements (opt-in)**: provide the formatter props and cell/selection changes are announced via a debounced live region — the package ships no built-in strings
+- 🧊 **Frozen columns & rows** (v0.5 / v0.6): `frozenColumns` pins the first N columns as a static left band and `frozenRows` pins the first N rows as a static top band — two-band headers, a Cartesian-product 4-quadrant clipped selection overlay, partition-aware hit-testing and ensure-visible on both axes, all riding the engine's anchor-free frozen bands
+- 🎨 **Rich cells as capability declarations** (v0.8 — ADR-13): eight optional adapter reads (`getCellFormat` / `getCellFormula` / `getCellNote` / `getCellComments` / `getCellHyperlink` / `getCellValidation` / `getConditionalFormats` / `getRangeExtrema` + `evaluateFormula`) unlock the full cell
+  format model (value format, alignment, vertical alignment, wrap, background / font colour, bold / italic / underline / strikethrough, font family / size in pt, per-side borders with Excel-style ownership folding), note / comment / link indicators, paint-time validation marks and sheet-level
+  conditional formats (cell value / text / empty / colour scale / custom formula, 2-D bucket index, first-match-per-property precedence) — every undeclared aspect keeps the v0.7 DOM byte-identical, and writes go through a patch-typed `applyEdits(edits, context)`
+  (`CellEdit = { row, col } & CellPatch`, absent key = untouched, `null` = clear) with a transaction id and a discriminated `EditContext`
+- 📎 **Excel / Sheets clipboard interop with a lossless own payload** (ADR-14): copy writes `text/plain` (raw TSV), `text/html` (an interop table Excel and Sheets read — typed `x:num` / `mso-number-format` / `data-sheets-*` attributes) carrying the package's lossless JSON in a `data-aqsp-clip`
+  attribute, plus a custom MIME fast marker on the paste event; paste detects ONE source (own → Sheets → Excel → generic HTML → TSV), estimates before materialising, and Paste Special (values / formats / formulas / no borders / widths / validation / conditional formats / comments and notes, Excel
+  arithmetic operations, skip blanks, transpose) runs on both the keyboard (`Ctrl+Shift+V`, `Ctrl+Alt+V`) and the menu path (`handle.paste(options)` over `navigator.clipboard.read`); cut-move matches by clip id on both channels, including cross-sheet moves
+- ⌨️ **Rebindable Sheets-style commands** (ADR-17): 70 `SpreadsheetCommand` literals (bold / italic / underline / strikethrough / alignment / number formats / borders / links / notes / comments / fill down / right / selection / date / time / hide / unhide / paste special, plus unbound extension
+  commands for colours, self-calc and highlight toggles) driven by ONE built-in table (`BUILTIN_ROWS`), a canonical chord grammar (`Ctrl+Alt+Shift+KEY`, letters by the produced character or the `code` letter, everything else by `event.code`), prop-time validation with `RangeError`s, and an
+  imperative `executeCommand` / `applyFormat` / `setBorders` / `setNote` / `addComment` / `setHyperlink` / `setValidation` handle group
+- 💬 **Popover layer and highlight bands** (ADR-15): note editor + hover note tip, comment thread, hyperlink editor, validation list picker and validation message on two resident anchors positioned by the overlay (zero DOM for a v0.7 adapter with default props, `renderPopover` to replace the defaults, a 24-key `labels` bag folding the former `sinkAriaLabel` / `rootAriaLabel` props), and Excel-style active row / column / intersection highlight bands (transform-only per scroll frame, `--aqsp-band-*` colours, controlled / uncontrolled `highlight` state)
+- 🧭 **Formula reference pointing**: with `getCellFormula` declared, typing `=SUM(` and clicking, dragging or arrowing over cells inserts / replaces the reference token at the caret (`A1`, `A1:B2`, `A:A`, `1:1`), F4 cycles `$` anchors, F2 toggles the arm — the editing session, selection and sink position stay put
+- 🔧 **TypeScript**: complete type definitions, ESM + CJS artifacts
+
+## Installation
+
+```bash
+pnpm add @aiquants/spreadsheet @aiquants/virtualscroll
+```
+
+`react` / `react-dom` (`^19.2`) and `@aiquants/virtualscroll` are peer dependencies.
+
+> **Browser floor**: the built-in cell display formats (v0.7) require `Intl.NumberFormat` v3
+> (string mathematical-value input + `signDisplay: "negative"`) — **Chrome/Edge 106+, Firefox 116+,
+> Safari 15.4+**. On older engines the NUMERIC value formats (number / percent / currency /
+> scientific) fail soft to the raw text (no crash); `date` (pure calendar math) and `text`
+> never touch Intl and keep working. The package compiles against `lib: ES2023`.
+
+## Basic Usage
+
+> **Required:** import both stylesheets once — the grid relies on `@aiquants/virtualscroll`'s
+> `.aqvs-*` classes for the scroll pane and this package's `.aqsp-*` classes for the grid chrome.
+> For hosts without Tailwind, `@aiquants/spreadsheet/styles/spreadsheet.standalone.css` is a
+> self-contained alternative that **already bundles** the virtualscroll CSS — import it *instead
+> of* the pair above, never alongside (double inclusion breaks the cascade).
+
+```tsx
+import { Spreadsheet, type SpreadsheetDataAdapter } from "@aiquants/spreadsheet"
+import "@aiquants/virtualscroll/styles/virtualscroll.css"
+import "@aiquants/spreadsheet/styles/spreadsheet.css"
+
+const cells = new Map<string, string>()
+
+const adapter: SpreadsheetDataAdapter = {
+    rowCount: 100_000,
+    colCount: 500,
+    getCellText: (row, col) => cells.get(`${row}:${col}`) ?? "",
+    applyEdits: (edits, context) => {
+        // context = { transaction, source, ... } — one call is one transaction (see "Editing, Undo, and rejection")
+        for (const edit of edits) {
+            // a CellEdit is a PATCH: an absent `text` leaves the text untouched (format-only edits carry none)
+            if (edit.text === undefined) {
+                continue
+            }
+            if (edit.text === "") {
+                cells.delete(`${edit.row}:${edit.col}`)
+            } else {
+                cells.set(`${edit.row}:${edit.col}`, edit.text)
+            }
+        }
+    },
+}
+
+export const Sheet = () => (
+    <div style={{ height: 600 }}>
+        <Spreadsheet adapter={adapter} />
+    </div>
+)
+```
+
+The host element must have a resolvable height — the grid fills its parent.
+
+## The adapter contract
+
+| Member | Contract |
+| :--- | :--- |
+| `rowCount` / `colCount` | Grid dimensions. Changing them requires swapping the adapter **object** (see below). |
+| `getCellText(row, col)` | Pure, synchronous read. Called for visible cells during render, for **every cell of a copied/cut range** (bounded by `maxOperationCells`), for the source cells of a fill and the measured cells of an autofit (both bounded — see "Operation limits"), and for the active cell when announcements are enabled — a viewport-only lazy store is not sufficient. |
+| `applyEdits(edits, context)` | One call = **one transaction** (a paste, a Delete, a fill, a cell commit, a format command, a self-calc, an annotation write each arrive as a single call). Each `CellEdit` is a **patch** (`{ row, col } & CellPatch` — `text?` / `format?` / `note?` / `comments?` / `hyperlink?` / `validation?`): an absent key leaves that aspect untouched, `null` clears it (`text` has no `null` — clear is `""`), `format` is always the WHOLE canonical `CellFormat` the package computed (store it verbatim and return it from `getCellFormat`), `comments` is the whole thread (entries with an `id` are kept verbatim, entries without one are new — YOU mint `id` / `author` / `createdAt`). Edits apply in array order with **per-key last-wins** duplicates (a later edit's keys override, its omitted keys keep the earlier value — cut-move relies on it). `context` is the discriminated `EditContext` (see "Editing, Undo, and rejection"): `{ transaction, source }` or, for a paste, `{ transaction, source: "paste", sameSheet, conditionalFormats }`. Throw to reject — the grid keeps or discards the in-flight state safely and fires `onEditRejected(error, rejection)`. |
+| `findDataEdge(from, direction)` | **Optional capability.** When present, Ctrl+Arrow / Ctrl+Shift+Arrow jump to the Excel data edge instead of the grid edge; absence keeps the grid-edge jump (a capability declaration, not a value fallback). You implement the Excel rule — non-empty cell with a non-empty neighbor: end of the contiguous run; otherwise: the next non-empty cell in `direction`; none: the grid edge — because only the store can jump in O(occupied cells). Returns are validated **fail-fast before dispatch**: non-integer, out-of-axis, or off-row/column coordinates throw a `RangeError` that propagates uncaught. Reference implementation: the `/edit` demo store. |
+| `getCellFormat(row, col)` | **Optional capability** (v0.7) — the cell's built-in display format: `{ align?, value? }`. `align` (`"left"`/`"center"`/`"right"`, undefined = **auto by the actual value**: text that parses under the cell's numeric/date format — or as a strict decimal with no format — goes right; labels stay left, so a `"Total"` in a currency column is never a right-aligned impostor) lands on the cell via inline `justify-content` + a `data-aqsp-align` attribute, and the in-place editor's textarea adopts the same alignment while editing (Excel parity); `value` (`number`/`percent`/`currency` (**`currency` code required** — no region default is assumed)/`scientific`/`date`/`text`) formats the **display** string. Absence keeps the v0.1 plain, left-aligned rendering. The engine is **exact**: the validated raw string is handed to `Intl.NumberFormat` **as a string** (NumberFormat v3 mathematical values — no binary-double round-trip, so percent `scale: false` boundaries and >2^53 integers stay exact), formatters are **interned** per option tuple (construction failures too — a broken column throws once, not per cell), negative zero is suppressed via `signDisplay: "negative"` (locale-proof), and dates are **pure calendar math** — no `Date` object, so host timezones, DST gaps, and two-digit-year remapping can never corrupt or reject a real date; with `decimals` omitted, `number` keeps every typed fraction digit (Excel General parity). Formatting is **totally fail-soft** — a non-numeric string (hex/binary like `"0x10"` stays raw), an invalid/rollover/mixed-separator date (`"2026-02-30"`, `"2026-09/02"`), or an out-of-range `Intl` option all render the raw text. It applies to **display only** — editing reads the raw `getCellText` (Excel parity), and copy/TSV carry the raw value too (a **deliberate deviation** from Excel — see the deviations table). Column autofit measures the **formatted** display string, and screen-reader announcements receive both the raw `text` and the formatted `displayText`. `renderCell` takes precedence over the built-in **value format** only; the resolved **alignment** is a cell property that still applies under `renderCell`. Return values are re-read only on a re-slice, so publish a live format change by bumping `dataVersion` (or swapping the adapter). Return a shared/interned `CellFormat` per column. The exported `formatCellValue(text, value)` is the same engine, reusable inside `renderCell`. Reference: the `/format` demo. **v0.8** widens `CellFormat` to the full rich model — `verticalAlign` (`"top"` / `"middle"` / `"bottom"`), `wrap`, `background`, `color`, `bold` / `italic` / `underline` / `strikethrough`, `fontFamily`, `fontSize` (pt), `borders` (`{ top?, right?, bottom?, left? }` of `{ style: "thin" \| "medium" \| "thick" \| "dashed" \| "dotted" \| "double" \| "hair"; color? }`, default colour `BORDER_DEFAULT_COLOR` = `#000000`) — painted as inline styles + `data-aqsp-valign` / `data-aqsp-wrap` state attributes; borders follow Excel ownership (a cell draws its own right / bottom, a neighbour's left / top folds onto them, own wins) and an unparseable colour or style skips that property alone. Formats are compared and interned by their **canonical form** (`canonicalizeFormat` — sorted keys, no `undefined` / `false`), and `mergeFormat(base, patch)` returns `base` by identity when nothing changes, so a command over 10,000 cells sharing one interned base writes ONE format object. This capability also gates every format command, `handle.applyFormat` / `setBorders`, the `formats` / `noBorders` paste modes and conditional formats. |
+| `getCellFormula(row, col)` | **Optional capability** (v0.8) — the cell's formula source, which MUST start with `=` (any other string is a `RangeError` — fail-fast like `findDataEdge`); `undefined` = no formula. Declaring it makes the editor open the formula source instead of `getCellText` (Excel parity), enables **reference pointing** (see Keymap), `fillDown` / `fillRight` / `fillSelection` and the fill handle shift relative references (`shiftFormula`), self-calc commands wrap formulas instead of rewriting values, copy writes an origin-relative R1C1 `f` per cell and paste resolves it at the target (`fromR1C1`), and the `formulas` paste mode becomes available. Without it a `"="`-prefixed text is just text — the package never sniffs `=`. |
+| `getCellNote(row, col)` | **Optional capability** (v0.8) — the note text or `undefined`. Unlocks the `data-aqsp-note` indicator, the hover note tip, the note popover (`Shift+F2` / `insertNote`), `handle.setNote` and the `commentsAndNotes` paste aspect. |
+| `getCellComments(row, col)` | **Optional capability** (v0.8) — the thread as `readonly CellComment[]` (`{ id, author, text, createdAt }`, all stamped by you) or `undefined`; an empty thread shows no indicator. Unlocks `data-aqsp-comment`, the comment popover (`Ctrl+Alt+M` / `insertComment`), `handle.addComment` (sends `[...existing, { text }]` — you mint the id) and the comments paste aspect (pasted comments arrive id-less, all new). |
+| `getCellHyperlink(row, col)` | **Optional capability** (v0.8) — the cell's href or `undefined`. Every read is a trust boundary: the raw URL is normalised through `normalizeHyperlink` (`http:` / `https:` / `mailto:` / `tel:` only), and a URL outside the allowlist is treated as link-less at every seam — never navigated, never exported into a clipboard flavour, never re-committed through `CellPatch.hyperlink`. Unlocks `data-aqsp-link`, the link popover (`Ctrl+K` / `insertLink`), `Alt+Enter` (`openHyperlink` → `onHyperlinkOpen` when declared — that row exists only while the active cell has a link, a link-less cell passes through; undeclared ⇒ the popover without an Open button), Ctrl / Meta+click opening the link when `onHyperlinkOpen` is declared (the selection stays frozen; a link-less cell keeps the append-range gesture), `handle.setHyperlink` (normalised through `normalizeHyperlink` — `http:` / `https:` / `mailto:` / `tel:` only), Delete / Backspace clearing the link (`hyperlink: null`) and the hyperlink paste aspect. Saving the popover with an empty display text and a valid URL writes the normalised href as the cell text — the href becomes the display text (Sheets / Excel parity, never an invisible link on a blank cell; clearing the URL too erases the link without touching the text). |
+| `getCellValidation(row, col)` | **Optional capability** (v0.8) — the cell's `DataValidationRule` (`list` / `number` / `textLength` / `date` / `text` / `checkbox` / `custom`, each with `strict?` / `inputMessage?` / `errorMessage?`) or `undefined`; return a **stable rule object per cell** (list Sets are interned by identity). A commit that changes the text is validated (`validateCellText`): a non-strict rule accepts the value and paints the `data-aqsp-invalid` mark, a `strict: true` rule refuses the commit (`onValidationRejected` + the message popover — the editing-column Ctrl+Enter `fillSelection` runs the same gate on every selected cell's own rule before its single `applyEdits`), a blank is always valid, a half-written rule (unparseable bound, missing `b`) is inert, and `custom` rules are evaluated only at commit through `evaluateFormula` (never at paint). Unlocks the list picker (`Alt+ArrowDown`), the input-message popover on active-cell change, `handle.setValidation` and the validation paste aspect. |
+| `getConditionalFormats()` | **Optional capability** (v0.8) — the sheet's `ConditionalFormatRule[]` in priority order (`{ id, ranges, condition, style, stopIfTrue? }`; conditions `cellValue` / `text` / `empty` / `notEmpty` / `colorScale` / `customFormula`; style = background / color / bold / italic / underline / strikethrough). **Requires `getCellFormat`** (declaring it alone throws a `RangeError` at mount). Keep the array identity stable and publish changes through `dataVersion`; the grid rebuilds a lazy 2-D 256 × 256 bucket index per (rules identity, render version) and, inside each bucket, a lazily materialised per-column slice, so per-cell cost is O(rules intersecting the cell's column within its 256-row band) — for whole-column rules exactly the rules on that column, whatever the sheet width (a sheet of ≤ 256 columns has a single column band, so the bucket alone would be the whole rule set). Every true rule contributes, an earlier rule wins per property, `stopIfTrue` ends the walk. Pasted rules arrive as `context.conditionalFormats` (`ConditionalFormatRuleInput` with `sourceRuleId` — you mint the new id). |
+| `getRangeExtrema(range)` / `evaluateFormula(formula, cell)` | **Optional capabilities** (v0.8) consumed by the rules above: `getRangeExtrema` returns `{ min, max }` (or `null` = no numeric value) for a `colorScale` point without `value` — called once per rule range per render version and memoised; `evaluateFormula` receives a `customFormula` verbatim (no reference shifting — you own relative semantics) and a `custom` validation formula at commit, truth = `true` or a finite non-zero number. Undeclared ⇒ the rules that need them are skipped (nothing is substituted). |
+
+- **Adapter identity is the sheet identity.** Replacing the adapter object means "sheet switch": selection resets to A1, any in-flight drag, editing session and open popover are terminated (value-discarding, exactly like Excel switching sheets — nothing is ever committed across a swap), an armed
+  **copy** is discarded, and an armed **cut** is kept as a *foreign* clip (`onClipChange({ kind: "cut", range, foreign: true })`, its marquee hidden) so the next `Ctrl+V` on the new sheet is a **cross-sheet move** — the target sheet is written first, then the source sheet is cleared under the same
+  transaction id (see "Cut matching rule").
+- **External writes** (your toolbar Undo, collaborative updates) are published by incrementing the `dataVersion` prop. This re-renders visible cells, rebuilds the conditional-format index, **and cancels any armed clip** — otherwise a stale cut could "move" cells whose content has changed underneath.
+
+## Editing, Undo, and rejection
+
+The package owns no history. `Ctrl+Z` / `Ctrl+Y` (and `Ctrl+Shift+Z`) are **relayed** to `onUndoRequest` / `onRedoRequest`; apply the inverse patches to your store and bump `dataVersion`. The `/edit` route of the repository demo (`demo/src/EditApp.tsx` — source checkout only, not in the npm tarball) is the reference implementation: a `Map`-backed store with an inverse-patch undo/redo stack, ~60 lines.
+
+`applyEdits` may throw to reject an edit. Every rejection fires `onEditRejected(error, rejection)` exactly once, where `rejection` is an
+`EditRejection` (exported) — a discriminated union naming the write path that was refused and, for an in-cell commit, what happened
+to the editing session:
+
+```ts
+type EditRejection =
+    | { source: "edit"; editSession: "kept" | "discarded" }
+    | { source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate" } // the SpreadsheetOperation write names onOperationRejected uses
+```
+
+Every write reaches the adapter as `applyEdits(edits, context)` (v0.8 — ADR-16). `edits` are **patches** and `context` is the exported
+discriminated `EditContext`:
+
+```ts
+type CellPatch = { text?: string; format?: CellFormat | null; note?: string | null; comments?: readonly CellCommentInput[] | null; hyperlink?: string | null; validation?: DataValidationRule | null }
+type CellEdit = { row: number; col: number } & CellPatch // absent key = untouched, null = cleared (text: "" clears)
+type EditContext =
+    | { transaction: number; source: "edit" | "fill" | "delete" | "format" | "calc" | "annotate" } // PlainEditContext
+    | { transaction: number; source: "paste"; sameSheet: boolean; conditionalFormats: readonly ConditionalFormatRuleInput[] } // PasteEditContext
+```
+
+`transaction` is a per-grid-instance id that increases strictly — one per `applyEdits` call, allocated **before** the call (a rejected
+call consumes its id too), so a cross-sheet cut-move (target write on sheet B, then source clear on sheet A) can be folded into one
+Undo entry by the id. An empty transaction (no edits and no conditional formats) never reaches the adapter. `source` names the
+gesture: `"edit"` (cell commit, list pick, `insertDate` / `insertTime` while idle), `"paste"` (paste, cut-move, Paste Special — with
+`sameSheet` = the armed payload came from this adapter, and `conditionalFormats` = the pasted rules translated per tile, `[]` when
+none), `"fill"` (fill handle, `fillDown` / `fillRight` / `fillSelection`), `"delete"` (Delete / Backspace), `"format"` (format commands,
+`applyFormat` / `setBorders`), `"calc"` (`multiplyBy100` … `signReversal`), `"annotate"` (note / comment / link / validation writes). The
+`/styles` demo store (`demo/src/pages/styles/richStore.ts`) is the reference for a patch-applying store that mints comment ids and
+folds a transaction's inverse patches into one Undo entry.
+
+- **In-grid commits** (Enter, Tab / Shift+Tab, PageUp / PageDown, clicking or right-clicking another cell, or a primary-button
+  press on a header / corner / scrollbar band / resize strip — a secondary-button press on those surfaces is a native-menu
+  passthrough that neither commits nor fires `onEditRejected`) →
+  `{ source: "edit", editSession: "kept" }`: the editing session stays alive with the typed value **and focus stays in the
+  editor**, so the user can fix the value or press Escape to cancel. A rejected pointer commit (clicking another cell or a header
+  while editing) also cancels the browser's default mousedown focus move, so focus is never stranded on the grid container.
+- **Focus leaving the grid** (clicking an element outside the grid, or focus moved outside by script — Tab / Shift+Tab while
+  editing are in-grid commits, not an exit) → `{ source: "edit", editSession: "discarded" }`: a session must never survive
+  without focus, so the grid discards it as this rejection completes — the callback runs first; once it returns, the typed value
+  is gone, the session is closed, and the hidden input is re-armed immediately, **without** moving focus: it stays wherever the
+  focusout left it — on the element the user chose, or still on the hidden input after a window blur (alt-tab; a null
+  `relatedTarget` takes the same discard path). Do **not** tell the user to "press Escape" for this case: the session is already
+  gone by the time they could act, and an idle Escape hands focus out of the grid (the WCAG 2.1.2 exit), which reads as "the
+  sheet loses focus and the cell can't be returned to a non-editing state".
+- **Paste, cut-move, fill, Delete / Backspace, format commands, self-calc, annotation writes** →
+  `{ source: "paste" | "fill" | "delete" | "format" | "calc" | "annotate" }`: no editing session is
+  involved; the selection and any armed copy / cut clip are left exactly as they were. These are the `SpreadsheetOperation`
+  **write** names — the same ones `onOperationRejected` reports for the same gesture, so one label map can serve both
+  callbacks. A cut-move is the Ctrl+V gesture and is reported as `"paste"` by both callbacks (Ctrl+X itself only serializes,
+  so `"cut"` and `"copy"` never write and `"resize"` is geometry — none of them can appear here). A rejected annotation
+  write from a popover keeps the popover open in its `rejected` state (Ctrl+Enter retries, Escape closes without saving).
+  The union is spelled out
+  literally (the d.ts rollup cannot follow `Extract<SpreadsheetOperation, …>`), and its exact equality with the write
+  members is machine-sealed by a type-parity guard (`src/model/dataAdapter.spec.ts`) that fails `tsc` on a missing write
+  member, a foreign name, or a non-write member leaking in.
+- **Strict validation** (`getCellValidation` rule with `strict: true`) refuses a changed commit *before* `applyEdits`: no
+  `onEditRejected` fires — `onValidationRejected({ cell, rule, text, message })` does, the message popover opens with the
+  verdict, and the editing session follows the same kept / discarded path as an adapter rejection. The editing-column
+  Ctrl+Enter (`fillSelection`) runs the same gate on **every selected cell's own rule** (rules differ per cell) before its
+  single `applyEdits`: the first strict rejection keeps the session open and writes nothing anywhere, exactly like Enter.
+  Idle fills, the fill handle, paste and self-calc are not validated — it is a commit-time gate, as in Excel.
+
+An unchanged commit (opening the editor and leaving without changing the text) never reaches `applyEdits`, so a plain focus-out on a
+read-only sheet produces no rejection at all. The demo's `demo/src/components/editRejection.ts` (`describeEditRejection`) is a
+reference for wording a notice from this context.
+
+## Operation limits (`maxOperationCells`, default 100,000)
+
+Every bulk operation is counted **before** any memory is allocated or any cell is read. Over-limit and out-of-bounds
+operations call `onOperationRejected(op, cellCount, reason)`
+(`op: "copy" | "cut" | "delete" | "paste" | "fill" | "resize" | "format" | "calc" | "annotate"`, `reason: "limit" | "bounds"`) and do
+nothing — wire it to a toast. A cut paste that would clip at the grid edge is rejected entirely (`"bounds"`) rather than silently
+losing the clipped cells, and the cut stays armed so the user can retry at a valid target. Every v0.8 selection write (format
+commands / `applyFormat` / `setBorders` → `"format"`, self-calc → `"calc"`, `setValidation` → `"annotate"`) counts the selected cells
+against the same ceiling before reading a single cell; pasted HTML is estimated from its markup (rows × the widest row's
+Σ`colspan`, an upper bound) before a `DOMParser` is even constructed, and an own-payload paste from its 512-byte header.
+
+**What `cellCount` counts — and the per-operation ceilings.** The count definitions are deliberately asymmetric: each
+operation counts the unit that actually costs, and the two resize-family gates use measured, lower ceilings (the flat
+`maxOperationCells` would let multi-second freezes through):
+
+| Operation | `cellCount` counts | Ceiling |
+| :--- | :--- | :--- |
+| `copy` / `cut` / `delete` / `paste` | Cells of the operated range(s) | `maxOperationCells` |
+| `fill` | Region cells (box − source) **+ charged source reads** — full m×n source block for a diagonal box; orthogonal span × min(source length, band length) for a pure band (v0.2-identical). An upper bound on distinct reads; a sum, not a range size | `maxOperationCells` |
+| `resize` (drag fan-out, columns) | Target tracks across all full-span selected ranges | `maxOperationCells` |
+| `resize` (drag fan-out, rows) | Target tracks, same as columns | **`maxOperationCells / 10`** — per-row height updates carry an unbatchable per-call cost (measured) |
+| `resize` (double-click autofit) | **Measured cells** = target columns × visible rows (the unit that costs; a track-count gate would let 16k columns × 40 visible rows through) | **`maxOperationCells / 4`** — per-cell text measurement cost (measured) |
+| `resize` (`hideRows` / `unhideRows` commands) | Selected row span (counted before materialising, overlapping ranges counted twice) | **`maxOperationCells / 10`** (same as row fan-out) |
+| `resize` (`hideColumns` / `unhideColumns` commands, pasted column widths) | Selected column span / pasted column tracks (the paste rectangle's width — the payload placed once on a 1 × 1 target, tiled over an integer-multiple target) | `maxOperationCells` |
+| `resize` (pasted row heights) | Pasted row tracks (the paste rectangle's height, counted the same way — a whole-row copy of R rows pasted onto a 1 × 1 target counts R) | **`maxOperationCells / 10`** (row axis — the same divisor as row fan-out and `hideRows`; a refusal leaves the pasted cells in place, because sizes are applied after the cell commit) |
+| `format` / `calc` / `annotate` | Cells of the selected range(s) | `maxOperationCells` |
+
+`reason: "bounds"` has three sources: a cut-move clipped at the grid edge, a cut-move whose armed source range has fallen off
+the source adapter's **current extents** (rows / columns deleted after `Ctrl+X` — see "Cut matching rule"), and a row hide
+(drag-to-zero, fan-out, the `hideRows` command or pasted row heights of 0) that would push the **axis-wide hidden-row total
+past 1,000** — for that one, `cellCount` reports the would-be hidden total.
+
+## Copy / cut marquee (marching ants)
+
+Both `Ctrl+C` and `Ctrl+X` arm an animated marching-ants marquee drawn **3px outside** the source range's border, so it
+never hides under the selection fill or the active-cell ring (visually identical for both kinds, Excel-style; the node
+carries `data-aqsp-clip-kind="copy" | "cut"` for styling/test hooks). A **copy** marquee survives
+paste — repeated pasting keeps the ants, exactly like Excel (including pastes of foreign clipboard content: the
+browser exposes no clipboard-change event, so unlike desktop Excel the ants cannot auto-dismiss when another app
+replaces the clipboard — a purely visual trait, since a copy clip can never trigger the move path) — and is dismissed by Escape, starting an edit, any other
+successful `applyEdits` **except a format or annotation commit** (Ctrl+B, a note or link write keep the ants, like Excel), undo/redo, a sheet switch, or a `dataVersion` bump. A **cut** marquee is consumed by its
+paste (the move) and additionally dismissed by the same triggers — with one exception: a sheet switch keeps the cut record as a
+*foreign* clip (marquee hidden, `onClipChange` reports `foreign: true`) so it can complete as a cross-sheet move; Escape discards
+a foreign cut too. Paste Special of an armed cut (values only, transpose, an operation, skip blanks) is a **copy-semantics** paste
+that keeps the cut armed. The ants stop animating under
+`prefers-reduced-motion: reduce` (the dashes stay visible) and degrade to a dashed `Highlight` border on the same
+edge-clamped ::after in forced-colors mode. Non-editing cells use the platform `default` (arrow) cursor; **only the cell being edited shows the `text` (caret) cursor** over its content. The Excel-style `cell` cross was dropped so the double-click no longer flashes the default arrow *between* two cross states (the reported 十字→矢印→十字) — the cursor value now changes at most once, on edit entry (arrow → caret).
+
+## Cut matching rule
+
+Every copy or cut stamps its payload with a fresh 128-bit **clip id** (`crypto.getRandomValues`) that travels in all three
+flavours the package writes — `text/plain` never carries it, so the match never depends on the text. `Ctrl+X` arms a cut record
+(`{ kind: "cut", range, clipId, sourceAdapter, payload }`). A later paste becomes a **move** (clear source + write destination) only
+when ALL of these hold:
+
+1. the clipboard's detected source is the package's own flavour (`application/x-aqsp-clip` on the paste event, or the
+   `data-aqsp-clip` attribute of the `text/html` table on either channel) **and** its header `clipId` equals the armed one —
+   the identity check reads only the first 512 bytes, never the body; a `text/plain`-only paste after a cut (another app
+   replaced the clipboard, or a host that strips HTML) is a **plain paste**, not a move;
+2. the paste is a *plain* paste: `mode: "all"`, no `operation`, no `transpose`, no `skipBlanks` — every Paste Special of a
+   cut is a copy-semantics paste that keeps the cut armed (Excel disables Paste Special after a cut; here it simply copies).
+
+A move never tiles (a 1×1 target expands once from the active cell) and is rejected whole with `reason: "bounds"` when it would
+clip at the grid edge (the cut stays armed). The same `"bounds"` refusal fires when the armed source range no longer fits the
+source adapter's **current extents** (rows or columns deleted after `Ctrl+X`, with or without a sheet switch — the deferred
+re-read and the source clears must never touch outside the grid; the cut stays armed, so restoring the axis lets the same
+record move). The cut record is a **reference to the range**, as in Excel: the moved cells are re-read
+from the source adapter at paste time (the payload captured at `Ctrl+X` keeps only the clip id and the dimensions), so a format,
+note, comment, hyperlink or validation committed after `Ctrl+X` (those commits keep the cut armed) travels with the move instead of
+being silently destroyed on both sides; a copy remains the snapshot taken at `Ctrl+C` (Sheets semantics). The source clear writes `text: ""` plus `null` for every aspect the **source**
+adapter declares (format / note / comments / hyperlink / validation). **Same sheet**: clears then writes in ONE transaction
+(`sameSheet: true`, overlap resolves clear → write). **Another sheet** (the adapter object changed since the cut): the target
+sheet is written first with `{ sameSheet: false, conditionalFormats: <translated rules> }`, then the source adapter receives the
+clears under the **same transaction id** (`conditionalFormats: []` — a cut never moves or removes rules from the source sheet); a
+throw from the source side is reported through `onEditRejected(error, { source: "paste" })` while the target write stands.
+
+The cut is disarmed (back to nothing) by Escape, starting an edit, a subsequent successful copy or cut, any successful
+`applyEdits` other than a format / annotation commit, an undo/redo relay, or a `dataVersion` bump; a sheet switch keeps it as a
+foreign clip (see the marquee section). Changing the selection does **not** disarm it (clicking the paste target is itself a
+selection change), and a rejected paste (limit / bounds / adapter throw) leaves it armed for a retry. The move consumes the record;
+a second `Ctrl+V` of the same clipboard content is a plain paste (see deviations).
+
+## Resize, hide/unhide, and autofit (pointer UI)
+
+Each header boundary carries a 6px grab strip **inside** the boundary (Excel's boundary-straddling zone is not replicated —
+the first pixels of the next header still select the column). Dragging shows a guideline; cell sizes change only at release,
+and releasing at the initial size is a no-op. Dragging a boundary to zero **hides** the track; a boundary that hides a run
+shows a 3px double-line **unhide marker** (a hidden run starting at column A / row 1 gets the marker on the first visible
+header's leading edge): dragging the marker re-expands the nearest hidden track, double-clicking it restores the default
+size. Degenerate (< 12px) tracks keep a 3px affordance overhanging the neighbor, so a 1px-clamped track is always
+recoverable. The last visible track of an axis can never be zeroed (it clamps to 1px) — the grid cannot be made fully
+invisible, because no menu-based recovery path exists here.
+
+When the pressed track belongs to a **full row/column selection** (header selections, Ctrl+A), the resize **fans out** to
+every selected track — hidden tracks included, which makes fan-out an implicit unhide (Excel-compatible). Fan-outs and
+hides are gated (see the limits table above; row hides are additionally capped at 1,000 hidden rows per axis).
+
+**Double-click autofit** (columns): each selected column is measured individually over the cells of the **current visible
+window** (not all data) and set to the widest text + padding; columns whose visible cells are all empty are left untouched.
+The measured text is the **formatted display string** (what the screen actually shows — v0.7): a currency column autofits
+to `"￥203,428"`, not to the raw `"203428"`, which used to left-clip the most significant digits of right-aligned cells.
+Row autofit restores the default row height (cells render single-line clipped). Autofit is disabled entirely when
+`renderCell` is set — custom cell DOM cannot be measured.
+
+> **Autofit measures with the header's font as its base.** Text measurement composes its font from the **header band's**
+> computed style (style / weight / size / family); since v0.8 the cell's **painted** format (bold / italic from the base format
+> and width-relevant conditional formats, `fontSize` in pt × 4/3, `fontFamily`) overrides those parts per cell, bucketed so
+> `ctx.font` is assigned once per distinct font. If your CSS gives body cells a different base font than the headers, autofit
+> will mismeasure — keep cell and header base fonts identical (the shipped stylesheets do).
+
+`enableResizeUI={false}` removes the strips **and the unhide markers** — a consumer with hidden tracks then has no
+in-package restore affordance (only the imperative API). The imperative `resizeRow` / `resizeColumn` calls bypass every UI
+gate (no 1px clamp, no hidden-row cap, no fan-out limit): mass-hiding rows through the API is your responsibility and falls
+outside the rendering guarantee.
+
+## Fill handle (autofill)
+
+A single-range selection shows a crosshair handle on its bottom-right corner (hidden while editing, during any other drag,
+and for multi-range selections). Dragging it extends toward the hover cell as a **bounding box** of source ∪ hover —
+single-axis drags give the classic band, and **diagonal drags fill the L-shaped region** (right band + bottom band +
+corner) in one gesture (a deliberate super-set of Excel, which is axis-constrained; cell-boundary quantization absorbs
+in-track jitter). The dashed preview shows the box; releasing applies a **cyclic copy fill** — the source pattern tiles
+with 2D source-start modular anchoring, and upward/leftward drags continue the cycle in reverse — as **one** `applyEdits`
+transaction. On success the selection becomes the box (anchor and active stay put).
+
+- Movements under 4px never write (Excel's drag threshold) — a plain click on the handle changes nothing.
+- The confirmed box is the **last previewed** box; hovering back inside the source collapses the box to nothing, so
+  releasing there changes nothing (Excel *clears* the re-covered cells — see deviations; planned).
+- Copy fill only: no series/smart fill, and double-clicking the handle does **not** fill down to adjacent data.
+- The drag carries exactly what `fillDown` / `fillRight` carry (v0.8): with `getCellFormula` declared a formula source is
+  shifted per target cell (`shiftFormula` — relative references move, `$` anchors stay); the declared aspects — canonical
+  `format`, `validation`, `hyperlink`, `note` — are copied from the source (a source without one clears the target's);
+  comments never travel (see deviations). A v0.7 adapter receives plain `{ row, col, text }` edits exactly as before.
+- The fill is size-estimated before any cell is read (see the limits table) — a rejection leaves data and selection
+  untouched, as does a rejected `applyEdits`.
+
+`enableFillHandle={false}` removes the handle and inerts the machine — recommended for read-only adapters, where every fill
+attempt would otherwise end in `onEditRejected`.
+
+## Accessibility model and trade-offs
+
+The grid renders cells as a **non-focusable virtualized surface** with a hidden 1px textarea ("sink") owning focus and
+keyboard input — this is what makes IME composition, clipboard events, and 16M-cell virtualization coexist. The trade-offs:
+
+- Screen readers do not walk cells as a native table/grid. Instead, cell and selection changes can be **announced** through a
+  debounced `aria-live="polite"` region — **strictly opt-in**: the package ships no built-in strings, and the live region is
+  rendered only when you provide `formatCellAnnouncement` and/or `formatSelectionAnnouncement`. Omit both and the grid is
+  silent to assistive technology beyond its labels. The cell-announcement context carries both `text` (the raw canonical
+  `getCellText`) and `displayText` (the formatted string a sighted user sees — identical to `text` on unformatted cells),
+  so a formatter can announce `"87.0%"` rather than `"0.87"`.
+- `labels.sinkAriaLabel` labels the input surface (its default explains the Escape hand-off in English); `labels.rootAriaLabel`
+  labels the grid container (default `"Spreadsheet"`). Both live in the `labels` prop (v0.8 — the former `sinkAriaLabel` /
+  `rootAriaLabel` props were folded into it, together with the 21 popover / indicator strings; `DEFAULT_LABELS` is exported and
+  an omitted or `undefined` key keeps its default). **Localize both together**, and a replacement `sinkAriaLabel` **must keep the
+  Escape-exit notice** — the word `Escape` must appear, otherwise the grid throws a `RangeError` while rendering: Escape moves
+  focus from the sink to the root, and without the notice (or with an unlabeled landing point) screen-reader users are stranded
+  mid-grid. Popovers are keyboard-complete (`role="dialog"` editors with an autofocused field, `role="tooltip"` note tip wired to
+  the sink's `aria-describedby` while its cell is active — a while-invariant, re-evaluated as arrow keys move the active cell in
+  both directions —, `role="combobox"` + `listbox` list picker, `role="status"` message) and
+  return focus to the sink on close; `formatCommandAnnouncement` (opt-in) announces command results with the toggle state.
+- Keyboard reachability is complete for the keymap below: every listed operation works without a pointer, and `Escape` from
+  the grid root returns focus to the page tab order (WCAG 2.1.2 — no keyboard trap). The grid never takes focus on mount
+  (the hidden input is armed focus-neutrally — WCAG 3.2.1 / 2.4.3): keyboard entry is the page tab order (Tab / Shift+Tab)
+  or a click, and re-entry always lands on the hidden input. The pointer-only affordances have non-pointer equivalents at
+  other layers: resizing via the imperative `resizeRow` / `resizeColumn`, filling via your own `applyEdits`-based UI.
+- The hidden input's `inputmode` is a **virtual-keyboard invitation**, not a mirror of the editing session — and not an idle
+  / editing predicate. It starts as `inputmode="none"`, and for keyboard and IME users it stays `"none"` forever (F2, a
+  printable key, or a composition opens the editor without touching the attribute): a touch / pen tap does not summon a
+  virtual keyboard (touch / pen is scroll-only — a tap never selects a cell or opens the editor, a long-press never fires
+  `onCellContextMenu`, and every press gate is mouse-only). Only an editor opened by pointer (double-click — the one way a
+  keyboard-less device can open one) raises the invitation to `inputmode="text"`, so a pointer-driven session on a
+  keyboard-less device whose pointer reports as `mouse` (iPad + trackpad, a tablet mode with a mouse) can get the on-screen
+  keyboard. The invitation then outlives the session: it stays `"text"` through Enter / Tab commits and Escape and through
+  the idle state after them ("type → Enter → type" keeps the keyboard), and is withdrawn only when focus really leaves the
+  grid or an idle (no session open) touch / pen press arrives (scroll intent — a tap that bounces focus back to the hidden
+  input must not summon the keyboard). A touch / pen press during an open session — caret placement or scrolling — leaves it
+  alone, so a user typing on the on-screen keyboard is not robbed of it; the withdrawal comes with the next idle touch / pen
+  press after the session ends. Because the imperative `startEdit` deliberately opens the editor **without** raising the invitation (it never
+  touches `inputmode`), the mouse double-click is the only invitation channel: a consumer-rendered "Edit" control (a toolbar
+  button calling `handle.startEdit`) opens the editor but cannot summon the on-screen keyboard — a documented limitation, not
+  a defect. The attribute therefore changes only on pointer and focus events (the double-click, whose press
+  gate has already committed any composition; an idle touch / pen press; a real grid exit, whose blur finishes a composition
+  before the focusout) and never inside an IME composition that has a session (the only session-less composition is one
+  started while a drag is in flight — `startEdit` bails on `isDragging` — and the idle sink's self-heal re-arms on every
+  `input` while no session is open, discarding it, so nothing a user could keep is affected): Chromium on Windows, Linux,
+  ChromeOS and Android forwards the change to the platform IME as a text-input-state change (macOS ignores mode-only
+  changes), and on Windows `InputMethodWinTSF::OnTextInputTypeChanged` then cancels the in-flight composition
+  (`TSFBridge::CancelComposition()` once its three early-return guards pass — a TSF bridge exists,
+  the client is the focused text-input client, the window is focused, all true in the reported situation — whether or not a
+  composition is in flight or only `inputmode` changed), which is how a session-driven attribute used to swallow a
+  single-character IME entry from an idle cell. Whether the keyboard actually appears when the attribute changes on the
+  already-focused editor depends on the engine: Chromium on Windows, Linux, ChromeOS and Android forwards the change to the
+  platform IME (macOS ignores mode-only changes), but the on-screen keyboard is shown only for focus-driven (or
+  touch-tap-driven) updates — the renderer sets `show_ime_if_needed` only for those, never for a bare attribute mutation —
+  so a bare attribute change cannot summon it (Chrome on Android with a mouse, or a Windows tablet mode with a mouse, does
+  not show it — a known limitation; a blur-and-refocus workaround would ride the focus-out discard path, so it is not used);
+  WebKit re-evaluates `inputmode` on the focused element and can show it (iPad + trackpad gets the keyboard). Hardware
+  keyboards and desktop IME are unaffected either way.
+
+## Context-menu constraint (right-click)
+
+Right-clicking a cell moves the selection (Excel-style) and calls `onCellContextMenu` with the cell and the native event —
+**the package renders no menu**; suppress the native menu and show your own, or ignore the callback to keep the browser menu.
+`Shift+F10` / the ContextMenu key deliver the same callback with a `keyboard` origin and the active cell's viewport
+rectangle. Right-clicking column/row headers is intentionally native (no column-select-plus-menu — see deviations).
+
+Right-clicks never strand keyboard focus. On every press surface (cells, column / row headers, resize strips, the corner, the
+fill handle, the scrollbar bands, and — as the last gate on the zoom wrapper — any unowned dead space such as the strip below
+the row-header band) a non-primary-button `pointerdown` (secondary, middle, back / forward) is ignored by the selection
+machinery, but its default action — the mousedown focus move from the hidden input onto the grid container — is cancelled
+(`preventDefault()` only: no `stopPropagation()`, no selection change); for the secondary button the `contextmenu` event plus
+the native menu still fire. Every mouse cell-area right-click that reaches the context-menu handler (i.e. not swallowed by the
+drag freeze) additionally recovers focus to the hidden input — before the hit test, whether or not it replaces the selection
+(a right-click inside the current selection leaves it unchanged) and whether or not the editing commit it triggers succeeds
+(a rejected commit keeps the session) — so Arrow keys, typing, and Escape keep working right after the click, also when focus
+was outside the grid before it; a consumer menu that focuses its own element afterwards still wins.
+
+Chorded buttons are covered too: a second button pressed or released while the primary is held arrives as a `pointermove`
+(never as `pointerdown` / `pointerup`, so no press gate runs) and is cancelled the same way by a root-level pointer watcher;
+releasing the primary first while a chord is held still confirms the drag instead of rolling it back — cell, header, and
+resize at that position, fill at its last painted preview band (the same box its `pointerup` confirms). The press gates are
+backed by a focus invariant: the only way focus leaves the hidden input for the grid container is the Escape hand-off, so
+the container returns focus to the hidden input only when focus arrives on it straight from the hidden input without that
+hand-off — a touch / pen tap (the press gates, including the zoom-wrapper dead-space gate, are mouse-only) — without re-arming,
+so an editing session keeps its value. Keyboard traversal is left alone: focus landing on the container from another in-grid tab
+stop (a scrollbar arrow button, a `renderCell` focusable) rests on the container, so Shift+Tab can leave the grid backwards.
+A middle click never pastes into the grid: the middle-button release is cancelled (also when it lands outside the grid, and
+also when the middle button was chorded onto a held primary; a touch tap while the middle button is held does not disarm
+it) so Linux's primary-selection paste cannot reach the hidden input; the cell editor itself keeps native middle-click paste.
+The hidden input carries `inputmode="none"` from mount and throughout every keyboard / IME session (the attribute is a
+virtual-keyboard invitation, not an idle / editing predicate), so a touch / pen tap does not summon a virtual keyboard (touch
+/ pen is scroll-only — a tap never selects a cell or opens the editor); only a pointer-opened editor (mouse double-click)
+raises the invitation to `inputmode="text"`, which then outlives the session — it stays `"text"` through commits, Escape and
+the idle state after them — until focus really leaves the grid or an idle (no session open) touch / pen press withdraws it; a
+touch / pen press during a session leaves it alone (see Accessibility).
+Touch / pen long-press is not affected (these gates are mouse-only) — and it never reaches `onCellContextMenu` either: the
+context-menu handler is mouse-only as well, so touch stays a scroll gesture from press to release.
+
+## Keymap (contract table)
+
+Modifiers match **strictly** — combinations not listed fall through to the browser untouched, with three deliberate
+exceptions: `Ctrl+Shift+PageUp` / `Ctrl+Shift+PageDown` (the sheet-switch class — there are no sheets here) are consumed
+as a no-op while idle (mid-edit they pass through natively, per the table columns), during an
+in-flight drag **all** non-Escape keys are consumed (state freeze), and Escape itself aborts an in-flight drag with any
+modifier held (the abort branch runs before the strict-modifier passthrough).
+
+**Package zoom**: Alt+Wheel over the grid and Ctrl+Alt+`=` / `+` / `-` / `0` change the package zoom (Ctrl+Wheel
+stays with the browser). All four keys match the PRODUCED character (`event.key`) regardless of Shift, so layouts that
+need Shift to type them work as-is — JIS `=` is Shift+`-`, US `+` is Shift+`=`, AZERTY `0` is Shift+`à`; mismatching
+shifted characters (US `_` / `)`) pass through. Chords carrying the `AltGraph` modifier state are never claimed —
+a defense-in-depth: evergreen browsers (Chromium 68+ / Firefox 63+) deliver real AltGr characters WITHOUT ctrl+alt,
+so typing e.g. Latvian AltGr+F `=` never reaches this handler at all; the guard shields legacy AltGr-emulation
+shapes (old engines, synthetic events, non-conforming embedders) only. The remaining consequence is
+layout-dependent bindings (e.g. German Shift+0 produces `=` and zooms in) — a host that needs a layout-independent
+chord should claim it by `event.code` in a capture listener ahead of the grid (`defaultPrevented` events are
+respected and ignored). Alt+Wheel claims ONLY the bare Alt chord — Shift/Ctrl/Meta-carrying Alt+Wheel passes through untouched (e.g. the Shift+wheel horizontal-scroll idiom stays with the browser). Passed-through chords that produce no character never open an edit session (the ctrl+alt printable-shape rule defers the session until a character actually arrives). Requests are ignored mid-drag; in controlled
+mode these fire `onZoomChange` only. The zoom keys are
+claimed in the capture phase — defense in depth: since v0.3.3 the deferred printable open alone guarantees no
+accidental edit session, so the capture claim is a redundant belt, kept deliberately. Other Ctrl+Alt combinations pass
+through untouched **except the command rows of the table below** (`Ctrl+Alt+M` = `insertComment`, `Ctrl+Alt+Digit9` =
+`hideRows`, `Ctrl+Alt+V` = `pasteSpecial`, and whatever `shortcuts` binds); command rows are never claimed while the
+`AltGraph` modifier state is set, and on layouts whose produced character for a `Ctrl+Alt(+Shift)` chord is `=` / `+` / `-` / `0`
+the zoom keys shadow that chord (the zoom token space `Ctrl+Alt` and `Ctrl+Alt+Shift` × `Equal` / `Minus` / `Digit0` /
+`NumpadAdd` / `NumpadSubtract` / `Numpad0` is reserved and cannot be bound). Events an outer (host) capture listener has already
+`preventDefault`ed are respected and ignored. In controlled mode, gestures step from the last *requested* value: a parent that rejects a
+request without re-rendering leaves the next detent continuing from the rejected value until any re-render re-syncs it —
+enforce a tighter range by clamping in `onZoomChange` and re-rendering with the clamped value. Wheel/key steps land on the nearest 0.1 detent in the travel direction
+(from the 0.25 bound the first step up is 0.3); Alt+Wheel with no vertical component (tilt wheel / horizontal pan) is
+passed through to the browser.
+
+Navigation is **visible-track aware**: arrows and Shift-arrows step to the next *visible* row/column (a hidden run is
+jumped in one keystroke; if none exists in that direction the active cell stays), Home/End land on the first/last visible
+track, and paging moves by exact viewport-height pixel geometry, so page landings are structurally visible.
+
+| Key | Idle | Editing (replace) | Editing (edit) | Command |
+| :--- | :--- | :--- | :--- | :--- |
+| Arrow | Move active one visible step (reset) | Commit + move — **while pointing**: move the reference cursor and insert / replace the token | Native caret — **while pointing**: reference cursor | — |
+| Shift+Arrow | Extend range (visible step) | Commit + start extension — while pointing: extend the token to a range | Native — while pointing: range token | — |
+| Ctrl+Arrow | Jump to data edge (with `findDataEdge`) / grid edge (without) | Native word caret — while pointing: reference cursor by data edge | Native — while pointing: data-edge cursor | — |
+| Ctrl+Shift+Arrow | Extend to data edge (with `findDataEdge`) / to visible grid edge (without) | Consumed (no-op) | Consumed (no-op) | — |
+| Tab / Shift+Tab | Cycle across selected ranges (identity resets to a move: single 1×1, or a full circle over duplicate identical ranges) | Commit + cycle | Commit + cycle | — |
+| Enter / Shift+Enter | Cycle across selected ranges (identity resets to a move: single 1×1, or a full circle over duplicate identical ranges) | Commit + cycle | Commit + cycle | — |
+| Alt+Enter | Open the active cell's hyperlink: with `onHyperlinkOpen` declared the row exists only while the active cell has a link (`onHyperlinkOpen(url, active)`; a cell without a link passes through — nothing is consumed), without it the link popover opens (no Open button — the Ctrl+K editor, also on a cell without a link) | Insert newline at caret | Insert newline at caret | `openHyperlink` (idle column only — the editing newline row is a different column) |
+| Home / End (+Ctrl) | First/last visible column / visible grid corner | Native | Native | — |
+| Shift+Home / Shift+End | Extend to the first / last visible column | Native | Native | — |
+| Ctrl+Shift+Home / End | Extend to the first / last visible grid corner | Native | Native | — |
+| PageUp / PageDown | Page move (one viewport height, exact) | Commit + page move | Commit + page move | — |
+| Shift+PageUp / PageDown | Extend by one viewport height | Native | Native | — |
+| Ctrl+Space / Shift+Space | Select whole columns / rows of **every** selected range (anchor/active stay) | Native | Native | — |
+| F2 | Start editing (edit) | Toggle the pointing arm — a session opens disarmed (Excel Edit mode: the first Arrow moves the caret), typing a trigger arms it, F2 is Excel's Edit ⇄ Enter (formula session with `getCellFormula`; otherwise native) | Toggle the pointing arm | — |
+| F4 | — | Cycle the `$` anchor of the reference under the caret (`A1` → `$A$1` → `A$1` → `$A1`) | Same | — |
+| Delete / Backspace | Clear selection (one transaction: `text: ""`, plus `hyperlink: null` when `getCellHyperlink` is declared) | Native | Native | — |
+| Escape | Abort drag > hide the note tip > close the rejected validation message > disarm clip (copy or cut, foreign too) > focus root | Cancel (discard value) — mid reference-drag: abort the drag only (token restored, session kept) | Same | — |
+| Ctrl+A | Select all (active stays) | Native | Native | — |
+| Ctrl+C / X / V | Clipboard (native event path) | Native textarea | Native textarea | — |
+| Ctrl+Shift+V | Values-only paste (arms `{ mode: "values" }` for the next native paste event; no `preventDefault`; layout-independent — matched by the VK rule like every letter row, so RU `Ctrl+Shift+М` / EL `Ctrl+Shift+Ω` on `KeyV` arm too) | Native | Native | — (fixed chord, not a command) |
+| Ctrl+Alt+V | Paste Special: `onPasteSpecialRequest({ kind: "keyboard", cellRect })` when declared, else a formats-only paste through the menu path | Native | Native | `pasteSpecial` (**non-rebindable**) |
+| Ctrl+Z / Y / Shift+Z | Relay to undo/redo callbacks | Native textarea undo | Native textarea undo | — |
+| Shift+F10 / ContextMenu | Context-menu callback | — | — | — |
+| Ctrl+B / Ctrl+I / Ctrl+U / Alt+Shift+Digit5 | Toggle on the selection (the active cell's state decides: on → clear, off → set) | Toggle on the session cell (editor repainted) | Same | `bold` / `italic` / `underline` / `strikethrough` |
+| Ctrl+Backslash / Ctrl+IntlYen / Ctrl+IntlRo | Clear every format key of the selection | Native | Native | `clearFormatting` |
+| Ctrl+Shift+L / Ctrl+Shift+E / Ctrl+Shift+R | Align left / center / right | Session cell | Same | `alignLeft` / `alignCenter` / `alignRight` |
+| Ctrl+Shift+Digit1 … Ctrl+Shift+Digit6 | Number (2 decimals, grouping) / time (`HH:mm:ss`) / date / currency (needs the `formats` prop) / percent / scientific value format | Session cell | Same | `formatNumber` / `formatTime` / `formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` |
+| Alt+Shift+Digit7 / Alt+Shift+Digit6 | Outer borders of each range (inner borders kept) / clear borders | Native | Native | `bordersOuter` / `bordersClear` |
+| Alt+Shift+Digit1 … Alt+Shift+Digit4 | Top / right / bottom / left edge of each range (thin, `#000000`; other cells' borders kept) | Native | Native | `borderTop` / `borderRight` / `borderBottom` / `borderLeft` |
+| Ctrl+K | Link popover on the active cell | Native | Native | `insertLink` |
+| Shift+F2 | Note popover on the active cell | Native | Native | `insertNote` |
+| Ctrl+Alt+M | Comment thread popover on the active cell | Native | Native | `insertComment` |
+| Alt+ArrowDown | Validation list picker (cells with a `list` rule) | Native | Native | `openValidationList` |
+| Ctrl+D / Ctrl+R | Fill down / right (first row / column of each range, or the neighbour above / left for a single row / column; formulas shift) | Native | Native | `fillDown` / `fillRight` |
+| Ctrl+Enter | Fill every selected cell with the active cell's content | Run the strict validation gate on every selected cell's own rule (the first strict rejection keeps the session open, exactly like Enter), then write the session text to every selected cell in one transaction and close the session | Same | `fillSelection` |
+| Ctrl+Semicolon / Ctrl+Shift+Semicolon | Write today's date (`YYYY-MM-DD`) / the current time (`HH:mm:ss`, local, `now` prop) into the **active cell only** | Insert at the caret | Same | `insertDate` / `insertTime` |
+| Ctrl+Alt+Digit9 / Ctrl+Shift+Digit9 / Ctrl+Shift+Digit0 | Hide the selected rows / unhide rows / unhide columns (through the resize gates) | Native | Native | `hideRows` / `unhideRows` / `unhideColumns` |
+| *(unbound by default)* | Hide the selected columns — bind it yourself, e.g. `shortcuts={{ hideColumns: ["Ctrl+Alt+Shift+Digit9"] }}` | — | — | `hideColumns` |
+| *(unbound by default)* | General (no value format) / all four borders | — | — | `formatGeneral` / `bordersAll` |
+| *(unbound by default)* | Paste Special modes through the menu path (`handle.paste`) | — | — | `pasteFormats` / `pasteFormulas` / `pasteAdd` / `pasteSubtract` / `pasteMultiply` / `pasteDivide` |
+| *(unbound by default)* | Self-calc over the selection (exact decimal shift, formulas wrapped `=(…)*100`; non-numeric cells untouched) | — | — | `multiplyBy100` / `multiplyBy1000` / `divideBy100` / `divideBy1000` / `signReversal` |
+| *(unbound by default)* | Fill colour toggles (pastel presets `#FFFF99` / `#CCFFFF` / `#CCFFCC` / `#FFCCCC` — legible behind the default text colour, the reference extension's values — / the five `colors.fill` slots) | — | — | `fillColorYellow` / `fillColorBlue` / `fillColorGreen` / `fillColorRed` / `fillColorCustom1` / `fillColorCustom2` / `fillColorCustom3` / `fillColorCustom4` / `fillColorCustom5` |
+| *(unbound by default)* | Font colour toggles (pure presets `#FFFF00` / `#0000FF` / `#00FF00` / `#FF0000` — a separate table from the fills — / the five `colors.font` slots) | — | — | `fontColorYellow` / `fontColorBlue` / `fontColorGreen` / `fontColorRed` / `fontColorCustom1` / `fontColorCustom2` / `fontColorCustom3` / `fontColorCustom4` / `fontColorCustom5` |
+| *(unbound by default)* | Highlight band toggles (`highlight` state) | — | — | `toggleRowHighlight` / `toggleColumnHighlight` / `toggleBothHighlight` / `toggleIntersectionHighlight` |
+| Printable / IME start | Start editing (replace) — macOS `Option`+char does not (see deviations) | (typing) | (typing) | — |
+
+### Command shortcuts (grammar, rebinding, reserved chords)
+
+Rows with a **Command** are rebindable through the `shortcuts` prop (except `pasteSpecial`) and reachable imperatively through
+`handle.executeCommand(command)`; every command exists only while its capability is declared (`getCellFormat` for formats /
+borders / colours, `getCellNote` / `getCellComments` / `getCellHyperlink` / `getCellValidation` for the popover commands, the
+`formats` prop for `formatCurrency`, `getCellFormula` for `pasteFormulas`) — an unavailable command's chord passes through
+untouched and `executeCommand` returns `false`. The editing columns consult only the 16 **editing-column commands**
+(`bold` / `italic` / `underline` / `strikethrough` / `alignLeft` / `alignCenter` / `alignRight` / `formatNumber` / `formatTime` /
+`formatDate` / `formatCurrency` / `formatPercent` / `formatScientific` / `fillSelection` / `insertDate` / `insertTime`); any other
+command chord pressed while editing is native. The exported `DEFAULT_SHORTCUTS` (`{ [command]: readonly string[] }`, `[]` =
+unbound: 34 commands bound over 36 chords, 36 unbound) and `SPREADSHEET_RESERVED_SHORTCUTS` (the 63 exact chords of the
+non-rebindable built-in rows consulted while idle) are derived from the same `BUILTIN_ROWS` table.
+
+- **Grammar** (`parseChord`, canonical spelling only): `[Ctrl+][Alt+][Shift+]KEY` in that fixed order (Cmd counts as Ctrl).
+  `KEY` is a bare Latin letter `A`–`Z`, a digit by code (`Digit0`–`Digit9`, `Numpad0`–`Numpad9`), or a `KeyboardEvent.code` name
+  (`Semicolon`, `Backslash`, `IntlYen`, `IntlRo`, `Minus`, `Equal`, `F1`–`F12`, `ArrowDown`, `Enter`, `Escape`, `Space`, …). Letters
+  resolve by the **produced character** when `event.key` is a single Latin letter, else by the letter of `event.code` (so RU
+  `Ctrl+и` on `KeyB` is `Ctrl+B`, macOS `Ctrl+∂` on `KeyD` is `Ctrl+D`); everything else resolves by `event.code`, so a synthetic
+  keydown must carry `code`. A row containing `Alt` is never claimed when `getModifierState("AltGraph")` is true. The idle
+  column's native letter rows (`Ctrl+A`, `Ctrl+Z`, `Ctrl+Shift+Z`, `Ctrl+Y`, `Ctrl+Shift+V`) are matched by the same rule
+  (`matchChord`), so they fire on non-Latin layouts (RU `Ctrl+Ф` selects all) exactly like the command rows.
+- **Prop shape**: `shortcuts?: { [command]?: readonly string[] | null }` — an array **replaces** that command's default list
+  (union is not supported), `null` unbinds it, a single string is a `RangeError`.
+- **Validation** (`validateShortcuts`, during render — like `zoom`): `RangeError` on a non-canonical spelling (`ctrl+B`,
+  `Shift+Ctrl+B`, `Ctrl+b`), a modifier-less chord, a single string, an unknown command key, any override of `pasteSpecial`, a
+  chord equal to a non-rebindable built-in row in a column where the command is consulted (`bold: ["Alt+Enter"]` clashes with the
+  editing-column newline row; `openHyperlink: ["Alt+Enter"]` is legal because that command lives in the idle column only), and one
+  chord bound to two commands after the merge (`{ bold: ["Ctrl+I"] }`). Families are NOT reserved: `Alt+ArrowDown`, `Alt+Enter`,
+  `Ctrl+Enter` and `Shift+F2` are valid defaults, and `Ctrl+Alt+Shift+Digit9` is a valid binding for `hideColumns`.
+- **Layout notes**: on AZERTY the physical `Semicolon` key reports the letter `m`, so `Ctrl+Semicolon` / `Ctrl+Shift+Semicolon`
+  (`insertDate` / `insertTime`) are unreachable there (no wrong command fires — Google Sheets has the same gap); JIS keyboards get
+  `clearFormatting` on `Ctrl+IntlYen` / `Ctrl+IntlRo` in addition to `Ctrl+Backslash`.
+
+Keymap notes:
+
+- **Ctrl+Arrow data edges** need the adapter's optional `findDataEdge` (see the adapter contract); without it the v0.1
+  grid-edge jump is kept. Ctrl+Shift+Arrow scans from the Excel-faithful hybrid coordinate (the active cell's row/column,
+  the extension corner's progression component) and extends only the progression axis, so an existing 2-D extension is
+  never collapsed. A data-edge landing on a hidden track rescans forward first, then backward when nothing is visible
+  ahead, and stays put only when neither side has a visible track (deviation — Excel can land on hidden cells).
+- **Ctrl+Space may never reach the page** in some environments — OSes and IMEs commonly bind it (e.g. input-source
+  switching).
+- **Ctrl+Shift+Space is not bound** (it falls through per the legend) — use Ctrl+A for select-all.
+- Shift+Space previously (v0.1) started replace editing with a space while idle; it now selects rows (Excel behavior).
+- Tab/Enter cycling does **not** skip hidden cells (see deviations) — the visible stepping above covers arrows, Home/End,
+  and paging.
+- **Reference pointing** (needs `getCellFormula`): inside a formula session, whenever the text before the caret ends with a
+  trigger — `=`, `(`, `,`, `;`, an operator or `:` (string literals blanked) — or with a trigger followed by a reference token
+  (that token is then the replace target), a primary-button press on a cell inserts its reference (`A1`) at the caret and a drag
+  replaces it with the rectangle (`A1:C3`); a column / row header press inserts `A:A` / `2:2`; Arrow / Shift+Arrow / Ctrl+Arrow
+  move a reference cursor from the editing cell — Shift+Arrow extends from the last pointed cell (the extension anchor, so upward /
+  leftward chains keep growing the range: `C4` → `C3:C4` → `C2:C4`; a hand-typed token anchors at its start, Excel parity); a
+  printable character closes the token, F4 cycles the `$` anchors, Escape during
+  a reference drag restores the token and keeps the session. Pointing is **armed** by typing that leaves the caret right after a
+  trigger (`=`, `+`, or Backspace back to one — Sheets' operator rule, Excel's Enter mode) or by F2, and F2 toggles it off (arrows
+  move the caret) and back on. A session opens **disarmed**: F2 / double-click on an existing `=A1+B1` edits its text and the first
+  Arrow moves the caret instead of rewriting `B1` (Excel Edit mode). The selection, the active cell and the editor's position
+  never change while pointing; the corner, resize strips, fill handle, scrollbar bands and zoom dead space are consumed without
+  inserting anything. A grid-exit focus-out commits the partial formula as typed.
+
+## Props reference
+
+| Prop | Type (abridged) | Notes |
+| :--- | :--- | :--- |
+| `adapter` | `SpreadsheetDataAdapter` | Required. Object identity = sheet identity. |
+| `dataVersion` | `number` | Bump after external writes (undo, collab). Re-renders visible cells and disarms a pending cut. |
+| `defaultRowHeight` / `defaultColumnWidth` | `number` | Integer px (defaults 24 / 100). Per-column widths are applied through the imperative `resizeColumn` (the v0.3 `initialColumnWidth` prop was retired in v0.4). |
+| `frozenColumns` | `number` | Freezes the first N columns at the left edge (v0.5; default 0, LIVE). Engine-validated (integer in [0, 128] — `RangeError` otherwise; values beyond `colCount` freeze every column). Frozen columns stay visible at any horizontal scroll; `scrollToCell` / keyboard ensure-visible treat them as horizontal no-ops. |
+| `frozenRows` | `number` | Freezes the first N rows at the top edge (v0.6; default 0, LIVE — the row-axis twin of `frozenColumns`). Engine-validated (integer in [0, 128] — `RangeError` otherwise; values beyond `rowCount` freeze every row). Frozen rows stay visible at any vertical scroll; keyboard ensure-visible treats them as vertical no-ops. |
+| `renderCell` | `(ctx: RenderCellContext) => ReactNode` — `RenderCellContext = { row; col; text }` (exported) | Custom cell rendering. **Must be identity-stable** (`useCallback`) — an inline arrow defeats the cell memo and re-renders every visible cell each pass. |
+| `maxOperationCells` | `number` | Bulk-operation ceiling (default 100,000). Row fan-out resize gates at 1/10 of it and autofit at 1/4 — see "Operation limits". |
+| `enableResizeUI` | `boolean` | Default `true`. `false` removes resize strips **and unhide markers** — hidden tracks then have no in-package restore path (imperative API only). |
+| `zoom` / `defaultZoom` / `onZoomChange` | `number` / `number` / `(zoom: number) => void` | Package zoom (v0.3): visual transform scale, logic stays in logical px. Controlled (`zoom`) or uncontrolled (`defaultZoom`, default 1). Gestures — Alt+Wheel and Ctrl+Alt+`=` / `+` / `-` / `0` (reset; the four keys match the produced character, Shift-agnostic; AltGraph-state chords are never claimed — legacy-shape defense in depth, see Keymap notes) — request via `onZoomChange`; Ctrl+Wheel is deliberately unbound (the browser owns it). Clamped to [0.25, 4]; a non-finite value (NaN / ±Infinity) throws a `RangeError` (fail-fast — no silent substitution). |
+| `enableFillHandle` | `boolean` | Default `true`. Fill writes through `applyEdits` — disable for read-only adapters. |
+| `onSelectionChange` | `(selection: SelectionState) => void` | Fires on confirmed changes only — never on mount, and never mid-drag with one documented exception: the header subtract reservation converts to a real press on the first movement that both really changes the pointer coordinates and lands on a different header index (in-index jitter and synthetic same-position moves keep the reservation), firing the deferred press replace mid-drag (total fire count matches v0.1). |
+| `onOperationRejected` | `(op, cellCount, reason) => void` | `op: SpreadsheetOperation` (`"copy" \| "cut" \| "delete" \| "paste" \| "fill" \| "resize" \| "format" \| "calc" \| "annotate"` — the three v0.8 names widen the callback's parameter, a 0.x-breaking change for consumers that annotated a narrower `op`), `reason: "limit" \| "bounds"` — count definitions and per-op ceilings under "Operation limits". |
+| `onEditRejected` | `(error: unknown, rejection: EditRejection) => void` | Fires once per rejected `applyEdits`. `rejection.source` names the refused write path (`"edit"`, or the `SpreadsheetOperation` write names `"paste"` / `"fill"` / `"delete"` / `"format"` / `"calc"` / `"annotate"` — the same vocabulary as `onOperationRejected`; a cut-move is the Ctrl+V gesture and reports `"paste"` in both callbacks, and the source-side clear of a cross-sheet move reports `"paste"` too while the target write stands); for `"edit"`, `rejection.editSession` is `"kept"` (in-grid commit — the editor is still open with focus, Escape cancels) or `"discarded"` (focus left the grid — the grid closes the session as this rejection completes: once the callback returns the typed value is gone and the hidden input is re-armed without moving focus — it stays wherever the focusout left it: on the element the user chose, or still on the hidden input after a window blur; do not advise Escape). See "Editing, Undo, and rejection". |
+| `onCopyMultiRange` | `() => void` | Notice that a multi-range copy serialized only the tail range. |
+| `onCellContextMenu` | `(cell, origin) => void` | Pointer or keyboard (`Shift+F10`) origin; no package menu. |
+| `onUndoRequest` / `onRedoRequest` | `() => void` | `Ctrl+Z` / `Ctrl+Y` / `Ctrl+Shift+Z` relays. |
+| `formatCellAnnouncement` / `formatSelectionAnnouncement` | formatter | Opt-in screen-reader announcements (see above). |
+| `formatCommandAnnouncement` | `(ctx: { command: SpreadsheetCommand; state: boolean \| null }) => string` | Opt-in (v0.8) live-region text after a successful format command; `state` is the toggle's post-state (`bold` / `italic` / `underline` / `strikethrough` / colour toggles), `null` for non-toggle commands. Also makes the live region render on its own. |
+| `labels` | `SpreadsheetLabelOverrides` (any subset of the 24 `SpreadsheetLabels` keys) | v0.8 — replaces the `sinkAriaLabel` / `rootAriaLabel` props (folded in) and names every popover / indicator string (`noteTitle`, `noteSave`, `noteEscapeHint`, `noteRejectedHint`, `commentTitle`, `commentReply`, `commentPost`, `commentCount` (string or `(n) => string`), `linkTitle`, `linkTextField`, `linkUrlField`, `linkOpen`, `linkSave`, `listTitle`, `listEmpty`, `listMore` (string or `(n) => string` — the validation-list picker mounts at most 500 options and announces the hidden-match count on this row), `messageTitle`, `validationRejected`, `popoverClose`, `indicatorNote`, `indicatorComment`, `indicatorInvalid`). Omitted / `undefined` keys keep the English `DEFAULT_LABELS`; `sinkAriaLabel` must mention `Escape` (`RangeError` during render otherwise). |
+| `shortcuts` | `ShortcutOverrides` = `{ [command]?: readonly string[] \| null }` | v0.8 — rebinds command chords (array = replace the default list, `null` = unbind); validated during render with `RangeError`s (see "Command shortcuts"). Identity-stable — consulted through a ref. |
+| `colors` | `{ fill?: readonly string[]; font?: readonly string[] }` | v0.8 — the five `#rrggbb` slots of `fillColorCustom1..5` / `fontColorCustom1..5` (exactly 5 six-digit hex strings per axis, `RangeError` otherwise); an omitted axis uses `DEFAULT_CUSTOM_COLORS` (`#FF0000` / `#00FF00` / `#0000FF` / `#FFFF00` / `#FF00FF`, exported). |
+| `formats` | `{ currency: string; locale?: string }` | v0.8 — the host currency (ISO code) and rendering locale for `formatCurrency` and for recovering bare currency symbols (`$`, `¥`) in pasted Excel / Sheets HTML; undeclared ⇒ `formatCurrency` passes through and bare symbols are not recovered. |
+| `highlight` / `defaultHighlight` / `onHighlightChange` | `HighlightState` = `{ row: boolean; column: boolean; intersection: boolean }` / same / `(h) => void` | v0.8 — active row / column / intersection highlight bands, controlled (`highlight` + `onHighlightChange`) or uncontrolled (`defaultHighlight`), the same two-phase contract as `zoom`. Default all off ⇒ zero band nodes (v0.7 DOM identity). Toggled by the `toggle*Highlight` commands. When exactly ONE family (row XOR column) is on and `intersection` is off, the cross node lights up tinted with that family's colour so the band runs unbroken through the selection (sheets-enhancer parity — with both families on the hole is kept). A whole-row / whole-column selection (row / column header press, Shift+Space / Ctrl+Space) draws no row / column bands — only the intersection — so the cross-axis band never tints the rest of the sheet. |
+| `highlightColors` | `HighlightColors` = `{ row; column; intersection; opacity }` | v0.8 — identity-stable band palette written to `--aqsp-band-row` / `-column` / `-intersection` / `-opacity` on the overlay in a layout effect; each colour must parse (`normalizeColor`), `opacity` must be a finite number in [0, 1] (`RangeError` otherwise). Undeclared ⇒ nothing is written while every band is off and `DEFAULT_HIGHLIGHT_COLORS` (`#0084FF` / `#42FF4F` / `#E1FF00` / 0.2, exported) is written once a band turns on. |
+| `popovers` | `PopoverOverrides` = `{ [kind]?: boolean }` (`note` / `note-tip` / `comment` / `link` / `list` / `message`) | v0.8 — `false` disables a kind: its commands pass through and `handle.openPopover(kind)` throws a `RangeError`. The popover layer mounts only when at least one kind is enabled AND its capability is declared. |
+| `renderPopover` | `(ctx: PopoverContext) => ReactNode` | v0.8 — replaces the default popover components; `ctx.kind` discriminates the six contexts (`NotePopoverContext` … `MessagePopoverContext`, exported) and the defaults (`NotePopover` / `NoteTip` / `CommentPopover` / `LinkPopover` / `ListPopover` / `MessagePopover`) are exported so a renderer can replace one kind and delegate the rest. |
+| `onClipChange` | `(clip: ClipInfo \| null) => void` | v0.8 — armed clip notice: `{ kind: "copy" \| "cut", range, foreign }` on arm, `null` on discard, `foreign: true` for a cut kept across a sheet switch. Idempotent (no call when nothing changes). |
+| `onHyperlinkOpen` | `(url: string, cell: CellCoord) => void` | v0.8 — navigation seam for `Alt+Enter`, the link popover's Open button and Ctrl / Meta+click on a link cell; `url` is always a normalised allow-listed href (`normalizeHyperlink` output — an adapter URL outside `http:` / `https:` / `mailto:` / `tel:` never reaches this seam, so `window.open(url)` is safe) (the click is consumed with the selection frozen; Ctrl+Shift stays range-extend); undeclared ⇒ no navigation, no Open button and no pointer gesture. |
+| `onValidationRejected` | `(ctx: { cell; rule; text; message }) => void` | v0.8 — a `strict` validation rule refused a changed commit (the adapter was not called; the message popover shows `message`). |
+| `onPasteSpecialRequest` | `(origin: { kind: "keyboard"; cellRect }) => void` | v0.8 — `Ctrl+Alt+V` asks the host for its Paste Special UI (the active cell's viewport rect in visual px, the `onCellContextMenu` keyboard shape); undeclared ⇒ `Ctrl+Alt+V` is a formats-only paste through the menu path. |
+| `onClipboardUnavailable` | `(cause: "insecure-origin" \| "permission-denied" \| "empty" \| "unreadable") => void` | v0.8 — the menu path's refusal channel (`handle.paste`, `Ctrl+Alt+V` without a request handler, the `paste*` commands); whenever it fires the paste resolves `"rejected"`. `"unreadable"` also fires on the paste event when the detected source cannot be parsed (the package never slides to another reader). |
+| `now` | `() => number` | v0.8 — clock seam of `insertDate` / `insertTime` (declared default `Date.now`). |
+| `testId` / `className` | `string` | Test hook / root class extension. |
+
+## Imperative handle
+
+```tsx
+const ref = useRef<SpreadsheetHandle>(null)
+// <Spreadsheet ref={ref} ... />
+ref.current?.resizeRow(1, 48)
+ref.current?.resizeColumn(0, 180)
+ref.current?.scrollToCell({ row: 0, col: 5_000_000 }, { alignX: "end" })
+```
+
+Sizes are integer pixels (rounded once). The imperative resize calls are the raw seam beneath the pointer resize UI and
+carry **none of its safety gates**: no 1px last-visible clamp, no 1,000-hidden-row cap, no fan-out ceiling. Mass-hiding
+rows through this API is the consumer's responsibility and falls outside the rendering guarantee.
+
+`scrollToCell(cell, options?)` is a programmatic viewport jump (delegating to the engine's floor-and-pin cell scroll);
+`ScrollToCellOptions` carries `alignX` (`start` / `end` / `center`), `alignY` (`top` / `bottom` / `center`), and
+`offsetX` / `offsetY`. It does **not** change the selection — it is a pure viewport move, and the deep grid stays
+reachable at any scale (10^9 px). The demo's `/huge` route wires it to the "deep jump" button.
+
+Per-column *initial* widths are also this seam's job since v0.4: apply them once from a mount effect
+(`useLayoutEffect(() => { widths.forEach((w, col) => ref.current?.resizeColumn(col, w)) }, [])`) — the demo's `/tune`
+route is the reference wiring.
+
+The v0.8 handle members are the toolbar seam (every writer returns `true` on commit, `false` on a gate / adapter / commit-gate
+refusal, and throws a `RangeError` when the capability it needs is undeclared):
+
+```tsx
+ref.current?.executeCommand("bold")                       // exactly what the chord does (false = unavailable / refused)
+ref.current?.applyFormat({ fontSize: 14, background: null }) // selection-wide CellFormatPatch (null clears a key), source "format"
+ref.current?.setBorders("outer", { style: "medium" })     // "outer" | "all" | "clear" | "top" | "right" | "bottom" | "left"
+ref.current?.setHyperlink("https://example.com")          // active cell, normalised; null clears; javascript: is a RangeError
+ref.current?.setNote("Reviewed")                          // active cell; null clears
+ref.current?.addComment({ text: "LGTM" })                 // appends to the active cell's thread (existing ids kept — you mint the new one)
+ref.current?.setValidation({ type: "list", values: ["A", "B"], strict: true }) // every selected cell; null clears
+await ref.current?.paste({ mode: "values" })              // menu path: Promise<PasteOutcome> = "applied" | "empty" | "rejected"
+ref.current?.getBaseFormat(cell)                          // the adapter's format (toolbar state)
+ref.current?.getPaintedFormat(cell)                       // base ⊕ conditional formats (what the user sees)
+ref.current?.getSelection()
+ref.current?.startEdit("edit")                            // opens the editor without the virtual-keyboard invitation
+ref.current?.openPopover("note")                          // RangeError when the kind is disabled / its capability undeclared
+ref.current?.focus({ preventScroll: true })               // focuses the hidden input and re-arms it when idle
+```
+
+`paste(options)` reads the clipboard through `navigator.clipboard.read({ unsanitized: ["text/html"] })` (one call): a missing
+`navigator.clipboard` is `"insecure-origin"`, a refused read `"permission-denied"`, no readable item `"empty"`, and a detected source
+that fails to parse `"unreadable"` — each fires `onClipboardUnavailable` and resolves `"rejected"`. `"applied"` means the adapter was
+called; `"empty"` means nothing was written (an own payload whose identity was suppressed, every cell skipped, a mode without cell
+aspects such as `columnWidths` — sizes may still have been applied).
+
+## Clipboard utilities (public)
+
+`parseTsv` / `serializeTsv` / `estimatePasteCellCount` / `expandPaste` are exported for building custom paste UIs and
+importers with the exact same Excel-compatible semantics the grid uses. `enumerateRangeCells`, `makeRange`,
+`rangeContains`, `rangeSize`, `columnIndexToName`, `columnNameToIndex` round out the toolkit. The named unions
+`SpreadsheetDirection` (`"up" | "down" | "left" | "right"` — the `findDataEdge` direction), `SpreadsheetOperation` (the
+`onOperationRejected` op), and `EditRejection` (the `onEditRejected` context — see "Editing, Undo, and rejection") are exported for
+consumer-side annotations.
+
+v0.8 adds the rich-cell engines as public pure functions (all React-free; `src/index.ts` exports 39 values and 94 types in total — every named type an exported declaration reaches is exported too, so nothing has to be extracted with `Awaited<ReturnType<>>` / `Extract<>`; `src/index.spec.ts` pins it):
+
+- **Clip payload** — `serializeClipPayload(payload)` / `parseClipPayload(json)` (the lossless wire format `{ v: 1, rows, cols, clipId, formats, validations, cells, colWidths?, rowHeights?, wholeRows, wholeCols, conditionalFormats }`; the parser is total and returns `null` on ANY malformed input, the serializer validates the same way and throws a `RangeError`),
+  `detectClipSource(flavours, channel)` (`"aqsp" | "sheets" | "excel" | "html" | "tsv" | "none"` — the ADR-14 detection over `{ types, getData }`), and the types `ClipPayload` / `ClipCell` / `ClipComment` / `ClipSource` / `ClipInfo` / `ClipFlavours` / `ClipChannel` (the `detectClipSource` parameter types).
+- **HTML interop** — `serializeHtmlTable(payload, clipJson)` (the interop table Excel / Sheets read: `data-aqsp-clip` first attribute, `<td style='white-space:pre'>`, `mso-number-format`, `x:num` / `x:str` / `x:fmla`, `data-sheets-value` / `-formula` / `-numberformat` / `-hyperlink` / `-note`) and `parseHtmlTable(html, kind, { currency?, locale? }, maxCells)` (a total reader of Sheets / Excel / generic HTML tables — `{ outcome: "payload", payload }`, `{ outcome: "limit", cells }` as soon as the lower bound of `rows × cols` exceeds `maxCells` (checked
+  before every allocation, so the reader never holds more than `maxCells` cells — and rows are pulled lazily through the sibling links, so the stop also ends the row walk), `{ outcome: "none" }` when there is no table; `maxCells` must be a positive integer or the call throws a `RangeError` before any `DOMParser` is built; its parameter types `HtmlTableKind` / `NumberFormatDecodeOptions`).
+- **Formats** — `canonicalizeFormat` / `mergeFormat` / `formatEquals`, `BORDER_DEFAULT_COLOR`, and the types `CellFormat` / `CellFormatPatch` / `CellBorder` / `CellBorders` / `CellBorderStyle` / `CellVerticalAlign` (plus the v0.7 `CellAlign` / `CellValueFormat` / `formatCellValue`).
+- **Formulas** — `shiftFormula(formula, dRow, dCol)` (relative references only, `#REF!` below zero), `toR1C1(formula, origin)` / `fromR1C1(r1c1, origin)` (the clip's origin-relative formula form, Google Sheets spelling `R[-1]C[0]`).
+- **Annotations and validation** — `normalizeHyperlink(text)` (`http:` / `https:` / `mailto:` / `tel:` only, WHATWG-serialised href or `null`), `validateCellText(rule, text, evaluate?)` with the types `DataValidationRule` (its base `ValidationRuleBase`, the seven members `ListValidationRule` / `NumberValidationRule` / `TextLengthValidationRule` / `DateValidationRule` / `TextValidationRule` / `CheckboxValidationRule` / `CustomValidationRule`,
+  the op vocabularies `ValidationCompareOp` / `ValidationTextOp` and the evaluator `ValidationEvaluate`) / `ValidationVerdict` / `CellComment` / `CellCommentInput` / `CellPatch` / `CellEdit` / `EditSource` / `EditContext` / `PlainEditContext` / `PasteEditContext`.
+- **Conditional formats** — the types `ConditionalFormatRule` / `ConditionalFormatRuleInput` / `ConditionalFormatStyle` / `CfCondition` (its six members `CellValueCondition` / `TextCondition` / `EmptyCondition` / `NotEmptyCondition` / `ColorScaleCondition` / `CustomFormulaCondition` and the `text` op vocabulary `CfTextOp`) / `CompareOp` / `ScalePoint` / `RangeExtrema` / `FormulaValue`.
+- **Commands and labels** — `DEFAULT_SHORTCUTS`, `SPREADSHEET_RESERVED_SHORTCUTS`, `parseChord`, `DEFAULT_CUSTOM_COLORS`, `DEFAULT_LABELS`, `resolveLabel(labels, key, n?)`, and the types `SpreadsheetCommand` / `ShortcutMap` / `ShortcutOverrides` / `ParsedChord` / `SpreadsheetLabels` / `SpreadsheetLabelOverrides` / `BorderPreset`.
+- **Paste Special** — the types `PasteMode` / `PasteOperation` / `PasteOptions` and the `handle.paste` outcome `PasteOutcome` (`"applied" | "empty" | "rejected"`).
+- **Popovers and bands** — the six default components `NotePopover` / `NoteTip` / `CommentPopover` / `LinkPopover` / `ListPopover` / `MessagePopover` (with their `*Props`), the types `PopoverKind` / `PopoverOverrides` / `PopoverContext` and its six members (their `anchorRect` is a `PopoverRect`), `DEFAULT_HIGHLIGHT_COLORS` and the types `HighlightState` / `HighlightColors`.
+
+The `/utils` demo route exercises the v0.1 toolkit live; the `/styles` route drives the v0.8 engines through the grid itself (own copy / paste round trips, Excel / Sheets fixture pastes, commands and popovers).
+
+## Deviations from Excel (deliberate)
+
+| Behavior | Here | Excel | Rationale |
+| :--- | :--- | :--- | :--- |
+| Diagonal fill | The handle fills the L-shaped box in one gesture (2D tiling) | Axis-constrained per drag | Requested super-set; single-axis drags behave identically to Excel |
+| In-cell editor size | Fixed to the cell box (Alt+Enter lines beyond the cell height are clipped while editing; committed text still stores every line) | The in-cell editor grows to show all lines | A growing editor needs its own layout machinery; the canonical value is unaffected |
+| Editor while scrolled away | The visible editor disappears once the edited cell's top-left corner leaves the viewport (session and value survive; it re-shows on scroll-back) | The editor scrolls off with its cell, partially clipped | The sink is viewport-clamped for focus/IME survival — showing it clamped would paint an editor over the wrong cells |
+| Zoom shortcuts | Alt+Wheel / Ctrl+Alt+`=` `+` `-` `0` (produced-character match, Shift-agnostic) | Ctrl+Wheel | The browser owns Ctrl+Wheel in a web page — a conflicting binding would fight page zoom |
+| Multi-range copy | Tail range only + `onCopyMultiRange` notice | Aligned ranges concatenate | Ambiguous general case; explicit callback instead of silent difference |
+| Cut paste clipping | Rejected entirely (`"bounds"`) | Rejects likewise | Clipping a move would silently destroy the clipped cells |
+| Ctrl+Arrow without `findDataEdge` | Grid edge | Data edge | Data-end scan is a store capability — declare `findDataEdge` for Excel behavior |
+| Ctrl+Arrow landing on a hidden cell | Rescans forward first, then backward, else stays | Can land on the hidden cell | Forward keeps data beyond a hidden edge reachable; the backward snap only fires when nothing is visible ahead |
+| Ctrl+End / Ctrl+Shift+End | Visible grid corner | Used-range corner | Consistent grid-edge family (used-range tracking is the store's domain) |
+| Shift+End | Extends to the row's last visible column (Sheets-style) | Toggles End mode | An End-mode state machine is out of scope |
+| Ctrl+Arrow while editing | Native word caret | Commit + jump | Caret ergonomics win inside a text field |
+| Double-click caret | Clicked character position (real browsers, default rendering) | Clicked character position | Falls back to end-of-text **per cell** when `renderCell` is set, when the cell's formatted display differs from its raw value (the hit offset would mis-map onto the raw text), or when the caret-position API is unavailable — text/label/unformatted cells of a formatted sheet keep the click-point caret |
+| Header right-click | Native menu, no selection | Column select + menu | No package-rendered menu exists to complete the gesture |
+| Escape during drag | Aborts with any modifier held | — | Shift-drag + Escape naturally arrives as Shift+Escape; strict matching would drop the abort |
+| Scrollbar/header press mid-edit | Commits first (commit gate, primary button) | Scrollbar keeps editing | Focus never leaves the sink, so a focusout commit can never fire; an explicit gate is the only correct commit path |
+| Shrinking Shift+Arrow with off-anchor active | Active clamps back into the tail range **only when it lands in no range at all** (an active living in another selected range stays put) | Active can strand outside | A stranded active corrupts cycling and paste origins; multi-range cycling needs the relaxed rule |
+| Enter after cut | Cycles in range (paste is `Ctrl+V` only) | Enter completes the cut-move | One paste channel; Enter keeps its navigation meaning |
+| Second `Ctrl+V` after a cut-move | Pastes again as a plain copy | Clipboard consumed by the move | The OS clipboard still holds the text; re-paste is the least surprising reading |
+| macOS `Option`+char | Does not start editing | Types the composed character | `Alt`-modified keys are indistinguishable from shortcuts at the keydown layer; deferred (§14) |
+| Mid-drag non-primary release | Only the primary button's release confirms a drag (a right-button release mid-drag confirms nothing; v0.1 confirmed it); releasing the primary first while a chord is held — delivered as a pointer move — confirms the drag (cell / header / resize at that position, fill at its last painted preview band — the same box its `pointerup` confirms) | Only the left release confirms | Excel-parity fix — a chorded right click must not commit a half-built selection |
+| Fill inward drag | Extension only — collapsing the band back into the source makes the release a no-op | Clears the re-covered cells | Inward-clear planned (roadmap) |
+| Fill semantics | Cyclic copy fill only | Series / smart fill (1, 2 → 3, 4...) | Pattern detection is a locale-dependent domain of its own |
+| Fill-handle double-click | No-op | Fills down to adjacent data | Needs composition with `findDataEdge` (roadmap) |
+| Copy / TSV of formatted cells | Carries the **raw** canonical `getCellText` | Copies the **display** string into `text/plain` | Raw preserves the numeric round-trip (paste back, spreadsheets, importers); the display string is a lossy projection |
+| Too-narrow formatted cells | Content clips (right-aligned cells clip on the **left**, Sheets-style); autofit now measures the formatted display, preventing the common case | Renders `####` for numeric cells that don't fit | A `####` substitute needs per-cell width probing on every paint; clipping keeps rendering O(visible) |
+| Autofit scope | Visible-window measurement (columns) / default-height restore (rows) | Scans all data / wrap-measures row heights | Scanning 1M rows would freeze; cells render single-line clipped |
+| Autofit / dblclick caret with `renderCell` | Disabled (no-op / caret at end) | — | Custom cell DOM cannot be measured or offset-mapped |
+| Same-value resize release | No-op | Equalizes all selected columns to the dragged width | A no-move release should change nothing |
+| Hiding everything | The last visible track of an axis clamps to 1px | Allows hiding all columns/rows | No select-all + Unhide menu exists here — an all-hidden grid would be unrecoverable |
+| Hidden-row volume (UI) | Hides pushing the axis-wide hidden-row total past 1,000 are rejected (`"bounds"`) | Unlimited | Rendering-window structural constraint; upstream removal planned |
+| Fan-out resize / autofit ceilings | Rejected past the "Operation limits" caps | Resizes any selection size | Freeze prevention ("never silently freezes") |
+| Resize grab zone | 6px strip inside the boundary only | Zone straddles the boundary | The next header's first pixels stay selectable |
+| Hidden-boundary double-click | Unhide marker restores the default size | Autofit-family behavior | Restore affordance kept simple |
+| Header Ctrl+drag subtract | Not supported (Ctrl+click toggle only; cell-surface Ctrl+drag subtract exists) | Drag-subtract on headers | Scope cut |
+| Tab / Enter cycling over hidden cells | Passes through (active can land on a hidden cell) | Skips hidden cells | Visible-aware cycling planned (roadmap) |
+| Hide / unhide hotkeys | Sheets chords: `Ctrl+Alt+Digit9` hides rows, `Ctrl+Shift+Digit9` / `Ctrl+Shift+Digit0` unhide rows / columns; `hideColumns` is **unbound by default** (bind it through `shortcuts`) | `Ctrl+9` / `Ctrl+0` / `Ctrl+Shift+9` / `Ctrl+Shift+0` | Sheets' `Ctrl+Alt+0` sits in the reserved zoom token space; Excel's `Ctrl+9` family is taken by browsers (tab switching) |
+| Notes / comments / validation / conditional formats on the clipboard | Travel only in the package's own payload (`data-aqsp-clip`); a Sheets `data-sheets-note` is read on paste, Excel HTML carries no notes | Office-internal formats carry them between workbooks | HTML tables have no standard carrier |
+| Copied values in `text/html` | The visible text is the **display** string; the raw value rides the typed attributes (`x:num`, `data-sheets-value`) — `text/plain` stays raw | Excel writes display strings everywhere | Excel / Sheets read the typed carriers; every other consumer sees what the grid shows |
+| Paste Special of an armed cut | Copy semantics (the cut stays armed) | Paste Special is disabled after a cut | One paste channel; the cut is still the user's intent |
+| `colspan` / `rowspan` in pasted tables | Anchor cell + blank unformatted cells | Merged cells | No merge model in the package |
+| Sheets compact JSON (`data-sheets-userformat` / text-style runs) | Not parsed (the CSS already carries the cell format) | — | No partial-format (run) model |
+| Column widths / row heights on the clipboard | Carried only by whole-column / whole-row copies, pasted by `all` / `noBorders` / `columnWidths`, never by a transposed paste; sizes are **non-undoable geometry** (no `applyEdits`), and every wire / HTML / gated size is capped at 10,000 px (`MAX_TRACK_SIZE_PX`) so a hostile pasted width can never wedge the grid | Pasted for any range incl. transposed | Sizes are outside the `applyEdits` vocabulary |
+| Paste Special ÷ 0 | Target untouched | `#DIV/0!` | No error-value vocabulary |
+| Paste Special results | 15 significant digits, no `-0`, non-finite results leave the target; non-numeric / `TRUE` / `FALSE` source cells are skipped | Excel display precision | No binary artefacts (`0.1 + 0.2` ⇒ `0.3`) |
+| Transposed paste formulas | Only fully relative references rotate; mixed / absolute references stay | Same | A mixed reference cannot rotate without moving its anchor |
+| Fill and comments | `fillDown` / `fillRight` / `fillSelection` / the fill handle never copy comments | Same for comments (notes are copied — and so are they here) | Thread ids are consumer-scoped |
+| Cross-sheet cut-move | Two writes (target, then source clear) under ONE transaction id; the source sheet's conditional-format rules are never moved or removed | One operation that moves rules too | Rules are a sheet-level consumer asset |
+| Conditional-format borders / number formats | Unsupported (`ConditionalFormatStyle` is the Sheets subset: background / colour / bold / italic / underline / strikethrough) | Excel supports both | Border ownership folding and CF composition are undefined |
+| `mso-number-format` over the menu path | Lost when the engine's `read()` strips `<style>` (Chromium keeps it with `unsanitized`); a stripped Excel marker makes the table detect as `html`, whose reader still honours `x:num` / `x:str` / `x:fmla` | — | Browser sanitiser behaviour |
+| `Ctrl+Shift+V` | Fixed values-only chord (not a command) | Same in Sheets | It must ride the native paste event |
+| Zoom chords | `Ctrl+Alt` and `Ctrl+Alt+Shift` × `Equal` / `Minus` / `Digit0` / `NumpadAdd` / `NumpadSubtract` / `Numpad0` are reserved; on layouts producing `=` / `+` / `-` / `0` for another `Ctrl+Alt(+Shift)` chord that chord is shadowed | — | The v0.3.3 produced-character zoom contract is kept byte-identical |
+| A literal starting with `=` | Cannot be stored through the grid when `getCellFormula` is declared (there is no apostrophe escape); copy protects such literals with `x:str` / a string-typed `data-sheets-value` | `'=` escapes it | The escape character is the store's convention |
+| AZERTY `Ctrl+;` | `insertDate` / `insertTime` unreachable (the physical Semicolon key reports the letter `m`) — no wrong command fires | Same gap in Sheets | Letters win in the VK rule |
+| `Ctrl+Alt+V` | Non-rebindable; `onPasteSpecialRequest` when declared, else a formats-only paste (insecure origins report `onClipboardUnavailable`) | Paste Special dialog | The package renders no dialog |
+| Note tip | Hidden by Escape (step 0 of the chain — the clip is untouched) and never shown while any drag (incl. a reference drag) is in flight; re-shown only after the pointer changes cell | Always shown on hover | One press = one action; no DOM churn mid-drag |
+| Partial formula on grid exit | A grid-exit focus-out commits the partial formula as typed | Excel refuses to leave the cell | A session cannot survive without focus (see "Focus leaving the grid") |
+| Highlight bands | At most the last 16 selected ranges get bands | Every range | 1,280 nodes per frame at 64 ranges × 4 quadrants (measured) |
+| Ragged HTML tables | The pre-parse estimate is `rows × max (carried rowspan + Σcolspan)` over the ASCII-case-folded markup — an upper bound of what the reader materialises (a wide header `colspan` can reject a table that is really under the cap); the reader itself stops at `maxOperationCells` before allocating (`outcome: "limit"`), so an attribute the estimate cannot read (`colspan="&#50;"`) is still bounded. Only the `<table` detection is lowercase-only: an all-upper-case `<TABLE>` document pastes as text | — | Conservative like `countRangeCells`; the estimate must never under-count, and nothing super-linear in the cell count runs before the cap |
+| `insertDate` / `insertTime` while idle | Write the active cell only | Sheets writes every selected cell | Avoids accidental overwrites of a multi-range selection |
+| `bordersOuter` / single-side border presets | Position-dependent range-edge application: only the cells on the targeted range edge(s) change, each keeping its own other sides; cells off the edge get no edit | Same (the plan prescribed a constant patch from the active cell to every selected cell) | Excel / Sheets parity; stamping the active cell's side set onto every cell would erase the other cells' borders |
+| `clearFormatting` | Cells that are already unformatted produce no edit | — | Identity rule of `mergeFormat` — no no-op writes reach the adapter |
+| Colour toggles | Compare the active cell's base colour after normalisation (`#ffff00` = `#FFFF00`), write the configured spelling verbatim | — | The target spelling is the consumer's choice |
+| Validation list picker | Case-insensitive **prefix** filter; mounts at most 500 options per render — a larger match set appends one `listMore` row naming the hidden count | Sheets filters by substring and virtualises the list | A pasted foreign rule may carry an arbitrarily large values array; mounting it whole would freeze the tab, and the prefix filter reaches everything beyond the cap |
+| Self-calc | Writes canonical decimals (exponent-form inputs keep exponent form), flips `TRUE` / `FALSE` case-insensitively, leaves custom checkbox labels alone, treats an `=`-prefixed text as text unless `getCellFormula` is declared, and wraps compound formulas (`=(A1)/100+(B1)/100` × 100 ⇒ `=((A1)/100+(B1)/100)*100`) instead of peeling | The reference extension peels greedily | The greedy regex produces the broken `=A1)/100+(B1` |
+| Excel / Word HTML without a table | `mso-` paragraphs (Word / Outlook) paste as text, not as an unreadable Excel clip | — | No table reader can read them; ADR-14 forbids trying another reader |
+
+## Demo (feature showcase, doubles as the E2E fixture)
+
+Run `pnpm run demo:dev` from a source checkout (the `demo/` app is not in the npm tarball) and open
+`http://localhost:5179`. Nine routes, each an in-header-nav page AND an E2E fixture (`tests/e2e/`):
+
+| Route | What you experience |
+| --- | --- |
+| `/` | The headline goal live: 1,000,000 × 16,384 read-only grid, rejection toasts, mount-time metric |
+| `/edit` | Editing, the reference inverse-patch Undo/Redo store, `findDataEdge` Ctrl+Arrow jumps, value-based auto-alignment via a bare `getCellFormat: () => undefined` declaration (typed numbers right-align like Excel), the imperative resize handle, and a Sheet A/B toggle (adapter-identity swap: selection resets to A1, the pending edit and an armed copy are discarded, an armed cut is kept as a foreign clip for a cross-sheet move) |
+| `/render` | `renderCell` formatting (currency / delta / meter / badge) over canonical strings, the selection readout (`onSelectionChange`), a custom context menu on both origins (right-click and Shift+F10), `onCopyMultiRange` |
+| `/format` | The built-in display formats (v0.7): a typed sheet whose columns declare `getCellFormat` (number with grouping / currency ¥ / percent / scientific / date / explicit-center text) with **no** `renderCell` — value-aware auto-alignment, raw-value editing and copy, formatted-display autofit, an **interactive format toolbar** (apply a value format and alignment to the selected cell/range independently, restore the column default — published through the documented `dataVersion` bump), plus the standard read-only wiring (`enableFillHandle={false}` and an `onEditRejected` readout whose wording is derived from the `EditRejection` context — a kept session says Escape cancels, a discarded one says the value is already gone — so Enter is never a silent dead key and a focus-out never gets bad advice) |
+| `/styles` | The v0.8 rich cells (`tests/e2e/styles.spec.ts`): a 300 × 26 sheet whose store declares all eight capabilities (a mini formula evaluator for `=A1+B1` / `SUM` / `AVERAGE` feeds `evaluateFormula` and the computed `getCellText`, `getCellFormula` returns the source), a patch-applying store with per-transaction inverse-patch Undo (a cross-sheet cut-move folds into one entry) and consumer-minted comment ids, a format toolbar driven by `handle.executeCommand` (every button keeps focus in the grid), colour pickers, border / number-format presets, link / note / comment / validation / conditional-format editors, a Paste Special menu opened by `onPasteSpecialRequest` (Excel accelerators — modes `A`ll / `F`ormulas / `V`alues / `T` formats / `C`omments and notes / `N` validation / `X` all except borders / `W`idths / `R` conditional formats, operations `O` none / `D` add / `S` subtract / `M` multiply / `I` divide, flags `B` skip blanks / `E` transpose / `J` inject formats → `handle.paste`), highlight-band settings, a shortcut rebinding table with reserved-chord warnings, a clip-info chip (`onClipChange`), a Sheet A / B toggle for cross-sheet paste and cut-move, and Excel / Sheets fixture buttons that write real interop HTML to the clipboard |
+| `/huge` | The v0.4 deep-reach proof: 1,000,000 × 10,000,000 on a pure functional adapter — Ctrl+→ (and End) reach the rightmost column 9,999,999 and Ctrl+↓ the last row 999,999 in one press (uniform-block Excel semantics, unified with the `/` route; ±1px cell placement), a "deep jump" button (`scrollToCell` to the interior column 5,000,000 ≈ 5 億 px, past the 2^25 wall), zoom ×4 holds ±1 logical px — plus runtime freeze toggles (0 ↔ 3 frozen rows above 0 ↔ 3 frozen columns), a context menu (right-click / Shift+F10) that opens at static frozen-cell coordinates even mid-deep-scroll, and the drag-freshness and performance-budget E2E gates |
+| `/tune` | Sizing knobs (`defaultRowHeight` / `defaultColumnWidth` / banded per-column widths via the imperative `resizeColumn` mount effect), hide / unhide (drag a boundary to 0, marker drag / dblclick restore, single-column dblclick autofit), a deliberately low LIVE `maxOperationCells` staging every rejection class (limit, row fan-out ÷10, autofit ÷4, bounds via the multi-cell corner recipe), live `enableResizeUI` / `enableFillHandle` opt-outs, an empty-grid staging toggle (rowCount 0 adapter swap), a data-reset button, and the zoom card (v0.3) — the controlled-mode reference wiring (`zoom` + `onZoomChange`, 50–200% select plus every zoom gesture) and the fixture for the zoom E2E gates |
+| `/a11y` | Custom Japanese `formatCellAnnouncement` / `formatSelectionAnnouncement` mirrored into visible readouts, overridden accessible names (Escape advisement kept), the WCAG 2.1.2 escape route |
+| `/utils` | The exported pure functions live: TSV round-trip, paste-expansion rules, column-name converter (incl. its fail-fast `RangeError`), range algebra, and a clipboard inspector card (discloses the raw text/html payload, textContent-rendered) |
+
+Appending `?css=standalone` to any route swaps the source CSS pair for the built single-file
+artifact `dist/styles/spreadsheet.standalone.css` (artifact-parity verification path — run
+`pnpm run build:css` first).
+
+## Performance
+
+Budgets are enforced by tests, not prose (`tests/e2e/performance.spec.ts`, `src/clipboard/pasteBudget.spec.ts`):
+initial mount of the 1M × 16,384 demo < 150ms (production build, best of 3 — shared-CI contention only ever adds time);
+zero cell re-renders during drag selection and within-window scrolling (DOM-identity verified); 100,000-cell paste
+parse→expand→apply < 100ms (median of 3, asserted as written under `AQSP_BENCH_SOLO=1` — 300 ms in-suite slack); DOM node count independent of data and selection size. The v0.4 deep-reach
+gates (`tests/e2e/virtualgrid-deep.spec.ts`) add: a 10,000,000-column deep jump paints its landing window < 150ms
+(min of 3) and a horizontal thumb teleport materializes the landing window within 2 vsync.
+
+The v0.8 rows (`src/clipboard/pasteBudget.spec.ts`, `src/clipboardRich.spec.tsx`, `src/richCells.spec.tsx`,
+`src/highlightBands.spec.tsx`, `tests/e2e/styles.spec.ts`) are deterministic-first: structural pins (adapter read counts,
+predicate evaluations, dictionary sizes, style-write counts) are the primary gates, and a quoted wall clock is asserted as
+written only under `AQSP_BENCH_SOLO=1` — that solo branch exists in `pasteBudget.spec.ts` (all three wall-clock rows), `richCells.spec.tsx` (every bench
+row, each wall clock in an `it` of its own so a loaded host can only redden the clock, never the structure pins — see below), `styles.spec.ts`, `v2b.spec.ts` and the v0.2 row-fan-out bench
+`resizeBudget.spec.tsx`; the in-suite runs carry slack, and every other jsdom wall clock is a secondary gate
+in an `it` of its own (the bench runs once into a memo both `it`s read) whose floor and slack are stated inline (`highlightBands.spec.tsx` has no wall clock at all): an own 100,000-cell JSON paste < 100 ms with ≤ 100 distinct R1C1 formulas
+(≈ 90 ms measured) and < 300 ms with all-distinct formulas (≈ 220 ms); a 100,000-cell copy (4 formats, 20 % formulas) emits
+`html.length ≤ 160 × cells` and ONE format-dictionary entry for fresh-but-equal format objects; an over-cap ragged HTML table is
+rejected with zero `DOMParser` constructions; painting 1,200 cells against 1,000 whole-column conditional-format rules spread over
+26 column bands stays within eight adapter reads per cell and walks only the cell's 2-D bucket, and the literal 26-adjacent-column
+shape accounts for exactly 71,200 `ranges` reads (both wall clocks sit in separate `it`s as a two-tier secondary gate calibrated on
+the documented jsdom seam floor of 20 ms — 40 ms solo / 100 ms in-suite — because the plan's 8 ms is a Chromium figure the jsdom
+seam never meets: ≈ 18 ms cold median on the B5 host, 3.7 / 13.1 ms on a 12-core host in 2026-09); 1,200 validated
+cells against a 10,000-item list paint their invalid marks with zero formula evaluations and one text read per cell, < 3 ms solo
+(≈ 1.4 ms measured; the in-suite gate is 3 ms × 5 slack, again in an `it` of its own); `getRangeExtrema` is called exactly once per
+value-less colour-scale range per render version (0 on a selection change); band repaints write only `transform` per scroll frame
+(Chromium: per-repaint p90 ≤ 4 ms with 16 ranges and both axes frozen — 1.30 ms measured solo over 320 band nodes); the
+Chromium gates on the 300 × 26 `/styles` demo (7,800 cells — a 100,000-cell own range is dimensionally unreachable there, so
+the "100k" rows are certified whole-sheet, with the foreign table generated in-page) add an own copy of the whole sheet < 150 ms
+(30.4 ms measured solo, `html.length ≤ 160 × cells`), an own `Ctrl+V` of it < 120 ms (27.1 ms), a menu-path paste < 350 ms
+(54.7 ms), a foreign 999 × 100 = 99,900-cell Sheets table < 1.5 s (1,133.9 ms), the 25,000-distinct-string autofit < 300 ms
+(`tests/e2e/v2b.spec.ts`), and a `ctx.font` write-count gate on the same demo (one assignment per distinct painted font,
+conditional-format italics included). The solo inventory above and the operation-limits table's row-axis ceilings are
+themselves pinned by `src/hxCensus.spec.ts` against the spec files that read the variable and against `ROW_FANOUT_DIVISOR`.
+
+## License
+
+Dual-licensed. Copyright © AI Quants Trading, LLC.
+
+- **Noncommercial use** — free of charge under the [PolyForm Noncommercial License 1.0.0](./LICENSE.md)
+  (personal, research, educational, charitable, and other noncommercial purposes).
+- **Commercial use** — requires a separate commercial license agreement with AI Quants Trading, LLC.
+
+Whatever the distribution channel (registry or repository), the package is provided solely under the dual terms
+above — see `LICENSE.md` for the governing text.