Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

bento/dash: a spreadsheet you could use instead of Excel (#248)

nyblneta7f2e83aeabc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index f683e159..8f4441db 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -316,6 +316,90 @@ jobs:
# do not know".
run: node scripts/test-dash-chart.ts
+ # ── the rest of bento/dash. Each of these asserts a way a spreadsheet can
+ # be CONFIDENTLY WRONG, which is the failure that matters here: nobody
+ # re-derives a number by hand, so a wrong one is not caught by the person
+ # relying on it. Each rig argues its own case in its header; the lines
+ # below say why it gates a merge.
+ - name: bento/dash function pack
+ # Lookups, multi-criteria, finance, statistics — including the three
+ # places we deliberately depart from Excel because Excel's default is a
+ # trap: an approximate VLOOKUP on unsorted data, an IRR that converges
+ # on nothing, a PERCENTILE that clamps instead of refusing.
+ run: node scripts/test-dash-functions.ts
+
+ - name: bento/dash cell formulas
+ # Evaluation ORDER. A cell computed before the cell it reads writes a
+ # stale number into the document, looking authoritative.
+ run: node scripts/test-dash-cellformula.ts
+
+ - name: bento/dash A1 references
+ # `$` pins against a COPY and not against structure, and a reference
+ # into a deleted row is #REF! rather than whatever slid up into it.
+ run: node scripts/test-dash-a1.ts
+
+ - name: bento/dash pivot
+ # Subtotals are COMPUTED, not summed: an average of averages is a
+ # different number, and a distinct count does not add up.
+ run: node scripts/test-dash-pivot.ts
+
+ - name: bento/dash dashboard
+ # Cross-filter selections compose, and the categories of a column
+ # PARTITION the sheet — no row dropped, none counted twice.
+ run: node scripts/test-dash-dashboard.ts
+
+ - name: bento/dash data story
+ # A gap tweens as a gap. Interpolating an absent quarter through zero is
+ # the animation telling a lie about the data.
+ run: node scripts/test-dash-story.ts
+
+ - name: bento/dash filter and sort
+ run: node scripts/test-dash-filter.ts
+
+ - name: bento/dash rows and columns
+ # Structure, and the rid watermark — a rid must never be minted twice,
+ # which is collaboration's correctness precondition.
+ run: node scripts/test-dash-rowcol.ts
+
+ - name: bento/dash selection and clipboard
+ run: node scripts/test-dash-select.ts
+
+ - name: bento/dash conditional formatting
+ run: node scripts/test-dash-condfmt.ts
+
+ - name: bento/dash side panels
+ run: node scripts/test-dash-panels.ts
+
+ - name: bento/dash About dialog
+ run: node scripts/test-dash-about.ts
+
+ - name: bento/dash thumbnail preview
+ # An encrypted workbook NEVER gets a preview — a plaintext title beside
+ # the ciphertext is the leak the password exists to prevent.
+ run: node scripts/test-dash-preview.ts
+
+ - name: bento/dash zip
+ # Verified against real unzip implementations, not only our own reader:
+ # a reader and a writer that share a bug agree with each other perfectly.
+ run: node scripts/test-dash-zip.ts
+
+ - name: bento/dash xlsx
+ # Both 1900 date epochs, including the leap-year bug — getting it wrong
+ # shifts every date by four years, silently.
+ run: node scripts/test-dash-xlsx.ts
+
+ - name: bento/dash WebGL
+ run: node scripts/test-dash-gl.ts
+
+ - name: bento/dash 3D scenes
+ run: node scripts/test-dash-viz3d.ts
+
+ - name: bento/dash CRDT convergence
+ # The big one: randomised concurrent edits across N replicas, asserted
+ # to converge. It has caught every ordering bug in the engine, and the
+ # two it did not catch were found by widening it.
+ run: node scripts/test-dash-sync.ts
+
- name: Built-in layout geometry rig
# The built-ins are drawn against 1600x900 while the model default is
# 1280x720, so they used to hang 200px off the right edge of a default
diff --git a/dash/index.html b/dash/index.html
index 92f1cb57..f2558419 100644
--- a/dash/index.html
+++ b/dash/index.html
@@ -22,17 +22,34 @@
<div class="dash-splash-mark">bento<span>/</span>dash</div>
</div>
<style>
+ /* The splash paints before any script runs — before the app stylesheet
+ is even inflated — so it carries its own two colours rather than the
+ tokens, and it declares `color-scheme` itself so that `light-dark()`
+ has something to resolve against this early. (That declaration also
+ overrides the <meta> above, which is what stops the browser painting
+ a white canvas behind a dark splash for one frame.)
+
+ It follows the OS on its own, and follows an EXPLICIT light/dark
+ choice as soon as about.ts injects its `color-scheme` rule — which
+ happens at module load, while the splash is still covering the
+ screen. That preference lives in localStorage and only script can
+ read it, so a reader whose choice differs from their OS sees the OS
+ colour for that fraction of a second. The alternative is a white flash
+ on a dark desktop, which is worse and lasts exactly as long. */
+ :root {
+ color-scheme: light dark;
+ }
#bento-splash {
position: fixed;
inset: 0;
display: flex;
align-items: center;
justify-content: center;
- background: #fff;
+ background: light-dark(#fff, #0e1319);
z-index: 9999;
transition: opacity 0.45s ease;
font: 600 20px/1.4 ui-sans-serif, system-ui, -apple-system, sans-serif;
- color: #1e2a3a;
+ color: light-dark(#1e2a3a, #d6dee9);
}
#bento-splash.done { opacity: 0; pointer-events: none; }
.dash-splash-mark span { color: #ff9e8a; }
diff --git a/dash/src/a1.ts b/dash/src/a1.ts
new file mode 100644
index 00000000..41c75227
--- /dev/null
+++ b/dash/src/a1.ts
@@ -0,0 +1,389 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// A1 addressing — cell references, ranges, and the only place `#REF!` is minted.
+//
+// dash's COLUMN formulas do not have the `#REF!` problem. A column expression
+// names a column by IDENTITY (model.ts `Column.id`), so inserting a row changes
+// nothing, deleting a row changes nothing, and dragging a column changes
+// nothing. That is the structural win formula.ts's header claims, and it is
+// real.
+//
+// A1 references give it back, and they have to. An invoice, a scratch pad, a
+// totals block — the `CanvasSheet` cases — are POSITIONAL by nature, and a
+// person typing `=B4*1.2` is not going to be talked out of it. So the two
+// coexist, and the entire cost of admitting them is concentrated in this file:
+// an A1 reference is a POSITION, positions move, and every structural edit has
+// to move them EXACTLY. Close is the dangerous answer, not the safe one — a
+// reference left pointing at whatever slid into the deleted row is a wrong
+// number wearing a right number's clothes, the same sin as an error that
+// becomes a zero.
+//
+// EVERYTHING HERE IS 0-BASED, columns AND rows: `A1` parses to {col:0, row:0}.
+// The `1` in `A1` is display exactly as the `A` is. The grid, the store's row
+// indices and `readCell` are all 0-based, so a 1-based row here would put a ±1
+// at every call site and one of them would eventually be wrong. `formatRef` is
+// the only place the +1 lives.
+//
+// `$` PINS AGAINST FILL, NOT AGAINST STRUCTURE — the rule that gets
+// re-litigated every time someone reads it. `translateRef` (fill-down,
+// copy-paste) leaves `$A$1` alone; `shiftRefsForInsert` (a row or column was
+// inserted or deleted) MOVES it, because the cell it names physically moved.
+// Insert a row above `$A$5` in Excel and you get `$A$6`. A "$ never moves"
+// implementation is wrong in the direction that quietly re-points references at
+// other people's data.
+//
+// WHAT IS NOT A REFERENCE, when rewriting an expression:
+// • text inside "quotes" — `="A1 is "&A1` shifted one row is `="A1 is "&A2`;
+// • a [bracketed name] — formula.ts's escape for a column whose name has
+// spaces, and the escape hatch for a column named like a cell;
+// • a name followed by `(` — `LOG10(x)` is a call, and `LOG10` is otherwise
+// a perfectly good cell address;
+// • a name followed by `!` or `[` — `Sheet1!A1` and `Table1[Col]` qualify
+// something, and `Sheet1`/`Table1` are both cell-shaped;
+// • anything over 3 letters or 7 digits. That is Excel's bound (XFD1048576),
+// and here it is also what keeps `REVENUE2024` a column name instead of a
+// cell address. `REV2024` is genuinely ambiguous and resolves as a CELL, as
+// it does in every spreadsheet on earth — write `[REV2024]` to mean the
+// column.
+
+/** The one error this file can produce. Visible, never a silent fallback. */
+export const REF_ERR = '#REF!'
+
+/**
+ * Cells `expandRange` will materialise before refusing.
+ *
+ * Excel's sheet is 1,048,576 rows, so `A1:A1048576` is a thing a person can
+ * type — and expanding it as objects is a ~200 MB allocation and a dead tab.
+ * Refusing with `null` is answerable; a hang is not.
+ */
+export const RANGE_CELL_MAX = 1_000_000
+
+/** Excel's bound (XFD = 16383), and the fence that keeps `REVENUE2024` a name. */
+const MAX_LETTERS = 3
+const MAX_DIGITS = 7
+
+export interface CellRef {
+ /** 0-based. A = 0. */
+ col: number
+ /** 0-based. The `1` of `A1` is display. */
+ row: number
+ absCol: boolean
+ absRow: boolean
+}
+
+export interface RangeRef { from: CellRef; to: CellRef }
+
+// --- Column letters ---------------------------------------------------------
+// BIJECTIVE base-26, which is the part everyone gets wrong. There is no zero
+// digit: after Z comes AA, not BA. Plain base-26 (A=0) makes 26 into "BA" and
+// gives two spellings for every column, so the round trip stops holding at the
+// 27th column — where nobody looks.
+
+/** 0→A, 25→Z, 26→AA, 701→ZZ, 702→AAA. `''` for a non-address. */
+export function colToLetters(i: number): string {
+ if (!Number.isInteger(i) || i < 0) return ''
+ let s = ''
+ let n = i
+ while (n >= 0) {
+ s = String.fromCharCode(65 + (n % 26)) + s
+ n = Math.floor(n / 26) - 1
+ }
+ return s
+}
+
+/** The inverse, case-insensitive. `-1` for anything that is not letters. */
+export function lettersToCol(s: string): number {
+ if (!s) return -1
+ let n = 0
+ for (let i = 0; i < s.length; i++) {
+ // | 32 lowercases a letter and moves everything else out of range, so the
+ // rejection is the same branch as the fold.
+ const c = s.charCodeAt(i) | 32
+ if (c < 97 || c > 122) return -1
+ n = n * 26 + (c - 96)
+ }
+ return n - 1
+}
+
+// --- References -------------------------------------------------------------
+
+const REF_RE = new RegExp(`^(\\$?)([A-Za-z]{1,${MAX_LETTERS}})(\\$?)([0-9]{1,${MAX_DIGITS}})$`)
+
+/** `A1`, `$A$1`, `A$1`, `$A1`, any case. `null` if it is not an address. */
+export function parseRef(s: string): CellRef | null {
+ const m = REF_RE.exec(s.trim())
+ if (!m) return null
+ const col = lettersToCol(m[2])
+ // `A0` is not a cell: rows are 1-based on the page, so 0 is a typo, and
+ // parsing it to row -1 would let it format straight back out as `A0`.
+ const row = Number(m[4]) - 1
+ if (col < 0 || row < 0) return null
+ return { col, row, absCol: m[1] === '$', absRow: m[3] === '$' }
+}
+
+/**
+ * The inverse. Canonical: letters uppercase, `$` where the ref says.
+ *
+ * An address that cannot exist formats as `#REF!` rather than as `A0` or `''`.
+ * This is deliberately the ONLY place the error is minted — every shift below
+ * builds a CellRef and hands it here, so no caller can forget the check and
+ * emit a plausible address for a cell that fell off the sheet.
+ */
+export function formatRef(r: CellRef): string {
+ const letters = colToLetters(r.col)
+ if (!letters || !Number.isInteger(r.row) || r.row < 0) return REF_ERR
+ return `${r.absCol ? '$' : ''}${letters}${r.absRow ? '$' : ''}${r.row + 1}`
+}
+
+// --- Ranges -----------------------------------------------------------------
+
+/** `A1:B10`. `null` unless BOTH ends are addresses. */
+export function parseRange(s: string): RangeRef | null {
+ const i = s.indexOf(':')
+ if (i < 0) return null
+ const from = parseRef(s.slice(0, i))
+ const to = parseRef(s.slice(i + 1))
+ return from && to ? { from, to } : null
+}
+
+export const formatRange = (r: RangeRef): string => `${formatRef(r.from)}:${formatRef(r.to)}`
+
+/**
+ * Every cell in the rectangle, in reading order (row-major), or `null` past
+ * RANGE_CELL_MAX.
+ *
+ * The corners are normalised, so `B10:A1` expands the same rectangle as
+ * `A1:B10` — a range is an area, and the order it was typed in is not data.
+ * The count is computed before anything is allocated; that is the whole point
+ * of the cap.
+ *
+ * Expanded cells carry `absCol/absRow: false`. They are ADDRESSES, and `$` is a
+ * property of how a reference was WRITTEN, not of the cell it lands on.
+ */
+export function expandRange(r: RangeRef): CellRef[] | null {
+ const c0 = Math.min(r.from.col, r.to.col)
+ const c1 = Math.max(r.from.col, r.to.col)
+ const r0 = Math.min(r.from.row, r.to.row)
+ const r1 = Math.max(r.from.row, r.to.row)
+ if (c0 < 0 || r0 < 0) return null
+ if ((c1 - c0 + 1) * (r1 - r0 + 1) > RANGE_CELL_MAX) return null
+ const out: CellRef[] = []
+ for (let row = r0; row <= r1; row++) {
+ for (let col = c0; col <= c1; col++) out.push({ col, row, absCol: false, absRow: false })
+ }
+ return out
+}
+
+// --- Translation (fill, copy/paste) -----------------------------------------
+
+const shifted = (r: CellRef, dRow: number, dCol: number): string => formatRef({
+ col: r.absCol ? r.col : r.col + dCol,
+ row: r.absRow ? r.row : r.row + dRow,
+ absCol: r.absCol,
+ absRow: r.absRow,
+})
+
+/**
+ * Move a reference by a fill/paste offset: relative parts shift, `$` parts do
+ * not. This is what dragging a formula down a column does.
+ *
+ * Off the top or left edge is `#REF!` — filling `=A1` upward has no answer, and
+ * clamping it to `A1` would silently make every row of the fill read the same
+ * cell.
+ *
+ * A string that is not an address comes back UNCHANGED: callers hand this whole
+ * tokens, and mangling `SUM` would be worse than ignoring it.
+ */
+export function translateRef(ref: string, dRow: number, dCol: number): string {
+ const r = parseRef(ref)
+ return r ? shifted(r, dRow, dCol) : ref
+}
+
+// --- The expression scanner -------------------------------------------------
+// One walk over the source, used by both rewrites below. It is a SCANNER and
+// not the parser from formula.ts on purpose: rewriting must return the author's
+// text with only the references changed — comments, spacing and any syntax this
+// build does not understand have to survive, and a parse→print round trip would
+// quietly normalise all of it away.
+
+interface Unit { from: CellRef; to?: CellRef }
+type MapUnit = (u: Unit) => string
+
+const isAlpha = (c: string): boolean => (c >= 'A' && c <= 'Z') || (c >= 'a' && c <= 'z')
+const isDigit = (c: string): boolean => c >= '0' && c <= '9'
+/** The identifier body formula.ts's lexer accepts, so words break identically. */
+const isWord = (c: string): boolean => isAlpha(c) || isDigit(c) || c === '_' || c === '.'
+
+/**
+ * Walk `src` and hand every reference to `map`, splicing its return in place.
+ *
+ * Exported because cellformula.ts substitutes references for bound names using
+ * the SAME walk the shifting rewrites use. A second scanner would be a second
+ * definition of what counts as a reference, and the two would disagree about a
+ * quoted string or a `[bracketed name]` on some Tuesday.
+ */
+export function mapRefs(src: string, map: MapUnit): string { return rewrite(src, map) }
+export type { Unit as RefUnit }
+
+function rewrite(src: string, map: MapUnit): string {
+ const n = src.length
+ const skipSpace = (j: number): number => {
+ while (j < n && (src[j] === ' ' || src[j] === '\t' || src[j] === '\n' || src[j] === '\r')) j++
+ return j
+ }
+ /** A maximal word, `$` included so `$A$1` is one token. */
+ const word = (j: number): number => {
+ while (j < n && (isWord(src[j]) || src[j] === '$')) j++
+ return j
+ }
+
+ let out = ''
+ let i = 0
+ while (i < n) {
+ const c = src[i]
+
+ // A string literal is copied byte for byte. `="A1 is "&A1` shifted a row is
+ // `="A1 is "&A2`: the text is a label a human wrote, not an address.
+ if (c === '"') {
+ let j = i + 1
+ while (j < n) {
+ if (src[j] === '"') {
+ if (src[j + 1] === '"') { j += 2; continue } // "" is an escaped quote
+ j++
+ break
+ }
+ j++
+ }
+ out += src.slice(i, j)
+ i = j
+ continue
+ }
+
+ // [Bracketed name] — formula.ts's column escape, and the way to say "the
+ // column called REV2024, not the cell".
+ if (c === '[') {
+ const close = src.indexOf(']', i)
+ const end = close < 0 ? n : close + 1
+ out += src.slice(i, end)
+ i = end
+ continue
+ }
+
+ // A number, and anything glued to it. Keeps `2024A1` from contributing a
+ // reference nobody wrote.
+ if (isDigit(c)) {
+ let j = i
+ while (j < n && isWord(src[j])) j++
+ out += src.slice(i, j)
+ i = j
+ continue
+ }
+
+ if (isAlpha(c) || c === '$' || c === '_') {
+ const j = word(i)
+ const text = src.slice(i, j)
+ const k = skipSpace(j)
+ // `(` = a call, `!` = a sheet qualifier, `[` = a structured reference.
+ // All three are followed by a name that is frequently cell-shaped
+ // (LOG10, Sheet1, Table1); translating one corrupts the formula.
+ if (src[k] === '(' || src[k] === '!' || src[k] === '[') {
+ out += text
+ i = j
+ continue
+ }
+ const from = parseRef(text)
+ if (!from) { out += text; i = j; continue }
+
+ // A range is mapped as ONE unit: deleting the rows under `A3:A5` has to
+ // collapse the whole thing to `#REF!`, which an endpoint on its own
+ // cannot know.
+ if (src[k] === ':') {
+ const m = skipSpace(k + 1)
+ const e = word(m)
+ const to = parseRef(src.slice(m, e))
+ const after = skipSpace(e)
+ if (to && src[after] !== '(' && src[after] !== '!' && src[after] !== '[') {
+ out += map({ from, to })
+ i = e
+ continue
+ }
+ }
+ out += map({ from })
+ i = j
+ continue
+ }
+
+ out += c
+ i++
+ }
+ return out
+}
+
+/**
+ * Translate every reference in an expression — what fill-down of a cell formula
+ * does. Quoted text, bracketed names, function names and sheet qualifiers are
+ * left exactly as written.
+ *
+ * A range with an off-sheet corner becomes `#REF!` whole. `#REF!:B1` is not a
+ * smaller range, it is not a range.
+ */
+export function rewriteFormulaRefs(src: string, dRow: number, dCol: number): string {
+ return rewrite(src, (u) => {
+ const a = shifted(u.from, dRow, dCol)
+ if (!u.to) return a
+ const b = shifted(u.to, dRow, dCol)
+ return a === REF_ERR || b === REF_ERR ? REF_ERR : `${a}:${b}`
+ })
+}
+
+/**
+ * Move every reference for a structural edit: `count` rows/columns inserted at
+ * 0-based index `at`, or REMOVED if `count` is negative.
+ *
+ * `$` DOES NOT PROTECT A REFERENCE HERE. The cell moved; `$` only ever meant
+ * "do not renumber me when I am copied". Excel agrees, and a reader who expects
+ * otherwise is expecting their totals to point one row short.
+ *
+ * A reference INTO a deleted row becomes `#REF!` — never the row that slid into
+ * that position, which is the failure this whole file exists to prevent.
+ *
+ * A RANGE spanning the hole SHRINKS instead: deleting three rows out of the
+ * middle of `A1:A10` gives `A1:A7`, because the range still means "the numbers
+ * under this heading" and the surviving ones are still there. It becomes
+ * `#REF!` only when both ends are gone.
+ */
+export function shiftRefsForInsert(
+ src: string,
+ axis: 'row' | 'col',
+ at: number,
+ count: number,
+): string {
+ const val = (r: CellRef): number => (axis === 'row' ? r.row : r.col)
+ const put = (r: CellRef, v: number): CellRef =>
+ (axis === 'row' ? { ...r, row: v } : { ...r, col: v })
+ const gone = count < 0 ? -count : 0
+
+ /** New index, or `null` if this line was one of the deleted ones. */
+ const moved = (v: number): number | null => {
+ if (!gone) return v >= at ? v + count : v
+ if (v < at) return v
+ if (v < at + gone) return null
+ return v - gone
+ }
+
+ return rewrite(src, (u) => {
+ const a = moved(val(u.from))
+ if (!u.to) return a === null ? REF_ERR : formatRef(put(u.from, a))
+ const b = moved(val(u.to))
+ if (a === null && b === null) return REF_ERR
+ // One end survived, so the range clamps to the surviving side of the hole:
+ // the low end to the first line after it (`at`), the high end to the last
+ // line before it (`at - 1`). Clamping both to `at` would extend the range
+ // over whatever moved up into the gap.
+ const lowFirst = val(u.from) <= val(u.to)
+ const fa = a ?? (lowFirst ? at : at - 1)
+ const fb = b ?? (lowFirst ? at - 1 : at)
+ if (fa < 0 || fb < 0) return REF_ERR
+ return `${formatRef(put(u.from, fa))}:${formatRef(put(u.to, fb))}`
+ })
+}
diff --git a/dash/src/about.css b/dash/src/about.css
new file mode 100644
index 00000000..8deadb37
--- /dev/null
+++ b/dash/src/about.css
@@ -0,0 +1,153 @@
+/* SPDX-License-Identifier: MIT
+ Copyright (c) 2026 The Bento authors
+ The About dialog. Separate from styles.css because it is a whole surface
+ nothing else shares — but the same tokens, so it inherits a theme change.
+
+ Vite concatenates every imported stylesheet into ONE <style> in head, which
+ is what postbuild-compress deflates (it takes the first <style> in head and
+ would leave a second one as plaintext). So this file must be IMPORTED, never
+ linked, and nothing here may depend on landing after styles.css in the
+ cascade — order follows the module graph, not intent.
+
+ Which is exactly why the shared radii/shadows/type sizes are CUSTOM
+ PROPERTIES and not a base rule some file overrides: a var() resolves where
+ it is used, so --radius-xl means the same thing here whether this file lands
+ before or after the one that declares it. */
+
+.dx-about-back {
+ position: fixed;
+ inset: 0;
+ z-index: 10000; /* above .dx-pop (9999): a popover left open must not sit on top */
+ background: var(--scrim);
+ display: flex;
+ align-items: flex-start;
+ justify-content: center;
+ padding: 5vh 16px;
+ overflow: auto;
+ overscroll-behavior: contain;
+}
+
+.dx-about {
+ background: var(--surface);
+ color: var(--ink);
+ border-radius: var(--radius-xl);
+ box-shadow: var(--shadow-dialog);
+ padding: 20px 22px 18px;
+ width: min(560px, 100%);
+ /* the notch, same rule as the top bar: the app pads its own chrome */
+ margin-bottom: max(16px, env(safe-area-inset-bottom));
+}
+
+.dx-about h2 {
+ font-size: var(--fs-micro);
+ font-weight: 650;
+ letter-spacing: 0.08em;
+ text-transform: uppercase;
+ color: var(--muted);
+ margin: 20px 0 8px;
+}
+.dx-about h2:first-child { margin-top: 0; }
+
+.dx-about-lede { margin: 0 0 10px; }
+.dx-about-lede b { font-weight: 650; }
+
+.dx-about-note {
+ color: var(--muted);
+ font-size: var(--fs-small);
+ line-height: 1.5;
+ margin: 6px 0 0;
+}
+
+.dx-about-row {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 4px 0;
+ font-size: var(--fs-ui);
+}
+.dx-about-row > span:first-child {
+ flex: 0 0 8.5rem;
+ color: var(--muted);
+}
+.dx-about-row > :last-child { flex: 1 1 auto; min-width: 0; }
+
+.dx-about-val {
+ font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+ overflow-wrap: anywhere;
+}
+
+.dx-about-in,
+.dx-about select {
+ font: inherit;
+ font-size: var(--fs-ui);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius);
+ padding: 4px 7px;
+ background: var(--surface);
+ color: inherit;
+ width: 100%;
+}
+.dx-about-in:focus,
+.dx-about select:focus { outline: none; border-color: var(--accent); }
+.dx-about-in[disabled] { background: var(--panel); color: var(--muted); }
+
+.dx-about-actions {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 8px;
+ margin-top: 6px;
+}
+
+.dx-about-paste {
+ font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+ width: 100%;
+ min-height: 9rem;
+ margin-top: 8px;
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius);
+ padding: 8px;
+ resize: vertical;
+ background: var(--surface);
+ color: inherit;
+}
+.dx-about-paste:focus { outline: none; border-color: var(--accent); }
+
+.dx-about-vers {
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+ max-height: 30vh;
+ overflow: auto;
+ border: 1px solid var(--line);
+ border-radius: var(--radius);
+ padding: 4px;
+}
+.dx-about-ver {
+ font: inherit;
+ font-size: var(--fs-ui);
+ display: flex;
+ gap: 10px;
+ align-items: baseline;
+ text-align: left;
+ border: 0;
+ background: transparent;
+ color: inherit;
+ border-radius: var(--radius);
+ padding: 5px 8px;
+ cursor: pointer;
+}
+.dx-about-ver:hover { background: var(--hover); }
+.dx-about-ver span:first-child { flex: 1 1 auto; font-variant-numeric: tabular-nums; }
+.dx-about-ver span:last-child { color: var(--accent); }
+
+.dx-about-close { margin-top: 18px; }
+
+/* The wordmark and the version chip are the way in — say so on hover, since
+ neither looks like a control. */
+.dx-mark[data-about], .dx-ver[data-about] { cursor: pointer; }
+.dx-mark[data-about]:hover, .dx-ver[data-about]:hover { color: var(--accent); }
+.dx-mark[data-about]:focus-visible, .dx-ver[data-about]:focus-visible {
+ outline: 2px solid var(--accent);
+ outline-offset: 2px;
+ border-radius: 4px;
+}
diff --git a/dash/src/about.ts b/dash/src/about.ts
new file mode 100644
index 00000000..4ff3cc96
--- /dev/null
+++ b/dash/src/about.ts
@@ -0,0 +1,652 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The About surface: what this file is, who wrote it, how it updates, what
+// language it speaks, and every way back out of it.
+//
+// A self-contained document has nowhere else to put any of this. PLATFORM §6
+// (signed update), §7 (the JSON round-trip), §8 (viewer-scoped language) and
+// §3 (identity, and the one sanctioned way to change it) all need a surface,
+// and one dialog behind the wordmark is the whole of it.
+//
+// TWO THINGS HERE ARE NOT COSMETIC and are the reason this is a module rather
+// than a slab of markup in main.ts:
+//
+// · REPLACING THE WORKBOOK CAN CRASH THE GRID. `Grid.sheet` throws when the
+// sheet id it holds is not in the document, and it reads it from a `doc`
+// listener registered before every other one — so a workbook arriving with
+// different sheet ids takes down the dirty flag and the chart with it.
+// `planReplace` below is the fix.
+// · THE DIALOG SITS INSIDE TWO DOCUMENT-LEVEL HANDLERS. main.ts routes bare
+// keystrokes into the grid and sniffs every paste for CSV; both would fire
+// while someone is typing an author name or pasting JSON in here.
+
+import './about.css'
+import {
+ APP_VERSION, applyUpdate, applyUpdateInPlace, canUpdateInPlace, checkForUpdates,
+ offlineEnabled, type ReleaseInfo,
+} from '../../kernel/src/update.ts'
+import {
+ canWriteInPlace, isEncryptionActive, openedFileName, saveFile, setEncryptionPassword,
+} from '../../kernel/src/save.ts'
+import {
+ addVersion, clearRecovery, clearVersions, listVersions,
+} from '../../kernel/src/autosave.ts'
+import { t, locale, localeChoices, setLocale } from './i18n.ts'
+import { docBudget, docBytes, parseDoc, rowCount, type DashDoc, type DocMeta } from './model.ts'
+import type { Store } from './store.ts'
+
+export interface AboutHooks {
+ store: Store
+ /** The sheet the grid is showing. Not derivable here — the grid owns it. */
+ showingSheet: () => string
+ /** Point the grid at another sheet (and repaint it). */
+ showSheet: (id: string) => void
+ /**
+ * The document changed outside `Store.commit`. Document properties are
+ * written straight onto `doc.meta` (see setMeta), so nothing emits `doc` for
+ * them and the dirty flag would never light — which means "close the tab and
+ * lose it" for a field the author just typed.
+ */
+ onDirty: () => void
+}
+
+// --- pure decisions, testable without a DOM ---------------------------------
+
+/** What a workbook swap has to do to survive the grid. */
+export interface ReplacePlan {
+ /** the sheet the grid must be showing afterwards */
+ show: string
+ /**
+ * Carry the sheet the grid is CURRENTLY showing through an intermediate
+ * document. `Store.replaceDoc` emits `doc` synchronously and the grid's
+ * listener — first in line, registered in its constructor — immediately
+ * reads `grid.sheet`, which THROWS when the incoming workbook has no sheet
+ * with that id. The throw escapes mid-emit, so every listener registered
+ * after the grid (the chart, the 3D panel, the dirty flag) never runs, and
+ * the workbook is left swapped with the app half-updated.
+ *
+ * There is no way to point the grid somewhere safe first: `setSheet` paints
+ * immediately, and the destination does not exist in the outgoing document.
+ * So the swap goes through a document containing BOTH — the new sheets plus
+ * the one being left — which is a valid workbook that neither the grid nor
+ * anything else can trip over, and is replaced again before it can be saved.
+ */
+ carry: boolean
+}
+
+/**
+ * Decide how to swap in `next` while the grid is showing `showing`.
+ * Null means the incoming document has no table sheet — nothing to show, so
+ * the swap is refused rather than performed into an empty screen.
+ */
+export function planReplace(next: DashDoc, showing: string): ReplacePlan | null {
+ const tables = next.sheets.filter((s) => s.kind === 'table')
+ if (!tables.length) return null
+ // Keeping the reader where they were matters more than it looks: the common
+ // case is an agent handing back the SAME workbook edited, which keeps every
+ // sheet id, and jumping to sheet one on every round trip would be a tell
+ // that something was rebuilt underneath.
+ if (tables.some((s) => s.id === showing)) return { show: showing, carry: false }
+ return { show: tables[0].id, carry: true }
+}
+
+const newDocId = (): string =>
+ typeof crypto !== 'undefined' && crypto.randomUUID
+ ? crypto.randomUUID()
+ : `doc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+
+/**
+ * A fork: same content, new identity (PLATFORM §3 — the ONLY sanctioned way a
+ * docId changes).
+ *
+ * The docId keys autosave recovery and the local version timeline, so a
+ * duplicate that kept it would inherit the original's history and overwrite
+ * its recovery snapshot — two files racing to restore each other's work.
+ */
+export function duplicateWorkbook(doc: DashDoc, docId: string = newDocId()): DashDoc {
+ const clone = JSON.parse(JSON.stringify(doc)) as DashDoc
+ clone.docId = docId
+ // The FILE is the capability (PLATFORM §5): a copy carrying `collab` joins
+ // the original's session and writes into it. dash mints no credentials yet,
+ // but the field is in the model and a hand-written or imported workbook can
+ // arrive with one — dropping it now costs nothing and cannot be retrofitted
+ // into copies already made.
+ delete clone.collab
+ // `template: true` means "every open starts a fresh document". A duplicate is
+ // a document, not a template.
+ delete clone.template
+ return clone
+}
+
+export interface WorkbookStats {
+ sheets: number
+ tables: number
+ rows: number
+ columns: number
+ bytes: number
+}
+
+export function workbookStats(doc: DashDoc): WorkbookStats {
+ let tables = 0
+ let columns = 0
+ for (const s of doc.sheets) {
+ if (s.kind !== 'table') continue
+ tables++
+ columns += s.columns.length
+ }
+ return { sheets: doc.sheets.length, tables, rows: rowCount(doc), columns, bytes: docBytes(doc) }
+}
+
+// --- theme: a VIEWER preference, never the document's --------------------------
+//
+// The same shape as story.ts's reduced-motion switch and the interface
+// language: this is ONE PERSON's preference about their own screen, so it
+// lives in localStorage and never enters the format (PLATFORM §8). Two people
+// opening the same workbook may sit in different themes exactly as they may
+// read it in different languages, and a file that carried a theme would be a
+// file that changed everyone's screen because of what one author preferred.
+//
+// `doc.theme` in model.ts is a DIFFERENT thing and must not be confused with
+// this: that is the document's own palette, it travels in the file, and it
+// colours the charts and the static preview. Nothing here reads or writes it.
+//
+// THE MECHANISM IS A TRANSIENT <style>, AND IT HAD TO BE. The obvious
+// implementation — `data-theme` on <html>, matched by `:root[data-theme=…]` in
+// styles.css — QUIETLY WRITES THE PREFERENCE INTO EVERY SAVED FILE.
+// `capturePristine()` (kernel/src/save.ts) clones the LIVE document at boot, so
+// anything sitting on the root element by then is in the shell every ⌘S
+// produces: measured, `bento.serialize()` came back with
+// `<html lang="en" data-theme="light">`, and that file would then force one
+// reader's choice on everyone who opened it. Exactly the bug this whole design
+// exists to avoid, arriving through the back door.
+//
+// A node carrying `data-bento-transient` is stripped from every serialized
+// shell (kernel save.ts TRANSIENT_SELECTOR) — the same mechanism the
+// compressed shell uses for its inflated stylesheet. So the override is a
+// <style> element carrying that attribute, and it declares `color-scheme`
+// rather than any colour: styles.css writes the palette as `light-dark()`
+// pairs, which resolve against the used `color-scheme`, so pinning that one
+// property flips every token at once. 'auto' REMOVES the element — the absence
+// of an override is what "follow the OS" means.
+//
+// `:root:root` for specificity (0,2,0), not `!important` and not a reliance on
+// document order: this <style> is appended at module load, while the app's own
+// stylesheet arrives from the deflate loader in the built shell and from Vite's
+// injector in dev, and those two orders are not the same.
+//
+// --bar-opacity rides along because `light-dark()` is colour-only; see the
+// note beside it in styles.css.
+
+export type ThemePref = 'auto' | 'light' | 'dark'
+
+const THEME_KEY = 'bento-theme'
+const THEME_STYLE_ID = 'dx-theme'
+
+/** The dark ground's data-bar opacity, kept in step with styles.css. */
+const BAR_OPACITY: Record<'light' | 'dark', string> = { light: '0.55', dark: '0.45' }
+
+export function readThemePref(): ThemePref {
+ try {
+ const v = localStorage.getItem(THEME_KEY)
+ return v === 'light' || v === 'dark' ? v : 'auto'
+ } catch { return 'auto' }
+}
+
+export function applyTheme(pref: ThemePref = readThemePref()): void {
+ const existing = document.getElementById(THEME_STYLE_ID)
+ if (pref === 'auto') { existing?.remove(); return }
+ const style = existing ?? document.createElement('style')
+ style.id = THEME_STYLE_ID
+ // Never let this reach a saved file (see above). Set before the node is in
+ // the document, so there is no window in which an unmarked style exists.
+ style.setAttribute('data-bento-transient', '')
+ style.textContent =
+ `:root:root{color-scheme:${pref};--bar-opacity:${BAR_OPACITY[pref]}}`
+ if (!existing) document.head.append(style)
+}
+
+export function setThemePref(pref: ThemePref): void {
+ try {
+ if (pref === 'auto') localStorage.removeItem(THEME_KEY)
+ else localStorage.setItem(THEME_KEY, pref)
+ } catch { /* private mode — the choice still holds for this session */ }
+ applyTheme(pref)
+}
+
+// AT MODULE LOAD, and deliberately not from `mountAbout`: main.ts imports this
+// module while it is booting and mounts About near the END of that boot, so
+// waiting for the hook would paint the whole workspace in the wrong theme
+// first. Here the rule lands before the app is built and while the splash is
+// still covering the screen — which is also what lets the splash itself follow
+// an explicit choice (index.html gives it `light-dark()` colours and nothing
+// else). Guarded because scripts/test-dash-about.ts imports this module in
+// Node, where there is no document to touch.
+if (typeof document !== 'undefined') applyTheme()
+
+// --- the local version timeline ---------------------------------------------
+
+/** Roughly one kept version per this much editing. Slides' number. */
+const VERSION_EVERY_MS = 120_000
+let lastVersionAt = 0
+
+/**
+ * Add this workbook to the local timeline the About dialog restores from,
+ * at most once per VERSION_EVERY_MS.
+ *
+ * NEVER for an encrypted workbook: a snapshot is the document as plain JSON,
+ * so writing one puts in IndexedDB exactly what the password exists to keep off
+ * the disk. The kernel does not guard this — every app has to, and dash already
+ * remembers it for `putRecovery`; this is the second store and the same rule.
+ */
+export async function rememberVersion(doc: DashDoc): Promise<void> {
+ if (isEncryptionActive()) return
+ if (Date.now() - lastVersionAt < VERSION_EVERY_MS) return
+ lastVersionAt = Date.now()
+ await addVersion(doc)
+}
+
+// --- the dialog ---------------------------------------------------------------
+
+/** Wire the ways in. The wordmark and the version chip are already in the top
+ * bar and neither does anything else, which is how slides does it too. */
+export function mountAbout(app: HTMLElement, hooks: AboutHooks): void {
+ for (const el of app.querySelectorAll<HTMLElement>('.dx-mark, .dx-ver')) {
+ el.dataset.about = '1'
+ el.tabIndex = 0
+ el.setAttribute('role', 'button')
+ el.title = t('About this workbook')
+ el.addEventListener('click', () => openAbout(hooks))
+ el.addEventListener('keydown', (e) => {
+ if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openAbout(hooks) }
+ })
+ }
+}
+
+export function openAbout(hooks: AboutHooks): void {
+ const { store } = hooks
+ document.querySelector('.dx-about-back')?.remove()
+
+ const back = document.createElement('div')
+ back.className = 'dx-about-back'
+ const card = document.createElement('div')
+ card.className = 'dx-about'
+ card.setAttribute('role', 'dialog')
+ card.setAttribute('aria-modal', 'true')
+ card.setAttribute('aria-label', t('About this workbook'))
+ const close = () => back.remove()
+
+ // --- small builders
+ const h = (label: string) => {
+ const n = document.createElement('h2')
+ n.textContent = label
+ return n
+ }
+ const note = (text: string) => {
+ const n = document.createElement('p')
+ n.className = 'dx-about-note'
+ n.textContent = text
+ return n
+ }
+ const value = (text: string) => {
+ const n = document.createElement('span')
+ n.className = 'dx-about-val'
+ n.textContent = text
+ return n
+ }
+ const row = (label: string, node: HTMLElement) => {
+ const r = document.createElement('div')
+ r.className = 'dx-about-row'
+ const s = document.createElement('span')
+ s.textContent = label
+ r.append(s, node)
+ return r
+ }
+ const button = (label: string, fn: () => void) => {
+ const b = document.createElement('button')
+ b.className = 'dx-btn'
+ b.textContent = label
+ b.addEventListener('click', fn)
+ return b
+ }
+ const actions = (...nodes: HTMLElement[]) => {
+ const wrap = document.createElement('div')
+ wrap.className = 'dx-about-actions'
+ wrap.append(...nodes)
+ return wrap
+ }
+
+ // --- what this is ---------------------------------------------------------
+ const stats = workbookStats(store.doc)
+ const lede = document.createElement('p')
+ lede.className = 'dx-about-lede'
+ lede.textContent = t(
+ 'bento/dash {version} · {sheets} sheet(s), {rows} row(s), {columns} column(s). The workbook, the grid and the formula engine are all in this one file.',
+ { version: APP_VERSION, sheets: stats.sheets, rows: stats.rows, columns: stats.columns },
+ )
+ card.append(h(t('This file')), lede)
+
+ const opened = openedFileName()
+ if (opened) card.append(row(t('File'), value(opened)))
+ card.append(row(t('Size'), value(t('{size} of a {budget} budget', {
+ size: bytes(stats.bytes), budget: bytes(docBudget(canWriteInPlace())),
+ }))))
+ // The docId is the identity every restore, recovery and future merge keys
+ // off, and the only place a reader can see it is here.
+ card.append(row(t('Document id'), value(store.doc.docId ?? t('(none — this workbook has no id)'))))
+ if (!canWriteInPlace()) {
+ card.append(note(t('This browser cannot write back to the file, so every save makes a new copy. Chrome and Edge on a computer can save in place.')))
+ }
+ if (store.readOnly) {
+ card.append(note(t('This workbook is open read-only, so nothing here writes to it.')))
+ }
+
+ // --- document properties --------------------------------------------------
+ //
+ // These go STRAIGHT onto doc.meta and are not undoable, which is a deliberate
+ // gap rather than an oversight: the patch union has no op that writes above
+ // the sheet except setTitle, and faking one (commit a setTitle with the
+ // current title) would put an entry in the undo stack whose undo visibly does
+ // nothing. Better a property that ⌘Z ignores than a ⌘Z that lies.
+ card.append(h(t('Document properties')))
+ const setMeta = (key: string, v: string) => {
+ if (store.readOnly) return
+ const meta: DocMeta = store.doc.meta ?? (store.doc.meta = {})
+ if (v) meta[key] = v
+ else delete meta[key]
+ // an empty object is noise in a file whose bytes are the budget
+ if (!Object.keys(meta).length) delete store.doc.meta
+ store.touch()
+ hooks.onDirty()
+ }
+ const META: Array<[string, string]> = [
+ ['author', t('Author')],
+ ['company', t('Company')],
+ ['subject', t('Subject')],
+ ['keywords', t('Keywords')],
+ ]
+ for (const [key, label] of META) {
+ const input = document.createElement('input')
+ input.className = 'dx-about-in'
+ input.value = String(store.doc.meta?.[key] ?? '')
+ input.disabled = store.readOnly
+ input.addEventListener('change', () => setMeta(key, input.value.trim()))
+ card.append(row(label, input))
+ }
+ // The title is edited in the top bar and only there — a second field for it
+ // here would have to be kept in step with that input, and the loser of that
+ // race silently overwrites the winner.
+ card.append(note(t('Properties travel in the file. The title is edited in the top bar.')))
+
+ // --- updates --------------------------------------------------------------
+ card.append(h(t('Updates')))
+ const upStatus = note(t('An update is verified before anything is rewritten: the release manifest is signed, and its signature is checked against a key inside this file.'))
+ card.append(upStatus)
+ const upActions = actions()
+ card.append(upActions)
+ upActions.append(button(t('Check for updates'), () => {
+ if (offlineEnabled()) {
+ upStatus.textContent = t('Offline mode is on, so nothing was contacted.')
+ return
+ }
+ upStatus.textContent = t('Checking…')
+ void checkForUpdates().then((res) => {
+ if (res.status === 'current') {
+ upStatus.textContent = t('You have the newest version ({v}).', { v: APP_VERSION })
+ return
+ }
+ if (res.status !== 'update') {
+ upStatus.textContent = t('Could not check for updates: {why}', { why: res.message })
+ return
+ }
+ const rel: ReleaseInfo = res.release
+ upStatus.textContent = t('Version {v} is available.', { v: rel.version })
+ upActions.append(button(t('Update this file'), () => {
+ upStatus.textContent = t('Downloading and verifying…')
+ // Two shapes, and the difference is worth stating because one of them
+ // leaves the file on disk untouched and the other does not.
+ const run = canUpdateInPlace()
+ ? applyUpdateInPlace(rel, store.doc).then((ok) => ok
+ ? t('Updated. A backup of the old version was downloaded beside it — reload to run {v}.', { v: rel.version })
+ : t('Cancelled — nothing was changed.'))
+ : applyUpdate(rel, store.doc).then(() =>
+ t('Downloaded. Open the new file — this one is unchanged.'))
+ void run
+ .then((msg) => { upStatus.textContent = msg })
+ .catch((err: unknown) => {
+ upStatus.textContent = t('The update was refused: {why}', {
+ why: err instanceof Error ? err.message : String(err),
+ })
+ })
+ }))
+ })
+ }))
+
+ // --- language -------------------------------------------------------------
+ card.append(h(t('Language')))
+ const choices = localeChoices()
+ const sel = document.createElement('select')
+ for (const c of choices) {
+ const o = document.createElement('option')
+ o.value = c.code
+ o.textContent = c.label
+ if (c.code === locale()) o.selected = true
+ sel.append(o)
+ }
+ sel.addEventListener('change', () => {
+ setLocale(sel.value)
+ close()
+ // NOT a repaint: main.ts builds the top bar, the grid chrome and the status
+ // bar from one template string with no way back in, so there is nothing to
+ // call. Menus, dialogs and findings built after this point are localized;
+ // the chrome catches up on the next open.
+ openAbout(hooks)
+ })
+ card.append(row(t('Interface language'), sel))
+ card.append(note(choices.length > 1
+ // the same rule as slides and spaces: language follows the READER
+ ? t('Language follows whoever opens the file. It is never written into the document, so a workbook reads in each reader’s own language. The rest of the interface catches up next time this file is opened.')
+ : t('Only English so far. Language follows whoever opens the file and is never written into the document.')))
+
+ // --- appearance -----------------------------------------------------------
+ // Beside Language, because it is the same KIND of setting: both follow the
+ // reader, neither is in the file. Applied live — the palette is custom
+ // properties, so the running app re-resolves without a rebuild, and unlike
+ // the language picker this one does not have to close and reopen the dialog.
+ card.append(h(t('Appearance')))
+ const themes: Array<[ThemePref, string]> = [
+ ['auto', t('Match my system')],
+ ['light', t('Light')],
+ ['dark', t('Dark')],
+ ]
+ const themeSel = document.createElement('select')
+ const current = readThemePref()
+ for (const [v, label] of themes) {
+ const o = document.createElement('option')
+ o.value = v
+ o.textContent = label
+ if (v === current) o.selected = true
+ themeSel.append(o)
+ }
+ themeSel.addEventListener('change', () => setThemePref(themeSel.value as ThemePref))
+ card.append(row(t('Theme'), themeSel))
+ card.append(note(t('The theme follows whoever opens the file and is kept in this browser only — it is never written into the workbook, so one file can be light on your screen and dark on someone else’s.')))
+
+ // --- password -------------------------------------------------------------
+ card.append(h(t('Password')))
+ const pwNote = note(isEncryptionActive()
+ ? t('This workbook is encrypted. Every save stays encrypted.')
+ : t('A password encrypts the workbook inside the file. There is no recovery — lose it and the data is gone.'))
+ card.append(pwNote)
+ card.append(actions(button(
+ isEncryptionActive() ? t('Remove password…') : t('Set a password…'),
+ () => {
+ if (isEncryptionActive()) {
+ if (!confirm(t('Remove the password? The next save writes the workbook in the clear.'))) return
+ setEncryptionPassword(null)
+ pwNote.textContent = t('Password removed. Save to write the workbook unencrypted.')
+ return
+ }
+ const pw = prompt(t('Choose a password. There is no way to recover it.'))
+ if (!pw) return
+ setEncryptionPassword(pw)
+ // Snapshots written BEFORE this moment are plaintext copies of the very
+ // thing now being encrypted, sitting in IndexedDB. Both stores: the
+ // single recovery snapshot and the whole version timeline.
+ void clearRecovery(store.doc.docId)
+ void clearVersions(store.doc.docId)
+ pwNote.textContent = t('Password set. Save to write the workbook encrypted, and keep the password somewhere safe.')
+ },
+ )))
+
+ // --- version history ------------------------------------------------------
+ card.append(h(t('Version history')))
+ const versions = document.createElement('div')
+ versions.className = 'dx-about-vers'
+ card.append(versions)
+ card.append(note(t('Versions are kept in this browser only — never in the file, never online. Restoring replaces the whole workbook and cannot be undone.')))
+ void listVersions(store.doc.docId).then((list) => {
+ if (!list.length) {
+ versions.replaceChildren(note(t('No versions kept yet — they accumulate as you edit.')))
+ return
+ }
+ versions.replaceChildren(...list.map((snap, i) => {
+ const b = document.createElement('button')
+ b.className = 'dx-about-ver'
+ b.disabled = store.readOnly
+ const when = document.createElement('span')
+ when.textContent = new Date(snap.at).toLocaleString([], {
+ month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit',
+ }) + (i === 0 ? ` · ${t('most recent')}` : '')
+ const doIt = document.createElement('span')
+ doIt.textContent = t('Restore')
+ b.append(when, doIt)
+ b.addEventListener('click', () => {
+ // A snapshot is this app's own JSON, but it is still parsed rather than
+ // trusted: it may predate an id repair, or a sheet this build refuses.
+ const res = parseDoc(snap.json)
+ if (!res.ok) { alert(t('That version could not be read.')); return }
+ if (!confirm(t('Restore this version? The current workbook is replaced and this cannot be undone.'))) return
+ if (replaceWorkbook(hooks, res.doc)) close()
+ else alert(t('That version has no table sheet to show.'))
+ })
+ return b
+ }))
+ })
+
+ // --- ways out -------------------------------------------------------------
+ card.append(h(t('Take it elsewhere')))
+ const outNote = note(t('The whole workbook is plain JSON inside this file — copy it into any tool or AI, and bring the edited JSON back.'))
+ const replaceBtn = button(t('Replace from JSON…'), () => openPaste())
+ const duplicateBtn = button(t('Duplicate as new workbook…'), () => {
+ // Identity fork, and this window BECOMES the copy: the save below points
+ // ⌘S at the new file, so leaving the old document loaded would mean the
+ // next save wrote the ORIGINAL workbook into it.
+ const clone = duplicateWorkbook(store.doc)
+ if (!replaceWorkbook(hooks, clone)) return
+ close()
+ void saveFile(clone, true)
+ })
+ // Both of these load a document into the running app, which is the one thing
+ // a frozen workbook must not do — see replaceWorkbook. Disabled rather than
+ // silently refused; the read-only note at the top of the dialog says why.
+ replaceBtn.disabled = store.readOnly
+ duplicateBtn.disabled = store.readOnly
+ card.append(actions(
+ button(t('Copy document JSON'), () => {
+ void navigator.clipboard?.writeText(JSON.stringify(store.doc, null, 2))
+ .then(() => { outNote.textContent = t('Copied — {size} of JSON.', { size: bytes(stats.bytes) }) })
+ .catch(() => { outNote.textContent = t('This browser refused clipboard access.') })
+ }),
+ replaceBtn,
+ duplicateBtn,
+ button(t('Save a copy…'), () => { void saveFile(store.doc, true) }),
+ ))
+ card.append(outNote)
+
+ /** The paste panel. A textarea, not `prompt()`: this is a whole workbook. */
+ function openPaste(): void {
+ if (store.readOnly) { outNote.textContent = t('This workbook is open read-only.'); return }
+ if (card.querySelector('.dx-about-paste')) return
+ const ta = document.createElement('textarea')
+ ta.className = 'dx-about-paste'
+ ta.spellcheck = false
+ ta.placeholder = t('Paste bento/dash document JSON here')
+ const go = button(t('Replace workbook'), () => {
+ if (!ta.value.trim()) { ta.focus(); return }
+ const res = parseDoc(ta.value)
+ if (!res.ok) {
+ outNote.textContent = t('That is not a bento/dash workbook: {why}',
+ { why: 'detail' in res ? res.detail : res.err })
+ return
+ }
+ // Undo does NOT reach across this. Store.replaceDoc empties both stacks,
+ // so unlike slides there is no ⌘Z back — say so before, not after.
+ if (!confirm(t('Replace this workbook with the pasted JSON? This cannot be undone.'))) return
+ if (!replaceWorkbook(hooks, res.doc)) {
+ outNote.textContent = t('That workbook has no table sheet to show.')
+ return
+ }
+ close()
+ })
+ const bar = actions(go, button(t('Cancel'), () => { ta.remove(); bar.remove() }))
+ // BEFORE the Close button, not appended to the card: `append` puts it after
+ // Close, which on a dialog this tall means the panel opens below the fold
+ // and the click reads as "nothing happened".
+ card.insertBefore(ta, closeBtn)
+ card.insertBefore(bar, closeBtn)
+ ta.focus()
+ ta.scrollIntoView({ block: 'nearest' })
+ }
+
+ const closeBtn = button(t('Close'), close)
+ closeBtn.classList.add('dx-about-close')
+ card.append(closeBtn)
+
+ // main.ts owns two DOCUMENT-level handlers that this dialog sits inside:
+ // · a keydown that routes any bare printable key into the selected cell —
+ // and its guard is `INPUT || isContentEditable`, so a TEXTAREA is not
+ // covered: typing JSON in here would have typed into the grid as well.
+ // · a paste sniffer that treats any clipboard text with a comma or a tab as
+ // a CSV import, and calls preventDefault — so pasting a workbook, or an
+ // author name with a comma in it, imported a junk sheet instead.
+ // Both are stopped at the backdrop, which contains everything in the dialog.
+ // ⌘S is stopped with them, deliberately: saving from behind a modal that may
+ // be mid-edit is not a gesture worth preserving.
+ back.addEventListener('keydown', (e) => {
+ if (e.key === 'Escape') close()
+ e.stopPropagation()
+ })
+ back.addEventListener('paste', (e) => e.stopPropagation())
+ back.addEventListener('mousedown', (e) => { if (e.target === back) close() })
+
+ back.append(card)
+ document.body.append(back)
+ card.querySelector('button')?.focus()
+}
+
+/**
+ * Swap the whole workbook in, keeping the grid on its feet. False when the
+ * incoming document has nothing the grid can show.
+ */
+function replaceWorkbook(hooks: AboutHooks, next: DashDoc): boolean {
+ const { store } = hooks
+ // replaceDoc does NOT check store.readOnly — it is the load/restore path, not
+ // an edit path — so a workbook frozen by an unknown policy or a future format
+ // version has to be defended here or About becomes the way to write to it.
+ if (store.readOnly) return false
+ const showing = hooks.showingSheet()
+ const plan = planReplace(next, showing)
+ if (!plan) return false
+ if (plan.carry) {
+ const carried = store.doc.sheets.find((s) => s.id === showing)
+ // Never saved and never autosaved: the second replaceDoc lands in the same
+ // turn, and the recovery snapshot is 2.5s behind on a timer.
+ store.replaceDoc(carried ? { ...next, sheets: [...next.sheets, carried] } : next)
+ hooks.showSheet(plan.show)
+ }
+ store.replaceDoc(next)
+ return true
+}
+
+const bytes = (n: number): string =>
+ n >= 1024 * 1024 ? `${(n / 1048576).toFixed(1)} MB` : `${Math.max(1, Math.round(n / 1024))} KB`
diff --git a/dash/src/cellformula.ts b/dash/src/cellformula.ts
new file mode 100644
index 00000000..fbbccf45
--- /dev/null
+++ b/dash/src/cellformula.ts
@@ -0,0 +1,302 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Per-cell formulas: `=B4*1.2` in one cell, evaluated in dependency order.
+//
+// WHY THIS EXISTS WHEN COLUMN FORMULAS ALREADY DO. A column expression is the
+// better tool and stays the default — it names columns by identity, so it
+// survives every structural edit (formula.ts's header makes that case, and a1.ts
+// explains the price of admitting positions back). But a spreadsheet that
+// cannot put a number in one cell is not a spreadsheet. A total under a block,
+// a fudge factor, an invoice line: these are single cells, and the person
+// typing `=B4*1.2` is not going to be argued out of it.
+//
+// THE WHOLE MODULE IS A BRIDGE, and deliberately owns no engine of its own:
+//
+// a1.ts decides what is a reference and where it points
+// formula.ts parses and evaluates the expression, and owns the error values
+// here binds one to the other, and orders the cells
+//
+// The binding trick is that formula.ts's `ref` node resolves a NAME against
+// `ctx.cols`. So a reference does not need parser support at all: rewrite `B4`
+// to a generated name, bind that name to a one-element vector holding B4's
+// value, and evaluate over `n = 1`. A RANGE binds the same way to a longer
+// vector, which is why `SUM(A1:A5)` works without `:` ever becoming an operator
+// — `SUM` already aggregates a vector.
+//
+// Generated names are `_a1_<i>`, which formula.ts's lexer reads as one
+// identifier and a1.ts's scanner will not mistake for a reference on a later
+// pass (it starts with `_`, and a reference must start with a letter). A column
+// genuinely called `_a1_0` would collide; it also cannot be typed as a column
+// name in the UI, and `[_a1_0]` still reaches it.
+//
+// ORDER IS THE CORRECTNESS PROBLEM, not evaluation. `=B1+1` in A1 and `=A1*2`
+// in C1 have to compute in that order or C1 reads a stale value — and unlike a
+// stale value in a cache, this one is written into the document and looks
+// authoritative. Kahn again (formula.ts does it over columns; this does it over
+// cells), and anything still in the graph when the queue drains is in a cycle
+// and gets `#CYCLE!`. Never a plausible number: a cycle resolved by "whatever we
+// had last time" is the failure mode where a model quietly reports a different
+// answer on every recalculation and nobody can tell which one was right.
+
+import { evaluate, isErr, FormulaError, type Cell, type Vec } from './formula.ts'
+import {
+ expandRange, formatRef, mapRefs, rewriteFormulaRefs, shiftRefsForInsert,
+ REF_ERR, type CellRef,
+} from './a1.ts'
+
+/**
+ * The sheet as a plain grid of positions, so this module never has to know
+ * about columns, rids, dictionary encoding or overrides. Whoever calls it owns
+ * that translation — and the rig can hand over a literal array.
+ */
+export interface CellSource {
+ rows: number
+ cols: number
+ /** The formula source at a position (with or without its leading `=`), if it has one. */
+ formulaAt(row: number, col: number): string | undefined
+ /** The STORED value at a position — never a formula's result. */
+ valueAt(row: number, col: number): Cell
+}
+
+/** `col,row`, both 0-based — the key a computed-cell map is keyed by. */
+export const cellKey = (row: number, col: number): string => `${col},${row}`
+
+export interface CellRecalc {
+ /** position key → computed value, for every cell that holds a formula */
+ values: Map<string, Cell>
+ /** the cells that could not be ordered, reported rather than guessed at */
+ cycles: string[]
+ /** evaluation order, for tests and for explaining a result to a reader */
+ order: string[]
+}
+
+/** Is this cell text a formula? The one place the `=` convention is decided. */
+export const isFormula = (v: unknown): v is string =>
+ typeof v === 'string' && v.length > 1 && v.startsWith('=')
+
+/** The expression inside a formula, without the `=`. */
+export const formulaBody = (src: string): string =>
+ src.startsWith('=') ? src.slice(1) : src
+
+// --- dependencies -----------------------------------------------------------
+
+interface Dep {
+ /** the generated name this reference was bound to */
+ name: string
+ /** the positions it covers — one for a reference, many for a range */
+ cells: CellRef[]
+ /** the range was too large to expand, so the whole formula is an error */
+ tooBig?: boolean
+ /** the source already carried a `#REF!` from an earlier structural edit */
+ dead?: boolean
+}
+
+/**
+ * Rewrite a formula's references to bound names, and report what it read.
+ *
+ * A `#REF!` already sitting in the source is carried through as `dead` rather
+ * than parsed: a1.ts minted it because the cell it named was deleted, and the
+ * only honest result is the same error again. Letting it reach formula.ts would
+ * turn a precise "that cell is gone" into `#VALUE! could not parse`.
+ */
+export function bindRefs(src: string): { expr: string; deps: Dep[] } {
+ const deps: Dep[] = []
+ const expr = mapRefs(src, (u) => {
+ const name = `_a1_${deps.length}`
+ if (!u.to) {
+ deps.push({ name, cells: [u.from] })
+ return name
+ }
+ const cells = expandRange({ from: u.from, to: u.to })
+ deps.push(cells === null
+ ? { name, cells: [], tooBig: true }
+ : { name, cells })
+ return name
+ })
+ // The scanner leaves `#REF!` alone (it is not a reference), so look for it in
+ // the ORIGINAL text — the rewrite may have introduced names around it.
+ return { expr, deps: src.includes(REF_ERR) ? [{ name: '', cells: [], dead: true }] : deps }
+}
+
+/** Every position a formula reads, for the dependency graph. */
+export const cellDeps = (src: string): CellRef[] =>
+ bindRefs(src).deps.flatMap((d) => d.cells)
+
+// --- evaluation -------------------------------------------------------------
+
+const ERR_REF = (): FormulaError => new FormulaError(REF_ERR, 'the referenced cell was deleted')
+const ERR_BIG = (): FormulaError =>
+ new FormulaError('#VALUE!', 'the range covers too many cells to evaluate')
+const ERR_CYCLE = (): FormulaError => new FormulaError('#CYCLE!')
+
+/**
+ * Evaluate one cell's formula, reading other cells through `read`.
+ *
+ * `read` returns what a reference SEES — a computed value if that cell is
+ * itself a formula, a stored value otherwise — which is why ordering happens
+ * outside this function and not inside it.
+ *
+ * A reference off the edge of the sheet is EMPTY, not an error. `A50` on a
+ * ten-row sheet is a blank cell in every spreadsheet ever written; `#REF!` means
+ * something specific and narrower — the cell you named was deleted — and
+ * spending it on "you pointed past the end" would make the one error that
+ * carries real information indistinguishable from a typo.
+ */
+export function evalCell(
+ src: string,
+ read: (r: CellRef) => Cell,
+ opts: { now?: string; cols?: Map<string, Vec> } = {},
+): Cell {
+ const { expr, deps } = bindRefs(formulaBody(src))
+ if (deps.some((d) => d.dead)) return ERR_REF()
+ if (deps.some((d) => d.tooBig)) return ERR_BIG()
+
+ // Column names stay visible, so a cell formula can also say `SUM(amount)`.
+ // The generated names are added on top and cannot collide with them.
+ const cols = new Map<string, Vec>(opts.cols ?? [])
+ for (const d of deps) cols.set(d.name, d.cells.map(read))
+
+ const out = evaluate(expr, { cols, n: 1, now: opts.now })
+ return out[0] ?? null
+}
+
+// --- ordering ---------------------------------------------------------------
+
+/**
+ * Compute every formula cell in the grid, in dependency order.
+ *
+ * Kahn's algorithm over CELLS. The edges run dependency → dependent, so the
+ * queue holds cells whose inputs are all settled; anything left when it drains
+ * is in a cycle. A cell that reads a non-formula position has no edge at all,
+ * because a stored value is already settled.
+ */
+export function recalcCells(src: CellSource, now?: string, cols?: Map<string, Vec>): CellRecalc {
+ const formulas = new Map<string, { row: number; col: number; src: string }>()
+ for (let r = 0; r < src.rows; r++) {
+ for (let c = 0; c < src.cols; c++) {
+ const f = src.formulaAt(r, c)
+ if (f !== undefined) formulas.set(cellKey(r, c), { row: r, col: c, src: f })
+ }
+ }
+
+ // edges, counted only between cells that BOTH hold formulas
+ const needs = new Map<string, Set<string>>()
+ const feeds = new Map<string, Set<string>>()
+ for (const [k, f] of formulas) {
+ const n = new Set<string>()
+ for (const ref of cellDeps(formulaBody(f.src))) {
+ const dk = cellKey(ref.row, ref.col)
+ if (dk === k || !formulas.has(dk)) {
+ // A self-reference is a cycle of one. It cannot be an edge (Kahn would
+ // never dequeue it and it would look like an unrelated cycle), so it is
+ // recorded as a dependency on itself and caught by the drain below.
+ if (dk === k) n.add(k)
+ continue
+ }
+ n.add(dk)
+ if (!feeds.has(dk)) feeds.set(dk, new Set())
+ feeds.get(dk)!.add(k)
+ }
+ needs.set(k, n)
+ }
+
+ const values = new Map<string, Cell>()
+ const order: string[] = []
+ const left = new Map<string, number>()
+ const queue: string[] = []
+ for (const [k, n] of needs) {
+ left.set(k, n.size)
+ if (n.size === 0) queue.push(k)
+ }
+
+ /** What a reference sees: a computed value if we have one, else what is stored. */
+ const read = (r: CellRef): Cell => {
+ if (r.row < 0 || r.col < 0 || r.row >= src.rows || r.col >= src.cols) return null
+ const k = cellKey(r.row, r.col)
+ if (values.has(k)) return values.get(k)!
+ // BACKSTOP, and currently unreachable: every formula dependency is an edge,
+ // so Kahn settles it before this cell is dequeued, and a formula inside a
+ // cycle is never dequeued at all. It stays because the failure it prevents
+ // is silent — a future change to the edge rules would otherwise let a
+ // reference read a stored value that a formula was about to overwrite, and
+ // the result would be a plausible number nobody could tell was stale.
+ // Deliberately not covered by the rig: a check that cannot fail is worse
+ // than no check, and this line's whole job is to be redundant.
+ if (formulas.has(k)) return ERR_CYCLE()
+ return src.valueAt(r.row, r.col)
+ }
+
+ while (queue.length) {
+ const k = queue.shift()!
+ const f = formulas.get(k)!
+ order.push(k)
+ values.set(k, evalCell(f.src, read, { now, cols }))
+ for (const d of feeds.get(k) ?? []) {
+ const rem = (left.get(d) ?? 1) - 1
+ left.set(d, rem)
+ if (rem === 0) queue.push(d)
+ }
+ }
+
+ const cycles: string[] = []
+ for (const k of formulas.keys()) {
+ if (!values.has(k)) { cycles.push(k); values.set(k, ERR_CYCLE()) }
+ }
+ return { values, cycles, order }
+}
+
+/** A computed value as the grid should show it. Errors print as their code. */
+export const displayCell = (v: Cell): string =>
+ v === null || v === undefined ? '' : isErr(v) ? String(v) : String(v)
+
+export const _internals = { formatRef, ERR_REF, ERR_BIG, ERR_CYCLE }
+
+// --- keeping references pointing at the right cells --------------------------
+//
+// The two halves of the problem a1.ts's header sets out, wired to the two
+// events that cause them. They are DIFFERENT rules and the difference is the
+// thing people get wrong:
+//
+// COPY/FILL the formula moved, the cells did not. References move WITH it,
+// except the `$`-pinned ones. `=A1*2` copied a row down is
+// `=A2*2` — that is the whole point of copying a formula.
+// INSERT/DEL the CELLS moved, the formula did not. Every reference moves,
+// `$` included, because the cell it names physically moved. A
+// reference INTO a deleted row becomes `#REF!`, never the row
+// that slid up into the gap — a reference silently re-pointed at
+// someone else's data is a wrong number wearing a right one's
+// clothes.
+
+/**
+ * A formula moved by (dRow, dCol) — copy, paste and fill.
+ *
+ * Returns the source unchanged when it holds no references, so a workbook of
+ * constants pays nothing.
+ */
+export function translateCellFormula(src: string, dRow: number, dCol: number): string {
+ if (!isFormula(src) || (dRow === 0 && dCol === 0)) return src
+ return `=${rewriteFormulaRefs(formulaBody(src), dRow, dCol)}`
+}
+
+/**
+ * Every cell formula in a sheet, rewritten because `count` rows or columns were
+ * inserted at 0-based index `at` (or removed, when `count` is negative).
+ *
+ * Returns the keys whose source CHANGED, and their new text. Rewriting the
+ * unchanged ones too would work and would also put the whole sheet's formulas
+ * into one undo step's inverse for an edit that touched three of them.
+ */
+export function shiftSheetFormulas(
+ formulas: Iterable<[string, string]>,
+ axis: 'row' | 'col',
+ at: number,
+ count: number,
+): Array<[string, string]> {
+ const out: Array<[string, string]> = []
+ for (const [key, src] of formulas) {
+ if (!isFormula(src)) continue
+ const next = `=${shiftRefsForInsert(formulaBody(src), axis, at, count)}`
+ if (next !== src) out.push([key, next])
+ }
+ return out
+}
diff --git a/dash/src/condfmt.ts b/dash/src/condfmt.ts
new file mode 100644
index 00000000..986e699a
--- /dev/null
+++ b/dash/src/condfmt.ts
@@ -0,0 +1,605 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Conditional formatting — rules in, styles out.
+//
+// PURE FUNCTIONS, NO DOM. A rule evaluates to a style and the grid applies it.
+// That split is what makes the feature testable in node, and it is also what
+// makes it cheap: the grid is windowed (grid.ts), so it asks for the styles of
+// the ~40 rows it is about to paint, not of 100,000 it is not.
+//
+// RULES COMPOSE, THEY DO NOT SHADOW. Excel's rule list is first-match-wins with
+// a "Stop If True" checkbox, and the result is the single most common complaint
+// about the feature: a colour scale and a "highlight negatives in red" rule are
+// both correct, both wanted, and one of them silently does nothing. Here the
+// LAST rule to set a PROPERTY wins that property, so a scale under a cell-value
+// rule keeps its background and takes the later rule's text colour. Composing
+// wrongly is visible; discarding silently is not.
+//
+// COLOURS BLEND IN LINEAR LIGHT, not by averaging the encoded bytes. sRGB is
+// gamma-encoded (~2.2), so the byte 128 is NOT half the light of 255 — it is
+// about 21.6% of it. Averaging bytes therefore loses about half the luminance
+// at the midpoint, which is why so many three-colour heatmaps have a dark muddy
+// band through the middle. The working, for red→green at t = 0.5:
+//
+// naive (255+0)/2 = 128 → #808000, a dark olive-brown
+// linear lin(255)=1, lin(0)=0
+// mid = 0.5 in LIGHT
+// enc(0.5) = 1.055·0.5^(1/2.4) − 0.055 = 0.7354 → 188
+// → #bcbc00, the yellow a person expects
+//
+// Alpha is NOT gamma-encoded — it is a coverage fraction — so it interpolates
+// linearly while the colour channels do not. Getting that backwards makes
+// translucent scales wrong in the opposite direction.
+//
+// DATA BARS SHARE ONE ZERO AXIS. This is the part naive implementations get
+// wrong: they map each value onto (v − min)/(max − min) from the LEFT EDGE, so
+// the most negative row gets a bar of length zero (invisible — the row that
+// most needs to be seen) and −50 beside +100 draws two-thirds as long as it
+// should. Zero belongs at |min|/(|min| + max) of the width, with one scale for
+// both sides and negatives running left from it. `axis` rides on every entry
+// because the renderer cannot recompute it from a single row.
+//
+// NO SPREAD MEANS NO RANKING. When every value is identical the fraction is
+// 0/0. Every cell is simultaneously the minimum and the maximum, so the only
+// non-arbitrary answer is the middle of the ramp — it claims neither "lowest"
+// nor "highest". What it must never be is NaN, which reaches CSS as
+// `#NaNNaNNaN` and paints nothing, on the day the data happened to be flat.
+//
+// A CELL WITH NO NUMBER GETS NO COLOUR. Text in a numeric column has no
+// position on a scale; giving it the min colour reads as "this is the lowest
+// value", which is a claim about data that is not there.
+//
+// Never `Math.min(...values)`: the spread is one argument per row and blows the
+// stack somewhere past ~125k of them, which is inside the row target the format
+// was sized for. Every reduction here is a loop.
+
+import { evaluate, isErr, type Cell, type EvalCtx, type Vec } from './formula.ts'
+
+// --- styles ------------------------------------------------------------------
+
+/**
+ * What a rule can say about one cell. Every property is optional because
+ * composition merges by PROPERTY: an absent one means "this rule has no opinion
+ * here", which is not the same as "clear it".
+ */
+export interface CellStyle {
+ color?: string
+ bg?: string
+ bold?: boolean
+ italic?: boolean
+ bar?: BarStyle
+}
+
+export interface BarStyle {
+ /** 0–100, as a fraction of the WHOLE cell width, measured FROM `axis`. */
+ pct: number
+ color: string
+ /** draw leftwards from the axis */
+ negative?: boolean
+ /**
+ * Where zero sits, 0–100 from the left edge. Carried per cell rather than
+ * returned once because the grid paints one row at a time and a bar drawn
+ * without its axis is drawn in the wrong place.
+ */
+ axis?: number
+}
+
+// --- rules -------------------------------------------------------------------
+
+export type CompareOp =
+ | '>' | '>=' | '<' | '<=' | '=' | '<>'
+ | 'between' | 'contains' | 'startsWith' | 'endsWith' | 'blank' | 'notBlank'
+
+export interface CellValueRule {
+ kind: 'cellValue'
+ op: CompareOp
+ value?: unknown
+ /** the upper bound of `between`; ignored by every other op */
+ to?: unknown
+ style: CellStyle
+}
+
+/** `colors` is [low, high] or [low, mid, high]. */
+export type ScaleColors = [string, string, string?]
+
+export interface ColorScaleRule {
+ kind: 'colorScale'
+ /** Absent means "from the data". Present pins the domain, so two columns can
+ * be coloured on the SAME scale and compared — which is the whole reason a
+ * fixed domain exists. */
+ min?: number
+ mid?: number
+ max?: number
+ colors: ScaleColors
+}
+
+export interface DataBarRule {
+ kind: 'dataBar'
+ color: string
+ /** Absent = negatives use `color`. A different colour is the honest default
+ * for a signed column, but it is the author's call, not ours. */
+ negativeColor?: string
+ min?: number
+ max?: number
+}
+
+export interface TopNRule {
+ kind: 'topN'
+ n: number
+ bottom?: boolean
+ style: CellStyle
+}
+
+export interface DuplicatesRule { kind: 'duplicates'; style: CellStyle }
+
+/**
+ * An arbitrary expression, evaluated by the formula engine with the column
+ * bound to `value` — `value > AVERAGE(value)` is one vectorised pass, not one
+ * parse per row.
+ */
+export interface FormulaRule { kind: 'formula'; expr: string; style: CellStyle }
+
+export type Rule =
+ | CellValueRule | ColorScaleRule | DataBarRule
+ | TopNRule | DuplicatesRule | FormulaRule
+
+// --- numbers -----------------------------------------------------------------
+
+/**
+ * The numeric position of a cell, or null if it has none.
+ *
+ * Deliberately STRICTER than formula.ts's `num`, which strips `%`, `,` and
+ * currency glyphs so that arithmetic over a scruffy import still works. Ranking
+ * is a different job: `num` puts "50%" at 50, which on a scale beside 0.5 is a
+ * category error — the two would sit at opposite ends of a colour ramp while
+ * meaning the same thing. So only a real number, or text that is unambiguously
+ * one, gets a position. Booleans do not: a tick column has no magnitude.
+ */
+function numOf(v: unknown): number | null {
+ if (typeof v === 'number') return Number.isFinite(v) ? v : null
+ if (typeof v === 'string') {
+ const t = v.trim()
+ if (t === '') return null
+ const n = Number(t)
+ return Number.isFinite(n) ? n : null
+ }
+ return null
+}
+
+const clamp = (x: number, lo: number, hi: number): number => (x < lo ? lo : x > hi ? hi : x)
+
+/** min/max in one loop. Spreading into Math.min overflows the stack at 100k. */
+function extent(values: unknown[]): { lo: number; hi: number; any: boolean } {
+ let lo = Infinity
+ let hi = -Infinity
+ let any = false
+ for (const v of values) {
+ const n = numOf(v)
+ if (n === null) continue
+ any = true
+ if (n < lo) lo = n
+ if (n > hi) hi = n
+ }
+ return { lo, hi, any }
+}
+
+// --- colour ------------------------------------------------------------------
+
+interface RGBA { r: number; g: number; b: number; a: number }
+
+/**
+ * Hex (3/4/6/8) and rgb()/rgba() with numeric channels. Named colours and
+ * `var(--accent)` return null ON PURPOSE: resolving them needs a DOM, this file
+ * has none, and inventing black would be a wrong colour rather than a missing
+ * one. `mixColors` degrades to the nearest stop instead — still a colour the
+ * author actually chose.
+ */
+function parseColor(s: string): RGBA | null {
+ const t = s.trim()
+ const hex = /^#([0-9a-f]+)$/i.exec(t)
+ if (hex) {
+ const h = hex[1]
+ if (h.length === 3 || h.length === 4) {
+ const ch = [...h].map((c) => parseInt(c + c, 16))
+ return { r: ch[0], g: ch[1], b: ch[2], a: h.length === 4 ? ch[3] / 255 : 1 }
+ }
+ if (h.length === 6 || h.length === 8) {
+ return {
+ r: parseInt(h.slice(0, 2), 16),
+ g: parseInt(h.slice(2, 4), 16),
+ b: parseInt(h.slice(4, 6), 16),
+ a: h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1,
+ }
+ }
+ return null
+ }
+ const fn = /^rgba?\(([^)]+)\)$/i.exec(t)
+ if (!fn) return null
+ const parts = fn[1].split(/[\s,/]+/).filter(Boolean).map(Number)
+ if (parts.length < 3 || !parts.slice(0, 3).every((x) => Number.isFinite(x))) return null
+ const a = parts.length > 3 && Number.isFinite(parts[3]) ? parts[3] : 1
+ return { r: parts[0], g: parts[1], b: parts[2], a }
+}
+
+const hex2 = (x: number): string =>
+ Math.round(clamp(x, 0, 255)).toString(16).padStart(2, '0')
+
+/** `#rrggbb` while opaque — shortest, and what a colour input round-trips. */
+function formatColor(c: RGBA): string {
+ if (c.a >= 1) return `#${hex2(c.r)}${hex2(c.g)}${hex2(c.b)}`
+ const a = Math.round(clamp(c.a, 0, 1) * 1000) / 1000
+ return `rgba(${Math.round(clamp(c.r, 0, 255))}, ${Math.round(clamp(c.g, 0, 255))}, ${Math.round(clamp(c.b, 0, 255))}, ${a})`
+}
+
+// The sRGB transfer function, both directions. The 0.04045/0.0031308 elbow is
+// the linear segment near black — dropping it (a plain 2.2 power) is close but
+// visibly wrong in the darkest few percent, which is exactly where a "low"
+// colour usually lives.
+const toLinear = (c: number): number => {
+ const x = clamp(c, 0, 255) / 255
+ return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4
+}
+const toSrgb = (x: number): number => {
+ const c = x <= 0.0031308 ? x * 12.92 : 1.055 * x ** (1 / 2.4) - 0.055
+ return Math.round(clamp(c, 0, 1) * 255)
+}
+
+/**
+ * Blend two colours in linear light. `t` outside [0,1] clamps, and t exactly at
+ * an endpoint returns that endpoint EXACTLY — a stop must never drift by a
+ * rounding unit as it passes through the encode/decode round trip, or the
+ * author's chosen midpoint colour is not the colour anybody sees at the middle.
+ */
+export function mixColors(a: string, b: string, t: number): string {
+ const ca = parseColor(a)
+ const cb = parseColor(b)
+ // Unparseable: snap, do not invent. See parseColor.
+ if (!ca || !cb) return t < 0.5 ? a : b
+ if (t <= 0) return formatColor(ca)
+ if (t >= 1) return formatColor(cb)
+ const ch = (x: number, y: number): number => toSrgb(toLinear(x) + (toLinear(y) - toLinear(x)) * t)
+ return formatColor({
+ r: ch(ca.r, cb.r),
+ g: ch(ca.g, cb.g),
+ b: ch(ca.b, cb.b),
+ // coverage, not light: linear in the encoded value
+ a: ca.a + (cb.a - ca.a) * t,
+ })
+}
+
+export interface ScaleOpts { min?: number; mid?: number; max?: number }
+
+/**
+ * One colour per value. Non-numeric cells get `''` — no colour, not the low
+ * colour.
+ *
+ * Two stops ramp low→high. Three ramp low→mid→high with `mid` at the VALUE the
+ * author names (default: halfway between the bounds), so a diverging scale can
+ * be pinned to zero on a column that runs −20…+300 and the neutral colour lands
+ * on zero rather than on 140.
+ */
+export function colorScale(values: unknown[], colors: ScaleColors, opts: ScaleOpts = {}): string[] {
+ // A rule is DOCUMENT data, so `colors` is whatever the file said it was.
+ // Two stops are the minimum a ramp can have; below that there is nothing to
+ // interpolate and no colour is the honest answer. Nothing here may throw —
+ // this runs inside the grid's paint path, and an exception there blanks the
+ // whole grid over one bad rule.
+ const list: unknown[] = Array.isArray(colors) ? colors : []
+ if (typeof list[0] !== 'string' || typeof list[1] !== 'string') return values.map(() => '')
+
+ const { lo: dataLo, hi: dataHi } = extent(values)
+ const lo = opts.min ?? dataLo
+ const hi = opts.max ?? dataHi
+ const three = typeof list[2] === 'string'
+ const c0 = list[0]
+ const c1 = list[1]
+ const c2 = three ? (list[2] as string) : list[1]
+
+ // With no numeric values at all lo/hi are ±Infinity, so the span is negative
+ // and this falls into the degenerate branch below — where every cell is
+ // non-numeric and therefore uncoloured anyway. No special case needed, and no
+ // NaN can escape.
+ const span = hi - lo
+ if (!(span > 0)) {
+ // No spread, so no ranking (header). Middle of the ramp, and for a
+ // three-stop scale that is exactly the author's mid colour.
+ const flat = three ? mixColors(c1, c1, 0) : mixColors(c0, c2, 0.5)
+ return values.map((v) => (numOf(v) === null ? '' : flat))
+ }
+
+ const mid = opts.mid ?? (lo + hi) / 2
+ return values.map((v) => {
+ const n = numOf(v)
+ if (n === null) return ''
+ const x = clamp(n, lo, hi)
+ if (!three) return mixColors(c0, c2, (x - lo) / span)
+ if (x <= mid) {
+ const sub = mid - lo
+ // mid pinned AT the low bound: everything at or below it is the mid colour
+ return mixColors(c0, c1, sub > 0 ? clamp((x - lo) / sub, 0, 1) : 1)
+ }
+ const sub = hi - mid
+ return mixColors(c1, c2, sub > 0 ? clamp((x - mid) / sub, 0, 1) : 0)
+ })
+}
+
+// --- data bars ---------------------------------------------------------------
+
+export interface BarOpts { min?: number; max?: number }
+
+export interface BarWidth {
+ /** 0–100 of the whole cell width, measured from `axis`. */
+ pct: number
+ negative: boolean
+ /** 0–100 from the left edge: where zero is. Identical for every row. */
+ axis: number
+}
+
+/**
+ * Bar geometry for a column, sharing ONE zero axis and ONE scale.
+ *
+ * The domain includes zero by default (`min(0, …)`, `max(0, …)`) — Excel's
+ * automatic rule, and the right one twice over: a column of 10…20 draws bars in
+ * proportion to their VALUES rather than making 10 invisible because it happens
+ * to be the smallest, and an all-equal column gets full bars instead of 0/0.
+ */
+export function dataBarWidths(values: unknown[], opts: BarOpts = {}): BarWidth[] {
+ const { lo: dataLo, hi: dataHi, any } = extent(values)
+ const lo = opts.min ?? (any ? Math.min(0, dataLo) : 0)
+ const hi = opts.max ?? (any ? Math.max(0, dataHi) : 0)
+ const span = hi - lo
+ if (!(span > 0)) return values.map(() => ({ pct: 0, negative: false, axis: 0 }))
+
+ // Zero's share of the width. All-positive data puts it at the left edge (0),
+ // all-negative at the right (100), and a signed column somewhere between —
+ // which is the only way a −50 and a +100 can be read against each other.
+ const axis = clamp((-lo / span) * 100, 0, 100)
+ return values.map((v) => {
+ const n = numOf(v)
+ if (n === null) return { pct: 0, negative: false, axis }
+ const x = clamp(n, lo, hi)
+ return { pct: clamp((Math.abs(x) / span) * 100, 0, 100), negative: x < 0, axis }
+ })
+}
+
+// --- predicates --------------------------------------------------------------
+
+const isBlank = (v: unknown): boolean =>
+ v == null || (typeof v === 'string' && v.trim() === '')
+
+const text = (v: unknown): string => (v == null ? '' : String(v).trim().toLowerCase())
+
+/**
+ * Numeric when BOTH sides are numeric, otherwise a case-insensitive text
+ * compare — Excel's rule, and the one people expect when a rule written for a
+ * number column meets a column that turned out to be text.
+ */
+function compare(op: CompareOp, a: unknown, b: unknown): boolean {
+ const x = numOf(a)
+ const y = numOf(b)
+ if (x !== null && y !== null) {
+ switch (op) {
+ case '>': return x > y
+ case '>=': return x >= y
+ case '<': return x < y
+ case '<=': return x <= y
+ case '=': return x === y
+ case '<>': return x !== y
+ default: return false
+ }
+ }
+ const s = text(a)
+ const t = text(b)
+ switch (op) {
+ case '>': return s > t
+ case '>=': return s >= t
+ case '<': return s < t
+ case '<=': return s <= t
+ case '=': return s === t
+ case '<>': return s !== t
+ default: return false
+ }
+}
+
+function matchCellValue(rule: CellValueRule, v: unknown): boolean {
+ switch (rule.op) {
+ case 'blank': return isBlank(v)
+ case 'notBlank': return !isBlank(v)
+ case 'contains':
+ case 'startsWith':
+ case 'endsWith': {
+ const needle = text(rule.value)
+ // An empty needle matches every cell — a rule that says nothing while
+ // looking like it says something. Refuse it.
+ if (needle === '') return false
+ const s = text(v)
+ return rule.op === 'contains' ? s.includes(needle)
+ : rule.op === 'startsWith' ? s.startsWith(needle)
+ : s.endsWith(needle)
+ }
+ case 'between': {
+ const n = numOf(v)
+ const a = numOf(rule.value)
+ const b = numOf(rule.to)
+ if (n === null || a === null || b === null) return false
+ // bounds sort themselves: "between 100 and 10" is a typo, not an empty set
+ return n >= Math.min(a, b) && n <= Math.max(a, b)
+ }
+ default: return compare(rule.op, v, rule.value)
+ }
+}
+
+/**
+ * The n largest (or smallest) values, TIES INCLUDED.
+ *
+ * Excluding a tie means the rule picks arbitrarily between two identical
+ * numbers, and the grid then shows one of two visibly equal cells highlighted —
+ * which reads as a difference in the data that does not exist. So "top 1" of
+ * 10, 10, 9 is both tens.
+ */
+function topNMask(values: unknown[], n: number, bottom: boolean): boolean[] {
+ const none = values.map(() => false)
+ if (!(n > 0)) return none
+ const nums: number[] = []
+ for (const v of values) {
+ const x = numOf(v)
+ if (x !== null) nums.push(x)
+ }
+ if (!nums.length) return none
+ nums.sort((a, b) => (bottom ? a - b : b - a))
+ const cut = nums[Math.min(n, nums.length) - 1]
+ return values.map((v) => {
+ const x = numOf(v)
+ return x !== null && (bottom ? x <= cut : x >= cut)
+ })
+}
+
+/**
+ * Values appearing more than once.
+ *
+ * Compared as trimmed, case-insensitive text, so what LOOKS the same counts as
+ * the same — the rule exists to catch what the eye should have caught, and a
+ * reader who sees "ACME" twice does not care that one of them is a number or
+ * has a trailing space. Blanks are never duplicates: absence repeated is still
+ * absence, and flagging it lights up every empty cell in a sparse column.
+ */
+function duplicatesMask(values: unknown[]): boolean[] {
+ const seen = new Map<string, number>()
+ const keys = values.map((v) => (isBlank(v) ? null : text(v)))
+ for (const k of keys) if (k !== null) seen.set(k, (seen.get(k) ?? 0) + 1)
+ return keys.map((k) => k !== null && (seen.get(k) ?? 0) > 1)
+}
+
+const toCell = (v: unknown): Cell => {
+ if (v == null) return null
+ if (typeof v === 'number') return Number.isFinite(v) ? v : null
+ if (typeof v === 'string' || typeof v === 'boolean') return v
+ return String(v)
+}
+
+/**
+ * Spreadsheet truth, not JavaScript truth. Only TRUE, a non-zero number, or the
+ * word "true" match; an error never does. JS would call every non-empty string
+ * truthy, so `expr: 'UPPER(value)'` would light up the entire column.
+ */
+const truthy = (c: Cell | undefined): boolean => {
+ if (c == null || isErr(c)) return false
+ if (typeof c === 'boolean') return c
+ if (typeof c === 'number') return c !== 0
+ return c.trim().toLowerCase() === 'true'
+}
+
+function formulaMask(expr: string, values: unknown[], cols?: Record<string, unknown[]>): boolean[] {
+ const map = new Map<string, Vec>()
+ if (cols) {
+ for (const [k, v] of Object.entries(cols)) {
+ const vec: Vec = v.map(toCell)
+ map.set(k, vec)
+ map.set(k.toLowerCase(), vec)
+ }
+ }
+ // last, so `value` always means the column being formatted
+ map.set('value', values.map(toCell))
+ const ctx: EvalCtx = { cols: map, n: values.length }
+ const out = evaluate(expr, ctx)
+ return values.map((_, i) => truthy(out[i]))
+}
+
+// --- evaluation --------------------------------------------------------------
+
+/**
+ * Merge one rule's opinion over what earlier rules said.
+ *
+ * Property by property, and NOT by spreading `next`: an object that carries an
+ * explicit `bg: undefined` (which is what `{...rule.style}` produces after a
+ * property is cleared in the UI) would spread that undefined straight over a
+ * background an earlier rule set, deleting it. Silently.
+ */
+function mergeStyle(base: CellStyle | null, next: CellStyle): CellStyle {
+ const out: CellStyle = base ? { ...base } : {}
+ if (next.color !== undefined) out.color = next.color
+ if (next.bg !== undefined) out.bg = next.bg
+ if (next.bold !== undefined) out.bold = next.bold
+ if (next.italic !== undefined) out.italic = next.italic
+ if (next.bar !== undefined) out.bar = next.bar
+ return out
+}
+
+function stylesFor(
+ rule: Rule,
+ values: unknown[],
+ cols?: Record<string, unknown[]>,
+): Array<CellStyle | null> {
+ // A rule with no `style` cannot say anything, and a file can carry one.
+ const mask = (m: boolean[], style: CellStyle | undefined): Array<CellStyle | null> =>
+ style && typeof style === 'object' ? m.map((hit) => (hit ? style : null)) : values.map(() => null)
+
+ switch (rule.kind) {
+ case 'colorScale':
+ return colorScale(values, rule.colors, rule).map((bg) => (bg ? { bg } : null))
+
+ case 'dataBar': {
+ const widths = dataBarWidths(values, rule)
+ return widths.map((w, i) => (numOf(values[i]) === null ? null : {
+ bar: {
+ pct: w.pct,
+ color: w.negative ? (rule.negativeColor ?? rule.color) : rule.color,
+ ...(w.negative ? { negative: true } : {}),
+ axis: w.axis,
+ },
+ }))
+ }
+
+ case 'cellValue':
+ return mask(values.map((v) => matchCellValue(rule, v)), rule.style)
+
+ case 'topN':
+ return mask(topNMask(values, rule.n, rule.bottom === true), rule.style)
+
+ case 'duplicates':
+ return mask(duplicatesMask(values), rule.style)
+
+ case 'formula':
+ return mask(formulaMask(rule.expr, values, cols), rule.style)
+
+ default:
+ // A rule kind from a later build. Ignored, never thrown on and never
+ // guessed at — model.ts's policy for unknown ops, for the same reason: a
+ // file must open, and a formatting rule nobody can read must not paint
+ // something that is merely plausible.
+ return values.map(() => null)
+ }
+}
+
+/**
+ * One style per row, or null where no rule had anything to say.
+ *
+ * Rules apply IN ORDER and the last one to set a property wins it, so ordering
+ * is meaningful without any rule being able to silence another (header).
+ *
+ * `cols` is the cross-column escape hatch: with it, a formula rule can say
+ * `value > [Target] * 1.1` and colour the Actual column by comparing it against
+ * another. Without it a formula sees `value` alone, which covers the common
+ * case and keeps the caller free of the whole sheet.
+ */
+export function evaluateRules(
+ rules: Rule[],
+ values: unknown[],
+ cols?: Record<string, unknown[]>,
+): Array<CellStyle | null> {
+ const out: Array<CellStyle | null> = values.map(() => null)
+ if (!values.length || !Array.isArray(rules)) return out
+ for (const rule of rules) {
+ // The list came out of the document. A hand edit can put anything in it,
+ // and the rules AROUND a broken one are still the author's intent.
+ if (!rule || typeof rule !== 'object') continue
+ const styles = stylesFor(rule, values, cols)
+ for (let i = 0; i < values.length; i++) {
+ const s = styles[i]
+ // mergeStyle always builds a fresh object, so a caller can never mutate a
+ // rule's own style through the result
+ if (s) out[i] = mergeStyle(out[i], s)
+ }
+ }
+ return out
+}
diff --git a/dash/src/dashboard.css b/dash/src/dashboard.css
new file mode 100644
index 00000000..940c4447
--- /dev/null
+++ b/dash/src/dashboard.css
@@ -0,0 +1,230 @@
+/* SPDX-License-Identifier: MIT
+ Copyright (c) 2026 The Bento authors
+ Dashboards. Colours come from dash's own :root (styles.css), so a tile sits
+ against the grid rather than importing a second palette — two surfaces that
+ agree on hue and spacing read as one product.
+
+ THE LAYOUT IS GRID UNITS, NOT PIXELS. `View.w` is a column count and a tile
+ carries x/y/w/h in those units, so the same document lays out on a laptop
+ and on a phone. The pixel height of a row is chrome and lives here; putting
+ it in the document would freeze one author's viewport into everyone else's
+ file. */
+
+.dbx {
+ flex: 1 1 auto;
+ min-width: 0;
+ min-height: 0;
+ overflow: auto;
+ padding: 12px;
+ background: var(--panel);
+ /* the document never mirrors — PLATFORM §8: tiles carry x/y coordinates, so
+ a dashboard must lay out identically for an RTL reader */
+ direction: ltr;
+}
+
+.dbx-grid-wrap {
+ display: grid;
+ grid-template-columns: repeat(var(--dbx-cols, 12), minmax(0, 1fr));
+ grid-auto-rows: 92px;
+ gap: 10px;
+}
+
+/* A phone cannot honour a twelve-column arrangement, and squeezing it produces
+ tiles too small to read OR to press. Every tile spans the width and keeps
+ its row span, which preserves the author's ORDER — the part of the layout
+ that still means something at this size. */
+@media (max-width: 700px) {
+ .dbx-grid-wrap { grid-template-columns: 1fr; }
+ .dbx-tile { grid-column: 1 / -1 !important; }
+}
+
+.dbx-tile {
+ display: flex;
+ flex-direction: column;
+ min-width: 0;
+ min-height: 0;
+ border: 1px solid var(--line);
+ border-radius: var(--radius-lg);
+ background: var(--surface);
+ overflow: hidden;
+}
+
+.dbx-head {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ padding: 7px 10px 4px;
+ flex: 0 0 auto;
+}
+/* the same label as a panel section header and a chart-panel title: 11px,
+ uppercase, wide-tracked, muted. Three surfaces had three different answers. */
+.dbx-title {
+ font-size: var(--fs-micro);
+ font-weight: 700;
+ text-transform: uppercase;
+ color: var(--muted);
+ letter-spacing: 0.06em;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+/* A tile filtered by a click somewhere else has to SAY so. A number that
+ quietly answers a narrower question than the reader thinks is the whole
+ failure mode of cross-filtering. */
+.dbx-filtered { font-size: 9px; color: var(--accent); }
+
+.dbx-body {
+ flex: 1 1 auto;
+ min-height: 0;
+ display: flex;
+ flex-direction: column;
+ padding: 0 10px 8px;
+}
+
+.dbx-note {
+ font-size: var(--fs-micro);
+ color: var(--muted);
+ padding-top: 4px;
+ flex: 0 0 auto;
+}
+
+/* ————— empty states —————
+ An empty tile says why it is empty. The alternative — an axis with no bars —
+ reads as zero, and zero is a number, and that number is wrong. */
+.dbx-empty,
+.dbx-blank {
+ flex: 1 1 auto;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ text-align: center;
+ font-size: var(--fs-small);
+ color: var(--muted);
+ padding: 8px;
+}
+.dbx-blank { height: 100%; }
+
+.dbx-text { font-size: var(--fs-ui); padding: 4px 0; }
+
+/* ————— the selection bar ————— */
+.dbx-chips {
+ display: flex;
+ align-items: center;
+ flex-wrap: wrap;
+ gap: 6px;
+ padding: 0 2px 10px;
+ font-size: var(--fs-small);
+}
+.dbx-chips-idle { color: var(--muted); }
+.dbx-chips-label { color: var(--muted); }
+.dbx-chip {
+ font: inherit;
+ font-size: var(--fs-small);
+ padding: 3px 9px;
+ border: 1px solid var(--accent);
+ border-radius: 999px;
+ background: var(--accent-wash);
+ color: var(--ink);
+ cursor: pointer;
+}
+.dbx-chip:hover { border-color: var(--ink); }
+.dbx-chip-clear { border-color: var(--line-strong); background: var(--bg); color: var(--muted); }
+
+/* ————— KPI ————— */
+.dbx-kpi .dbx-body { justify-content: center; }
+.dbx-value {
+ /* Sized to the BOX, not to taste. The tile is a fixed-height grid cell with
+ `overflow: hidden`, so a figure that wants more than its share is simply
+ cut — measured at 30px/33px: the value needed 34px of height in a 20px box
+ and 166px of width in 125px, and "£97,050.00" rendered as "£97,05" with
+ the descenders sliced off. A KPI tile that truncates its own number is
+ worse than one with smaller type, because the reader cannot tell it
+ happened.
+ `flex: 0 0 auto` stops the column squashing the line box below its own
+ line-height; `min-width: 0` is what lets the ellipsis actually engage
+ inside a flex child. */
+ flex: 0 0 auto;
+ min-width: 0;
+ font-size: clamp(18px, 2.2vw, 26px);
+ font-weight: 650;
+ line-height: 1.2;
+ letter-spacing: -0.02em;
+ font-variant-numeric: tabular-nums;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.dbx-sub { font-size: var(--fs-small); color: var(--muted); padding-top: 2px; }
+/* Direction is a hue AND a sign in the text, never hue alone — a colour-blind
+ reader gets the same answer. */
+.dbx-up { color: var(--up-ink); }
+.dbx-down { color: var(--down-ink); }
+
+/* ————— charts ————— */
+.dbx-svg { flex: 1 1 auto; min-height: 0; width: 100%; overflow: visible; }
+.dbx-grid { stroke: var(--grid-line); stroke-width: 1; }
+.dbx-axis { stroke: var(--line-strong); stroke-width: 1; }
+.dbx-ytick { font-size: 9px; fill: var(--muted); text-anchor: end; }
+.dbx-xtick { font-size: 9px; fill: var(--muted); text-anchor: middle; }
+.dbx-line { fill: none; stroke-width: 2; stroke-linejoin: round; stroke-linecap: round; }
+
+/* The pick target is the whole band, so a category with no bar — a null, which
+ is a gap and not a zero — can still be clicked. Invisible, never absent. */
+.dbx-hit { fill: transparent; cursor: pointer; }
+.dbx-hit:hover { fill: var(--wash); }
+.dbx-band-on { fill: var(--sel); }
+.dbx-bar, .dbx-slice, .dbx-dot, .dbx-key { cursor: pointer; }
+/* Cross-highlight: what is NOT selected fades, rather than vanishing. A tile
+ that dropped its other categories would be a tile you cannot click your way
+ out of. */
+.dbx-dim { opacity: 0.28; }
+.dbx-slice-on { stroke: var(--ink); stroke-width: 1.5; }
+.dbx-swatch { rx: 2; }
+.dbx-keytext { font-size: 10px; fill: var(--ink); }
+
+.dbx-legend {
+ display: flex;
+ flex-wrap: wrap;
+ gap: 10px;
+ font-size: var(--fs-micro);
+ color: var(--muted);
+ padding-bottom: 2px;
+ flex: 0 0 auto;
+}
+.dbx-legend i { display: inline-block; width: 9px; height: 9px; border-radius: 2px; margin-right: 4px; }
+
+/* ————— table tile ————— */
+.dbx-scroll { flex: 1 1 auto; min-height: 0; overflow: auto; }
+.dbx-table {
+ width: 100%;
+ border-collapse: collapse;
+ font-size: var(--fs-small);
+ font-variant-numeric: tabular-nums;
+}
+.dbx-table th {
+ position: sticky;
+ top: 0;
+ background: var(--grid-head);
+ text-align: left;
+ font-weight: 600;
+ color: var(--muted);
+ border-bottom: 1px solid var(--line-strong);
+ padding: 3px 6px;
+ white-space: nowrap;
+}
+.dbx-table td {
+ padding: 3px 6px;
+ border-bottom: 1px solid var(--grid-line);
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ max-width: 220px;
+}
+.dbx-table tr[data-tile] { cursor: pointer; }
+.dbx-table tr[data-tile]:hover td { background: var(--wash); }
+.dbx-row-on td { background: var(--sel); }
+
+/* Toggled from the topbar. `.dbx` sets no `display`, so the UA default for
+ [hidden] applies — but state it, because a later `display: flex` here would
+ silently un-hide the whole surface. */
+.dbx[hidden] { display: none; }
diff --git a/dash/src/dashboard.ts b/dash/src/dashboard.ts
new file mode 100644
index 00000000..ada3bb67
--- /dev/null
+++ b/dash/src/dashboard.ts
@@ -0,0 +1,1124 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Dashboards: a grid of tiles over one workbook, and CROSS-FILTERING.
+//
+// A dashboard is the app's output surface, not its subject (docs/DECISIONS.md,
+// 2026-08-02 — `dash` is DAta SHeets). What makes one worth building is the
+// thing a screenshot of six charts is not: click a bar and every other tile
+// re-derives against that selection, click again and it lets go.
+//
+// THREE RULES HOLD THE WHOLE FILE UP.
+//
+// 1. THE SELECTION IS VIEWER STATE. It goes through `store.view()` — no
+// checkpoint, no dirty flag, no op (store.ts:544, grid.ts:326 is the
+// precedent). Writing a click as a `commit` is the easy mistake and
+// nobody notices until the file dirties itself every time a reader
+// explores it, autosave rewrites the workbook, and — once collab lands —
+// one reader's exploring moves everybody else's dashboard. The LAYOUT is
+// the opposite: it is what the author arranged, so it is document data
+// and travels in the file.
+//
+// 2. NOTHING IS CACHED. Series are derived at render (chart.ts:5) precisely
+// so a chart cannot disagree with the table beside it, and a cross-filter
+// is the case where a cache would be most tempting and most wrong: a
+// stale tile under a live selection is a chart that is confidently
+// answering a question nobody asked. `deriveTile` is a pure function of
+// (sheet, tile, rows) and is called again for every paint.
+//
+// 3. NULL IS A CATEGORY, NOT AN EXEMPTION. See `catOf` below. A row with a
+// blank Region is not swept into "North" and not quietly dropped from the
+// dashboard: it is in the "(blank)" category, which is drawn, clickable
+// and selectable like any other. So the categories of a column PARTITION
+// the sheet, and picking every category in turn accounts for every row.
+// The rig proves that as an equality, because it is the kind of thing
+// that silently stops being true.
+//
+// A TILE NEVER FILTERS ITSELF. The selection carries the id of the tile the
+// click came from and a tile skips its own entries. Without that, clicking
+// "North" on a region chart leaves a chart with one bar, and there is no way
+// back to "South" except an undo the reader does not have — the selection is
+// not in the undo stack, by rule 1. Power BI, Tableau and Looker all made the
+// same choice; it is not a nicety, it is the difference between a control and
+// a trap.
+//
+// WHAT IS DERIVED WHERE. The grouping arithmetic is chart.ts's `optionFor`,
+// called over a PROJECTED sheet holding just the surviving rows. That is
+// deliberate: a dashboard puts a chart and a table side by side, so a second
+// group-by implementation in this file would be exactly the disagreement rule
+// 2 exists to prevent. The aggregates are filter.ts's `summarize` for the same
+// reason — it is what the status bar reports, it divides by the values PRESENT,
+// and it answers `null` rather than 0 when there is nothing to aggregate.
+
+import './dashboard.css'
+import { optionFor, type ChartBinding } from './chart.ts'
+import {
+ buildOrder, isBlank, summarize, type ColumnFilter, type Get,
+} from './filter.ts'
+import { formatValue } from './format.ts'
+import { t } from './i18n.ts'
+import type { Column, DashDoc, Sheet, TableSheet, View } from './model.ts'
+import { readCell, type Store } from './store.ts'
+
+// --- The document shape ----------------------------------------------------
+//
+// TO BE MOVED TO model.ts. `View` and `Tile` are already there (model.ts:256)
+// and already carry `x/y/w/h`, `bind` and an index signature, so everything
+// below round-trips through `parseDoc` today — unknown fields survive by
+// construction (PLATFORM §3). What the model's types cannot yet express is
+// `kind: 'table'`, a tile `id`, and the two extra `bind` keys; those are
+// declared here so this file type-checks, and the boundary casts are the only
+// place that knows the difference.
+
+/**
+ * Tile kinds this build draws. The stored `kind` is a plain string, NOT this
+ * union, for the same reason `Step.op` is (model.ts:41): a tile written by a
+ * newer dash must survive a round trip through this one, and the type system
+ * must not be able to express "only these". An unrecognised kind renders as a
+ * labelled placeholder — never as an empty box, which reads as "this chart has
+ * no data" when the truth is "this build cannot draw it".
+ */
+export type KnownTileKind = 'chart' | 'kpi' | 'table' | 'text'
+
+export type ChartKind = 'bar' | 'line' | 'pie'
+
+export interface TileBind {
+ sheet: string
+ /** chart: the category column. */
+ x?: string
+ /** table: the column a row click selects on. */
+ by?: string
+ /** chart: one series per column id. */
+ series?: string[]
+ /** kpi: the column being aggregated. */
+ col?: string
+ /** kpi: a NAMED measure (doc.measures). Not evaluated yet — see the report. */
+ measure?: string
+ agg?: string
+ /** table: which columns to show. Absent means the first few. */
+ cols?: string[]
+}
+
+export interface DashTile {
+ /**
+ * Tile identity, and load-bearing: it is what a selection remembers so a tile
+ * can skip its own entries. Positional identity would break the moment a
+ * tile moved, which is a thing authors do.
+ */
+ id: string
+ kind: string
+ /** Grid units — see `DashView`. */
+ x: number
+ y: number
+ w: number
+ h: number
+ title?: string
+ bind?: TileBind
+ chart?: string
+ /**
+ * The KPI's comparison.
+ * `all` — the same aggregate over every row, ignoring the selection.
+ * Reads as "£412k of £1.2m, 34% of all".
+ * `column` — the same aggregate over the same rows, of another column.
+ * Reads as "£412k against a £500k target, −18%".
+ */
+ compare?: { of: 'all' } | { of: 'column'; col: string }
+ [extra: string]: unknown
+}
+
+/**
+ * A dashboard.
+ *
+ * `w` and `h` are GRID UNITS — columns and rows — not pixels. The pixel height
+ * of a row is chrome and lives in the stylesheet, because a dashboard has to
+ * reflow onto a phone and a layout frozen in pixels cannot. Tiles are placed
+ * in that unit grid, so the layout means the same thing to every reader, which
+ * is the invariant PLATFORM §8 states for document coordinates.
+ */
+export interface DashView {
+ id: string
+ name: string
+ w: number
+ h: number
+ tiles: DashTile[]
+ [extra: string]: unknown
+}
+
+/** Grid columns a dashboard uses when the stored view does not say. */
+export const DEFAULT_COLS = 12
+/** Rows a table tile paints. Past this the tile says how many it is not showing. */
+export const TABLE_ROWS = 200
+
+// --- The selection ---------------------------------------------------------
+
+/**
+ * One click, remembered.
+ *
+ * `v` is the CATEGORY, canonicalised by `catOf` — a string, or `null` for the
+ * blank category. It is deliberately not the raw cell value: the categories a
+ * chart draws are already strings (chart.ts:64 stringifies the x column), so
+ * storing the raw value would mean a bar click and a row click on the same
+ * category produce two entries that do not cancel. Matching back to rows goes
+ * through filter.ts's `isOneOf`, which canonicalises "10" and 10 to one key —
+ * so a ticked category cannot fail to match its own rows (filter.ts:34).
+ */
+export interface SelectionEntry {
+ /** The tile the click came from. A tile never applies its own entries. */
+ from: string
+ sheet: string
+ col: string
+ v: string | null
+}
+
+export type CrossSelection = SelectionEntry[]
+
+/**
+ * The category a value belongs to.
+ *
+ * BLANK IS A CATEGORY OF ITS OWN, and this one function is why no row is
+ * silently dropped or silently kept:
+ *
+ * - Every row maps to exactly one category of a column, blanks included, so
+ * the categories partition the sheet. Selecting "North" cannot match a
+ * blank Region; selecting "(blank)" matches exactly those rows.
+ * - `isBlank` is filter.ts's, so "" and " " land in the same category the
+ * filter menu's "(Blanks)" box selects, and `isOneOf` matches a `null` in
+ * the set against exactly those rows (filter.ts:147 — `matchKey` sends
+ * every blank to one key). One definition of blank across the app, rather
+ * than a chart that offers a category the filter cannot express.
+ *
+ * The alternative — treating a null as "matches everything" so a selection
+ * never hides an unknown — is the seductive wrong answer: the totals then do
+ * not add up, because a row is counted under North AND South.
+ */
+export const catOf = (v: unknown): string | null => (isBlank(v) ? null : String(v))
+
+/** What a category is called on screen. */
+export const catLabel = (c: string | null): string => (c === null ? t('(blank)') : c)
+
+/**
+ * Add a category to the selection, or take it out if it is already there.
+ *
+ * PURE, and returns a NEW array: the class assigns the result inside
+ * `store.view()`, and a mutation in place would leave the previous value
+ * indistinguishable from the next one for anything holding a reference.
+ *
+ * Within one column, values OR (click North, then South, see both). Across
+ * columns they AND (region = North AND stage = Won) — see `selectionFilters`.
+ * That is what every BI tool does, and it is the only pair that makes clicking
+ * a second bar mean something other than "no rows".
+ */
+export function toggleSelection(sel: CrossSelection, e: SelectionEntry): CrossSelection {
+ const i = sel.findIndex(
+ (x) => x.from === e.from && x.sheet === e.sheet && x.col === e.col && x.v === e.v,
+ )
+ return i >= 0 ? [...sel.slice(0, i), ...sel.slice(i + 1)] : [...sel, e]
+}
+
+/**
+ * The filters ONE tile derives against.
+ *
+ * Two exclusions, and both are correctness rather than taste:
+ *
+ * - ENTRIES FROM THIS TILE. A chart that filtered itself collapses to the
+ * one bar you clicked, and the other bars — the ones you would click to
+ * change your mind — are gone.
+ * - ENTRIES FROM ANOTHER SHEET. Two sheets sharing a column NAME are not
+ * related; a join is (model.ts:169), and dash has no relationship model
+ * yet. Filtering across sheets on a name coincidence would produce a
+ * number that looks joined and is not, which is the worst failure a
+ * dashboard has. So a selection reaches the tiles bound to its own sheet
+ * and stops there.
+ *
+ * The result is one `isOneOf` per column: OR inside, AND between, which is
+ * exactly how `buildOrder` composes a list of ColumnFilters (filter.ts:341).
+ */
+export function selectionFilters(sel: CrossSelection, tile: DashTile): ColumnFilter[] {
+ const sheet = tile.bind?.sheet
+ if (!sheet) return []
+ const byCol = new Map<string, Set<unknown>>()
+ for (const e of sel) {
+ if (e.from === tile.id) continue
+ if (e.sheet !== sheet) continue
+ let set = byCol.get(e.col)
+ if (!set) { set = new Set<unknown>(); byCol.set(e.col, set) }
+ // `null` in the set IS the "(Blanks)" box — filter.ts:66 says so, and
+ // `matchKey` matches it against every blank in the column.
+ set.add(e.v)
+ }
+ // Map preserves insertion order, so the filter list is deterministic and two
+ // readers of one file build the same one.
+ return [...byCol].map(([col, set]) => ({ col, pred: { op: 'isOneOf', set } }))
+}
+
+/** The categories picked ON this tile — what the tile highlights. */
+export function pickedOn(
+ sel: CrossSelection, tile: DashTile, col: string | undefined,
+): Set<string | null> {
+ const out = new Set<string | null>()
+ if (!col) return out
+ for (const e of sel) if (e.from === tile.id && e.col === col) out.add(e.v)
+ return out
+}
+
+export interface Chip { entry: SelectionEntry; label: string }
+
+/** The "Region: North ✕" row above the tiles — the only thing that makes a
+ * composed selection legible. A dashboard filtered by three clicks and saying
+ * so nowhere is how a reader ends up quoting a number for the wrong slice. */
+export function selectionChips(sel: CrossSelection, doc: DashDoc): Chip[] {
+ return sel.map((entry) => {
+ const sheet = doc.sheets.find((s: Sheet) => s.id === entry.sheet)
+ const col = sheet && sheet.kind === 'table'
+ ? sheet.columns.find((c) => c.id === entry.col)
+ : undefined
+ return { entry, label: `${col?.name ?? entry.col}: ${catLabel(entry.v)}` }
+ })
+}
+
+// --- Rows ------------------------------------------------------------------
+
+export const rowCount = (s: TableSheet): number => s.rids.reduce((n, [, c]) => n + c, 0)
+
+const expandRids = (s: TableSheet): number[] => {
+ const out: number[] = []
+ for (const [start, count] of s.rids) for (let i = 0; i < count; i++) out.push(start + i)
+ return out
+}
+
+/**
+ * Read one cell of a sheet, the way the reader sees it.
+ *
+ * OVERRIDES ARE HONOURED, and that is a fix rather than a flourish: a hand
+ * correction (`sheet.cells`) is what the grid paints (grid.ts:398), so a
+ * dashboard that read past it would put a number on a tile that disagrees with
+ * the cell three inches away. chart.ts's own `colVals` reads the raw column —
+ * but every tile here hands its columns to `optionFor` through this accessor
+ * (see `deriveChart`), so the chart gets the corrections for free and the two
+ * cannot diverge.
+ *
+ * `computed` is the grid's freshly recalculated formula columns; passing it
+ * means a tile can chart a column that is nowhere in the document.
+ *
+ * The rid table is expanded ONCE per accessor and only when the sheet actually
+ * has overrides — walking the run-length runs per cell would be O(runs) on
+ * every read, and a full scan calls this once per row per column.
+ */
+export function sheetGet(sheet: TableSheet, computed?: Map<string, unknown[]>): Get {
+ const over = sheet.cells
+ const rids = over && Object.keys(over).length > 0 ? expandRids(sheet) : null
+ return (col, row) => {
+ const c = computed?.get(col)
+ if (c) return c[row]
+ if (rids) {
+ const o = over![`${col}:${rids[row]}`]
+ if (o && 'v' in o) return o.v
+ }
+ return readCell(sheet.data[col], row)
+ }
+}
+
+/**
+ * The rows a tile derives over: 0-based positions in the sheet's own order.
+ *
+ * `null` means EVERY row and is a fast path, not a special case — with no
+ * filters `buildOrder` would allocate the identity vector for a 250k-row sheet
+ * on every paint of every tile. The rig asserts the two agree, because a fast
+ * path that quietly disagrees with the slow one is how a tile ends up showing
+ * a different population from the tile beside it.
+ *
+ * Sorting is deliberately not applied: tiles group, and a group-by does not
+ * care what order its input arrived in. A table tile shows sheet order, which
+ * is the order the author put the rows in — grid sorting is that reader's view
+ * of the grid, not a property of the dashboard.
+ */
+export function rowsForTile(
+ sheet: TableSheet, get: Get, filters: ColumnFilter[],
+): number[] | null {
+ if (!filters.length) return null
+ return buildOrder(rowCount(sheet), get, filters, [])
+}
+
+/** Materialise a row list. `null` (every row) becomes 0..n-1. */
+export const rowList = (sheet: TableSheet, rows: number[] | null): number[] =>
+ rows ?? Array.from({ length: rowCount(sheet) }, (_, i) => i)
+
+// --- Derived tile data -----------------------------------------------------
+
+export type EmptyReason =
+ /** the selection left this tile with nothing */
+ | 'no-rows'
+ /** rows, but nothing numeric to plot */
+ | 'no-values'
+ /** the tile names a sheet that is not in this workbook */
+ | 'no-sheet'
+ /** the tile is not bound to columns yet */
+ | 'no-binding'
+ /** a tile kind this build does not draw */
+ | 'unknown-kind'
+
+export interface Series { name: string; data: Array<number | null> }
+
+export type TileData =
+ | { kind: 'empty'; reason: EmptyReason; note?: string }
+ | {
+ kind: 'chart'; chart: ChartKind; cats: Array<string | null>
+ series: Series[]; colors: string[]; rows: number; note?: string
+ }
+ | {
+ kind: 'kpi'; value: number | null; column?: Column; agg: Agg; rows: number
+ /** which comparison was asked for — the RENDERER MUST BRANCH ON THIS and
+ * never on `baselineLabel`, which is a translated string: a branch on
+ * displayed text works in English and silently takes the wrong arm in
+ * every other locale (PLATFORM §8 — model values stay English words,
+ * and this is not even a model value). */
+ compare: 'all' | 'column' | null
+ baseline: number | null; baselineLabel?: string; baselineColumn?: Column
+ /** value − baseline */
+ delta: number | null
+ /** delta / |baseline| — `null` when the baseline is 0 or absent */
+ pct: number | null
+ /** value / baseline — `null` when the baseline is 0 or absent */
+ share: number | null
+ note?: string
+ }
+ | { kind: 'table'; cols: Column[]; rows: number[]; total: number; by?: string }
+ | { kind: 'text'; text: string }
+
+const AGGS = ['sum', 'avg', 'min', 'max', 'count'] as const
+export type Agg = (typeof AGGS)[number]
+
+const aggOf = (s: string | undefined): Agg =>
+ (AGGS as readonly string[]).includes(s ?? '') ? (s as Agg) : 'sum'
+
+/** chart.ts groups with these four and no others; anything else means `sum`. */
+const chartAggOf = (s: string | undefined): NonNullable<ChartBinding['aggregate']> =>
+ s === 'avg' || s === 'count' || s === 'none' ? s : 'sum'
+
+const chartKindOf = (s: unknown): ChartKind =>
+ s === 'line' || s === 'pie' ? s : 'bar'
+
+const tableOf = (doc: DashDoc, id: string | undefined): TableSheet | undefined => {
+ const s = doc.sheets.find((x: Sheet) => x.id === id)
+ return s && s.kind === 'table' ? s : undefined
+}
+
+/**
+ * Everything a tile needs to paint, and nothing about how it looks.
+ *
+ * Pure, and re-run on every paint — see rule 2 in the header. The whole
+ * cross-filter is this function called with a different `rows`.
+ */
+export function deriveTile(
+ doc: DashDoc, tile: DashTile, rows: number[] | null,
+ computed?: Map<string, unknown[]>,
+): TileData {
+ if (tile.kind === 'text') return { kind: 'text', text: String(tile.text ?? tile.title ?? '') }
+ if (tile.kind !== 'chart' && tile.kind !== 'kpi' && tile.kind !== 'table') {
+ return { kind: 'empty', reason: 'unknown-kind' }
+ }
+ const sheet = tableOf(doc, tile.bind?.sheet)
+ if (!sheet) return { kind: 'empty', reason: 'no-sheet' }
+ const list = rowList(sheet, rows)
+ // NOTHING LEFT IS ITS OWN ANSWER. Falling through to the renderer would draw
+ // an axis with no bars, and an empty bar chart reads as ZERO — which is a
+ // number, which is a lie (model.ts:174 states the same rule for unresolved
+ // transform steps).
+ if (!list.length) return { kind: 'empty', reason: 'no-rows' }
+
+ if (tile.kind === 'chart') return deriveChart(sheet, tile, list, computed)
+ if (tile.kind === 'kpi') return deriveKpi(sheet, tile, list, computed)
+ return deriveTable(sheet, tile, list)
+}
+
+function deriveChart(
+ sheet: TableSheet, tile: DashTile, list: number[], computed?: Map<string, unknown[]>,
+): TileData {
+ const b = tile.bind
+ const series = (b?.series ?? []).filter((id) => typeof id === 'string')
+ if (!b?.x || !series.length) return { kind: 'empty', reason: 'no-binding' }
+
+ const get = sheetGet(sheet, computed)
+ // THE PROJECTION. `optionFor` takes a sheet and an optional map of
+ // already-computed columns; hand it the SURVIVING rows in that map and a
+ // sheet whose row count matches, and the app's one grouping implementation
+ // does the cross-filtered arithmetic unchanged. Every bound column is in the
+ // map, so `optionFor` never reads the raw encoding — which is also how the
+ // chart inherits `sheetGet`'s cell overrides.
+ const sub = new Map<string, unknown[]>()
+ for (const id of series) sub.set(id, list.map((i) => get(id, i)))
+ // THE CATEGORY COLUMN GOES THROUGH `catOf` FIRST, and this is what makes the
+ // bars and the selection the same thing. chart.ts groups by `String(v)`, so
+ // `null`, `''` and `' '` are THREE categories — three bars all labelled
+ // "(blank)", each selecting all the others' rows, because filter.ts sends
+ // every blank to one key. Canonicalising before the group-by collapses them
+ // into the one category the filter can express, so the categories a tile
+ // draws are exactly the classes a click selects, and they partition the
+ // sheet. (A number canonicalises to its own digits — "10" — which `isOneOf`
+ // matches back to the cell holding 10; filter.ts:146 does that round trip.)
+ const xcol = b.x
+ sub.set(xcol, list.map((i) => catOf(get(xcol, i))))
+ const projected = { ...sheet, rids: [[0, list.length]] as Array<[number, number]> }
+
+ const kind = chartKindOf(tile.chart)
+ const opt = optionFor(projected, {
+ x: b.x, series, kind, aggregate: chartAggOf(b.agg),
+ }, sub)
+ const colors = Array.isArray(opt.color) ? (opt.color as string[]) : []
+ const note = tile.chart === 'scatter'
+ // A scatter point is a ROW; the dashboard's unit of picking is a CATEGORY,
+ // so there is nothing to click. Drawn as a bar rather than refused, and
+ // said out loud rather than silently substituted.
+ ? t('Shown as bars — a scatter has no category to select.')
+ : undefined
+
+ if (kind === 'pie') {
+ const data = (((opt.series as unknown[])[0] as { data?: unknown[] })?.data ?? []) as
+ Array<{ name?: unknown; value?: unknown }>
+ const cats = data.map((d) => catOf(d.name))
+ const vals = data.map((d) => (typeof d.value === 'number' && Number.isFinite(d.value) ? d.value : null))
+ const first = sheet.columns.find((c) => c.id === series[0])
+ return {
+ kind: 'chart', chart: 'pie', cats, colors, rows: list.length,
+ series: [{ name: first?.name ?? series[0], data: vals }],
+ note: series.length > 1 ? t('A pie shows one series; the rest are in the legend of the bar view.') : note,
+ }
+ }
+
+ const cats = (((opt.xAxis as { data?: unknown[] })?.data ?? []) as unknown[]).map(catOf)
+ const out = ((opt.series ?? []) as Array<{ name?: unknown; data?: unknown[] }>).map((s) => ({
+ name: String(s.name ?? ''),
+ data: ((s.data ?? []) as unknown[]).map((v) =>
+ typeof v === 'number' && Number.isFinite(v) ? v : null),
+ }))
+ return { kind: 'chart', chart: kind, cats, series: out, colors, rows: list.length, note }
+}
+
+/**
+ * One number, and what it is being compared with.
+ *
+ * The aggregate is filter.ts's `summarize` over the surviving rows, which is
+ * the same call the status bar makes — so a KPI and a selection summary can
+ * never disagree, and three of its properties are load-bearing here:
+ *
+ * - IT DIVIDES BY THE VALUES PRESENT. An average over a column with blanks
+ * divides by the numbers, not by the rows; dividing by rows quietly
+ * understates every average in proportion to how patchy the data is.
+ * - IT ANSWERS null, NOT 0, when there is nothing to aggregate. A sum of
+ * nothing shown as £0 is a lie with a number's face.
+ * - `count` is the count of values PRESENT, not of rows. Same definition as
+ * the status bar's Count; a KPI that counted blanks would disagree with
+ * the number in the footer for the same selection.
+ */
+function deriveKpi(
+ sheet: TableSheet, tile: DashTile, list: number[], computed?: Map<string, unknown[]>,
+): TileData {
+ const col = tile.bind?.col
+ if (!col) {
+ return {
+ kind: 'empty', reason: 'no-binding',
+ // A named measure carries an EXPRESSION (model.ts:240) and dash has no
+ // aggregate evaluator yet. Saying so beats rendering a plausible number
+ // derived from something else.
+ note: tile.bind?.measure ? t('Named measures need the measure engine.') : undefined,
+ }
+ }
+ const get = sheetGet(sheet, computed)
+ const agg = aggOf(tile.bind?.agg)
+ const pick = (c: string, rows: number[]): number | null => {
+ const s = summarize(get, c, rows)
+ return agg === 'count' ? s.count
+ : agg === 'avg' ? s.avg
+ : agg === 'min' ? s.min
+ : agg === 'max' ? s.max
+ : s.sum
+ }
+
+ const value = pick(col, list)
+ const column = sheet.columns.find((c) => c.id === col)
+
+ let baseline: number | null = null
+ let baselineLabel: string | undefined
+ let baselineColumn: Column | undefined
+ const cmp = tile.compare
+ if (cmp?.of === 'all') {
+ // Deliberately the WHOLE sheet, selection and all — that is the point of
+ // this comparison: "how much of everything is this?".
+ baseline = pick(col, rowList(sheet, null))
+ baselineLabel = t('of all rows')
+ } else if (cmp?.of === 'column' && cmp.col) {
+ baseline = pick(cmp.col, list)
+ baselineColumn = sheet.columns.find((c) => c.id === cmp.col)
+ baselineLabel = baselineColumn?.name ?? cmp.col
+ }
+
+ // A RATIO AGAINST NOTHING IS NOT A RATIO. `value / 0` is Infinity and `0 / 0`
+ // is NaN, and both render as a confident string on a dashboard tile
+ // ("Infinity%" above a target of zero). A missing baseline and a zero
+ // baseline both answer null, which the renderer shows as "—".
+ const usable = baseline !== null && Number.isFinite(baseline) && baseline !== 0
+ const delta = value !== null && baseline !== null ? value - baseline : null
+ return {
+ kind: 'kpi', value, column, agg, rows: list.length,
+ compare: cmp?.of === 'all' ? 'all' : cmp?.of === 'column' && cmp.col ? 'column' : null,
+ baseline, baselineLabel, baselineColumn,
+ delta,
+ pct: usable && delta !== null ? delta / Math.abs(baseline as number) : null,
+ share: usable && value !== null ? value / (baseline as number) : null,
+ note: value === null && list.length
+ ? t('No numeric values in this column for the current selection.')
+ : undefined,
+ }
+}
+
+function deriveTable(sheet: TableSheet, tile: DashTile, list: number[]): TileData {
+ const want = tile.bind?.cols
+ const cols = want?.length
+ ? want.map((id) => sheet.columns.find((c) => c.id === id)).filter((c): c is Column => !!c)
+ : sheet.columns.slice(0, 6)
+ return { kind: 'table', cols, rows: list, total: rowCount(sheet), by: tile.bind?.by }
+}
+
+// --- Views in the document -------------------------------------------------
+
+/** The dashboards a workbook carries. Absent is normal, not an error. */
+export const viewsOf = (doc: DashDoc): DashView[] =>
+ (Array.isArray(doc.views) ? doc.views : []) as unknown as DashView[]
+
+/**
+ * A document with this dashboard in it, replacing any view with the same id.
+ *
+ * NOT A MUTATION, and not a `commit` either: the store's Patch union has no op
+ * that writes a top-level document field other than the title, so persisting a
+ * layout needs `setView` (see the report). Until then this is the honest path —
+ * `store.replaceDoc(withView(doc, v))` — which is undoable-as-a-whole and does
+ * not pretend to be finer-grained than it is.
+ */
+export function withView(doc: DashDoc, view: DashView): DashDoc {
+ const views = viewsOf(doc)
+ const at = views.findIndex((v) => v.id === view.id)
+ const next = at >= 0
+ ? [...views.slice(0, at), view, ...views.slice(at + 1)]
+ : [...views, view]
+ return { ...doc, views: next as unknown as View[] }
+}
+
+/**
+ * A dashboard for a workbook that has none: a KPI row, a bar chart, a pie and
+ * the rows underneath. It is EPHEMERAL until something writes it into the
+ * document — a dashboard nobody arranged should not dirty the file just for
+ * being looked at.
+ *
+ * Returns null when the sheet has nothing to put on one, rather than an empty
+ * grid of empty tiles.
+ */
+export function defaultDashboard(doc: DashDoc): DashView | null {
+ const sheet = doc.sheets.find((s: Sheet): s is TableSheet => s.kind === 'table')
+ if (!sheet || !sheet.columns.length) return null
+ const label = sheet.columns.find((c) => c.type === 'text' || c.type === 'enum')
+ const nums = sheet.columns.filter((c) => c.type === 'money' || c.type === 'number')
+ const pcts = sheet.columns.filter((c) => c.type === 'percent')
+ const measure = nums[0] ?? pcts[0]
+ if (!measure) return null
+ const second = sheet.columns.find(
+ (c) => (c.type === 'text' || c.type === 'enum') && c.id !== label?.id,
+ )
+ const s = sheet.id
+
+ const tiles: DashTile[] = [
+ {
+ id: 'kpi-total', kind: 'kpi', x: 0, y: 0, w: 3, h: 1,
+ title: `${t('Total')} ${measure.name}`,
+ bind: { sheet: s, col: measure.id, agg: 'sum' }, compare: { of: 'all' },
+ },
+ {
+ id: 'kpi-avg', kind: 'kpi', x: 3, y: 0, w: 3, h: 1,
+ title: `${t('Average')} ${measure.name}`,
+ bind: { sheet: s, col: measure.id, agg: 'avg' },
+ },
+ {
+ id: 'kpi-rows', kind: 'kpi', x: 6, y: 0, w: 3, h: 1,
+ title: t('Rows'),
+ bind: { sheet: s, col: measure.id, agg: 'count' }, compare: { of: 'all' },
+ },
+ ...(pcts[0] && pcts[0].id !== measure.id
+ ? [{
+ id: 'kpi-pct', kind: 'kpi', x: 9, y: 0, w: 3, h: 1,
+ title: `${t('Average')} ${pcts[0].name}`,
+ bind: { sheet: s, col: pcts[0].id, agg: 'avg' },
+ } as DashTile]
+ : []),
+ ]
+
+ if (label) {
+ tiles.push({
+ id: 'chart-by-label', kind: 'chart', x: 0, y: 1, w: 7, h: 3,
+ title: `${measure.name} ${t('by')} ${label.name}`, chart: 'bar',
+ bind: { sheet: s, x: label.id, series: [measure.id], agg: 'sum' },
+ })
+ }
+ if (second) {
+ tiles.push({
+ id: 'chart-by-second', kind: 'chart', x: label ? 7 : 0, y: 1, w: 5, h: 3,
+ title: `${measure.name} ${t('by')} ${second.name}`, chart: 'pie',
+ bind: { sheet: s, x: second.id, series: [measure.id], agg: 'sum' },
+ })
+ }
+ tiles.push({
+ id: 'table-rows', kind: 'table', x: 0, y: 4, w: 12, h: 3,
+ title: sheet.name,
+ bind: { sheet: s, by: label?.id ?? second?.id },
+ })
+
+ return {
+ id: `view-${sheet.id}`, name: t('Dashboard'), w: DEFAULT_COLS,
+ h: tiles.reduce((n, tile) => Math.max(n, tile.y + tile.h), 0), tiles,
+ }
+}
+
+// --- Drawing ---------------------------------------------------------------
+//
+// The tiles paint their own SVG rather than mounting charts-lite, and the
+// reason is picking: `mountChart` (kernel/src/charts.ts:741) draws marks with
+// no identity and offers no click callback, so there is no way to ask it which
+// bar was pressed. Guessing the plot rectangle from the outside and overlaying
+// hit strips would tie this file to charts-lite's internal margins — a silent
+// break the first time they change. The ARITHMETIC still comes from
+// `optionFor`; only the painting is local, and every mark carries the category
+// it stands for. (The hook that would collapse this is in the report.)
+
+const esc = (s: unknown): string =>
+ String(s).replace(/[&<>"']/g, (c) =>
+ ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]!))
+
+const CW = 400
+const CH = 210
+const PAD = { l: 46, r: 10, t: 14, b: 26 }
+
+/** Axis ticks a person would have chosen. */
+export function niceTicks(min: number, max: number, want = 4): number[] {
+ if (!Number.isFinite(min) || !Number.isFinite(max)) return [0]
+ if (!(max > min)) return [min]
+ const raw = (max - min) / Math.max(1, want)
+ const mag = 10 ** Math.floor(Math.log10(raw))
+ const norm = raw / mag
+ const step = (norm >= 5 ? 10 : norm >= 2 ? 5 : norm >= 1 ? 2 : 1) * mag
+ const out: number[] = []
+ const lo = Math.floor(min / step) * step
+ const hi = Math.ceil(max / step) * step
+ for (let v = lo; v <= hi + step / 1e6; v += step) out.push(Math.abs(v) < step / 1e6 ? 0 : v)
+ return out
+}
+
+/** Axis labels have ~40px; 12,400,000 does not fit and 12.4M does. */
+function short(n: number): string {
+ const a = Math.abs(n)
+ const [d, suffix] = a >= 1e9 ? [1e9, 'B'] : a >= 1e6 ? [1e6, 'M'] : a >= 1e3 ? [1e3, 'k'] : [1, '']
+ const v = n / d
+ return (Math.abs(v) < 10 && v % 1 !== 0 ? v.toFixed(1) : Math.round(v).toString()) + suffix
+}
+
+const clip = (s: string, n = 12): string => (s.length > n ? `${s.slice(0, n - 1)}…` : s)
+
+interface PickAttrs { tile: string; col: string }
+
+/** The attributes that make a mark pickable. `data-blank` is how a null
+ * category survives an HTML attribute round trip — an absent `data-cat` and a
+ * `data-cat=""` are the same string on the way back, and one of them means
+ * the blank category while the other means a bug. */
+const pickAttr = (p: PickAttrs, cat: string | null): string =>
+ `data-tile="${esc(p.tile)}" data-col="${esc(p.col)}" ` +
+ (cat === null ? 'data-blank="1"' : `data-cat="${esc(cat)}"`)
+
+function cartesianSvg(
+ td: Extract<TileData, { kind: 'chart' }>, pick: PickAttrs, on: Set<string | null>,
+): string {
+ const vals = td.series.flatMap((s) => s.data).filter((v): v is number => v !== null)
+ if (!vals.length) return ''
+ const line = td.chart === 'line'
+ // A BAR'S BASELINE IS ZERO. Cropping the axis to the data makes a 2% spread
+ // look like a doubling, which is the oldest chart lie there is. A LINE may
+ // crop — it is read as a trend, not as an area.
+ const lo = Math.min(...vals, line ? Infinity : 0)
+ const hi = Math.max(...vals, line ? -Infinity : 0)
+ const ticks = niceTicks(lo, hi === lo ? lo + 1 : hi)
+ const y0 = ticks[0]
+ const y1 = ticks[ticks.length - 1]
+ const pw = CW - PAD.l - PAD.r
+ const ph = CH - PAD.t - PAD.b
+ const yOf = (v: number): number => PAD.t + ph - ((v - y0) / (y1 - y0 || 1)) * ph
+ const band = pw / Math.max(1, td.cats.length)
+ const dim = on.size > 0
+
+ const parts: string[] = []
+ for (const tv of ticks) {
+ const y = yOf(tv)
+ parts.push(`<line class="dbx-grid" x1="${PAD.l}" y1="${y.toFixed(1)}" x2="${CW - PAD.r}" y2="${y.toFixed(1)}"/>`)
+ parts.push(`<text class="dbx-ytick" x="${PAD.l - 6}" y="${(y + 3.5).toFixed(1)}">${esc(short(tv))}</text>`)
+ }
+
+ const every = Math.ceil(td.cats.length / 9)
+ td.cats.forEach((cat, i) => {
+ const x = PAD.l + i * band
+ const sel = on.has(cat)
+ if (sel) {
+ parts.push(`<rect class="dbx-band-on" x="${x.toFixed(1)}" y="${PAD.t}" width="${band.toFixed(1)}" height="${ph}"/>`)
+ }
+ if (i % every === 0) {
+ parts.push(`<text class="dbx-xtick" x="${(x + band / 2).toFixed(1)}" y="${CH - PAD.b + 14}">${esc(clip(catLabel(cat)))}</text>`)
+ }
+ // The hit target is the whole BAND, not the bar: a 6px bar is not a click
+ // target, and a category whose value is null has no bar at all — but it is
+ // still a category, and refusing to let it be picked would put rows beyond
+ // reach of the reader.
+ parts.push(
+ `<rect class="dbx-hit" ${pickAttr(pick, cat)} x="${x.toFixed(1)}" y="${PAD.t}" ` +
+ `width="${band.toFixed(1)}" height="${ph}"><title>${esc(catLabel(cat))}</title></rect>`,
+ )
+ })
+
+ if (line) {
+ td.series.forEach((s, si) => {
+ const color = td.colors[si % Math.max(1, td.colors.length)] ?? '#888'
+ let run: string[] = []
+ const flush = (): void => {
+ if (run.length > 1) parts.push(`<polyline class="dbx-line" points="${run.join(' ')}" stroke="${esc(color)}"/>`)
+ run = []
+ }
+ s.data.forEach((v, i) => {
+ // A GAP, NEVER A ZERO (chart.ts:16): the line breaks where the data is
+ // missing rather than diving to the axis and back.
+ if (v === null) { flush(); return }
+ const x = PAD.l + i * band + band / 2
+ run.push(`${x.toFixed(1)},${yOf(v).toFixed(1)}`)
+ parts.push(
+ `<circle class="dbx-dot${dim && !on.has(td.cats[i]) ? ' dbx-dim' : ''}" ` +
+ `cx="${x.toFixed(1)}" cy="${yOf(v).toFixed(1)}" r="3" fill="${esc(color)}"/>`,
+ )
+ })
+ flush()
+ })
+ } else {
+ const inner = band * 0.72
+ const bw = inner / Math.max(1, td.series.length)
+ td.series.forEach((s, si) => {
+ const color = td.colors[si % Math.max(1, td.colors.length)] ?? '#888'
+ s.data.forEach((v, i) => {
+ if (v === null) return
+ const x = PAD.l + i * band + (band - inner) / 2 + si * bw
+ const yv = yOf(v)
+ const yz = yOf(Math.min(Math.max(0, y0), y1))
+ const top = Math.min(yv, yz)
+ const h = Math.max(1, Math.abs(yz - yv))
+ parts.push(
+ `<rect class="dbx-bar${dim && !on.has(td.cats[i]) ? ' dbx-dim' : ''}" ` +
+ `x="${x.toFixed(1)}" y="${top.toFixed(1)}" width="${Math.max(1, bw - 1).toFixed(1)}" ` +
+ `height="${h.toFixed(1)}" fill="${esc(color)}"/>`,
+ )
+ })
+ })
+ }
+
+ parts.push(`<line class="dbx-axis" x1="${PAD.l}" y1="${yOf(Math.min(Math.max(0, y0), y1)).toFixed(1)}" x2="${CW - PAD.r}" y2="${yOf(Math.min(Math.max(0, y0), y1)).toFixed(1)}"/>`)
+ return parts.join('')
+}
+
+function pieSvg(
+ td: Extract<TileData, { kind: 'chart' }>, pick: PickAttrs, on: Set<string | null>,
+): string {
+ // A PIE OF NEGATIVE NUMBERS IS NOT A PIE. A slice is a share of a whole, and
+ // a negative share has no angle; drawing |v| would silently show a loss as a
+ // gain. They are dropped and counted, and the tile says how many.
+ const slices = td.cats
+ .map((cat, i) => ({ cat, v: td.series[0]?.data[i] ?? null }))
+ .filter((s): s is { cat: string | null; v: number } => s.v !== null && s.v > 0)
+ const total = slices.reduce((n, s) => n + s.v, 0)
+ if (!slices.length || !(total > 0)) return ''
+
+ const cx = 118
+ const cy = CH / 2
+ const r = 78
+ const dim = on.size > 0
+ const parts: string[] = []
+ let a = -Math.PI / 2
+ slices.forEach((s, i) => {
+ const color = td.colors[i % Math.max(1, td.colors.length)] ?? '#888'
+ const sweep = (s.v / total) * Math.PI * 2
+ const cls = `dbx-slice${dim && !on.has(s.cat) ? ' dbx-dim' : ''}${on.has(s.cat) ? ' dbx-slice-on' : ''}`
+ if (slices.length === 1) {
+ // One slice is a whole circle, and an arc from an angle back to itself
+ // draws nothing at all.
+ parts.push(`<circle class="${cls}" ${pickAttr(pick, s.cat)} cx="${cx}" cy="${cy}" r="${r}" fill="${esc(color)}"><title>${esc(catLabel(s.cat))}</title></circle>`)
+ } else {
+ const x0 = cx + r * Math.cos(a)
+ const y0 = cy + r * Math.sin(a)
+ const x1 = cx + r * Math.cos(a + sweep)
+ const y1 = cy + r * Math.sin(a + sweep)
+ parts.push(
+ `<path class="${cls}" ${pickAttr(pick, s.cat)} fill="${esc(color)}" ` +
+ `d="M${cx} ${cy}L${x0.toFixed(1)} ${y0.toFixed(1)}A${r} ${r} 0 ${sweep > Math.PI ? 1 : 0} 1 ` +
+ `${x1.toFixed(1)} ${y1.toFixed(1)}Z"><title>${esc(catLabel(s.cat))}</title></path>`,
+ )
+ }
+ a += sweep
+ })
+
+ slices.slice(0, 7).forEach((s, i) => {
+ const color = td.colors[i % Math.max(1, td.colors.length)] ?? '#888'
+ const y = 26 + i * 22
+ parts.push(
+ `<g class="dbx-key${dim && !on.has(s.cat) ? ' dbx-dim' : ''}" ${pickAttr(pick, s.cat)}>` +
+ `<rect class="dbx-swatch" x="228" y="${y - 9}" width="10" height="10" fill="${esc(color)}"/>` +
+ `<text class="dbx-keytext" x="244" y="${y}">${esc(clip(catLabel(s.cat), 16))} · ` +
+ `${esc(Math.round((s.v / total) * 100))}%</text></g>`,
+ )
+ })
+ return parts.join('')
+}
+
+function chartSvg(
+ td: Extract<TileData, { kind: 'chart' }>, pick: PickAttrs, on: Set<string | null>,
+): string {
+ const body = td.chart === 'pie' ? pieSvg(td, pick, on) : cartesianSvg(td, pick, on)
+ if (!body) return `<div class="dbx-empty">${esc(t('Nothing numeric to plot for this selection.'))}</div>`
+ const legend = td.chart !== 'pie' && td.series.length > 1
+ ? `<div class="dbx-legend">${td.series.map((s, i) =>
+ `<span><i style="background:${esc(td.colors[i % Math.max(1, td.colors.length)] ?? '#888')}"></i>${esc(s.name)}</span>`).join('')}</div>`
+ : ''
+ return `${legend}<svg class="dbx-svg" viewBox="0 0 ${CW} ${CH}" preserveAspectRatio="xMidYMid meet" role="img">${body}</svg>`
+}
+
+// --- The surface -----------------------------------------------------------
+
+export interface DashboardHost {
+ el: HTMLElement
+ store: Store
+ /** Which stored view to show. Absent means the first one. */
+ viewId?: string
+}
+
+export class Dashboard {
+ private host: HTMLElement
+ private store: Store
+ private offs: Array<() => void> = []
+ /** A dashboard minted for a workbook that carries none. Ephemeral: it is
+ * never written to the document by being looked at. */
+ private fallback: DashView | null = null
+ private fallbackFor = ''
+
+ viewId?: string
+ /** VIEWER state. Never in the document, never synced, never undoable — the
+ * same tier as the grid's sort and the reduce-motion flag in slides. */
+ selection: CrossSelection = []
+ /**
+ * The grid's recalculated formula columns, so a tile can chart a column that
+ * is nowhere in the document.
+ *
+ * A CALLBACK, not a Map: `Grid.paint` REPLACES `grid.computed` on every
+ * recalculation rather than mutating it, so a field holding the map would
+ * hold last recalculation's copy — a tile quietly plotting a formula column
+ * as it was two edits ago, which is exactly the staleness deriving at render
+ * exists to prevent. Reading it through a function cannot go stale.
+ */
+ computed?: () => Map<string, unknown[]> | undefined
+ onSelectionChange?: (sel: CrossSelection) => void
+
+ constructor(opts: DashboardHost) {
+ this.host = opts.el
+ this.store = opts.store
+ this.viewId = opts.viewId
+ this.host.classList.add('dbx')
+ this.host.addEventListener('click', this.onClick)
+ // Both events: 'doc' because a cell edit must move every tile, 'view'
+ // because that is what a pick emits.
+ this.offs.push(this.store.on('doc', this.render))
+ this.offs.push(this.store.on('view', this.render))
+ this.render()
+ }
+
+ destroy(): void {
+ this.host.removeEventListener('click', this.onClick)
+ for (const off of this.offs) off()
+ this.offs = []
+ this.host.innerHTML = ''
+ }
+
+ /** The dashboard being shown: the document's, or a minted one. */
+ get view(): DashView | null {
+ const views = viewsOf(this.store.doc)
+ const stored = this.viewId ? views.find((v) => v.id === this.viewId) : views[0]
+ if (stored) return stored
+ // Re-mint when the workbook changes identity (a load, a replaceDoc), and
+ // not on every paint — a fresh object each frame would throw away the tile
+ // ids the selection is keyed by.
+ const key = `${this.store.doc.docId}:${this.store.doc.sheets.map((s: Sheet) => s.id).join(',')}`
+ if (this.fallbackFor !== key) {
+ this.fallback = defaultDashboard(this.store.doc)
+ this.fallbackFor = key
+ }
+ return this.fallback
+ }
+
+ /**
+ * Pick a category, or let it go.
+ *
+ * THROUGH `store.view()`: no checkpoint, no dirty flag, no op. This one call
+ * is the difference between a dashboard you can explore and a file that
+ * rewrites itself while you do.
+ */
+ pick(entry: SelectionEntry): void {
+ this.store.view(() => { this.selection = toggleSelection(this.selection, entry) })
+ this.onSelectionChange?.(this.selection)
+ }
+
+ clearSelection(): void {
+ if (!this.selection.length) return
+ this.store.view(() => { this.selection = [] })
+ this.onSelectionChange?.(this.selection)
+ }
+
+ private onClick = (ev: MouseEvent): void => {
+ const el = (ev.target as HTMLElement | null)?.closest<HTMLElement>('[data-tile]')
+ if (el) {
+ const tile = el.dataset.tile!
+ const col = el.dataset.col!
+ const sheet = el.closest<HTMLElement>('.dbx-tile')?.dataset.sheet
+ ?? this.view?.tiles.find((x) => x.id === tile)?.bind?.sheet
+ if (!sheet) return
+ const cat = el.hasAttribute('data-blank') ? null : (el.dataset.cat ?? '')
+ this.pick({ from: tile, sheet, col, v: cat })
+ return
+ }
+ const chip = (ev.target as HTMLElement | null)?.closest<HTMLElement>('[data-chip]')
+ if (chip) {
+ const i = Number(chip.dataset.chip)
+ const e = this.selection[i]
+ if (e) this.pick(e)
+ return
+ }
+ if ((ev.target as HTMLElement | null)?.closest('[data-clear]')) this.clearSelection()
+ }
+
+ render = (): void => {
+ const doc = this.store.doc
+ const view = this.view
+ if (!view) {
+ this.host.innerHTML = `<div class="dbx-blank">${esc(t('This workbook has no dashboard yet.'))}</div>`
+ return
+ }
+ const chips = selectionChips(this.selection, doc)
+ const bar = chips.length
+ ? `<div class="dbx-chips"><span class="dbx-chips-label">${esc(t('Filtered by'))}</span>` +
+ chips.map((c, i) =>
+ `<button class="dbx-chip" data-chip="${i}" title="${esc(t('Remove this filter'))}">${esc(c.label)} ✕</button>`).join('') +
+ `<button class="dbx-chip dbx-chip-clear" data-clear="1">${esc(t('Clear all'))}</button></div>`
+ : `<div class="dbx-chips dbx-chips-idle">${esc(t('Click a bar, a slice or a row to filter every tile.'))}</div>`
+
+ const tiles = view.tiles.map((tile) => this.tileHtml(doc, tile)).join('')
+ this.host.style.setProperty('--dbx-cols', String(Math.max(1, view.w || DEFAULT_COLS)))
+ this.host.innerHTML = `${bar}<div class="dbx-grid-wrap">${tiles}</div>`
+ }
+
+ private tileHtml(doc: DashDoc, tile: DashTile): string {
+ const sheet = tableOf(doc, tile.bind?.sheet)
+ // EVERY PAINT RE-DERIVES (rule 2): the filters, the rows and the numbers.
+ const filters = selectionFilters(this.selection, tile)
+ const computed = this.computed?.()
+ const rows = sheet ? rowsForTile(sheet, sheetGet(sheet, computed), filters) : null
+ const td = deriveTile(doc, tile, rows, computed)
+
+ const style = `grid-column:${tile.x + 1}/span ${Math.max(1, tile.w)};` +
+ `grid-row:${tile.y + 1}/span ${Math.max(1, tile.h)}`
+ const head = tile.title
+ ? `<div class="dbx-head"><span class="dbx-title">${esc(tile.title)}</span>` +
+ (filters.length ? `<span class="dbx-filtered" title="${esc(t('This tile is filtered by another tile'))}">▼</span>` : '') +
+ `</div>`
+ : ''
+ return `<section class="dbx-tile dbx-${esc(tile.kind)}" data-sheet="${esc(tile.bind?.sheet ?? '')}" style="${style}">` +
+ `${head}<div class="dbx-body">${this.bodyHtml(tile, td)}</div></section>`
+ }
+
+ private bodyHtml(tile: DashTile, td: TileData): string {
+ const note = (s: string | undefined): string => (s ? `<div class="dbx-note">${esc(s)}</div>` : '')
+ switch (td.kind) {
+ case 'empty':
+ return `<div class="dbx-empty">${esc(EMPTY_TEXT[td.reason]())}</div>${note(td.note)}`
+ case 'text':
+ return `<div class="dbx-text">${esc(td.text)}</div>`
+ case 'chart': {
+ const col = tile.bind?.x ?? ''
+ return chartSvg(td, { tile: tile.id, col }, pickedOn(this.selection, tile, col)) + note(td.note)
+ }
+ case 'kpi':
+ return this.kpiHtml(td) + note(td.note)
+ case 'table':
+ return this.tableHtml(tile, td)
+ }
+ }
+
+ private kpiHtml(td: Extract<TileData, { kind: 'kpi' }>): string {
+ // "—", NEVER "0". A KPI showing zero for "we could not compute this" is the
+ // single most expensive wrong number a dashboard can print.
+ const asText = (v: number | null, col?: Column): string =>
+ v === null ? '—'
+ : td.agg === 'count' ? v.toLocaleString()
+ : formatValue(v, col ?? { type: 'number' })
+ const value = asText(td.value, td.column)
+ let sub: string
+ if (td.compare === 'all' && td.baseline !== null) {
+ // "of all" is a SHARE, never a delta: a filtered slice being smaller than
+ // the whole is not a fall, and colouring it red would say it was.
+ sub = `${td.share === null ? '—' : `${Math.round(td.share * 100)}%`} ${td.baselineLabel ?? ''}` +
+ ` · ${asText(td.baseline, td.column)}`
+ } else if (td.compare === 'column' && td.baseline !== null) {
+ const pct = td.pct === null ? '—' : `${td.pct > 0 ? '+' : ''}${Math.round(td.pct * 100)}%`
+ sub = `${pct} ${t('vs')} ${td.baselineLabel ?? ''} ${asText(td.baseline, td.baselineColumn)}`
+ } else {
+ sub = `${td.rows.toLocaleString()} ${td.rows === 1 ? t('row') : t('rows')}`
+ }
+ const dir = td.compare !== 'column' || td.delta === null || td.delta === 0
+ ? '' : td.delta > 0 ? ' dbx-up' : ' dbx-down'
+ return `<div class="dbx-value">${esc(value)}</div><div class="dbx-sub${dir}">${esc(sub)}</div>`
+ }
+
+ private tableHtml(tile: DashTile, td: Extract<TileData, { kind: 'table' }>): string {
+ const doc = this.store.doc
+ const sheet = tableOf(doc, tile.bind?.sheet)!
+ const get = sheetGet(sheet, this.computed?.())
+ const by = td.by
+ const on = pickedOn(this.selection, tile, by)
+ const shown = td.rows.slice(0, TABLE_ROWS)
+ const head = `<tr>${td.cols.map((c) => `<th>${esc(c.name)}</th>`).join('')}</tr>`
+ const body = shown.map((r) => {
+ const cat = by ? catOf(get(by, r)) : undefined
+ const attrs = by ? ` ${pickAttr({ tile: tile.id, col: by }, cat ?? null)}` : ''
+ const cls = by && on.has(cat ?? null) ? ' class="dbx-row-on"' : ''
+ return `<tr${cls}${attrs}>${td.cols.map((c) =>
+ `<td>${esc(formatValue(get(c.id, r), c))}</td>`).join('')}</tr>`
+ }).join('')
+ // The footer states BOTH numbers. "200 rows" under a filtered table is how
+ // a reader quotes a subtotal as a total.
+ const foot = `<div class="dbx-note">${esc(
+ td.rows.length === td.total
+ ? t('{n} rows').replace('{n}', td.total.toLocaleString())
+ : t('{k} of {n} rows').replace('{k}', td.rows.length.toLocaleString()).replace('{n}', td.total.toLocaleString()),
+ )}${td.rows.length > shown.length ? esc(` · ${t('showing the first {k}').replace('{k}', String(TABLE_ROWS))}`) : ''}</div>`
+ return `<div class="dbx-scroll"><table class="dbx-table">${head}${body}</table></div>${foot}`
+ }
+}
+
+/**
+ * Why a tile is empty, said in words.
+ *
+ * Functions, not a frozen record: `t()` must never be called at module scope
+ * (PLATFORM §8 — the catalog is not loaded yet and the string freezes in
+ * English forever).
+ */
+const EMPTY_TEXT: Record<EmptyReason, () => string> = {
+ 'no-rows': () => t('No rows match the current selection.'),
+ 'no-values': () => t('Nothing numeric to plot for this selection.'),
+ 'no-sheet': () => t('This tile points at a sheet that is not in this workbook.'),
+ 'no-binding': () => t('This tile is not bound to any columns yet.'),
+ 'unknown-kind': () => t('This tile needs a newer version of dash.'),
+}
+
+export const _internals = { esc, short, clip, chartSvg, cartesianSvg, pieSvg, CW, CH }
diff --git a/dash/src/filter.ts b/dash/src/filter.ts
new file mode 100644
index 00000000..942853b2
Binary files /dev/null and b/dash/src/filter.ts differ
diff --git a/dash/src/formula.ts b/dash/src/formula.ts
index 39f9dc07..58fe2292 100644
--- a/dash/src/formula.ts
+++ b/dash/src/formula.ts
@@ -206,7 +206,26 @@ const bool = (v: Cell): boolean => {
const numbersIn = (v: Vec): number[] =>
v.map(num).filter((x): x is number => typeof x === 'number')
+const REF = '#REF!'
+
const AGG: Record<string, (v: Vec) => Cell> = {
+ VAR: (v) => variance(numbersIn(v), true),
+ VARP: (v) => variance(numbersIn(v), false),
+ STDEVP: (v) => { const r = variance(numbersIn(v), false); return isErr(r) ? r : Math.sqrt(r as number) },
+ COUNTUNIQUE: (v) => new Set(v.filter((x) => x != null && x !== '').map((x) => String(x))).size,
+ MODE: (v) => {
+ const n = numbersIn(v)
+ if (!n.length) return ERR.na()
+ const seen = new Map<number, number>()
+ let best = n[0]
+ let bestC = 0
+ for (const x of n) {
+ const c = (seen.get(x) ?? 0) + 1
+ seen.set(x, c)
+ if (c > bestC) { bestC = c; best = x }
+ }
+ return bestC > 1 ? best : ERR.na()
+ },
SUM: (v) => numbersIn(v).reduce((a, b) => a + b, 0),
AVERAGE: (v) => { const n = numbersIn(v); return n.length ? n.reduce((a, b) => a + b, 0) / n.length : ERR.div0() },
MIN: (v) => { const n = numbersIn(v); return n.length ? Math.min(...n) : 0 },
@@ -233,12 +252,119 @@ AGG.AVG = AGG.AVERAGE
/** SUMIF/COUNTIF/AVERAGEIF — high-frequency, so worth having in v1. */
const CONDITIONAL = new Set(['SUMIF', 'COUNTIF', 'AVERAGEIF'])
+/**
+ * The multi-criteria family: `SUMIFS(sum, r1, c1, r2, c2, …)`.
+ *
+ * Note the argument order is NOT SUMIF's. Excel put the sum range LAST in
+ * SUMIF and FIRST in SUMIFS, and every spreadsheet in the world now depends on
+ * both. Matching Excel here is not politeness — a formula pasted from a
+ * colleague's workbook has to mean the same thing or the number is wrong and
+ * looks fine.
+ */
+const MULTI = new Set(['SUMIFS', 'COUNTIFS', 'AVERAGEIFS', 'MINIFS', 'MAXIFS'])
+
+/** Lookups. Vector-shaped, because dash is column-shaped — see LOOKUP_NOTE. */
+const LOOKUPS = new Set(['XLOOKUP', 'VLOOKUP', 'INDEX', 'MATCH', 'LOOKUP'])
+
const round = (x: number, dp: number) => {
const f = 10 ** dp
return Math.round((x + Number.EPSILON * Math.sign(x)) * f) / f
}
+const nums = (a: Array<Cell | Vec>): number[] =>
+ a.flatMap((x) => (Array.isArray(x) ? x : [x]))
+ .map((x) => num(x as Cell)).filter((x): x is number => typeof x === 'number')
+
+/**
+ * Functions that consume a WHOLE COLUMN, dispatched before SCALAR.
+ *
+ * SCALAR broadcasts: it finds the widest vector argument and calls the function
+ * once per row, which is exactly right for `ROUND(value, 2)` and exactly wrong
+ * for `CORREL(a, b)` — that ran per row and correlated two single numbers,
+ * which is 0/0. Same for IRR over a column of cash flows, PERCENTILE over a
+ * column, and TEXTJOIN of one. They take the arguments UNBROADCAST.
+ */
+const RAW: Record<string, (a: Array<Cell | Vec>) => Cell> = {
+ NPV: (a) => { const r = num(a[0] as Cell); return isErr(r) ? r : npv(r, nums(a.slice(1))) },
+ IRR: (a) => irr(nums(a)),
+ PERCENTILE: (a) => { const k = num(a[1] as Cell); return isErr(k) ? k : percentile(nums([a[0]]), k) },
+ QUARTILE: (a) => { const q = num(a[1] as Cell); return isErr(q) ? q : percentile(nums([a[0]]), (q as number) / 4) },
+ CORREL: (a) => correl(nums([a[0]]), nums([a[1]])),
+ RANK: (a) => {
+ const v = num(a[0] as Cell)
+ if (isErr(v)) return v
+ const list = nums([a[1]])
+ const desc = a[2] === undefined || num(a[2] as Cell) === 0
+ const sorted = [...list].sort((x, y) => (desc ? y - x : x - y))
+ const i = sorted.findIndex((x) => x === v)
+ return i < 0 ? ERR.na() : i + 1
+ },
+ TEXTJOIN: (a) => {
+ const sep = str(a[0] as Cell)
+ const skip = bool(a[1] as Cell)
+ const parts = a.slice(2).flatMap((x) => (Array.isArray(x) ? x : [x])).map((x) => str(x as Cell))
+ return (skip ? parts.filter((p) => p !== '') : parts).join(sep)
+ },
+}
+
const SCALAR: Record<string, (a: Cell[]) => Cell> = {
+ // --- logic
+ // TRUE()/FALSE() are functions in Excel, and people type them. Their absence
+ // was not an error either: `TRUE()` parsed as an unknown NAME, so `IF(TRUE(),
+ // …)` quietly took the false branch.
+ TRUE: () => true,
+ FALSE: () => false,
+ IFS: (a) => {
+ for (let i = 0; i + 1 < a.length; i += 2) if (bool(a[i])) return a[i + 1]
+ return ERR.na()
+ },
+ SWITCH: (a) => {
+ for (let i = 1; i + 1 < a.length; i += 2) if (looseEq(a[0], a[i])) return a[i + 1]
+ // an odd trailing argument is the default, as Excel has it
+ return a.length % 2 === 0 ? a[a.length - 1] : ERR.na()
+ },
+ XOR: (a) => a.filter(bool).length % 2 === 1,
+ IFNA: (a) => (isErr(a[0]) && String(a[0]) === '#N/A' ? a[1] ?? '' : a[0]),
+ // --- text
+ PROPER: (a) => str(a[0]).replace(/\w\S*/g, (w) => w[0].toUpperCase() + w.slice(1).toLowerCase()),
+ REPT: (a) => { const n = num(a[1]); return isErr(n) ? n : n < 0 ? ERR.value('negative count') : str(a[0]).repeat(Math.floor(n)) },
+ DATE: (a) => {
+ const y = num(a[0]); const m = num(a[1]); const d = num(a[2])
+ if (isErr(y)) return y; if (isErr(m)) return m; if (isErr(d)) return d
+ return isoOf(new Date(Date.UTC(y, m - 1, d)))
+ },
+ EOMONTH: (a) => {
+ const d = asDate(a[0]); const k = num(a[1] ?? 0)
+ if (!d) return ERR.value('not a date'); if (isErr(k)) return k
+ return isoOf(new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + k + 1, 0)))
+ },
+ EDATE: (a) => {
+ const d = asDate(a[0]); const k = num(a[1] ?? 0)
+ if (!d) return ERR.value('not a date'); if (isErr(k)) return k
+ return isoOf(new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + k, d.getUTCDate())))
+ },
+ DAYS: (a) => {
+ const b = asDate(a[0]); const c = asDate(a[1])
+ return b && c ? Math.round((b.getTime() - c.getTime()) / DAY_MS) : ERR.value('not a date')
+ },
+ WEEKDAY: (a) => { const d = asDate(a[0]); return d ? d.getUTCDay() + 1 : ERR.value('not a date') },
+ // --- finance. Every rate is PER PERIOD; nothing here divides by twelve for you.
+ PMT: (a) => {
+ const r = num(a[0]); const n = num(a[1]); const p = num(a[2])
+ if (isErr(r)) return r; if (isErr(n)) return n; if (isErr(p)) return p
+ return pmt(r, n, p, a[3] === undefined ? 0 : (num(a[3]) as number), a[4] === undefined ? 0 : (num(a[4]) as number))
+ },
+ FV: (a) => {
+ const r = num(a[0]); const n = num(a[1]); const p = num(a[2])
+ if (isErr(r)) return r; if (isErr(n)) return n; if (isErr(p)) return p
+ return fvOf(r, n, p, a[3] === undefined ? 0 : (num(a[3]) as number), a[4] === undefined ? 0 : (num(a[4]) as number))
+ },
+ PV: (a) => {
+ const r = num(a[0]); const n = num(a[1]); const p = num(a[2])
+ if (isErr(r)) return r; if (isErr(n)) return n; if (isErr(p)) return p
+ return pvOf(r, n, p, a[3] === undefined ? 0 : (num(a[3]) as number), a[4] === undefined ? 0 : (num(a[4]) as number))
+ },
+ // --- statistics over explicit arguments
IF: (a) => (bool(a[0]) ? a[1] ?? true : a[2] ?? false),
AND: (a) => a.every(bool),
OR: (a) => a.some(bool),
@@ -368,6 +494,179 @@ function matches(v: Cell, crit: Cell): boolean {
return bool(r as Cell)
}
+// --- lookups ----------------------------------------------------------------
+//
+// LOOKUP_NOTE. dash is COLUMN-shaped: a reference resolves to a vector, and a
+// range binds to one flat vector of the cells it covers. Excel's VLOOKUP takes
+// a 2-D table and a column NUMBER, which only means something if the shape is
+// known — so a range carries its width, and VLOOKUP reads it. Where the shape
+// is unknown (a bare column), a `col` of 1 is the column itself and anything
+// higher is #REF!, which is what Excel says when you index past the table.
+//
+// XLOOKUP is the one to reach for and the one that fits dash without
+// contortion: two vectors, no index arithmetic, and no silent breakage when a
+// column is inserted in the middle of the table — the failure VLOOKUP is
+// famous for. VLOOKUP exists because people's existing formulas use it.
+
+/** A range's shape, when the binding knew it. See cellformula.ts's bindRefs. */
+export interface Shaped { __rows?: number; __cols?: number }
+const shapeOf = (v: Vec): { rows: number; cols: number } => {
+ const s = v as Vec & Shaped
+ const cols = typeof s.__cols === 'number' && s.__cols > 0 ? s.__cols : 1
+ return { rows: Math.ceil(v.length / cols), cols }
+}
+
+/** Row-major cell at (r, c) of a shaped range. */
+const cellAt = (v: Vec, r: number, c: number): Cell => {
+ const { cols } = shapeOf(v)
+ return v[r * cols + c] ?? null
+}
+
+/**
+ * First index in `hay` matching `needle`.
+ *
+ * EXACT by default, and that is a deliberate departure from VLOOKUP's legacy
+ * 4th argument defaulting to TRUE (approximate). An approximate match on
+ * UNSORTED data returns a confidently wrong row, and that default has produced
+ * more quiet spreadsheet errors than any other single thing in Excel. Ours
+ * defaults to exact; approximate is available by asking for it.
+ */
+function findIndex(hay: Vec, needle: Cell, approx = false): number {
+ if (!approx) {
+ for (let i = 0; i < hay.length; i++) if (looseEq(hay[i], needle)) return i
+ return -1
+ }
+ // approximate: the LAST value <= needle, which assumes ascending order —
+ // Excel's rule, and its documented requirement
+ let best = -1
+ for (let i = 0; i < hay.length; i++) {
+ const c = binop('<=', hay[i], needle)
+ if (c === true) best = i
+ }
+ return best
+}
+
+const asVec = (v: Cell | Vec): Vec => (Array.isArray(v) ? v : [v])
+
+// --- finance ----------------------------------------------------------------
+//
+// The reason a finance team opens Excel rather than anything else. All of these
+// take a RATE PER PERIOD, not an annual rate — the single most common way these
+// get used wrongly, so the argument is named `rate` everywhere and never
+// silently divided by twelve.
+
+/** Net present value of `flows`, discounted one period each, first flow at t=1. */
+const npv = (rate: number, flows: number[]): number =>
+ flows.reduce((acc, f, i) => acc + f / (1 + rate) ** (i + 1), 0)
+
+/**
+ * Internal rate of return: the rate at which NPV is zero.
+ *
+ * Bisection, not Newton-Raphson. Newton is faster and diverges on exactly the
+ * cash-flow shapes people have (a sign change late in the series), returning a
+ * number rather than failing. Bisection over a bracketed range either converges
+ * or reports #NUM!, and a refusal is worth more than a plausible rate.
+ */
+function irr(flows: number[], guess = 0.1): Cell {
+ const f = (r: number) => flows.reduce((a, c, i) => a + c / (1 + r) ** i, 0)
+ let lo = -0.9999
+ let hi = 10
+ let flo = f(lo)
+ let fhi = f(hi)
+ if (!Number.isFinite(flo) || !Number.isFinite(fhi) || flo * fhi > 0) {
+ void guess
+ return new FormulaError('#NUM!', 'no rate brackets a sign change in these cash flows')
+ }
+ for (let i = 0; i < 200; i++) {
+ const mid = (lo + hi) / 2
+ const fm = f(mid)
+ if (Math.abs(fm) < 1e-10) return mid
+ if (flo * fm < 0) { hi = mid; fhi = fm } else { lo = mid; flo = fm }
+ }
+ void fhi
+ return (lo + hi) / 2
+}
+
+/** Payment per period for a loan. Excel's sign convention: a payment is negative. */
+const pmt = (rate: number, nper: number, pv: number, fv = 0, type = 0): number => {
+ if (rate === 0) return -(pv + fv) / nper
+ const p = (1 + rate) ** nper
+ return -(pv * p + fv) * rate / ((p - 1) * (1 + rate * (type ? 1 : 0)))
+}
+
+const fvOf = (rate: number, nper: number, pmtv: number, pv = 0, type = 0): number => {
+ if (rate === 0) return -(pv + pmtv * nper)
+ const p = (1 + rate) ** nper
+ return -(pv * p + pmtv * (1 + rate * (type ? 1 : 0)) * (p - 1) / rate)
+}
+
+const pvOf = (rate: number, nper: number, pmtv: number, fv = 0, type = 0): number => {
+ if (rate === 0) return -(fv + pmtv * nper)
+ const p = (1 + rate) ** nper
+ return -(fv + pmtv * (1 + rate * (type ? 1 : 0)) * (p - 1) / rate) / p
+}
+
+// --- statistics -------------------------------------------------------------
+
+/**
+ * Linear-interpolated percentile, Excel's PERCENTILE.INC.
+ *
+ * `k` is a FRACTION (0.9), not a percentage (90) — passing 90 gets #NUM! rather
+ * than being clamped to the maximum, because clamping would silently answer a
+ * question nobody asked.
+ */
+function percentile(nums: number[], k: number): Cell {
+ if (!nums.length) return ERR.div0()
+ if (!(k >= 0 && k <= 1)) return new FormulaError('#NUM!', 'percentile takes a fraction between 0 and 1')
+ const s = [...nums].sort((a, b) => a - b)
+ const pos = k * (s.length - 1)
+ const lo = Math.floor(pos)
+ const hi = Math.ceil(pos)
+ return lo === hi ? s[lo] : s[lo] + (s[hi] - s[lo]) * (pos - lo)
+}
+
+/** Sample variance (n−1). VARP/STDEVP use the population divisor. */
+const variance = (nums: number[], sample: boolean): Cell => {
+ const n = nums.length
+ if (n < (sample ? 2 : 1)) return ERR.div0()
+ const mean = nums.reduce((a, b) => a + b, 0) / n
+ const ss = nums.reduce((a, b) => a + (b - mean) ** 2, 0)
+ return ss / (sample ? n - 1 : n)
+}
+
+function correl(xs: number[], ys: number[]): Cell {
+ const n = Math.min(xs.length, ys.length)
+ if (n < 2) return ERR.div0()
+ const mx = xs.slice(0, n).reduce((a, b) => a + b, 0) / n
+ const my = ys.slice(0, n).reduce((a, b) => a + b, 0) / n
+ let sxy = 0
+ let sxx = 0
+ let syy = 0
+ for (let i = 0; i < n; i++) {
+ const dx = xs[i] - mx
+ const dy = ys[i] - my
+ sxy += dx * dy; sxx += dx * dx; syy += dy * dy
+ }
+ const d = Math.sqrt(sxx * syy)
+ return d === 0 ? ERR.div0() : sxy / d
+}
+
+// --- dates ------------------------------------------------------------------
+//
+// Dates are ISO STRINGS in dash, not serial numbers (model.ts). So date maths
+// parses, computes in UTC and formats back — never through the local timezone,
+// which would move a date across midnight for half the world's readers.
+
+const asDate = (v: Cell): Date | null => {
+ if (typeof v !== 'string') return null
+ const m = v.match(/^(\d{4})-(\d{2})-(\d{2})/)
+ if (!m) return null
+ const d = new Date(Date.UTC(+m[1], +m[2] - 1, +m[3]))
+ return Number.isNaN(d.getTime()) ? null : d
+}
+const isoOf = (d: Date): string => d.toISOString().slice(0, 10)
+const DAY_MS = 86_400_000
+
function callFn(node: Node & { k: 'call' }, ctx: EvalCtx): Cell | Vec {
const name = node.name
@@ -392,6 +691,77 @@ function callFn(node: Node & { k: 'call' }, ctx: EvalCtx): Cell | Vec {
if (name === 'SUMIF') return vals.reduce((a, b) => a + b, 0)
return vals.length ? vals.reduce((a, b) => a + b, 0) / vals.length : ERR.div0()
}
+ if (MULTI.has(name)) {
+ // SUMIFS(sum, r1, c1, …) / COUNTIFS(r1, c1, …) — count has no sum range.
+ const counting = name === 'COUNTIFS'
+ const target = counting ? null : asVec(evalNode(node.args[0], ctx))
+ const pairsFrom = counting ? 0 : 1
+ const pairs: Array<{ range: Vec; crit: Cell | Vec }> = []
+ for (let i = pairsFrom; i + 1 < node.args.length; i += 2) {
+ pairs.push({
+ range: asVec(evalNode(node.args[i], ctx)),
+ crit: evalNode(node.args[i + 1], ctx),
+ })
+ }
+ if (!pairs.length) return ERR.value(`${name} needs at least one range and criterion`)
+ const rows = Math.max(...pairs.map((p) => p.range.length), target?.length ?? 0)
+ const keep: number[] = []
+ for (let i = 0; i < rows; i++) {
+ // EVERY criterion must hold. `some` here instead of `every` is the bug
+ // that turns a two-condition report into a one-condition one, and the
+ // total still looks like a total.
+ if (pairs.every((p) => matches(p.range[i] ?? null, at(p.crit, i)))) keep.push(i)
+ }
+ if (counting) return keep.length
+ const vals = keep.map((i) => num(target![i] ?? null)).filter((x): x is number => typeof x === 'number')
+ if (name === 'SUMIFS') return vals.reduce((a, b) => a + b, 0)
+ if (!vals.length) return name === 'AVERAGEIFS' ? ERR.div0() : 0
+ if (name === 'AVERAGEIFS') return vals.reduce((a, b) => a + b, 0) / vals.length
+ return name === 'MINIFS' ? Math.min(...vals) : Math.max(...vals)
+ }
+
+ if (LOOKUPS.has(name)) {
+ const a = node.args.map((x) => evalNode(x, ctx))
+ if (name === 'MATCH') {
+ const i = findIndex(asVec(a[1]), a[0] as Cell, num((a[2] ?? 0) as Cell) !== 0)
+ return i < 0 ? ERR.na() : i + 1 // 1-based, as Excel reports it
+ }
+ if (name === 'INDEX') {
+ const v = asVec(a[0])
+ const n = num(a[1] as Cell)
+ if (isErr(n)) return n
+ // INDEX(range, row, col) on a shaped range; INDEX(vector, n) otherwise
+ if (node.args.length > 2) {
+ const c = num(a[2] as Cell)
+ if (isErr(c)) return c
+ return cellAt(v, n - 1, c - 1)
+ }
+ return n >= 1 && n <= v.length ? v[n - 1] : new FormulaError(REF, 'index is outside the range')
+ }
+ if (name === 'XLOOKUP') {
+ const i = findIndex(asVec(a[1]), a[0] as Cell)
+ if (i < 0) return a[3] !== undefined ? (a[3] as Cell) : ERR.na()
+ return asVec(a[2])[i] ?? null
+ }
+ if (name === 'LOOKUP') {
+ const i = findIndex(asVec(a[1]), a[0] as Cell, true)
+ return i < 0 ? ERR.na() : asVec(a[2] ?? a[1])[i] ?? null
+ }
+ // VLOOKUP(value, table, col, [approx])
+ const table = asVec(a[1])
+ const { cols } = shapeOf(table)
+ const colN = num(a[2] as Cell)
+ if (isErr(colN)) return colN
+ if (colN < 1 || colN > cols) return new FormulaError(REF, `column ${colN} is outside a ${cols}-column range`)
+ const firstCol: Vec = []
+ for (let r = 0; r * cols < table.length; r++) firstCol.push(cellAt(table, r, 0))
+ const i = findIndex(firstCol, a[0] as Cell, a[3] !== undefined && bool(a[3] as Cell))
+ return i < 0 ? ERR.na() : cellAt(table, i, colN - 1)
+ }
+
+ const raw = RAW[name]
+ if (raw) return raw(node.args.map((x) => evalNode(x, ctx)))
+
const fn = SCALAR[name]
if (!fn) return ERR.name(name)
@@ -495,5 +865,6 @@ export function recalc(sheet: TableSheet, now?: string): RecalcResult {
/** Every function name this build knows — the agent surface needs to say. */
export const FUNCTIONS: string[] = [
- ...Object.keys(AGG), ...CONDITIONAL, ...Object.keys(SCALAR), ...VOLATILE,
+ ...Object.keys(AGG), ...CONDITIONAL, ...MULTI, ...LOOKUPS,
+ ...Object.keys(RAW), ...Object.keys(SCALAR), ...VOLATILE,
].sort()
diff --git a/dash/src/gl.ts b/dash/src/gl.ts
new file mode 100644
index 00000000..2459f697
--- /dev/null
+++ b/dash/src/gl.ts
@@ -0,0 +1,680 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// A minimal WebGL2 layer: the maths, and a thin wrapper over the context.
+//
+// WHY HAND-ROLLED. three.js is 600 KB+ minified; this shell is 43 KB
+// compressed in total. A project that deleted ECharts for being 47% of the
+// file and refused DuckDB-WASM at 9.4 MB cannot then ship a renderer twelve
+// times the size of the app to draw points and boxes. What a data viewer
+// actually needs is one camera, one projection, buffers of floats, and a
+// draw call — measured here at 8.8 KB minified, 3.7 KB deflated standalone
+// (less in-shell, where it shares a compression dictionary with the rest of
+// the bundle). That is 0.6% of three.js. Everything else in a scene graph
+// (materials, loaders, lights, raycasters, a whole node hierarchy) is weight
+// with no reader-visible return.
+//
+// THE MATHS IS PURE AND THE GL IS NOT. Every function above `GLView` runs in
+// node with no DOM, which is why the rig can test the camera at all — the
+// bugs that matter (a transposed multiply, a flipped screen y, a gimbal flip
+// at the pole) are arithmetic, and arithmetic is testable. Below `GLView`
+// nothing is testable in node, so that part is kept as small and as boring as
+// it can be.
+//
+// COLUMN-MAJOR, LIKE GL. `m[col * 4 + row]`, so a Mat4 goes straight into
+// `uniformMatrix4fv(loc, false, m)` with no transpose. Row-major storage plus
+// `transpose = true` is a legal alternative that WebGL1 did not support and
+// that every shader author then has to remember; one convention, matching the
+// platform's, is cheaper than being clever.
+//
+// FLOAT64 FOR THE MATHS, FLOAT32 AT THE BOUNDARY. Data ranges in a dashboard
+// are not tidy (timestamps in ms, revenue in pence): f32 has 24 bits of
+// mantissa and a camera composed of five f32 matrices visibly jitters at those
+// magnitudes. The conversion happens once per uniform per frame in `setUniform`
+// — note that `uniformMatrix4fv` REJECTS a Float64Array outright, so the copy
+// is not optional anyway.
+
+// --- vectors ----------------------------------------------------------------
+
+export type Vec3 = [number, number, number]
+
+export const add = (a: Vec3, b: Vec3): Vec3 => [a[0] + b[0], a[1] + b[1], a[2] + b[2]]
+export const sub = (a: Vec3, b: Vec3): Vec3 => [a[0] - b[0], a[1] - b[1], a[2] - b[2]]
+export const dot = (a: Vec3, b: Vec3): number => a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+export const cross = (a: Vec3, b: Vec3): Vec3 => [
+ a[1] * b[2] - a[2] * b[1],
+ a[2] * b[0] - a[0] * b[2],
+ a[0] * b[1] - a[1] * b[0],
+]
+export const length = (a: Vec3): number => Math.hypot(a[0], a[1], a[2])
+
+/** Vec3 scale. Named `vscale` because `scale` is the Mat4 builder; see `V3`. */
+export const vscale = (a: Vec3, s: number): Vec3 => [a[0] * s, a[1] * s, a[2] * s]
+
+/**
+ * A zero-length vector normalises to ZERO, not to NaN. Anything else and one
+ * degenerate camera vector turns every projected point into NaN, the scene
+ * silently disappears, and nothing in the console says why — a viewer that
+ * draws nothing is a better failure than a viewer that draws garbage.
+ */
+export function normalize(a: Vec3): Vec3 {
+ const l = Math.hypot(a[0], a[1], a[2])
+ return l > 0 ? [a[0] / l, a[1] / l, a[2] / l] : [0, 0, 0]
+}
+
+/** The Vec3 ops under their plain names, for `V3.scale` / `V3.length`. */
+export const V3 = { add, sub, scale: vscale, dot, cross, normalize, length }
+
+// --- matrices ---------------------------------------------------------------
+
+export type Mat4 = Float64Array
+
+export function identity(): Mat4 {
+ const m = new Float64Array(16)
+ m[0] = m[5] = m[10] = m[15] = 1
+ return m
+}
+
+/**
+ * The matrix product A·B — so `multiply(a, b)` applies **b first**, exactly as
+ * the maths reads when a point is a column vector on the right: `(A·B)·v`.
+ * Getting this backwards is the classic transposed-multiply bug, and it is
+ * invisible against the identity matrix (I is symmetric); the rig pins it with
+ * a translate/rotate pair, which do not commute.
+ */
+export function multiply(a: Mat4, b: Mat4): Mat4 {
+ const o = new Float64Array(16)
+ for (let c = 0; c < 4; c++) {
+ const b0 = b[c * 4], b1 = b[c * 4 + 1], b2 = b[c * 4 + 2], b3 = b[c * 4 + 3]
+ for (let r = 0; r < 4; r++) {
+ o[c * 4 + r] = a[r] * b0 + a[4 + r] * b1 + a[8 + r] * b2 + a[12 + r] * b3
+ }
+ }
+ return o
+}
+
+/**
+ * Right-handed perspective, clip depth in [-1, +1] — the GL convention, not
+ * D3D's [0, 1]. `fovY` is in RADIANS (degrees here would be a silent 57x error
+ * that still renders something).
+ */
+export function perspective(fovY: number, aspect: number, near: number, far: number): Mat4 {
+ const f = 1 / Math.tan(fovY / 2)
+ const nf = 1 / (near - far)
+ const m = new Float64Array(16)
+ m[0] = f / aspect
+ m[5] = f
+ m[10] = (far + near) * nf
+ m[11] = -1
+ m[14] = 2 * far * near * nf
+ return m
+}
+
+/**
+ * The view matrix for a camera at `eye` looking at `target`.
+ *
+ * The `up` vector is nudged when it is parallel to the view direction. Orbit
+ * clamps its elevation so it can never ask for that, but lookAt is public and
+ * "look straight down" is the first thing anyone tries; without the nudge the
+ * cross product is zero, the basis is NaN, and the failure surfaces three
+ * frames later as an empty canvas.
+ */
+export function lookAt(eye: Vec3, target: Vec3, up: Vec3 = [0, 1, 0]): Mat4 {
+ const z = normalize(sub(eye, target)) // camera backward
+ let x = cross(up, z)
+ if (Math.hypot(x[0], x[1], x[2]) < 1e-8) {
+ // up ∥ view: pick any other axis to build the basis from
+ x = cross(Math.abs(z[1]) > 0.9 ? [0, 0, 1] : [0, 1, 0], z)
+ }
+ x = normalize(x)
+ const y = cross(z, x)
+ const m = new Float64Array(16)
+ m[0] = x[0]; m[1] = y[0]; m[2] = z[0]
+ m[4] = x[1]; m[5] = y[1]; m[6] = z[1]
+ m[8] = x[2]; m[9] = y[2]; m[10] = z[2]
+ m[12] = -dot(x, eye); m[13] = -dot(y, eye); m[14] = -dot(z, eye)
+ m[15] = 1
+ return m
+}
+
+/** Builders, not mutators: compose with `multiply`, which keeps the order visible. */
+export function translate(v: Vec3): Mat4 {
+ const m = identity()
+ m[12] = v[0]; m[13] = v[1]; m[14] = v[2]
+ return m
+}
+
+export function scale(v: Vec3 | number): Mat4 {
+ const s: Vec3 = typeof v === 'number' ? [v, v, v] : v
+ const m = new Float64Array(16)
+ m[0] = s[0]; m[5] = s[1]; m[10] = s[2]; m[15] = 1
+ return m
+}
+
+export function rotateX(rad: number): Mat4 {
+ const c = Math.cos(rad), s = Math.sin(rad), m = identity()
+ m[5] = c; m[6] = s; m[9] = -s; m[10] = c
+ return m
+}
+
+export function rotateY(rad: number): Mat4 {
+ const c = Math.cos(rad), s = Math.sin(rad), m = identity()
+ m[0] = c; m[2] = -s; m[8] = s; m[10] = c
+ return m
+}
+
+export function rotateZ(rad: number): Mat4 {
+ const c = Math.cos(rad), s = Math.sin(rad), m = identity()
+ m[0] = c; m[1] = s; m[4] = -s; m[5] = c
+ return m
+}
+
+/**
+ * Transform a POINT (w = 1) and divide through by w, so this unprojects as
+ * well as it projects — feed it `invert(viewProjection)` and an NDC point and
+ * you get the world ray's position back. A direction vector must NOT go
+ * through here: it has w = 0 and wants the upper 3x3 only.
+ */
+export function transformPoint(m: Mat4, v: Vec3): Vec3 {
+ const x = m[0] * v[0] + m[4] * v[1] + m[8] * v[2] + m[12]
+ const y = m[1] * v[0] + m[5] * v[1] + m[9] * v[2] + m[13]
+ const z = m[2] * v[0] + m[6] * v[1] + m[10] * v[2] + m[14]
+ const w = m[3] * v[0] + m[7] * v[1] + m[11] * v[2] + m[15]
+ // w === 0 is a point on the eye plane; return it undivided rather than
+ // manufacturing infinities the caller will plot at the edge of the screen.
+ return w === 0 || w === 1 ? [x, y, z] : [x / w, y / w, z / w]
+}
+
+/**
+ * The 4x4 inverse (cofactor expansion), or NULL when the matrix is singular.
+ *
+ * Null rather than identity: a zero-scaled or otherwise collapsed matrix has
+ * no inverse, and handing back the identity would let a hit-test quietly
+ * report world coordinates that are really screen coordinates.
+ */
+export function invert(a: Mat4): Mat4 | null {
+ const a00 = a[0], a01 = a[1], a02 = a[2], a03 = a[3]
+ const a10 = a[4], a11 = a[5], a12 = a[6], a13 = a[7]
+ const a20 = a[8], a21 = a[9], a22 = a[10], a23 = a[11]
+ const a30 = a[12], a31 = a[13], a32 = a[14], a33 = a[15]
+
+ const b00 = a00 * a11 - a01 * a10, b01 = a00 * a12 - a02 * a10
+ const b02 = a00 * a13 - a03 * a10, b03 = a01 * a12 - a02 * a11
+ const b04 = a01 * a13 - a03 * a11, b05 = a02 * a13 - a03 * a12
+ const b06 = a20 * a31 - a21 * a30, b07 = a20 * a32 - a22 * a30
+ const b08 = a20 * a33 - a23 * a30, b09 = a21 * a32 - a22 * a31
+ const b10 = a21 * a33 - a23 * a31, b11 = a22 * a33 - a23 * a32
+
+ let det = b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06
+ if (!det || !Number.isFinite(det)) return null
+ det = 1 / det
+
+ const o = new Float64Array(16)
+ o[0] = (a11 * b11 - a12 * b10 + a13 * b09) * det
+ o[1] = (a02 * b10 - a01 * b11 - a03 * b09) * det
+ o[2] = (a31 * b05 - a32 * b04 + a33 * b03) * det
+ o[3] = (a22 * b04 - a21 * b05 - a23 * b03) * det
+ o[4] = (a12 * b08 - a10 * b11 - a13 * b07) * det
+ o[5] = (a00 * b11 - a02 * b08 + a03 * b07) * det
+ o[6] = (a32 * b02 - a30 * b05 - a33 * b01) * det
+ o[7] = (a20 * b05 - a22 * b02 + a23 * b01) * det
+ o[8] = (a10 * b10 - a11 * b08 + a13 * b06) * det
+ o[9] = (a01 * b08 - a00 * b10 - a03 * b06) * det
+ o[10] = (a30 * b04 - a31 * b02 + a33 * b00) * det
+ o[11] = (a21 * b02 - a20 * b04 - a23 * b00) * det
+ o[12] = (a11 * b07 - a10 * b09 - a12 * b06) * det
+ o[13] = (a00 * b09 - a01 * b07 + a02 * b06) * det
+ o[14] = (a31 * b01 - a30 * b03 - a32 * b00) * det
+ o[15] = (a20 * b03 - a21 * b01 + a22 * b00) * det
+ return o
+}
+
+/**
+ * World → screen pixels, for labels and hit-testing.
+ *
+ * `y` is flipped: NDC counts up from the bottom, CSS counts down from the top,
+ * and a viewer that forgets renders every label mirrored about the horizon —
+ * which looks plausible on a symmetric scatter plot and is why the rig asserts
+ * the number, not just the sign.
+ *
+ * CHECK `z` BEFORE DRAWING. A point BEHIND the camera has a negative clip w,
+ * so x/y come back mirrored into the visible screen — a label for something
+ * behind you, in the wrong place. Such a point always lands at `z > 1`, so the
+ * one test `-1 <= z && z <= 1` rejects both the behind-camera case and points
+ * beyond the far plane.
+ */
+export function project(vp: Mat4, p: Vec3, w: number, h: number): { x: number; y: number; z: number } {
+ const cx = vp[0] * p[0] + vp[4] * p[1] + vp[8] * p[2] + vp[12]
+ const cy = vp[1] * p[0] + vp[5] * p[1] + vp[9] * p[2] + vp[13]
+ const cz = vp[2] * p[0] + vp[6] * p[1] + vp[10] * p[2] + vp[14]
+ const cw = vp[3] * p[0] + vp[7] * p[1] + vp[11] * p[2] + vp[15]
+ if (cw === 0) return { x: NaN, y: NaN, z: Infinity } // exactly on the eye plane
+ const iw = 1 / cw
+ return {
+ x: (cx * iw * 0.5 + 0.5) * w,
+ y: (0.5 - cy * iw * 0.5) * h,
+ z: cz * iw,
+ }
+}
+
+// --- camera -----------------------------------------------------------------
+
+const UP: Vec3 = [0, 1, 0]
+
+/**
+ * Elevation stops JUST short of the pole. At exactly ±90° the view direction
+ * is parallel to `up`, `cross(up, forward)` is the zero vector, and the camera
+ * basis is NaN — in practice the scene flips upside down for one frame and
+ * then vanishes. Every hand-rolled orbit control has shipped this bug once.
+ *
+ * 1e-4 rad is 0.006° — no one can see the camera stop short, and it leaves the
+ * cross product a magnitude of 1e-4, which is enormous in float64.
+ */
+const MAX_EL = Math.PI / 2 - 1e-4
+
+const clamp = (v: number, lo: number, hi: number) => (v < lo ? lo : v > hi ? hi : v)
+/** Keep an angle in [-π, π] so a long session cannot accumulate a huge azimuth. */
+const wrapPi = (a: number) => a - 2 * Math.PI * Math.round(a / (2 * Math.PI))
+
+/**
+ * The orbit camera: spherical position around a target, which is what every 3D
+ * data view wants (there is nothing to walk through, only something to look at
+ * from all sides). Angles in radians, drag deltas in CSS pixels.
+ *
+ * Drags follow the POINTER, not the camera: dragging right turns the model to
+ * the right, which means the camera azimuth goes the other way.
+ */
+export class Orbit {
+ azimuth = 0
+ elevation = 0.4
+ distance = 5
+ target: Vec3 = [0, 0, 0]
+ fovY = Math.PI / 4
+ near = 0.1
+ far = 1000
+ /** Distance never reaches 0: lookAt of a zero-length forward is NaN. */
+ minDistance = 0.05
+ maxDistance = 5000
+ rotateSpeed = 0.008
+ /** Viewport height in CSS px. Set it on resize — pan only tracks the pointer
+ * 1:1 if this matches the canvas the drag happened on. */
+ height = 600
+
+ rotate(dx: number, dy: number): void {
+ this.azimuth = wrapPi(this.azimuth - dx * this.rotateSpeed)
+ this.elevation = clamp(this.elevation + dy * this.rotateSpeed, -MAX_EL, MAX_EL)
+ }
+
+ /** `f < 1` moves in. A non-positive factor is ignored — it would put the
+ * camera at the target, or pull it through to the other side. */
+ zoom(f: number): void {
+ if (!(f > 0)) return
+ this.distance = clamp(this.distance * f, this.minDistance, this.maxDistance)
+ }
+
+ /**
+ * Slide the target in the screen plane. The pixel→world scale is the world
+ * height visible at the target's depth divided by the viewport height, so
+ * the model stays stuck to the pointer at every zoom level; a fixed constant
+ * here is the "panning is too fast when zoomed in" complaint.
+ */
+ pan(dx: number, dy: number): void {
+ const k = (2 * this.distance * Math.tan(this.fovY / 2)) / Math.max(1, this.height)
+ const fwd = normalize(sub(this.target, this.eye()))
+ const right = normalize(cross(fwd, UP))
+ const up = cross(right, fwd)
+ this.target = add(this.target, add(vscale(right, -dx * k), vscale(up, dy * k)))
+ }
+
+ eye(): Vec3 {
+ const ce = Math.cos(this.elevation), se = Math.sin(this.elevation)
+ const ca = Math.cos(this.azimuth), sa = Math.sin(this.azimuth)
+ const [tx, ty, tz] = this.target
+ const d = this.distance
+ return [tx + d * ce * sa, ty + d * se, tz + d * ce * ca]
+ }
+
+ view(): Mat4 {
+ return lookAt(this.eye(), this.target, UP)
+ }
+
+ /** view-projection, ready for a shader's `u_vp`. */
+ matrix(aspect: number): Mat4 {
+ return multiply(perspective(this.fovY, aspect || 1, this.near, this.far), this.view())
+ }
+}
+
+// --- GL (browser only) ------------------------------------------------------
+
+let webgl2Probe: boolean | undefined
+
+/**
+ * Whether WebGL2 exists at all. Decides the 2D fallback (`Tile.fallback`), so
+ * it must answer FALSE rather than throw where there is no DOM — node runs the
+ * rigs, and the shell's static preview renders with scripts off.
+ */
+export function supportsWebGL2(): boolean {
+ if (webgl2Probe !== undefined) return webgl2Probe
+ webgl2Probe = false
+ try {
+ if (typeof document === 'undefined') return webgl2Probe
+ webgl2Probe = !!document.createElement('canvas').getContext('webgl2')
+ } catch {
+ webgl2Probe = false
+ }
+ return webgl2Probe
+}
+
+export type UniformValue = number | boolean | number[] | Float32Array | Float64Array
+
+/** A compiled program. Keeps its SOURCE so a lost context can rebuild it. */
+export class GLProgram {
+ vs: string
+ fs: string
+ p: WebGLProgram | null = null
+ u = new Map<string, WebGLUniformLocation | null>()
+ a = new Map<string, number>()
+ constructor(vs: string, fs: string) { this.vs = vs; this.fs = fs }
+}
+
+/**
+ * A GPU buffer. Holds a REFERENCE to the caller's typed array (not a copy) —
+ * that is what makes a context restore possible, since GPU memory cannot be
+ * read back cheaply, and it costs nothing when the caller keeps the array
+ * anyway (which a data app does: it is a column).
+ */
+export class GLBuffer {
+ data: ArrayBufferView
+ index: boolean
+ dynamic: boolean
+ b: WebGLBuffer | null = null
+ constructor(data: ArrayBufferView, index: boolean, dynamic: boolean) {
+ this.data = data; this.index = index; this.dynamic = dynamic
+ }
+}
+
+export interface Attrib {
+ buffer: GLBuffer
+ /** components per vertex, 1..4 */
+ size: number
+ /** bytes; 0 = tightly packed */
+ stride?: number
+ offset?: number
+ /** 1 = one value per INSTANCE rather than per vertex */
+ divisor?: number
+}
+
+export interface DrawOpts {
+ program: GLProgram
+ attribs: Record<string, Attrib>
+ uniforms?: Record<string, UniformValue>
+ /** vertices, or indices when `index` is given */
+ count: number
+ instances?: number
+ mode?: 'triangles' | 'triangle-strip' | 'lines' | 'line-strip' | 'points'
+ index?: GLBuffer
+ /** default true */
+ depth?: boolean
+ /** default false; premultiplied-alpha-free src-alpha blending */
+ blend?: boolean
+}
+
+/**
+ * The whole GL surface: compile, buffer, draw, resize, dispose.
+ *
+ * CONTEXT LOSS IS A NORMAL EVENT, not an error — a laptop waking from sleep,
+ * a GPU driver reset, a background tab reclaimed on mobile. The browser hands
+ * back a context whose every program and buffer handle is dead. Because this
+ * class remembers the shader source and the buffer data, restore is a rebuild
+ * and a redraw; the alternative, and what most small wrappers do, is a canvas
+ * that is simply blank forever with nothing in the console.
+ */
+export class GLView {
+ canvas: HTMLCanvasElement
+ gl: WebGL2RenderingContext | null = null
+ /** Called after the context comes back and everything is rebuilt: redraw here. */
+ onRestore: (() => void) | null = null
+ /** Called when the context is lost: stop the animation loop here. */
+ onLost: (() => void) | null = null
+
+ private programs: GLProgram[] = []
+ private buffers: GLBuffer[] = []
+ private disposed = false
+ private f32 = new Float32Array(16)
+ // Bound once and kept, because removeEventListener needs the SAME function
+ // object — a fresh `this.handle.bind(this)` at removal time silently removes
+ // nothing and leaves the view alive after dispose().
+ private lost = (e: Event) => {
+ // Without preventDefault the browser never fires `webglcontextrestored`.
+ // This one line is the difference between recovering and not.
+ e.preventDefault()
+ this.gl = null
+ for (const p of this.programs) { p.p = null; p.u.clear(); p.a.clear() }
+ for (const b of this.buffers) b.b = null
+ this.onLost?.()
+ }
+ private restored = () => {
+ if (this.disposed) return
+ this.gl = this.canvas.getContext('webgl2', CTX_ATTRS)
+ if (!this.gl) return
+ for (const p of this.programs) this.link(p)
+ for (const b of this.buffers) this.upload(b)
+ this.resize()
+ this.onRestore?.()
+ }
+
+ constructor(canvas: HTMLCanvasElement) {
+ this.canvas = canvas
+ this.gl = canvas.getContext('webgl2', CTX_ATTRS)
+ canvas.addEventListener('webglcontextlost', this.lost)
+ canvas.addEventListener('webglcontextrestored', this.restored)
+ }
+
+ get ok(): boolean { return !!this.gl && !this.gl.isContextLost() }
+ get aspect(): number { return this.canvas.width / Math.max(1, this.canvas.height) }
+
+ compile(vs: string, fs: string): GLProgram {
+ const p = new GLProgram(vs, fs)
+ this.programs.push(p)
+ this.link(p)
+ return p
+ }
+
+ buffer(data: ArrayBufferView, opts?: { index?: boolean; dynamic?: boolean }): GLBuffer {
+ const b = new GLBuffer(data, !!opts?.index, !!opts?.dynamic)
+ this.buffers.push(b)
+ this.upload(b)
+ return b
+ }
+
+ /** Replace a buffer's contents (and the copy kept for context restore). */
+ update(buf: GLBuffer, data: ArrayBufferView): void {
+ buf.data = data
+ this.upload(buf)
+ }
+
+ clear(r = 0, g = 0, b = 0, a = 0): void {
+ const gl = this.gl
+ if (!gl) return
+ gl.clearColor(r, g, b, a)
+ gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT)
+ }
+
+ draw(o: DrawOpts): void {
+ const gl = this.gl
+ const prog = o.program.p
+ if (!gl || !prog) return // lost context: skip the frame, restore redraws
+ gl.useProgram(prog)
+
+ if (o.depth === false) gl.disable(gl.DEPTH_TEST)
+ else { gl.enable(gl.DEPTH_TEST); gl.depthFunc(gl.LEQUAL) }
+ if (o.blend) { gl.enable(gl.BLEND); gl.blendFunc(gl.SRC_ALPHA, gl.ONE_MINUS_SRC_ALPHA) }
+ else gl.disable(gl.BLEND)
+
+ const bound: number[] = []
+ for (const name in o.attribs) {
+ const at = o.attribs[name]
+ let loc = o.program.a.get(name)
+ if (loc === undefined) { loc = gl.getAttribLocation(prog, name); o.program.a.set(name, loc) }
+ if (loc < 0 || !at.buffer.b) continue
+ gl.bindBuffer(gl.ARRAY_BUFFER, at.buffer.b)
+ gl.enableVertexAttribArray(loc)
+ gl.vertexAttribPointer(loc, at.size, gl.FLOAT, false, at.stride ?? 0, at.offset ?? 0)
+ if (at.divisor) gl.vertexAttribDivisor(loc, at.divisor)
+ bound.push(loc)
+ }
+
+ if (o.uniforms) for (const name in o.uniforms) this.setUniform(o.program, name, o.uniforms[name])
+
+ const mode = MODES(gl)[o.mode ?? 'triangles']
+ if (o.index && o.index.b) {
+ gl.bindBuffer(gl.ELEMENT_ARRAY_BUFFER, o.index.b)
+ const t = o.index.data instanceof Uint16Array ? gl.UNSIGNED_SHORT : gl.UNSIGNED_INT
+ if (o.instances) gl.drawElementsInstanced(mode, o.count, t, 0, o.instances)
+ else gl.drawElements(mode, o.count, t, 0)
+ } else if (o.instances) {
+ gl.drawArraysInstanced(mode, 0, o.count, o.instances)
+ } else {
+ gl.drawArrays(mode, 0, o.count)
+ }
+
+ // Reset what we touched. A divisor left on an attribute LOCATION outlives
+ // the program that set it (there is one default VAO), so the next draw
+ // reusing location 2 renders one vertex per instance and looks like a
+ // corrupt buffer rather than a leaked state bit.
+ for (const loc of bound) { gl.vertexAttribDivisor(loc, 0); gl.disableVertexAttribArray(loc) }
+ }
+
+ /**
+ * Match the drawing buffer to the CSS box. DPR is capped at 2: a 3x phone
+ * screen triples the fragment count for a difference invisible on a scatter
+ * plot, and on a large canvas it is the difference between 60fps and not.
+ * Returns whether anything changed, so a caller can skip a redraw.
+ */
+ resize(): boolean {
+ const c = this.canvas
+ const dpr = Math.min(typeof devicePixelRatio === 'number' ? devicePixelRatio : 1, 2)
+ const w = Math.max(1, Math.round((c.clientWidth || c.width) * dpr))
+ const h = Math.max(1, Math.round((c.clientHeight || c.height) * dpr))
+ if (c.width === w && c.height === h) return false
+ c.width = w; c.height = h
+ this.gl?.viewport(0, 0, w, h)
+ return true
+ }
+
+ dispose(): void {
+ this.disposed = true
+ this.canvas.removeEventListener('webglcontextlost', this.lost)
+ this.canvas.removeEventListener('webglcontextrestored', this.restored)
+ const gl = this.gl
+ if (gl) {
+ for (const p of this.programs) if (p.p) gl.deleteProgram(p.p)
+ for (const b of this.buffers) if (b.b) gl.deleteBuffer(b.b)
+ // Free the GPU allocation now rather than at the next GC: a dashboard
+ // swaps tiles, and a handful of orphaned contexts hits the browser's
+ // hard limit (~16), at which point the OLDEST live context is killed —
+ // i.e. a tile the reader is still looking at goes blank. The listeners
+ // came off above, so this deliberate loss cannot re-enter the handler.
+ gl.getExtension('WEBGL_lose_context')?.loseContext()
+ }
+ this.programs = []
+ this.buffers = []
+ this.gl = null
+ this.onRestore = null
+ this.onLost = null
+ }
+
+ // --- internals ---
+
+ private link(p: GLProgram): void {
+ const gl = this.gl
+ if (!gl) return
+ const vs = this.shader(gl.VERTEX_SHADER, p.vs)
+ const fs = this.shader(gl.FRAGMENT_SHADER, p.fs)
+ const prog = gl.createProgram()
+ if (!prog || !vs || !fs) return
+ gl.attachShader(prog, vs)
+ gl.attachShader(prog, fs)
+ gl.linkProgram(prog)
+ gl.deleteShader(vs)
+ gl.deleteShader(fs)
+ // A failed link yields a program that draws NOTHING and reports no error
+ // anywhere; throwing is the only way the mistake reaches whoever made it.
+ if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
+ const log = gl.getProgramInfoLog(prog)
+ gl.deleteProgram(prog)
+ throw new Error(`shader link failed: ${log}`)
+ }
+ p.p = prog
+ p.u.clear()
+ p.a.clear()
+ }
+
+ private shader(type: number, src: string): WebGLShader | null {
+ const gl = this.gl!
+ const s = gl.createShader(type)
+ if (!s) return null
+ gl.shaderSource(s, src)
+ gl.compileShader(s)
+ if (!gl.getShaderParameter(s, gl.COMPILE_STATUS)) {
+ const log = gl.getShaderInfoLog(s)
+ gl.deleteShader(s)
+ throw new Error(`shader compile failed: ${log}`)
+ }
+ return s
+ }
+
+ private upload(b: GLBuffer): void {
+ const gl = this.gl
+ if (!gl) return
+ if (!b.b) b.b = gl.createBuffer()
+ if (!b.b) return
+ const target = b.index ? gl.ELEMENT_ARRAY_BUFFER : gl.ARRAY_BUFFER
+ gl.bindBuffer(target, b.b)
+ gl.bufferData(target, b.data, b.dynamic ? gl.DYNAMIC_DRAW : gl.STATIC_DRAW)
+ }
+
+ private setUniform(p: GLProgram, name: string, v: UniformValue): void {
+ const gl = this.gl!
+ let loc = p.u.get(name)
+ if (loc === undefined) { loc = gl.getUniformLocation(p.p!, name); p.u.set(name, loc) }
+ // null = the compiler optimised it away because nothing reads it. Normal,
+ // not an error: shaders get edited and uniforms outlive their use.
+ if (loc === null) return
+ if (typeof v === 'number') { gl.uniform1f(loc, v); return }
+ if (typeof v === 'boolean') { gl.uniform1i(loc, v ? 1 : 0); return }
+ switch (v.length) {
+ case 1: gl.uniform1f(loc, v[0]); return
+ case 2: gl.uniform2f(loc, v[0], v[1]); return
+ case 3: gl.uniform3f(loc, v[0], v[1], v[2]); return
+ case 4: gl.uniform4f(loc, v[0], v[1], v[2], v[3]); return
+ case 16: {
+ // Our matrices are Float64Array, which uniformMatrix4fv rejects.
+ const s = this.f32
+ for (let i = 0; i < 16; i++) s[i] = v[i]
+ gl.uniformMatrix4fv(loc, false, s)
+ return
+ }
+ }
+ }
+}
+
+// `preserveDrawingBuffer` stays OFF: it costs a full copy every frame, and the
+// only thing it buys is toDataURL() at an arbitrary later moment. Snapshot by
+// drawing and reading pixels in the SAME turn instead.
+const CTX_ATTRS: WebGLContextAttributes = {
+ alpha: true,
+ antialias: true,
+ depth: true,
+ preserveDrawingBuffer: false,
+}
+
+// GL enum values only exist on a live context, so this is a function, not a
+// module-level table — a table would need the WebGL2RenderingContext global,
+// which does not exist in node and would break importing this file at all.
+const MODES = (gl: WebGL2RenderingContext) => ({
+ triangles: gl.TRIANGLES,
+ 'triangle-strip': gl.TRIANGLE_STRIP,
+ lines: gl.LINES,
+ 'line-strip': gl.LINE_STRIP,
+ points: gl.POINTS,
+})
diff --git a/dash/src/grid.ts b/dash/src/grid.ts
index 8b56cdb2..c4b163d1 100644
--- a/dash/src/grid.ts
+++ b/dash/src/grid.ts
@@ -21,10 +21,42 @@
import { formatValue, alignFor, TYPE_LABEL } from './format.ts'
import type { Column, ColumnType, TableSheet } from './model.ts'
-import { readCell, type Store } from './store.ts'
+import { readCell, type Patch, type Store } from './store.ts'
import { recalc, isErr, type Vec } from './formula.ts'
+import {
+ Selection, keyToAction, applyMotion, contains, tsvFromRange, parseTsv,
+ fillSeries, type Range,
+} from './select.ts'
+import { buildOrder, type ColumnFilter } from './filter.ts'
+import { evaluateRules, type CellStyle } from './condfmt.ts'
+import { colToLetters } from './a1.ts'
+import { t } from './i18n.ts'
+import { resizeColumn, autoFitWidth, hiddenSet, readFrozen } from './rowcol.ts'
+import {
+ cellKey, isFormula, recalcCells, translateCellFormula, shiftSheetFormulas,
+ type CellSource,
+} from './cellformula.ts'
-const ROW_H = 30
+/**
+ * Row height, in px — SPREADSHEET density, not web-table density.
+ *
+ * Excel's default row is exactly this at 96dpi; Google Sheets' is 21px. dash
+ * sat at 30, which is why the grid read as a table on a web page: a third fewer
+ * rows on screen, and the eye has to travel further for every comparison a
+ * spreadsheet exists to make. 22 was an intermediate step; 20 is the target,
+ * chosen with the 'dense pro' direction.
+ *
+ * THIS CONSTANT AND THE `--row-h` CUSTOM PROPERTY MUST AGREE. They are two
+ * declarations of one number — the rows are absolutely positioned at
+ * `top: i * ROW_H` from here while their height comes from the stylesheet — so
+ * a change to one alone perforates the grid: the cells shrink and the row
+ * boxes do not. That drift is not hypothetical; it is what stopped the density
+ * fix the first time it was tried. So the grid WRITES the property from this
+ * constant at build time, and the value in styles.css is only a fallback for
+ * anything that renders before the grid mounts.
+ */
+const ROW_H = 20
+const GUTTER_W = 52
const OVERSCAN = 8
export interface GridHost {
@@ -33,9 +65,25 @@ export interface GridHost {
sheetId: string
}
-const cols = (s: TableSheet) => s.columns
+const cols = (s: TableSheet) => {
+ const hidden = hiddenSet(s)
+ return s.columns.filter((c) => !hidden.has(c.id))
+}
const rowCount = (s: TableSheet) => s.rids.reduce((n, [, c]) => n + c, 0)
+/** Shared empty map, so "no cell formulas" costs no allocation on every paint. */
+const EMPTY_CELLS: ReadonlyMap<string, unknown> = new Map()
+
+/** Canonical row index → rid. The inverse of `dataRow`, ignoring the view. */
+function ridForDataRow(sheet: TableSheet, r: number): number {
+ let i = 0
+ for (const [start, count] of sheet.rids) {
+ if (r < i + count) return start + (r - i)
+ i += count
+ }
+ return -1
+}
+
/** Row index → rid, honouring the view's order vector when one exists. */
function ridAt(store: Store, sheet: TableSheet, i: number): number {
const order = store.order[sheet.id]
@@ -70,8 +118,19 @@ export class Grid {
* file cannot carry a number that disagrees with its own formula. */
computed = new Map<string, Vec>()
cycles: string[] = []
+ /** per-cell formula results, keyed by CANONICAL position (see cellformula.ts) */
+ private cellValues: ReadonlyMap<string, unknown> = EMPTY_CELLS
+ /** the selection model — visible positions, never rids (see select.ts) */
+ sel!: Selection
+ filters: ColumnFilter[] = []
+ sorts: Array<{ col: string; dir: 'asc' | 'desc' }> = []
+ /** conditional-format styles for the painted window, keyed colId */
+ private styles = new Map<string, Array<CellStyle | null>>()
+ onSelectionChange?: (summary: string, ref: string, value: string) => void
+ onContextMenu?: (row: number, col: number, x: number, y: number) => void
+ onFilterMenu?: (colId: string, x: number, y: number) => void
/** set by the app so a type change can be routed through one place */
- onRetype?: (col: Column) => void
+ onRetype?: (col: Column, x: number, y: number) => void
/** double-clicking a computed cell edits the FORMULA, not the value */
onEditFormula?: (col: Column) => void
@@ -79,17 +138,77 @@ export class Grid {
this.host = opts.el
this.store = opts.store
this.sheetId = opts.sheetId
+ this.sel = new Selection(rowCount(this.sheet), cols(this.sheet).length)
this.build()
- this.store.on('doc', () => this.paint())
+ this.store.on('doc', () => {
+ // A structural edit invalidates the order VECTOR: it holds row indices,
+ // and insert/delete renumber the rows underneath them. Leaving it alone
+ // left the grid drawing blanks and rows in an order matching nothing.
+ if (this.store.lastTouched.structural || this.store.lastTouched.all) this.applyView()
+ this.sel.resize(this.store.order[this.sheet.id]?.length ?? rowCount(this.sheet),
+ cols(this.sheet).length)
+ this.paint()
+ })
this.store.on('view', () => this.paint())
}
+ /**
+ * The patch that keeps every cell formula pointing at the right cells after
+ * `count` rows or columns are inserted at canonical index `at` (removed, if
+ * negative). Returns nothing when no formula moved.
+ *
+ * This must be committed IN THE SAME step as the structural patch. Two steps
+ * would put a document on screen — and on the undo stack, and over collab —
+ * in which the rows have moved and the formulas have not, which is a workbook
+ * of wrong numbers that each look perfectly reasonable.
+ */
+ shiftFormulas(axis: 'row' | 'col', at: number, count: number): Patch[] {
+ const s = this.sheet
+ const cells = s.cells
+ if (!cells) return []
+ const pairs: Array<[string, string]> = []
+ for (const k in cells) {
+ const f = cells[k]?.f
+ if (typeof f === 'string') pairs.push([k, f])
+ }
+ const moved = shiftSheetFormulas(pairs, axis, at, count)
+ if (!moved.length) return []
+ return [{
+ op: 'setOverrides', sheet: s.id,
+ keys: moved.map(([k]) => k),
+ v: moved.map(([k, f]) => ({ ...cells[k], f })),
+ }]
+ }
+
+ /**
+ * A VISIBLE row index → the sheet's own row index.
+ *
+ * These are the same number until somebody sorts or filters, and then they
+ * are not. Every structural op in rowcol.ts takes a CANONICAL index — it has
+ * to, because a document edit cannot be expressed in one reader's view — so
+ * anything acting on "the row the user clicked" has to convert here first.
+ * It did not, and right-clicking the top row of a Value-sorted grid and
+ * choosing Delete row deleted a DIFFERENT row: measured, £22,750 selected and
+ * £12,400 destroyed, with the re-sorted view hiding the evidence.
+ */
+ canonicalRow(visible: number): number {
+ const rid = ridAt(this.store, this.sheet, visible)
+ return rid < 0 ? -1 : dataRow(this.sheet, rid)
+ }
+
+ /** Fires whenever the grid points at a different sheet — the sheet list follows it. */
+ onSheetChange?: (id: string) => void
+
/** Point the grid at a different sheet — an import adds one and shows it. */
setSheet(id: string): void {
this.sheetId = id
this.sort = null
+ this.filters = []
+ this.sorts = []
this.scroller.scrollTop = 0
+ this.sel = new Selection(rowCount(this.sheet), cols(this.sheet).length)
this.paint()
+ this.onSheetChange?.(id)
}
get sheet(): TableSheet {
@@ -118,6 +237,8 @@ export class Grid {
'<div class="dg-sizer"></div>' +
'<div class="dg-foot-row"></div>' +
'</div></div>'
+ // One number, written where the stylesheet can see it. See ROW_H.
+ this.host.style.setProperty('--row-h', `${ROW_H}px`)
this.scroller = this.host.querySelector('.dg-scroll')!
this.table = this.host.querySelector('.dg-sizer')!
this.head = this.host.querySelector('.dg-head-row')!
@@ -126,16 +247,71 @@ export class Grid {
this.paint()
}
- /** Header: name, a type control, and a sort affordance. */
+ /** Header: the corner box, then a letter, name, type control and sort mark. */
+ /**
+ * Sticky offsets for the frozen columns, indexed by visible position.
+ *
+ * Frozen COLUMNS only. Frozen rows would need a second pane — the rows are
+ * absolutely positioned by index so a subset cannot simply stick — and they
+ * buy much less here, because the header is sticky already. Losing the label
+ * column when you scroll right is the gap a reader actually hits.
+ */
+ private frozenLefts(): number[] {
+ const n = readFrozen(this.sheet).cols
+ const out: number[] = []
+ let left = GUTTER_W
+ const vis = cols(this.sheet)
+ for (let i = 0; i < n && i < vis.length; i++) {
+ out.push(left)
+ left += vis[i].w ?? 130
+ }
+ return out
+ }
+
+ /** `style`/`class` fragments that stick column `ci` if it is frozen. */
+ private freeze(ci: number): { st: string; cls: string } {
+ const lefts = this.frozenLefts()
+ if (lefts[ci] === undefined) return { st: '', cls: '' }
+ const last = ci === lefts.length - 1 ? ' dg-freeze-edge' : ''
+ return { st: `position:sticky;left:${lefts[ci]}px;`, cls: ` dg-frozen${last}` }
+ }
+
private header(): string {
const s = this.sheet
- return `${cols(s).map((c) => {
+ return `<div class="dg-cell dg-corner" data-all="1" title="Select all"></div>` +
+ `${cols(s).map((c, ci) => {
const arrow = this.sort?.col === c.id ? (this.sort.dir === 'asc' ? ' ▲' : ' ▼') : ''
- return `<div class="dg-cell dg-h" style="width:${c.w ?? 130}px" data-col="${c.id}">` +
+ const filtered = this.filters.some((f) => f.col === c.id)
+ const fz = this.freeze(ci)
+ // The COLUMN header lights with the selection, as the row gutter already
+ // did. Excel and Sheets both mark the selected row AND column headers,
+ // and with only one of the two the eye keeps losing which column it is
+ // in on a wide sheet — the header is the only thing still on screen once
+ // the cursor has scrolled away.
+ const box = this.sel.bounds()
+ const on = ci >= box.left && ci <= box.right ? ' dg-h-on' : ''
+ return `<div class="dg-cell dg-h${filtered ? ' dg-filtered' : ''}${on}${fz.cls}" style="${fz.st}width:${c.w ?? 130}px" data-col="${c.id}" data-ci="${ci}">` +
+ // TWO LINES, because one could not hold them: the letter, the name,
+ // the type control, the filter arrow and the resize grip were sharing
+ // 130px and the NAME lost — every column read "A R", "B O", "C :".
+ // A spreadsheet whose column names are unreadable is not a spreadsheet.
+ // The letter goes on its own strip, where Excel puts it and where it is
+ // also the obvious click target for selecting the column.
+ // The TYPE rides on the letter strip, which has room going spare, and
+ // not beside the name, which does not: a full-width `PERCENT` badge is
+ // what clipped `Probability` down to `P.`. It stays a button — the type
+ // being one click away is what makes import's refusal to guess honest.
+ `<span class="dg-hstrip">` +
+ `<span class="dg-letter" title="${esc(t('Select column'))}">${colToLetters(ci)}</span>` +
+ `<button class="dg-type" data-retype="${c.id}" title="${esc(TYPE_LABEL[c.type])} — click to change">${esc(TYPE_LABEL[c.type])}</button>` +
+ `</span>` +
+ `<span class="dg-hmain">` +
`<span class="dg-name" title="${esc(c.formula ? `= ${c.formula}` : c.name)}">${esc(c.name)}${arrow}</span>` +
(c.formula ? `<span class="dg-fx" title="${esc('= ' + c.formula)}">fx</span>` : '') +
- `<button class="dg-type" data-retype="${c.id}" title="${esc(TYPE_LABEL[c.type])} — click to change">${esc(TYPE_LABEL[c.type])}</button>` +
(c.failed ? `<span class="dg-warn" title="${c.failed} value(s) could not be read as ${esc(TYPE_LABEL[c.type])}">!</span>` : '') +
+ `<span class="dg-filter" data-filter="${c.id}" title="Filter and sort">▾</span>` +
+ `</span>` +
+ `<span class="dg-grip" data-grip="${c.id}" title="Drag to resize, double-click to fit"></span>` +
`</div>`
}).join('')}`
}
@@ -144,9 +320,10 @@ export class Grid {
const s = this.sheet
if (!s.totals) return ''
const n = rowCount(s)
- return `${cols(s).map((c) => {
+ return `<div class="dg-cell dg-gutter"></div>` + `${cols(s).map((c, ci) => {
const spec = s.totals?.[c.id]
- if (!spec) return `<div class="dg-cell" style="width:${c.w ?? 130}px"></div>`
+ const fz = this.freeze(ci)
+ if (!spec) return `<div class="dg-cell${fz.cls}" style="${fz.st}width:${c.w ?? 130}px"></div>`
const data = s.data[c.id]
const comp = this.computed.get(c.id)
let acc = 0
@@ -160,14 +337,35 @@ export class Grid {
else acc += v
}
const out = spec === 'avg' ? (seen ? acc / seen : 0) : spec === 'count' ? seen : acc
- return `<div class="dg-cell" style="width:${c.w ?? 130}px;text-align:${alignFor(c.type)}">` +
+ return `<div class="dg-cell${fz.cls}" style="${fz.st}width:${c.w ?? 130}px;text-align:${alignFor(c.type)}">` +
`<span class="dg-agg">${esc(String(spec))}</span> ${esc(formatValue(out, c))}</div>`
}).join('')}`
}
- paint(): void {
+ /**
+ * Rebuild the view order from the current filters and sorts.
+ *
+ * VIEW state: it writes `store.order`, which `store.view()` mutates without
+ * a checkpoint — so filtering and sorting never dirty the file and never
+ * produce an op. Formula columns are read through `computed`, so you can
+ * sort by a calculated column that is nowhere in the document.
+ */
+ applyView(): void {
const s = this.sheet
const n = rowCount(s)
+ const get = (col: string, row: number): unknown => {
+ const comp = this.computed.get(col)
+ return comp ? comp[row] : readCell(s.data[col], row)
+ }
+ const order = this.filters.length || this.sorts.length
+ ? buildOrder(n, get, this.filters, this.sorts)
+ : undefined
+ this.store.view(() => { this.store.order[s.id] = order })
+ }
+
+ paint(): void {
+ const s = this.sheet
+ const all = rowCount(s)
if (s.columns.some((c) => c.formula)) {
// `now` is frozen from the document so TODAY() shows every reader the
// same date rather than each reader's own
@@ -175,6 +373,38 @@ export class Grid {
this.computed = r.values
this.cycles = r.cycles
} else if (this.computed.size) { this.computed = new Map(); this.cycles = [] }
+
+ // Per-cell formulas, over CANONICAL positions.
+ //
+ // A1 addressing counts `s.columns` (every column, hidden included) and the
+ // sheet's own row order — NOT the visible grid. Sorting and filtering are
+ // view state (store.view()), so a formula must not change meaning when a
+ // reader sorts: `=B4*1.2` names a cell in the document, and two people
+ // looking at the same file through different sorts have to see the same
+ // number. Hiding a column is document state but still editorial, and
+ // renumbering every reference behind it would be a silent rewrite.
+ this.cellValues = this.hasCellFormulas()
+ ? recalcCells(this.cellSource(), this.store.doc.modified, this.columnVectors()).values
+ : EMPTY_CELLS
+
+ // Conditional formats are evaluated over the WHOLE column, not the painted
+ // window: a colour scale needs the real min and max, and top-N needs every
+ // candidate. Evaluating the ~40 visible rows would rescale the ramp on every
+ // scroll — the same data would change colour as you moved.
+ this.styles.clear()
+ const rules = (s as unknown as { condfmt?: Record<string, unknown[]> }).condfmt
+ if (rules) {
+ for (const c of cols(s)) {
+ const rs = rules[c.id]
+ if (!Array.isArray(rs) || !rs.length) continue
+ const comp = this.computed.get(c.id)
+ const vals = Array.from({ length: all }, (_, i) => comp ? comp[i] : readCell(s.data[c.id], i))
+ this.styles.set(c.id, evaluateRules(rs as never, vals))
+ }
+ }
+ const order = this.store.order[s.id]
+ const n = order ? order.length : all
+ this.sel.resize(n, cols(s).length)
this.table.style.height = `${n * ROW_H}px`
// Only the visible slice exists. 100k x 6 would be 600,000 nodes, and that
@@ -187,38 +417,624 @@ export class Grid {
for (let i = top; i < end; i++) {
const rid = ridAt(this.store, s, i)
const r = dataRow(s, rid)
- body.push(`<div class="dg-row" data-rid="${rid}" style="top:${i * ROW_H}px">` +
- cols(s).map((c) => {
+ const box = this.sel.bounds()
+ const rowSelected = i >= box.top && i <= box.bottom
+ body.push(`<div class="dg-row" data-rid="${rid}" data-row="${i}" style="top:${i * ROW_H}px">` +
+ `<div class="dg-cell dg-gutter${rowSelected ? ' dg-gutter-on' : ''}" data-rowhead="${i}">${i + 1}</div>` +
+ cols(s).map((c, ci) => {
const over = s.cells?.[`${c.id}:${rid}`]
const comp = this.computed.get(c.id)
- const v = comp ? comp[r]
- : over && 'v' in over ? over.v
- : readCell(s.data[c.id], r)
+ const fv = this.cellFormulaValue(r, c.id)
+ const v = fv !== undefined ? fv
+ : comp ? comp[r]
+ : over && 'v' in over ? over.v
+ : readCell(s.data[c.id], r)
const note = over?.note ? ' dg-noted' : ''
const bad = isErr(v) ? ' dg-err' : ''
+ const inSel = this.sel.ranges().some((rg) => contains(rg, i, ci))
+ const isCursor = this.sel.cursor.row === i && this.sel.cursor.col === ci
+ const cf = this.styles.get(c.id)?.[r] ?? null
+ let st = `width:${c.w ?? 130}px;text-align:${alignFor(c.type)}`
+ if (cf?.bg) st += `;background:${cf.bg}`
+ if (cf?.color) st += `;color:${cf.color}`
+ if (cf?.bold) st += ';font-weight:600'
+ const bar = cf?.bar
+ ? `<span class="dg-bar" style="left:${bar0(cf)}%;width:${cf.bar.pct}%;background:${cf.bar.color}"></span>`
+ : ''
const shown = isErr(v) ? String(v) : formatValue(v, c)
- return `<div class="dg-cell${note}${bad}" data-col="${c.id}" ` +
- `style="width:${c.w ?? 130}px;text-align:${alignFor(c.type)}">${esc(shown)}</div>`
+ const fz = this.freeze(ci)
+ return `<div class="dg-cell${note}${bad}${inSel ? ' dg-sel' : ''}${isCursor ? ' dg-cursor' : ''}${fz.cls}" ` +
+ `data-col="${c.id}" data-ci="${ci}" style="${fz.st}${st}">${bar}<span class="dg-v">${esc(shown)}</span></div>`
}).join('') + '</div>')
}
+ this.paintEmptyGrid()
this.head.innerHTML = this.header()
- this.table.innerHTML = body.join('')
+ this.table.innerHTML = body.join('') + this.outline()
this.foot.innerHTML = this.totalsRow()
this.wire()
}
+ /**
+ * Every column as a vector, under BOTH its id and its name.
+ *
+ * A cell formula has to be able to say `SUMIFS(value, region, "North")` —
+ * naming columns is half of what makes one worth writing. Only the COMPUTED
+ * columns were being passed, so every reference to an ordinary column was an
+ * unknown name: `SUMIFS` then matched nothing and returned 0, `XLOOKUP` gave
+ * #N/A, and a formula that mentioned no column at all (a PMT, say) worked
+ * perfectly — which is exactly the pattern that makes this look like four
+ * unrelated bugs instead of one.
+ */
+ private columnVectors(): Map<string, Vec> {
+ const s = this.sheet
+ const n = rowCount(s)
+ const out = new Map<string, Vec>()
+ const put = (k: string, v: Vec) => { out.set(k, v); out.set(k.toLowerCase(), v) }
+ for (const c of s.columns) {
+ const comp = this.computed.get(c.id)
+ const v = comp ?? Array.from({ length: n }, (_, i) => readCell(s.data[c.id], i) as never)
+ put(c.id, v)
+ put(c.name, v)
+ }
+ return out
+ }
+
+ /** The formula stored at a canonical position, if any. */
+ private formulaAtPos(row: number, col: number): string | undefined {
+ const s = this.sheet
+ const c = s.columns[col]
+ if (!c) return undefined
+ const rid = ridForDataRow(s, row)
+ const f = s.cells?.[`${c.id}:${rid}`]?.f
+ return typeof f === 'string' && f !== '' ? f : undefined
+ }
+
+ private hasCellFormulas(): boolean {
+ const cells = this.sheet.cells
+ if (!cells) return false
+ for (const k in cells) if (typeof cells[k]?.f === 'string') return true
+ return false
+ }
+
+ /** The sheet as a plain grid of positions, which is all cellformula.ts wants. */
+ private cellSource(): CellSource {
+ const s = this.sheet
+ return {
+ rows: rowCount(s),
+ cols: s.columns.length,
+ formulaAt: (r, c) => this.formulaAtPos(r, c),
+ valueAt: (r, c) => {
+ const col = s.columns[c]
+ if (!col) return null
+ const rid = ridForDataRow(s, r)
+ const over = s.cells?.[`${col.id}:${rid}`]
+ if (over && 'v' in over) return over.v as never
+ const comp = this.computed.get(col.id)
+ return (comp ? comp[r] : readCell(s.data[col.id], r)) as never
+ },
+ }
+ }
+
+ /** The computed value of a cell formula at a canonical position, if it has one. */
+ private cellFormulaValue(row: number, colId: string): unknown {
+ if (this.cellValues === EMPTY_CELLS) return undefined
+ const ci = this.sheet.columns.findIndex((c) => c.id === colId)
+ if (ci < 0) return undefined
+ const k = cellKey(row, ci)
+ return this.cellValues.has(k) ? this.cellValues.get(k) : undefined
+ }
+
+ /**
+ * Rule the EMPTY space past the last row and the last column.
+ *
+ * A spreadsheet's grid does not stop where the data stops — Excel and Sheets
+ * both rule the whole window, and that continuing lattice is a good part of
+ * what makes a grid read as a sheet rather than as a table someone put on a
+ * web page. dash drew rows only where rows existed, so an eight-row workbook
+ * ended in a large white rectangle.
+ *
+ * Painted as a BACKGROUND on the scrolling element rather than as filler
+ * rows: empty rows would be real DOM, would have to be virtualised, and would
+ * be selectable and editable — a grid you can type into a thousand rows below
+ * your data is a different product decision, and not one to make by accident.
+ * The background costs nothing and cannot be clicked.
+ *
+ * It lives on `.dg-table`, which scrolls WITH the content, so the lines stay
+ * aligned to the rows. `background-position` steps it down past the header,
+ * which is in normal flow above the sizer.
+ */
+ private paintEmptyGrid(): void {
+ const vis = cols(this.sheet)
+ const line = 'var(--grid-line, #edf0f4)'
+ // vertical rules at each column boundary, starting after the gutter
+ const stops: string[] = []
+ let x = GUTTER_W
+ stops.push(`transparent 0 ${x - 1}px`, `${line} ${x - 1}px ${x}px`)
+ for (const c of vis) {
+ const w = c.w ?? 130
+ stops.push(`transparent ${x}px ${x + w - 1}px`, `${line} ${x + w - 1}px ${x + w}px`)
+ x += w
+ }
+ const headH = ROW_H + 20
+ this.table.parentElement!.style.backgroundImage =
+ `repeating-linear-gradient(to bottom, transparent 0 ${ROW_H - 1}px, ${line} ${ROW_H - 1}px ${ROW_H}px),` +
+ `linear-gradient(to right, ${stops.join(',')}, transparent ${x}px)`
+ this.table.parentElement!.style.backgroundPosition = `0 ${headH}px, 0 0`
+ // The ruled area is exactly as WIDE as the sheet. Excel rules to the window
+ // edge because its columns go on forever; dash's do not, and ruling past
+ // the last one draws cells that cannot be typed into. So the row rules tile
+ // down within the sheet's width and stop, and past the final column is
+ // plain background — which is the truthful answer to "is there anything
+ // over there".
+ this.table.parentElement!.style.backgroundSize = `${x}px auto, auto auto`
+ this.table.parentElement!.style.backgroundRepeat = 'repeat-y, repeat-y'
+ }
+
+ /** Value at a VISIBLE position — what the clipboard and the status bar read. */
+ private valueAt(row: number, ci: number): unknown {
+ const s = this.sheet
+ const c = cols(s)[ci]
+ if (!c) return null
+ const rid = ridAt(this.store, s, row)
+ const r = dataRow(s, rid)
+ const fv = this.cellFormulaValue(r, c.id)
+ if (fv !== undefined) return fv
+ const over = s.cells?.[`${c.id}:${rid}`]
+ if (over && 'v' in over) return over.v
+ const comp = this.computed.get(c.id)
+ return comp ? comp[r] : readCell(s.data[c.id], r)
+ }
+
+ /** Write a block of values starting at a visible position. One undo step. */
+ private writeBlock(row: number, ci: number, block: unknown[][], extra: Patch[] = []): void {
+ const s = this.sheet
+ const vis = cols(s)
+ const patches: Patch[] = [...extra]
+ const byCol = new Map<string, { rids: number[]; v: unknown[] }>()
+ block.forEach((line, dr) => {
+ line.forEach((val, dc) => {
+ const c = vis[ci + dc]
+ if (!c || c.formula) return // a computed column is defined by
+ const rid = ridAt(this.store, s, row + dr) // its expression, not by a paste
+ if (rid < 0) return
+ const e = byCol.get(c.id) ?? { rids: [], v: [] }
+ e.rids.push(rid); e.v.push(val)
+ byCol.set(c.id, e)
+ })
+ })
+ for (const [col, e] of byCol) patches.push({ op: 'setCells', sheet: s.id, col, rids: e.rids, v: e.v })
+ if (patches.length) this.store.commit(patches)
+ }
+
+ /** Clear every selected cell — one undo step, formula COLUMNS untouched. */
+ clearSelection(): void {
+ const s = this.sheet
+ const b = this.sel.bounds()
+ const block: unknown[][] = []
+ for (let r = b.top; r <= b.bottom; r++) block.push(new Array(b.right - b.left + 1).fill(null))
+ // Clearing a cell has to drop its FORMULA too, not just blank the stored
+ // value underneath it. Writing nulls alone left the formula in place and it
+ // simply recomputed, so a cut appeared to do nothing and Delete on a
+ // formula cell was a no-op.
+ const keys: string[] = []
+ const overs: Array<Record<string, unknown> | null> = []
+ const vis = cols(s)
+ for (let r = b.top; r <= b.bottom; r++) {
+ for (let c = b.left; c <= b.right; c++) {
+ const col = vis[c]
+ if (!col) continue
+ const rid = ridAt(this.store, s, r)
+ const key = `${col.id}:${rid}`
+ const had = s.cells?.[key]
+ if (had?.f === undefined) continue
+ const { f: _f, ...rest } = had
+ keys.push(key)
+ overs.push(Object.keys(rest).length ? rest : null)
+ }
+ }
+ // ONE commit, so one ⌘Z puts back both the values and the formulas.
+ this.writeBlock(b.top, b.left, block, keys.length
+ ? [{ op: 'setOverrides', sheet: s.id, keys, v: overs as never, dropEmpty: true }]
+ : [])
+ }
+
+ /** Write the formula bar's contents into the active cell. */
+ setActiveCell(text: string): void {
+ const s = this.sheet
+ const c = cols(s)[this.sel.cursor.col]
+ if (!c || this.store.readOnly) return
+ const rid = ridAt(this.store, s, this.sel.cursor.row)
+ if (rid < 0) return
+ if (text.trim().startsWith('=')) {
+ // a leading = in the formula bar sets the COLUMN's expression: dash's
+ // formulas are per column, so this is the honest place for it to land
+ this.store.commit({ op: 'setColumn', sheet: s.id, col: c.id, patch: { formula: text.trim().slice(1).trim() } })
+ return
+ }
+ if (c.formula) return // typing a value over a computed column would be
+ this.writeBlock(this.sel.cursor.row, this.sel.cursor.col, [[coerceForColumn(text, c.type)]])
+ }
+
+ /**
+ * The clip this grid last copied — formulas and all.
+ *
+ * The SYSTEM clipboard carries values, because that is what every other
+ * application expects to receive: paste into Numbers or a mail message and
+ * `=D1*3` is not useful there, £37,200 is. But pasting back into a
+ * spreadsheet has to preserve the formula, so the copy is remembered here and
+ * a paste whose text still MATCHES what we wrote is recognised as our own.
+ * That is how Excel and Sheets behave, and the text comparison is what makes
+ * it honest: copy something else in between and the match fails, so a stale
+ * internal clip can never be pasted in place of what the user actually
+ * copied.
+ */
+ private clip: {
+ tsv: string
+ block: Array<Array<{ v: unknown; f?: string }>>
+ /** a CUT, not a copy — see writeClip for why that changes the answer */
+ cut?: boolean
+ } | null = null
+
+ copyTsv(): string {
+ const b = this.sel.bounds()
+ const tsv = tsvFromRange((r, c) => this.valueAt(r, c),
+ { anchor: { row: b.top, col: b.left }, head: { row: b.bottom, col: b.right } } as Range)
+ const s = this.sheet
+ const block: Array<Array<{ v: unknown; f?: string }>> = []
+ for (let r = b.top; r <= b.bottom; r++) {
+ const line: Array<{ v: unknown; f?: string }> = []
+ for (let c = b.left; c <= b.right; c++) {
+ const col = cols(s)[c]
+ const dr = dataRow(s, ridAt(this.store, s, r))
+ line.push({
+ v: this.valueAt(r, c),
+ f: col ? this.formulaAtPos(dr, s.columns.findIndex((x) => x.id === col.id)) : undefined,
+ })
+ }
+ block.push(line)
+ }
+ this.clip = { tsv, block }
+ this.clipTop = dataRow(s, ridAt(this.store, s, b.top))
+ this.clipLeft = s.columns.findIndex((x) => x.id === cols(s)[b.left]?.id)
+ return tsv
+ }
+
+ pasteTsv(text: string): void {
+ const cur = this.sel.cursor
+ // our own clip, still intact on the system clipboard? then formulas ride
+ // along, TRANSLATED by how far the block moved
+ if (this.clip && this.clip.tsv === text) {
+ this.writeClip(cur.row, cur.col, this.clip.block)
+ return
+ }
+ const grid = parseTsv(text)
+ if (!grid.length) return
+ this.writeBlock(cur.row, cur.col, grid)
+ }
+
+ /**
+ * Paste a remembered block, translating each formula by the offset it moved.
+ *
+ * The offset is measured in CANONICAL positions, not visible ones: A1
+ * addresses name the document, so a block copied and pasted while a sort is
+ * on must shift by the distance the cells actually moved, not by the distance
+ * they appear to have moved.
+ */
+ private writeClip(
+ row: number, ci: number, block: Array<Array<{ v: unknown; f?: string }>>,
+ ): void {
+ const s = this.sheet
+ const vis = cols(s)
+ const srcTop = this.clipTop ?? row
+ const srcLeft = this.clipLeft ?? ci
+ const cut = this.clip?.cut === true
+ const patches: Patch[] = []
+ const byCol = new Map<string, { rids: number[]; v: unknown[] }>()
+ const keys: string[] = []
+ const overs: Array<Record<string, unknown> | null> = []
+ block.forEach((line, dr) => {
+ line.forEach((cellv, dc) => {
+ const c = vis[ci + dc]
+ if (!c || c.formula) return
+ const rid = ridAt(this.store, s, row + dr)
+ if (rid < 0) return
+ const key = `${c.id}:${rid}`
+ if (cellv.f !== undefined) {
+ // A CUT does not translate. Copying makes a second formula that
+ // should mean the same thing in its new place, so its references
+ // move; cutting moves the ONE formula, and a formula that travels
+ // with its cells still means exactly what it did. Excel agrees, and
+ // getting this backwards silently re-points a moved formula at the
+ // wrong data.
+ //
+ // NOT DONE, and a real limitation: formulas ELSEWHERE that referenced
+ // the cut cells should follow them to the new location. They do not —
+ // they keep pointing at the old, now-empty positions.
+ const dRow = cut ? 0 : dataRow(s, rid) - (srcTop + dr)
+ const dColIdx = cut ? 0 : s.columns.findIndex((x) => x.id === c.id) - (srcLeft + dc)
+ keys.push(key)
+ overs.push({ ...(s.cells?.[key] ?? {}), f: translateCellFormula(cellv.f, dRow, dColIdx) })
+ } else {
+ const e = byCol.get(c.id) ?? { rids: [], v: [] }
+ e.rids.push(rid); e.v.push(cellv.v)
+ byCol.set(c.id, e)
+ // pasting a plain value over a formula cell must REMOVE the formula
+ const had = s.cells?.[key]
+ if (had?.f !== undefined) {
+ const { f: _f, ...rest } = had
+ keys.push(key)
+ overs.push(Object.keys(rest).length ? rest : null)
+ }
+ }
+ })
+ })
+ for (const [col, e] of byCol) patches.push({ op: 'setCells', sheet: s.id, col, rids: e.rids, v: e.v })
+ if (keys.length) {
+ patches.push({ op: 'setOverrides', sheet: s.id, keys, v: overs as never, dropEmpty: true })
+ }
+ if (patches.length) this.store.commit(patches)
+ }
+
+ /** Canonical top-left of the remembered clip, for measuring the paste offset. */
+ private clipTop: number | null = null
+ private clipLeft: number | null = null
+
+ /** Fill the selection down from its first row, continuing a series if there is one. */
+ fillDownSelection(): void {
+ const b = this.sel.bounds()
+ if (b.bottom <= b.top) return
+ const block: unknown[][] = []
+ for (let c = b.left; c <= b.right; c++) {
+ const seeds = [this.valueAt(b.top, c)]
+ if (b.bottom - b.top >= 1) seeds.push(this.valueAt(b.top + 1, c))
+ const filled = fillSeries(seeds, b.bottom - b.top + 1)
+ filled.forEach((v, i) => { (block[i] ??= [])[c - b.left] = v })
+ }
+ this.writeBlock(b.top, b.left, block)
+ }
+
+ /** Tell the app what is selected, for the formula bar and the status bar. */
+ private announce(): void {
+ if (!this.onSelectionChange) return
+ const s = this.sheet
+ const vis = cols(s)
+ const cur = this.sel.cursor
+ const c = vis[cur.col]
+ const ref = c ? `${colToLetters(cur.col)}${cur.row + 1}` : ''
+ const v = this.valueAt(cur.row, cur.col)
+ const raw = v == null ? '' : isErr(v) ? String(v) : String(v)
+ const b = this.sel.bounds()
+ let summary = ''
+ if (b.bottom > b.top || b.right > b.left) {
+ // the status-bar aggregate people select cells specifically to see
+ const nums: number[] = []
+ for (let r = b.top; r <= b.bottom; r++) {
+ for (let cc = b.left; cc <= b.right; cc++) {
+ const x = this.valueAt(r, cc)
+ if (typeof x === 'number' && Number.isFinite(x)) nums.push(x)
+ }
+ }
+ const cells = (b.bottom - b.top + 1) * (b.right - b.left + 1)
+ summary = nums.length
+ ? `Sum ${fmtNum(nums.reduce((a, x) => a + x, 0))} · Avg ${fmtNum(nums.reduce((a, x) => a + x, 0) / nums.length)} · Count ${nums.length} · Cells ${cells}`
+ : `Cells ${cells}`
+ }
+ // The formula bar shows the SOURCE when there is one — a per-cell formula
+ // first, then the column's expression, then the value. A bar that shows the
+ // computed number for a formula cell is the one place a spreadsheet user
+ // looks to find out whether a number was typed or derived.
+ const cellSrc = c
+ ? this.formulaAtPos(dataRow(s, ridAt(this.store, s, cur.row)),
+ s.columns.findIndex((x) => x.id === c.id))
+ : undefined
+ this.onSelectionChange(summary, ref,
+ cellSrc !== undefined ? cellSrc : c?.formula ? `= ${c.formula}` : raw)
+ }
+
+ /** The full keyboard set, routed through select.ts's typed actions. */
+ handleKey(e: KeyboardEvent): boolean {
+ if (this.editing) return false
+ const a = keyToAction(e)
+ if (!a) return false
+ if (a.kind === 'edit') return this.editActive()
+ if (a.kind === 'clear') { this.clearSelection(); return true }
+ if (a.kind === 'copy' || a.kind === 'cut') {
+ void navigator.clipboard?.writeText(this.copyTsv())
+ if (a.kind === 'cut') { if (this.clip) this.clip.cut = true; this.clearSelection() }
+ return true
+ }
+ if (a.kind === 'paste') return false // the document paste listener has the data
+ if (a.kind === 'undo') { this.store.undo(); return true }
+ if (a.kind === 'redo') { this.store.redo(); return true }
+
+ const moved = applyMotion(this.sel, a, {
+ page: Math.max(1, Math.floor(this.scroller.clientHeight / ROW_H) - 1),
+ filled: (row, col) => {
+ const v = this.valueAt(row, col)
+ return v != null && v !== ''
+ },
+ })
+ if (!moved) return false
+ this.scrollIntoView()
+ this.paint()
+ this.announce()
+ return true
+ }
+
+ private cellEl(row: number, ci: number): HTMLElement | null {
+ return this.table.querySelector<HTMLElement>(`.dg-row[data-row="${row}"] .dg-cell[data-ci="${ci}"]`)
+ }
+
+ private scrollIntoView(): void {
+ const y = this.sel.cursor.row * ROW_H
+ const top = this.scroller.scrollTop
+ const h = this.scroller.clientHeight - ROW_H * 2
+ if (y < top) this.scroller.scrollTop = y
+ else if (y + ROW_H > top + h) this.scroller.scrollTop = y + ROW_H - h
+ }
+
+ /**
+ * The selection's outline and its fill handle, as ONE absolutely-positioned
+ * box over the rows.
+ *
+ * A per-cell tint alone does not read as a selection — the eye needs the
+ * rectangle. And the handle is how a spreadsheet user expects to fill: not a
+ * menu item, a square in the corner you drag.
+ */
+ private outline(): string {
+ const b = this.sel.bounds()
+ const vis = cols(this.sheet)
+ if (!vis.length) return ''
+ const w = (i: number) => vis[i]?.w ?? 130
+ let left = GUTTER_W
+ for (let i = 0; i < b.left; i++) left += w(i)
+ let width = 0
+ for (let i = b.left; i <= b.right && i < vis.length; i++) width += w(i)
+ const top = b.top * ROW_H
+ const height = (b.bottom - b.top + 1) * ROW_H
+ return `<div class="dg-outline" style="left:${left}px;top:${top}px;width:${width}px;height:${height}px">` +
+ `<span class="dg-handle" title="Drag to fill"></span></div>`
+ }
+
private wire(): void {
+ // the fill handle: drag down to extend the selection and fill it
+ const handle = this.table.querySelector<HTMLElement>('.dg-handle')
+ if (handle) {
+ handle.onmousedown = (e) => {
+ e.preventDefault(); e.stopPropagation()
+ const start = this.sel.bounds()
+ const move = (m: MouseEvent) => {
+ const t = (m.target as HTMLElement)?.closest?.('.dg-row[data-row]') as HTMLElement | null
+ if (!t) return
+ const r2 = Number(t.dataset.row)
+ if (Number.isFinite(r2) && r2 >= start.top) {
+ this.sel.moveTo(start.top, start.left)
+ this.sel.extendTo(r2, start.right)
+ this.paint()
+ }
+ }
+ const up = () => {
+ document.removeEventListener('mousemove', move)
+ document.removeEventListener('mouseup', up)
+ this.fillDownSelection()
+ this.announce()
+ }
+ document.addEventListener('mousemove', move)
+ document.addEventListener('mouseup', up)
+ }
+ }
this.head.querySelectorAll<HTMLElement>('.dg-name').forEach((el) => {
- el.onclick = () => this.toggleSort(el.parentElement!.dataset.col!)
+ el.onclick = () => {
+ const col = el.closest<HTMLElement>('[data-col]')?.dataset.col
+ if (col) this.toggleSort(col)
+ }
+ })
+ // select a whole column by its letter, the whole sheet by the corner
+ this.head.querySelectorAll<HTMLElement>('.dg-letter').forEach((el) => {
+ el.onclick = () => {
+ // `closest`, not `parentElement`: the letter sits inside a strip now,
+ // and reading `ci` off the immediate parent gave NaN the moment the
+ // header grew a second line.
+ const ci = Number(el.closest<HTMLElement>('[data-ci]')?.dataset.ci)
+ if (!Number.isFinite(ci)) return
+ this.sel.selectCol(ci)
+ this.paint(); this.announce()
+ }
+ })
+ const corner = this.head.querySelector<HTMLElement>('.dg-corner')
+ if (corner) corner.onclick = () => { this.sel.selectAll(); this.paint(); this.announce() }
+ // filter caret
+ this.head.querySelectorAll<HTMLElement>('[data-filter]').forEach((el) => {
+ el.onclick = (e) => {
+ e.stopPropagation()
+ const r = el.getBoundingClientRect()
+ this.onFilterMenu?.(el.dataset.filter!, r.left, r.bottom)
+ }
+ })
+ // column resize: drag the grip, double-click to fit the content
+ this.head.querySelectorAll<HTMLElement>('[data-grip]').forEach((el) => {
+ const id = el.dataset.grip!
+ el.onmousedown = (e) => {
+ e.preventDefault(); e.stopPropagation()
+ const col = this.sheet.columns.find((c) => c.id === id)!
+ const startX = e.clientX
+ const startW = col.w ?? 130
+ const cell = el.parentElement as HTMLElement
+ const move = (m: MouseEvent) => {
+ // live width during the drag, committed once on release — a commit
+ // per mousemove would be one undo entry per pixel
+ const w = Math.max(48, Math.round(startW + m.clientX - startX))
+ cell.style.width = `${w}px`
+ this.table.querySelectorAll<HTMLElement>(`.dg-cell[data-col="${id}"]`)
+ .forEach((c) => { c.style.width = `${w}px` })
+ }
+ const up = (m: MouseEvent) => {
+ document.removeEventListener('mousemove', move)
+ document.removeEventListener('mouseup', up)
+ const w = Math.max(48, Math.round(startW + m.clientX - startX))
+ if (w !== startW) this.store.commit(resizeColumn(this.sheet, id, w))
+ }
+ document.addEventListener('mousemove', move)
+ document.addEventListener('mouseup', up)
+ }
+ el.ondblclick = (e) => {
+ e.stopPropagation()
+ const s2 = this.sheet
+ const col = s2.columns.find((c) => c.id === id)!
+ const comp = this.computed.get(id)
+ const w = autoFitWidth(
+ (row) => comp ? comp[row] : readCell(s2.data[id], row),
+ col, rowCount(s2))
+ this.store.commit(resizeColumn(s2, id, w))
+ }
+ })
+ // row header selects the row
+ this.table.querySelectorAll<HTMLElement>('[data-rowhead]').forEach((el) => {
+ el.onmousedown = () => {
+ this.sel.selectRow(Number(el.dataset.rowhead))
+ this.paint(); this.announce()
+ }
})
this.head.querySelectorAll<HTMLElement>('[data-retype]').forEach((el) => {
el.onclick = (e) => {
e.stopPropagation()
const col = this.sheet.columns.find((c) => c.id === el.dataset.retype)
- if (col) this.onRetype?.(col)
+ const r = el.getBoundingClientRect()
+ if (col) this.onRetype?.(col, r.left, r.bottom)
}
})
- this.table.querySelectorAll<HTMLElement>('.dg-row[data-rid] .dg-cell').forEach((el) => {
+ this.table.querySelectorAll<HTMLElement>('.dg-row[data-rid] .dg-cell[data-ci]').forEach((el) => {
+ const row = Number(el.parentElement!.dataset.row)
+ const ci = Number(el.dataset.ci)
+ el.onmousedown = (e) => {
+ if (e.button !== 0) return
+ if (e.shiftKey) this.sel.extendTo(row, ci)
+ else this.sel.moveTo(row, ci)
+ this.paint(); this.announce()
+ // drag to extend
+ const move = (m: MouseEvent) => {
+ const t = (m.target as HTMLElement)?.closest?.('.dg-cell[data-ci]') as HTMLElement | null
+ if (!t) return
+ const r2 = Number(t.parentElement!.dataset.row)
+ const c2 = Number(t.dataset.ci)
+ if (Number.isFinite(r2) && Number.isFinite(c2)) {
+ this.sel.extendTo(r2, c2); this.paint(); this.announce()
+ }
+ }
+ const up = () => {
+ document.removeEventListener('mousemove', move)
+ document.removeEventListener('mouseup', up)
+ }
+ document.addEventListener('mousemove', move)
+ document.addEventListener('mouseup', up)
+ }
+ el.oncontextmenu = (e) => {
+ e.preventDefault()
+ if (!this.sel.ranges().some((rg) => contains(rg, row, ci))) {
+ this.sel.moveTo(row, ci); this.paint()
+ }
+ this.onContextMenu?.(row, ci, e.clientX, e.clientY)
+ }
el.ondblclick = () => this.edit(Number(el.parentElement!.dataset.rid), el.dataset.col!, el)
})
}
@@ -228,24 +1044,41 @@ export class Grid {
* takes no checkpoint, sets no dirty flag and produces no op.
*/
private toggleSort(colId: string): void {
- const s = this.sheet
const dir = this.sort?.col === colId && this.sort.dir === 'asc' ? 'desc' : 'asc'
this.sort = { col: colId, dir }
- const n = rowCount(s)
- const data = s.data[colId]
- const idx = Array.from({ length: n }, (_, i) => i)
- const sign = dir === 'asc' ? 1 : -1
- idx.sort((a, b) => {
- const x = readCell(data, a)
- const y = readCell(data, b)
- if (x == null) return 1 // blanks sink, both directions — a blank is
- if (y == null) return -1 // not "smallest", it is "not a value"
- return x < y ? -sign : x > y ? sign : 0
- })
- this.store.view(() => { this.store.order[s.id] = idx })
+ // Shift-click accumulates keys; a plain click replaces them. filter.ts's
+ // buildOrder does the multi-key comparison and sinks blanks in BOTH
+ // directions, which the hand-rolled single-key sort here did not.
+ this.sorts = [{ col: colId, dir }]
+ this.applyView()
+ }
+
+ /** Add or replace a sort key without clearing the others — shift-click. */
+ addSort(colId: string, dir: 'asc' | 'desc'): void {
+ this.sorts = this.sorts.filter((k) => k.col !== colId).concat({ col: colId, dir })
+ this.sort = { col: colId, dir }
+ this.applyView()
}
- private edit(rid: number, colId: string, cell: HTMLElement): void {
+ setFilter(colId: string, f: ColumnFilter | null): void {
+ this.filters = this.filters.filter((x) => x.col !== colId)
+ if (f) this.filters.push(f)
+ this.applyView()
+ }
+
+ clearView(): void { this.filters = []; this.sorts = []; this.sort = null; this.applyView() }
+
+ /**
+ * Open a cell for editing.
+ *
+ * `seed` is the character that STARTED the edit. Typing over a selected cell
+ * replaces its contents in every spreadsheet ever made — it is the single
+ * most-used interaction in the whole application, and requiring a
+ * double-click first is the difference between "a grid" and "a spreadsheet".
+ * When seed is undefined the existing value is loaded and selected, which is
+ * what F2 and a double-click do instead.
+ */
+ private edit(rid: number, colId: string, cell: HTMLElement, seed?: string): void {
const s = this.sheet
const col = s.columns.find((c) => c.id === colId)
if (!col || this.store.readOnly) return
@@ -257,37 +1090,119 @@ export class Grid {
const raw = readCell(s.data[colId], r)
cell.classList.add('dg-editing')
cell.contentEditable = 'true'
- cell.textContent = raw == null ? '' : String(raw)
+ // A formula cell edits its SOURCE. Showing the computed value would make
+ // every edit of a formula silently replace it with its own last result —
+ // the cell would look unchanged and the formula would be gone.
+ const src = this.formulaAtPos(dataRow(s, rid), s.columns.findIndex((c) => c.id === colId))
+ cell.textContent = seed !== undefined ? seed
+ : src !== undefined ? src
+ : (raw == null ? '' : String(raw))
cell.focus()
const range = document.createRange()
range.selectNodeContents(cell)
+ if (seed !== undefined) range.collapse(false) // caret AFTER the typed char
getSelection()?.removeAllRanges()
getSelection()?.addRange(range)
- const commit = () => {
- if (!this.editing) return
+ let done = false
+ const finish = (write: boolean, move?: 'down' | 'up' | 'right' | 'left') => {
+ if (done || !this.editing) return
+ done = true
this.editing = null
+ const text = cell.textContent ?? ''
cell.contentEditable = 'false'
cell.classList.remove('dg-editing')
- const text = cell.textContent ?? ''
- const v = coerceForColumn(text, col.type)
- this.store.runEdit(`${colId}:${rid}`, {
- op: 'setCells', sheet: s.id, col: colId, rids: [rid], v: [v],
- })
- this.store.endRun()
+ cell.onblur = null
+ if (write) {
+ const key = `${colId}:${rid}`
+ const had = s.cells?.[key]
+ if (isFormula(text)) {
+ // A formula rides on the cell OVERRIDE (`CellOverride.f`), which the
+ // format reserved for exactly this. The stored value is left alone:
+ // the document holds the expression and the number is derived, so a
+ // file can never carry a result that disagrees with its own formula.
+ this.store.runEdit(key, {
+ op: 'setOverrides', sheet: s.id, keys: [key], v: [{ ...had, f: text }],
+ })
+ } else {
+ const v = coerceForColumn(text, col.type)
+ const patches: Patch[] = [
+ { op: 'setCells', sheet: s.id, col: colId, rids: [rid], v: [v] },
+ ]
+ // Typing over a formula REMOVES it. Leaving `f` in place would show
+ // the typed number for one paint and then quietly recompute over it.
+ if (had?.f !== undefined) {
+ const { f: _f, ...rest } = had
+ patches.push({
+ op: 'setOverrides', sheet: s.id, keys: [key],
+ v: [Object.keys(rest).length ? rest : null], dropEmpty: true,
+ })
+ }
+ this.store.runEdit(key, patches)
+ }
+ this.store.endRun()
+ }
+ // COMMIT AND MOVE. Enter goes down, Tab goes right — a spreadsheet that
+ // leaves the cursor where it was makes you reach for the mouse between
+ // every value, which is most of what data entry is.
+ if (move) {
+ const d = move === 'down' ? [1, 0] : move === 'up' ? [-1, 0] : move === 'right' ? [0, 1] : [0, -1]
+ this.sel.move(d[0], d[1], {})
+ this.scrollIntoView()
+ }
+ this.paint()
+ this.announce()
+ this.focusGrid()
}
- cell.onblur = commit
+ cell.onblur = () => finish(true)
cell.onkeydown = (e) => {
- if (e.key === 'Enter') { e.preventDefault(); commit(); return }
- if (e.key === 'Escape') {
- e.preventDefault()
- this.editing = null
- cell.contentEditable = 'false'
- cell.classList.remove('dg-editing')
- this.paint()
- }
+ // stopPropagation on EVERY branch, including the ones that close the
+ // editor. finish() clears contentEditable synchronously, so by the time
+ // the event reaches the document the "is something being edited?" guard
+ // there no longer sees an editor — and Enter moved the cursor twice.
+ e.stopPropagation()
+ if (e.key === 'Enter') { e.preventDefault(); finish(true, e.shiftKey ? 'up' : 'down'); return }
+ if (e.key === 'Tab') { e.preventDefault(); finish(true, e.shiftKey ? 'left' : 'right'); return }
+ if (e.key === 'Escape') { e.preventDefault(); finish(false) }
}
}
+
+ /** Keep keystrokes coming to the grid after an edit closes. */
+ private focusGrid(): void {
+ if (this.scroller.tabIndex < 0) this.scroller.tabIndex = 0
+ this.scroller.focus({ preventScroll: true })
+ }
+
+ /**
+ * A printable key over a selected cell starts an edit with that character.
+ * Called from the app's keydown handler BEFORE keyToAction, because
+ * keyToAction deliberately returns null for bare printable keys so that
+ * typing can reach exactly here.
+ */
+ typeInto(ch: string): boolean {
+ if (this.editing || this.store.readOnly) return false
+ const vis = cols(this.sheet)
+ const col = vis[this.sel.cursor.col]
+ if (!col) return false
+ const rid = ridAt(this.store, this.sheet, this.sel.cursor.row)
+ if (rid < 0) return false
+ const cell = this.cellEl(this.sel.cursor.row, this.sel.cursor.col)
+ if (!cell) return false
+ this.edit(rid, col.id, cell, ch)
+ return true
+ }
+
+ /** F2 / double-click: edit the existing value rather than replacing it. */
+ editActive(): boolean {
+ if (this.editing) return false
+ const vis = cols(this.sheet)
+ const col = vis[this.sel.cursor.col]
+ const rid = ridAt(this.store, this.sheet, this.sel.cursor.row)
+ const cell = this.cellEl(this.sel.cursor.row, this.sel.cursor.col)
+ if (!col || rid < 0 || !cell) return false
+ this.edit(rid, col.id, cell)
+ return true
+ }
}
/** What the user typed, under the column's declared type. */
@@ -303,5 +1218,12 @@ function coerceForColumn(text: string, type: ColumnType): unknown {
return s
}
+/** Where a data bar starts, as a percentage — negatives run left of the axis. */
+const bar0 = (cf: CellStyle): number =>
+ cf.bar ? (cf.bar.negative ? Math.max(0, (cf.bar as { axis?: number }).axis ?? 0) - cf.bar.pct : (cf.bar as { axis?: number }).axis ?? 0) : 0
+
+const fmtNum = (n: number): string =>
+ new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 }).format(n)
+
const esc = (s: string): string =>
s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
diff --git a/dash/src/main.ts b/dash/src/main.ts
index 447dc697..3248a408 100644
--- a/dash/src/main.ts
+++ b/dash/src/main.ts
@@ -25,10 +25,23 @@ import { configureApp, appConfig } from '../../kernel/src/app.ts'
import {
capturePristine, readEmbeddedDoc, serializeFile, serializeAuto, saveFile,
parseEnvelope, decryptEnvelope, setEncryptionPassword, isEncryptionActive,
- canWriteInPlace, downloadFile, suggestedFileName, openedFileName,
+ canWriteInPlace, downloadFile, suggestedFileName, openedFileName, registerPreview,
} from '../../kernel/src/save.ts'
import { putRecovery, pruneOld } from '../../kernel/src/autosave.ts'
import { APP_VERSION } from '../../kernel/src/update.ts'
+import { mountAbout, openAbout, rememberVersion } from './about.ts'
+import { mountPanels } from './panels.ts'
+import { installStory } from './story.ts'
+import { Dashboard } from './dashboard.ts'
+import { SyncSession } from './sync/session.ts'
+import { mountPeople } from './sync/people.ts'
+import { ridBase, ridBlockFor } from './model.ts'
+import { setRidBlock } from './rowcol.ts'
+import { importXlsx, exportXlsx, xlsxFileName } from './xlsx.ts'
+import { runPivot, mountPivot, defaultPivot, newPivotSheet, type PivotSpec } from './pivot.ts'
+import { buildSheetPreview } from './preview.ts'
+import { installSaveMenu, adoptOpenedDoc } from './saveui.ts'
+import { dismissSplash, dismissSplashNow } from './splash.ts'
import { t } from './i18n.ts'
import {
parseDoc, docBytes, docBudget, rowCount, DOC_BUDGET_FSA, DOC_BUDGET_DOWNLOAD,
@@ -40,7 +53,53 @@ import { Grid } from './grid.ts'
import { importDelimited } from './import.ts'
import { TYPE_LABEL } from './format.ts'
import { defaultBinding, renderChart, type ChartBinding } from './chart.ts'
+import { readCell } from './store.ts'
+import {
+ insertRowsAt, deleteRowsAt, insertColumn, deleteColumn, resizeColumn,
+ autoFitWidth, setHidden, freezeAt, readFrozen } from './rowcol.ts'
import { FUNCTIONS } from './formula.ts'
+import { buildScene, defaultViz3d, mountViz3d, type Viz3dBinding, type Viz3dKind } from './viz3d.ts'
+
+// --- topbar icons -----------------------------------------------------------
+//
+// Every top-bar control carries an icon AND a <span> label, because that is the
+// only shape that survives a narrow window: under 1280px the CSS hides the
+// spans and the icons carry on alone (slides/src/styles.css does the same, and
+// its comment — "labels give way, never a scrollbar" — is the whole rule). A
+// label-only button has nothing left to shrink to, which is exactly how this
+// bar came to be 1436px wide inside an 802px window with Save off the end.
+//
+// 15px box, 1.6px strokes, currentColor: they have to read at 100% and at the
+// 0.45 opacity a disabled button gets.
+const SVG = (d: string): string =>
+ `<svg class="dx-i" viewBox="0 0 20 20" width="15" height="15" aria-hidden="true" fill="none" ` +
+ `stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round">${d}</svg>`
+
+const ICON = {
+ plus: SVG('<path d="M10 4v12M4 10h12"/>'),
+ fx: SVG('<path d="M12 4.5h-1.2a2 2 0 0 0-2 2V16"/><path d="M6.5 9.5h5"/><path d="M13 11l4 5M17 11l-4 5"/>'),
+ chart: SVG('<path d="M3.5 16.5h13"/><path d="M6.5 16.5v-5M10 16.5V5.5M13.5 16.5v-8"/>'),
+ cube: SVG('<path d="M10 2.8l6 3.4v7.6l-6 3.4-6-3.4V6.2z"/><path d="M4 6.2l6 3.4 6-3.4M10 9.6v7.6"/>'),
+ pivot: SVG('<rect x="3.2" y="3.2" width="13.6" height="13.6" rx="1.6"/><path d="M3.2 8h13.6M8 3.2v13.6"/>'),
+ dashboard: SVG('<rect x="3.2" y="3.2" width="6" height="6" rx="1.2"/><rect x="10.8" y="3.2" width="6" height="6" rx="1.2"/>' +
+ '<rect x="3.2" y="10.8" width="6" height="6" rx="1.2"/><rect x="10.8" y="10.8" width="6" height="6" rx="1.2"/>'),
+ story: SVG('<rect x="2.8" y="4" width="14.4" height="9.6" rx="1.4"/><path d="M7 17h6"/>'),
+ undo: SVG('<path d="M7 7H4.5V4.5"/><path d="M4.9 7.4A5.6 5.6 0 1 1 4.4 12"/>'),
+ data: SVG('<ellipse cx="10" cy="5.4" rx="5.6" ry="2.4"/><path d="M4.4 5.4v9.2c0 1.3 2.5 2.4 5.6 2.4s5.6-1.1 5.6-2.4V5.4"/><path d="M4.4 10c0 1.3 2.5 2.4 5.6 2.4s5.6-1.1 5.6-2.4"/>'),
+ // Import and export get OPPOSITE arrows, not two copies of the cylinder. Four
+ // rows reading "Import CSV / Export CSV / Import Excel / Export Excel" behind
+ // the same glyph is four rows you have to read word by word; the arrow is
+ // what lets you find the one you meant at a glance.
+ imp: SVG('<path d="M10 3v8.5"/><path d="M6.6 8.2L10 11.6l3.4-3.4"/><path d="M4.2 13.6v2.2h11.6v-2.2"/>'),
+ exp: SVG('<path d="M10 11.6V3.1"/><path d="M6.6 6.5L10 3.1l3.4 3.4"/><path d="M4.2 13.6v2.2h11.6v-2.2"/>'),
+ save: SVG('<path d="M4.4 3.6h8.3l3.3 3.3v9.5H4.4z"/><path d="M7 3.6v4.2h5V3.6"/><path d="M7 16.4v-4.6h6v4.6"/>'),
+ info: SVG('<circle cx="10" cy="10" r="7"/><path d="M10 9.2v4.4"/><path d="M10 6.6h.01"/>'),
+ down: SVG('<path d="M6 8l4 4 4-4"/>'),
+} as const
+
+/** A top-bar button: icon + collapsible label, the one shape the bar can shrink. */
+const barBtn = (act: string, icon: string, label: string, tip: string, extra = ''): string =>
+ `<button class="dx-btn${extra}" data-act="${act}" title="${esc(tip)}">${icon}<span>${esc(label)}</span></button>`
configureApp({
appId: 'bento-dash',
@@ -50,6 +109,11 @@ configureApp({
capturePristine()
+// The file-manager thumbnail. Registered BEFORE any save can happen: a save
+// that ran first would write a shell with no preview in it, and the next
+// thumbnail request would show the boot splash again.
+registerPreview(buildSheetPreview)
+
// --- boot -------------------------------------------------------------------
const blockEl = document.getElementById('bento-doc')
@@ -70,7 +134,7 @@ if (envelope) {
/** An encrypted workbook: ask, then take the same boot path. */
async function passwordGate(raw: string): Promise<void> {
- document.getElementById('bento-splash')?.remove()
+ dismissSplashNow()
document.body.innerHTML =
`<div class="dx-gate"><h1>${t('This file is encrypted.')}</h1>` +
`<p>${t('Enter the password to open this workbook.')}</p>` +
@@ -100,7 +164,7 @@ async function passwordGate(raw: string): Promise<void> {
* subscription are constructed, and none of them exist on this path.
*/
function refuse(res: Extract<ParseResult, { ok: false }>): void {
- document.getElementById('bento-splash')?.remove()
+ dismissSplashNow()
const why = res.err === 'empty' ? '' : 'detail' in res ? res.detail : ''
const found = 'found' in res && res.found ? ` (${res.found})` : ''
document.body.innerHTML =
@@ -127,32 +191,81 @@ function refuse(res: Extract<ParseResult, { ok: false }>): void {
function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): void {
document.title = `${doc.title} — ${appConfig().appName}`
- document.getElementById('bento-splash')?.remove()
+ dismissSplash()
const store = new Store(doc)
if (frozen) store.readOnly = true
+ // A template mints a fresh docId on open; a read-only copy locks the store
+ // (and with it the title field, which reads store.readOnly below).
+ adoptOpenedDoc(doc, store)
const app = document.getElementById('app')!
app.innerHTML =
+ // THE BAR IS GROUPED, AND IT NEVER SCROLLS. It used to be thirteen flat
+ // buttons: measured at an 802px window its scrollWidth was 1436px, and the
+ // controls hanging off the right edge included Save — the one control the
+ // whole application exists to reach. The layout strategy is slides':
+ // labels give way to icons, then whole groups fold into menus, and a
+ // horizontal scrollbar is never the answer (see styles.css "responsive
+ // top bar" for the widths and what happens at each).
+ //
+ // The grouping is a spreadsheet's, not an alphabet: identity · insert ·
+ // (right) history · data in-out · save · about. Import/export live behind
+ // ONE menu at every width — four buttons for something done twice a
+ // session is what pushed Save off screen in the first place.
`<header class="dx-bar">` +
- `<span class="dx-mark">bento<span>/</span>dash</span>` +
+ `<span class="dx-mark"><span class="dx-mark-b">bento</span><span class="dx-slash">/</span>dash</span>` +
`<input class="dx-title" value="">` +
- `<span class="dx-dirty" hidden>•</span>` +
- `<button class="dx-btn" data-act="formula">${t('+ Formula column')}</button>` +
- `<button class="dx-btn" data-act="chart">${t('+ Chart')}</button>` +
- `<button class="dx-btn" data-act="import">${t('Import CSV…')}</button>` +
- `<button class="dx-btn" data-act="undo">${t('Undo')}</button>` +
- `<button class="dx-btn" data-act="export">${t('Export CSV')}</button>` +
- `<button class="dx-btn" data-act="save">${t('Save')}</button>` +
+ // Insert group. `display: contents` at wide widths (the six buttons sit in
+ // the bar); a real dropdown below 1040px, where they do not fit. No JS
+ // reparenting, so every listener below keeps working at every width.
+ `<div class="dx-dd dx-insert-dd">` +
+ `<button class="dx-btn dx-dd-trig" data-dd="insert" title="${esc(t('Insert a formula column, chart, pivot, dashboard or story'))}">` +
+ `${ICON.plus}<span>${t('Insert')}</span>${ICON.down}</button>` +
+ `<div class="dx-menu">` +
+ barBtn('formula', ICON.fx, t('Formula'), t('Add a formula column')) +
+ barBtn('chart', ICON.chart, t('Chart'), t('Chart the selected columns')) +
+ barBtn('viz3d', ICON.cube, t('3D'), t('Plot three numeric columns in 3D')) +
+ barBtn('pivot', ICON.pivot, t('Pivot'), t('Summarise this sheet as a pivot table')) +
+ barBtn('dashboard', ICON.dashboard, t('Dashboard'), t('Show or hide the dashboard')) +
+ barBtn('story', ICON.story, t('Story'), t('Build a data story from saved views')) +
+ `</div></div>` +
+ `<div class="dx-group dx-bar-end">` +
+ barBtn('undo', ICON.undo, t('Undo'), t('Undo (⌘Z)')) +
+ `<div class="dx-dd dx-data-dd">` +
+ `<button class="dx-btn dx-dd-trig" data-dd="data" title="${esc(t('Import and export CSV and Excel files'))}">` +
+ `${ICON.data}<span>${t('Data')}</span>${ICON.down}</button>` +
+ `<div class="dx-menu">` +
+ barBtn('import', ICON.imp, t('Import CSV…'), t('Add a sheet from a CSV or TSV file')) +
+ barBtn('export', ICON.exp, t('Export CSV'), t('Download this sheet as CSV')) +
+ `<div class="dx-menu-sep"></div>` +
+ barBtn('import-xlsx', ICON.imp, t('Import Excel…'), t('Add sheets from an .xlsx workbook')) +
+ barBtn('export-xlsx', ICON.exp, t('Export Excel'), t('Download this workbook as .xlsx')) +
+ `</div></div>` +
+ // Save keeps its label all the way down to a phone: it is the control the
+ // user names when it is missing, and an unlabelled floppy is a guess.
+ // The unsaved dot badges its corner rather than floating loose in the bar,
+ // where it explained nothing (slides made the same move).
+ `<button class="dx-btn dx-btn-save" data-act="save" title="${esc(t('Save this workbook (⌘S)'))}">` +
+ `${ICON.save}<span class="dx-save-lab">${t('Save')}</span><span class="dx-dirty" hidden></span></button>` +
+ barBtn('about', ICON.info, t('About'), t('About this workbook')) +
`<span class="dx-ver">v${APP_VERSION}</span>` +
+ `</div>` +
`</header>` +
+ `<div class="dx-formula"><span class="dx-ref">A1</span>` +
+ `<span class="dx-fx-mark">fx</span>` +
+ `<input class="dx-fx-input" spellcheck="false" placeholder="${t('value or = formula')}">` +
+ `</div>` +
`<div class="dx-findings" hidden></div>` +
`<div class="dx-body"><div class="dx-grid"></div>` +
+ `<div class="dx-dash" hidden></div>` +
`<div class="dx-chart" hidden><div class="dx-chart-head">` +
`<span class="dx-chart-title"></span>` +
`<button class="dx-btn dx-chart-kind">${t('Bar')}</button>` +
`<button class="dx-btn dx-chart-close" title="${t('Hide chart')}">✕</button>` +
- `</div><div class="dx-chart-body"></div></div></div>`
+ `</div><div class="dx-chart-body"></div></div></div>` +
+ `<footer class="dx-status"><span class="dx-status-view"></span>` +
+ `<span class="dx-status-sum"></span></footer>`
const titleEl = app.querySelector<HTMLInputElement>('.dx-title')!
const dirtyEl = app.querySelector<HTMLElement>('.dx-dirty')!
@@ -160,8 +273,43 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): vo
titleEl.value = doc.title
titleEl.disabled = store.readOnly
+ const refEl = app.querySelector<HTMLElement>('.dx-ref')!
+ const fxEl = app.querySelector<HTMLInputElement>('.dx-fx-input')!
+ const sumEl = app.querySelector<HTMLElement>('.dx-status-sum')!
+ const viewEl = app.querySelector<HTMLElement>('.dx-status-view')!
+
const grid = new Grid({ el: app.querySelector<HTMLElement>('.dx-grid')!, store, sheetId: doc.sheets[0].id })
- grid.onRetype = (col) => retype(store, col)
+
+ // --- the formula bar and the status bar, both driven by the selection
+ grid.onSelectionChange = (summary, ref, value) => {
+ refEl.textContent = ref
+ if (document.activeElement !== fxEl) fxEl.value = value
+ sumEl.textContent = summary
+ }
+ fxEl.addEventListener('keydown', (e) => {
+ if (e.key !== 'Enter') return
+ grid.setActiveCell(fxEl.value)
+ fxEl.blur()
+ })
+
+ // --- the filter and sort menu, hung off each column header's caret
+ grid.onFilterMenu = (colId, x, y) => openFilterMenu(store, grid, colId, x, y, viewEl)
+ grid.onContextMenu = (row, ci, x, y) => openCellMenu(store, grid, row, ci, x, y)
+
+ // keyboard: the grid owns the key set when nothing else has focus
+ document.addEventListener('keydown', (e) => {
+ const t = e.target as HTMLElement | null
+ if (t && (t.tagName === 'INPUT' || t.isContentEditable)) return
+ // A bare printable key REPLACES the selected cell — the most-used gesture
+ // in a spreadsheet, and the one that makes a grid feel like one. It has to
+ // be tried before keyToAction, which returns null for printable keys
+ // precisely so that typing can reach here.
+ if (!e.metaKey && !e.ctrlKey && !e.altKey && e.key.length === 1) {
+ if (grid.typeInto(e.key)) { e.preventDefault(); return }
+ }
+ if (grid.handleKey(e)) e.preventDefault()
+ })
+ grid.onRetype = (col, x, y) => retype(store, col, x, y)
grid.onEditFormula = (col) => editFormula(store, grid, col)
// --- chart: bound to columns, derived at render, never stored
@@ -186,14 +334,24 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): vo
}
store.on('doc', drawChart)
kindBtn.addEventListener('click', () => {
+ if (viz) {
+ viz.kind = KINDS3D[(KINDS3D.indexOf(viz.kind) + 1) % KINDS3D.length]
+ draw3d()
+ return
+ }
if (!binding) return
binding.kind = KINDS[(KINDS.indexOf(binding.kind) + 1) % KINDS.length]
drawChart()
})
app.querySelector('.dx-chart-close')!.addEventListener('click', () => {
- chartEl.hidden = true; teardown?.(); teardown = null
+ chartEl.hidden = true
+ clearPivot()
+ teardown?.(); teardown = null
+ vizDown?.(); vizDown = null; viz = null
})
app.querySelector('[data-act="chart"]')!.addEventListener('click', () => {
+ clearPivot()
+ vizDown?.(); vizDown = null; viz = null
binding = defaultBinding(grid.sheet)
if (!binding) { showFindings(findingsEl, [{ message: t('This sheet has no numeric column to chart yet.') }]); return }
chartEl.hidden = false
@@ -201,6 +359,121 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): vo
})
app.querySelector('[data-act="formula"]')!.addEventListener('click', () => addFormula(store, grid))
+ // --- 3D: the same panel, a different renderer. Geometry is derived from the
+ // columns exactly as the 2D chart's series are, so nothing is stored.
+ let viz: Viz3dBinding | null = null
+ let vizDown: (() => void) | null = null
+ const KINDS3D: Viz3dKind[] = ['scatter', 'surface', 'bars', 'globe']
+ const draw3d = () => {
+ if (!viz || chartEl.hidden) return
+ vizDown?.(); teardown?.(); teardown = null
+ const sheet = grid.sheet
+ chartTitle.textContent = `3D ${viz.kind} · ` +
+ [viz.x, viz.y, viz.z, viz.lat, viz.lon].filter(Boolean)
+ .map((id) => sheet.columns.find((c) => c.id === id)?.name ?? id).join(' / ')
+ kindBtn.textContent = viz.kind[0].toUpperCase() + viz.kind.slice(1)
+ const scene = buildScene(sheet, viz, grid.computed as Map<string, unknown[]>)
+ vizDown = mountViz3d(chartBody, scene)
+ }
+ store.on('doc', () => { if (viz) draw3d() })
+ app.querySelector('[data-act="viz3d"]')!.addEventListener('click', () => {
+ clearPivot()
+ viz = defaultViz3d(grid.sheet)
+ if (!viz) {
+ showFindings(findingsEl, [{ message: t('This sheet needs at least three numeric columns, or a latitude and longitude, to plot in 3D.') }])
+ return
+ }
+ binding = null
+ chartEl.hidden = false
+ draw3d()
+ })
+
+ // Sheets on the left, properties on the right — the suite's shared chrome.
+ // AFTER grid.onSelectionChange is set: mountPanels CHAINS that callback
+ // rather than replacing it, so the formula bar and status bar keep working.
+ mountPanels({ store, grid, body: app.querySelector<HTMLElement>('.dx-body')! })
+
+ // --- pivot. A pivot is a DOCUMENT, not a view: "revenue by region by
+ // quarter" is an argument about what the data means, somebody built it, and
+ // "look at the pivot on sheet 3" has to name something that exists in the
+ // file. The sheet stores the SPEC and never the numbers.
+ let pivotSpec: PivotSpec | null = null
+ let pivotDown: (() => void) | null = null
+ const drawPivot = (): void => {
+ if (!pivotSpec || chartEl.hidden) return
+ pivotDown?.(); teardown?.(); teardown = null
+ const src = store.doc.sheets.find((sh) => sh.id === pivotSpec!.from)
+ if (!src || src.kind !== 'table') return
+ chartTitle.textContent = `${t('Pivot')} · ${src.name}`
+ // A pivot has no chart KIND, so the Bar/Line toggle beside the title is a
+ // control that does nothing to what is on screen. Hidden here and restored
+ // by the chart path below.
+ kindBtn.hidden = true
+ const computed = grid.computed as Map<string, unknown[]>
+ pivotDown = mountPivot(chartBody, runPivot(src, pivotSpec, { computed }), { sheet: src, computed })
+ }
+ const clearPivot = (): void => {
+ pivotDown?.(); pivotDown = null; pivotSpec = null
+ kindBtn.hidden = false
+ }
+ store.on('doc', () => { if (pivotSpec) drawPivot() })
+
+ app.querySelector('[data-act="import-xlsx"]')!.addEventListener('click', () => {
+ void pickXlsx(store, findingsEl, grid)
+ })
+ app.querySelector('[data-act="export-xlsx"]')!.addEventListener('click', () => {
+ void saveXlsx(store, grid, findingsEl)
+ })
+
+ app.querySelector('[data-act="pivot"]')!.addEventListener('click', () => {
+ const spec = defaultPivot(grid.sheet)
+ if (!spec) {
+ showFindings(findingsEl, [{ message:
+ t('This sheet needs a category column and a numeric column to pivot.') } as never])
+ return
+ }
+ // A PATCH, not replaceDoc: creating a pivot used to clear the undo stack,
+ // so every edit you could previously take back vanished the moment you
+ // asked for a summary of them.
+ const id = `pivot-${Math.floor(Date.now() % 1e8).toString(36)}`
+ store.commit({
+ op: 'setSheet', id,
+ sheet: newPivotSheet(id, `${grid.sheet.name} — ${t('pivot')}`, spec),
+ } as never)
+ binding = null; viz = null; vizDown?.(); vizDown = null
+ pivotSpec = spec
+ chartEl.hidden = false
+ drawPivot()
+ })
+
+ // --- the dashboard. The LAYOUT is document data (doc.views); the SELECTION
+ // is viewer state and goes through store.view(), so a cross-filter click
+ // never dirties the file.
+ const dashEl = app.querySelector<HTMLElement>('.dx-dash')!
+ const dash = new Dashboard({ el: dashEl, store })
+ // a CALLBACK, not a snapshot: Grid.paint REPLACES grid.computed each paint
+ dash.computed = () => grid.computed as Map<string, unknown[]>
+ app.querySelector('[data-act="dashboard"]')!.addEventListener('click', () => {
+ const show = dashEl.hidden
+ dashEl.hidden = !show
+ app.querySelector<HTMLElement>('.dx-grid')!.hidden = show
+ if (show) dash.render()
+ })
+
+ // The hook: a workbook that presents itself. A step is a saved VIEW — filter,
+ // sort, chart binding, camera, caption — and stepping between them morphs the
+ // chart from the model, because both frames are already in the file.
+ installStory({
+ store,
+ button: app.querySelector<HTMLElement>('[data-act="story"]')!,
+ sheetId: () => grid.sheet.id,
+ filters: () => grid.filters,
+ sorts: () => grid.sorts,
+ chart: () => binding,
+ viz: () => viz,
+ computed: (id) => (id === grid.sheet.id ? (grid.computed as Map<string, unknown[]>) : undefined),
+ })
+
const notes: Notice[] = []
if (frozen) {
notes.push({
@@ -225,10 +498,59 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): vo
// NEVER write an encrypted workbook's plaintext to IndexedDB. The kernel
// states the rule in its own header and enforces it in neither place, so
// every app has to remember — and the second one did not.
- if (!isEncryptionActive()) void putRecovery(store.doc)
+ if (!isEncryptionActive()) {
+ void putRecovery(store.doc)
+ // the timeline the About dialog restores from — throttled inside, and
+ // it refuses an encrypted workbook for the same reason putRecovery does
+ void rememberVersion(store.doc)
+ }
}, 2500)
}
+ // --- live collaboration.
+ //
+ // The session is CONSTRUCTED for every workbook but connects to nothing
+ // unless the file arrived carrying credentials or the reader opts in this
+ // session (`shareEligible`) — a freshly created workbook must never phone
+ // home (PLATFORM §5).
+ //
+ // The rid block is set FIRST and before any edit can happen. Two replicas
+ // minting the same rid for different rows would merge them into one and lose
+ // a row, and rid is identity everywhere — the CRDT node key, overrides,
+ // comments. See model.ts's partitioning note.
+ const sync = new SyncSession(store)
+ setRidBlock(ridBase(ridBlockFor(sync.actor)))
+ ;(window as unknown as Record<string, unknown>).__sync = sync
+
store.on('doc', markDirty)
+
+ // The wordmark and the version chip open About. Mounted AFTER markDirty
+ // exists — it takes it as the dirty signal for the edits it makes itself.
+ const aboutHooks = {
+ store,
+ showingSheet: () => grid.sheet.id,
+ showSheet: (id: string) => grid.setSheet(id),
+ onDirty: markDirty,
+ }
+ // The People panel: who else is in this workbook.
+ //
+ // It takes OVER its host (`host.innerHTML = …` on every render), so it gets
+ // a container of its own. Handing it `app` erased the entire application on
+ // boot — grid, panels, everything — and left only the panel markup behind,
+ // with nothing in the console because nothing threw.
+ const peopleEl = document.createElement('div')
+ // INSIDE the right-hand group, not after it. The bar's end group is what the
+ // responsive ladder measures and collapses; anything appended after it sits
+ // outside that arithmetic and pushes the whole toolbar — Save included —
+ // straight off the screen again.
+ const barEnd = app.querySelector<HTMLElement>('.dx-bar-end') ?? app.querySelector<HTMLElement>('.dx-bar')!
+ barEnd.insertBefore(peopleEl, barEnd.firstChild)
+ mountPeople(peopleEl, sync, store)
+ mountAbout(app, aboutHooks)
+ // …and an EXPLICIT way in. mountAbout only arms the wordmark and the version
+ // chip, and nobody guesses that a logo is a button — the chip, meanwhile, is
+ // the first thing the responsive rules drop. The ⓘ button is the real door;
+ // the other two stay as shortcuts for whoever already found them.
+ app.querySelector('[data-act="about"]')!.addEventListener('click', () => openAbout(aboutHooks))
void pruneOld()
titleEl.addEventListener('input', () => {
@@ -236,8 +558,45 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): vo
document.title = `${titleEl.value} — ${appConfig().appName}`
})
+ // --- the top-bar dropdowns.
+ // Two rules, and they are the whole of it: a trigger toggles its own group,
+ // and ANY click outside shuts every group. The second rule has to be
+ // pointerdown on the document — a menu that survives the click that opened
+ // the next one leaves two panels overlapping, which is how a bar with one
+ // menu is fine and a bar with two is not.
+ //
+ // Note the menus are NOT rebuilt per width: at wide widths CSS gives the
+ // group `display: contents` and its buttons sit in the bar, so `.open` is
+ // simply inert. Nothing moves, so nothing loses a listener.
+ const shutMenus = (except?: Element) => {
+ for (const dd of app.querySelectorAll('.dx-dd.open')) if (dd !== except) dd.classList.remove('open')
+ }
+ for (const trig of app.querySelectorAll<HTMLElement>('.dx-dd-trig')) {
+ trig.addEventListener('click', (e) => {
+ e.stopPropagation()
+ const dd = trig.closest('.dx-dd')!
+ const opening = !dd.classList.contains('open')
+ shutMenus()
+ dd.classList.toggle('open', opening)
+ })
+ }
+ // a menu item is a command: run it and get out of the way
+ for (const item of app.querySelectorAll('.dx-menu .dx-btn')) {
+ item.addEventListener('click', () => shutMenus())
+ }
+ document.addEventListener('pointerdown', (e) => {
+ const dd = (e.target as HTMLElement | null)?.closest?.('.dx-dd')
+ shutMenus(dd ?? undefined)
+ })
+ document.addEventListener('keydown', (e) => { if (e.key === 'Escape') shutMenus() })
+
// --- actions
app.querySelector('[data-act="save"]')!.addEventListener('click', () => { void doSave() })
+ installSaveMenu({
+ button: app.querySelector<HTMLElement>('[data-act="save"]')!,
+ store,
+ save: doSave,
+ })
app.querySelector('[data-act="undo"]')!.addEventListener('click', () => { store.undo() })
app.querySelector('[data-act="export"]')!.addEventListener('click', () => exportCsv(store))
app.querySelector('[data-act="import"]')!.addEventListener('click', () => {
@@ -253,10 +612,17 @@ function boot(doc: DashDoc, repaired: number, frozen?: 'policy' | 'version'): vo
})
document.addEventListener('paste', (e) => {
if ((e.target as HTMLElement)?.isContentEditable) return
+ const target = e.target as HTMLElement | null
+ if (target && target.tagName === 'INPUT') return
const text = e.clipboardData?.getData('text/plain')
- if (!text || !/[,;\t]/.test(text.split('\n')[0] ?? '')) return
+ if (!text) return
e.preventDefault()
- applyImport(store, findingsEl, grid, text, 'pasted')
+ // INTO THE CELLS, at the cursor — the gesture every spreadsheet has.
+ // This used to route every pasted block into the CSV importer, so ⌘V
+ // created a whole new sheet instead of filling the selection, and
+ // `grid.pasteTsv` sat there with no callers at all. Importing a file is
+ // what the Import button is for; ⌘V is paste.
+ grid.pasteTsv(text)
})
async function doSave(): Promise<void> {
@@ -345,18 +711,29 @@ function showFindings(host: HTMLElement, findings: Notice[]): void {
}
/** The correctable half of the type row: import guesses, you settle it. */
-function retype(store: Store, col: Column): void {
+/**
+ * Pick a column's type.
+ *
+ * A POPOVER, not `window.prompt`. Import refuses to guess a type it cannot
+ * decide and says so, and that refusal is only honest if fixing it is one
+ * click — which it was not when the click opened a native dialog asking the
+ * reader to type the NUMBER of the type they wanted from a list.
+ */
+function retype(store: Store, col: Column, x: number, y: number): void {
const types: ColumnType[] = ['text', 'number', 'money', 'percent', 'date', 'bool']
- const list = types.map((tp, i) => `${i + 1}. ${TYPE_LABEL[tp]}`).join('\n')
- const pick = window.prompt(`${t('Column type for')} "${col.name}"\n\n${list}`,
- String(types.indexOf(col.type) + 1))
- if (!pick) return
- const next = types[Number(pick) - 1]
- if (!next || next === col.type) return
+ const el = popover(x, y, types.map((tp) =>
+ `<button data-t="${tp}"${tp === col.type ? ' class="dx-pop-on"' : ''}>` +
+ `${esc(TYPE_LABEL[tp])}${tp === col.type ? ' ✓' : ''}</button>`).join(''))
const sheet = store.doc.sheets.find((s) =>
s.kind === 'table' && s.columns.some((c) => c.id === col.id)) as TableSheet | undefined
- if (!sheet) return
- store.commit({ op: 'setColumn', sheet: sheet.id, col: col.id, patch: { type: next } })
+ el.querySelectorAll<HTMLElement>('button').forEach((b) => {
+ b.onclick = () => {
+ const next = b.dataset.t as ColumnType
+ el.remove()
+ if (!sheet || next === col.type) return
+ store.commit({ op: 'setColumn', sheet: sheet.id, col: col.id, patch: { type: next } })
+ }
+ })
}
// --- export -----------------------------------------------------------------
@@ -382,8 +759,16 @@ function exportCsv(store: Store): void {
setTimeout(() => URL.revokeObjectURL(a.href), 1000)
}
-const esc = (s: string): string =>
- s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+// A FUNCTION DECLARATION, and it has to stay one. The boot dispatcher above
+// calls boot() during module evaluation — i.e. before this line runs — so as a
+// `const esc = …` arrow this sat in the temporal dead zone for the entire
+// first paint. Nothing noticed while only refuse() used it; the moment the top
+// bar did, every load died on "Cannot access 'esc' before initialization" with
+// the splash still up and nothing in the console (the boot try/catch swallows
+// it into the dark card). A declaration hoists, so the landmine is gone.
+function esc(s: string): string {
+ return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
// referenced so the budget constants are not tree-shaken out of the bundle,
// and so a reader of this file sees both halves of the rule in one place
@@ -422,3 +807,207 @@ function editFormula(store: Store, grid: Grid, col: Column): void {
patch: expr.trim() ? { formula: expr } : { formula: undefined },
})
}
+
+
+// --- menus -------------------------------------------------------------------
+
+/** A small popover, dismissed by the next click anywhere. */
+function popover(x: number, y: number, html: string): HTMLElement {
+ document.querySelector('.dx-pop')?.remove()
+ const el = document.createElement('div')
+ el.className = 'dx-pop'
+ el.style.left = `${Math.min(x, innerWidth - 260)}px`
+ el.style.top = `${Math.min(y, innerHeight - 40)}px`
+ el.innerHTML = html
+ document.body.appendChild(el)
+ setTimeout(() => {
+ const off = (e: MouseEvent) => {
+ if (!el.contains(e.target as Node)) { el.remove(); document.removeEventListener('mousedown', off) }
+ }
+ document.addEventListener('mousedown', off)
+ }, 0)
+ return el
+}
+
+/** Sort and filter for one column — the caret in its header. */
+function openFilterMenu(
+ store: Store, grid: Grid, colId: string, x: number, y: number, viewEl: HTMLElement,
+): void {
+ const col = grid.sheet.columns.find((c) => c.id === colId)
+ if (!col) return
+ const numeric = col.type === 'number' || col.type === 'money' || col.type === 'percent'
+ const el = popover(x, y,
+ `<button data-a="asc">${t('Sort A → Z')}</button>` +
+ `<button data-a="desc">${t('Sort Z → A')}</button>` +
+ `<div class="dx-pop-sep"></div>` +
+ `<label class="dx-pop-row"><span>${numeric ? t('Greater than') : t('Contains')}</span>` +
+ `<input class="dx-pop-in" spellcheck="false"></label>` +
+ `<button data-a="apply">${t('Apply filter')}</button>` +
+ `<button data-a="clear">${t('Clear filters and sorts')}</button>` +
+ `<div class="dx-pop-sep"></div>` +
+ `<button data-a="hide">${t('Hide this column')}</button>` +
+ `<button data-a="fit">${t('Fit width to content')}</button>` +
+ `<div class="dx-pop-sep"></div>` +
+ `<button data-a="freeze">${frozenTo(grid, colId) ? t('Unfreeze columns') : t('Freeze up to this column')}</button>`)
+ const input = el.querySelector<HTMLInputElement>('.dx-pop-in')!
+ const showView = () => {
+ const n = store.order[grid.sheet.id]?.length
+ viewEl.textContent = n === undefined ? ''
+ : t('{n} of {all} rows').replace('{n}', String(n))
+ .replace('{all}', String(grid.sheet.rids.reduce((a, [, c]) => a + c, 0)))
+ }
+ el.querySelectorAll<HTMLElement>('button').forEach((b) => {
+ b.onclick = () => {
+ const a = b.dataset.a
+ if (a === 'asc' || a === 'desc') grid.addSort(colId, a)
+ else if (a === 'apply') {
+ const v = input.value.trim()
+ // `v`, not `value` — and NO `as never`. The cast is what let this
+ // compile: filter.ts spells the payload `v`, so `{op:'greater',
+ // value:…}` reached the predicate with an undefined bound. Measured
+ // before the fix: "greater than 10000" left 0 of 8 rows, and `contains`
+ // matched everything, so the feature looked inert rather than wrong.
+ grid.setFilter(colId, v === '' ? null : {
+ col: colId,
+ pred: numeric
+ ? { op: 'greater', v: Number(v.replace(/[,\s£$€¥%]/g, '')) }
+ : { op: 'contains', v },
+ })
+ } else if (a === 'clear') grid.clearView()
+ else if (a === 'hide') store.commit(setHidden(grid.sheet, colId, true))
+ else if (a === 'freeze') {
+ // "up to this column" counts VISIBLE position, which is what the reader
+ // pointed at; a hidden column between them would otherwise freeze one
+ // more column than the menu item named.
+ const at = grid.sheet.columns.filter((c) => !c.hidden).findIndex((c) => c.id === colId)
+ store.commit(freezeAt(grid.sheet, 0, frozenTo(grid, colId) ? 0 : at + 1))
+ }
+ else if (a === 'fit') {
+ const sh = grid.sheet
+ const comp = grid.computed.get(colId)
+ store.commit(resizeColumn(sh, colId,
+ autoFitWidth((row) => comp ? comp[row] : readCellOf(sh, colId, row), col,
+ sh.rids.reduce((n, [, c]) => n + c, 0))))
+ }
+ showView()
+ el.remove()
+ }
+ })
+ input.focus()
+}
+
+/** Is the freeze already exactly at this column? Then the item offers to undo it. */
+const frozenTo = (grid: Grid, colId: string): boolean => {
+ const at = grid.sheet.columns.filter((c) => !c.hidden).findIndex((c) => c.id === colId)
+ return readFrozen(grid.sheet).cols === at + 1
+}
+
+/** Open a .xlsx. Every worksheet arrives as its own dash sheet. */
+async function pickXlsx(store: Store, host: HTMLElement, grid: Grid): Promise<void> {
+ const input = document.createElement('input')
+ input.type = 'file'
+ input.accept = '.xlsx,application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+ input.addEventListener('change', () => {
+ const f = input.files?.[0]
+ if (!f) return
+ void f.arrayBuffer().then(async (buf) => {
+ try {
+ const r = await importXlsx(new Uint8Array(buf), {
+ source: f.name, at: new Date().toISOString(),
+ idPrefix: `xl-${Math.floor(Date.now() % 1e8).toString(36)}`,
+ })
+ store.doc.sheets.push(...r.sheets)
+ store.replaceDoc(store.doc)
+ if (r.sheets.length) grid.setSheet(r.sheets[0].id)
+ showFindings(host, r.findings as never)
+ } catch (e) {
+ // A refusal, not a crash: the file on disk is untouched.
+ showFindings(host, [{ message: `${t('That .xlsx could not be opened.')} ${e instanceof Error ? e.message : String(e)}` }] as never)
+ }
+ })
+ })
+ input.click()
+}
+
+/**
+ * Save as .xlsx. `grid.computed` carries the formula columns' VALUES, which are
+ * never stored — without them a computed column exports empty, and the exporter
+ * says so in its findings rather than shipping blanks quietly.
+ */
+async function saveXlsx(store: Store, grid: Grid, host: HTMLElement): Promise<void> {
+ const r = await exportXlsx(store.doc, {
+ at: new Date(),
+ computed: { [grid.sheet.id]: grid.computed as Map<string, unknown[]> },
+ })
+ const a = document.createElement('a')
+ a.href = URL.createObjectURL(new Blob([r.bytes as BlobPart], {
+ type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+ }))
+ a.download = xlsxFileName(store.doc.title)
+ a.click()
+ setTimeout(() => URL.revokeObjectURL(a.href), 1000)
+ showFindings(host, r.findings as never)
+}
+
+const readCellOf = (sheet: TableSheet, colId: string, row: number): unknown =>
+ readCell(sheet.data[colId], row)
+
+/** Right-click on the grid: the structural operations. */
+function openCellMenu(store: Store, grid: Grid, row: number, ci: number, x: number, y: number): void {
+ const sheet = grid.sheet
+ const col = sheet.columns[ci]
+ const el = popover(x, y,
+ `<button data-a="irow-above">${t('Insert row above')}</button>` +
+ `<button data-a="irow-below">${t('Insert row below')}</button>` +
+ `<button data-a="drow">${t('Delete row')}</button>` +
+ `<div class="dx-pop-sep"></div>` +
+ `<button data-a="icol">${t('Insert column')}</button>` +
+ `<button data-a="dcol">${t('Delete column')}</button>` +
+ `<div class="dx-pop-sep"></div>` +
+ `<button data-a="fill">${t('Fill down')}</button>` +
+ `<button data-a="clear">${t('Clear contents')}</button>` +
+ `<div class="dx-pop-sep"></div>` +
+ `<button data-a="cf-scale">${t('Colour scale')}</button>` +
+ `<button data-a="cf-bar">${t('Data bars')}</button>` +
+ `<button data-a="cf-off">${t('Remove formatting')}</button>`)
+ el.querySelectorAll<HTMLElement>('button').forEach((b) => {
+ b.onclick = () => {
+ const a = b.dataset.a
+ // `row` is a VISIBLE index and every structural op takes a canonical
+ // one. They differ the moment somebody sorts, and passing the wrong one
+ // deletes the wrong row — silently, because the view re-sorts over the
+ // evidence. Each edit also carries the reference shift for the cell
+ // formulas, in the SAME commit: a document where the rows have moved and
+ // the formulas have not is a workbook of plausible wrong numbers.
+ const at = grid.canonicalRow(row)
+ if (a === 'irow-above') {
+ store.commit([...insertRowsAt(sheet, at, 1), ...grid.shiftFormulas('row', at, 1)])
+ } else if (a === 'irow-below') {
+ store.commit([...insertRowsAt(sheet, at + 1, 1), ...grid.shiftFormulas('row', at + 1, 1)])
+ } else if (a === 'drow') {
+ store.commit([...deleteRowsAt(sheet, at, 1), ...grid.shiftFormulas('row', at, -1)])
+ } else if (a === 'icol') {
+ const name = window.prompt(t('Column name'), t('New column')) || t('New column')
+ const id = `c-${Math.floor(Date.now() % 1e8).toString(36)}`
+ const cAt = sheet.columns.findIndex((c) => c.id === col?.id) + 1
+ store.commit([...insertColumn(sheet, cAt, { id, name, type: 'text' }),
+ ...grid.shiftFormulas('col', cAt, 1)])
+ } else if (a === 'dcol' && col) {
+ const cAt = sheet.columns.findIndex((c) => c.id === col.id)
+ store.commit([...deleteColumn(sheet, col.id), ...grid.shiftFormulas('col', cAt, -1)])
+ }
+ else if (a === 'fill') grid.fillDownSelection()
+ else if (a === 'clear') grid.clearSelection()
+ else if (col && (a === 'cf-scale' || a === 'cf-bar' || a === 'cf-off')) {
+ // Conditional formats are DOCUMENT data — they travel with the file —
+ // and live in an additive field, so an older build keeps them.
+ const cf = { ...((sheet as unknown as { condfmt?: Record<string, unknown> }).condfmt ?? {}) }
+ if (a === 'cf-off') delete cf[col.id]
+ else if (a === 'cf-scale') cf[col.id] = [{ kind: 'colorScale', colors: ['#fee2e2', '#fef9c3', '#dcfce7'] }]
+ else cf[col.id] = [{ kind: 'dataBar', color: '#F7A600', negativeColor: '#E1616C' }]
+ store.commit({ op: 'setSheetProps', sheet: sheet.id, props: { condfmt: cf } } as never)
+ }
+ el.remove()
+ }
+ })
+}
diff --git a/dash/src/model.ts b/dash/src/model.ts
index cbe501c3..75324d4e 100644
--- a/dash/src/model.ts
+++ b/dash/src/model.ts
@@ -113,6 +113,15 @@ export interface CellOverride {
was?: unknown
/** A per-cell formula, for the cases a column expression cannot express. */
f?: string
+ /**
+ * The formula an imported .xlsx held, kept VERBATIM even when dash will not
+ * evaluate it — a cross-sheet reference, an external workbook, a function we
+ * lack. `f` is what dash computes; this is what the file said. Keeping both
+ * is what stops an xlsx → dash → xlsx round trip from quietly deleting
+ * somebody's model, and it is why an import that cannot run a formula still
+ * shows the cached VALUE rather than a blank or a zero.
+ */
+ xlsxF?: string
/** Volatiles (`TODAY()`): the moment this value was committed. */
froze?: string
/**
@@ -189,6 +198,22 @@ export interface TableSheet {
* attach to.
*/
rids: Array<[number, number]>
+ /**
+ * The rid watermark: the next rid this sheet may mint.
+ *
+ * MONOTONIC, and deliberately not restored by undo. Without it the floor is
+ * derived from the current maximum, so deleting the last row lowers it and
+ * the next insert REUSES that rid — measured: rid 3 deleted, then minted
+ * again for a different row. The header above says rids are never reused,
+ * and everything that attaches to one (overrides, comments, CRDT nodes)
+ * assumes it. Under collaboration it stops being untidy and becomes a
+ * correctness precondition: two replicas would mint the same rid for two
+ * different rows and merge them into one.
+ *
+ * Optional because files written before it exists have none; `nextRidFloor`
+ * falls back to deriving it, which is the old behaviour.
+ */
+ nextRid?: number
columns: Column[]
/** colId → encoded column. */
data: Record<string, ColumnData>
@@ -230,7 +255,77 @@ export interface CanvasCell {
[extra: string]: unknown
}
-export type Sheet = TableSheet | CanvasSheet
+/**
+ * A pivot sheet holds a SPEC and never the numbers it produces — the same rule
+ * a chart tile follows, so a pivot cannot disagree with its data, go stale, or
+ * double the file.
+ */
+export interface PivotSheet {
+ id: string
+ name: string
+ kind: 'pivot'
+ pivot: Record<string, unknown>
+ [extra: string]: unknown
+}
+
+// --- rid partitioning -------------------------------------------------------
+//
+// TWO REPLICAS MUST NEVER MINT THE SAME RID FOR DIFFERENT ROWS. The watermark
+// (`TableSheet.nextRid`) makes minting monotonic, which fixes reuse after a
+// delete — but it cannot help the CONCURRENT case, where two people insert at
+// the same moment, both compute "one past the highest I know about", and both
+// get the same number. rid is identity: the CRDT keys a row node on it, and
+// overrides and comments attach to it. Two different rows sharing one would
+// merge into a single row and silently lose one of them.
+//
+// So under collaboration each replica mints from its OWN BLOCK of the rid
+// space. `rid = base + counter`, and no two replicas share a base.
+//
+// THE SPLIT. JavaScript integers are exact to 2^53. That budget is divided
+// 30 bits of block by 23 bits of counter: 1.07e9 blocks, and 8.4M rows per
+// replica per workbook — comfortably past `docBudget`, which stops a document
+// long before then. The alternative split (more rows, fewer blocks) buys
+// capacity nobody reaches at the cost of the only thing that matters here.
+//
+// BLOCK 0 IS RESERVED and is what a solo document uses, so an unshared
+// workbook still numbers its rows 1, 2, 3 and run-length encodes to
+// `[[1, 4200]]`. Nothing about the common case changes; the cost is paid only
+// once a second person is actually editing.
+//
+// THE RESIDUAL RISK, stated plainly: a block is derived from the actor id, so
+// two replicas collide only if their derived blocks collide. That is the same
+// assumption the engine already rests on everywhere else — actor ids are
+// random per session and every register comparison assumes they differ. With
+// 1.07e9 blocks the chance for ten concurrent editors is about 5e-8, and for a
+// hundred about 5e-6. It is not zero, and pretending otherwise would be worse
+// than saying so.
+
+/** Rows one replica may mint in one workbook: 2^23. */
+export const RID_BLOCK = 8_388_608
+/** Blocks available: 2^30. Block 0 is the solo/pre-collab range. */
+export const RID_BLOCKS = 1_073_741_824
+
+/**
+ * The rid block for an actor id — deterministic, and never 0.
+ *
+ * FNV-1a over the id. It only has to spread evenly; it is not a security
+ * property, and the uniqueness it inherits is the actor id's.
+ */
+export function ridBlockFor(actor: string): number {
+ let h = 0x811c9dc5
+ for (let i = 0; i < actor.length; i++) {
+ h ^= actor.charCodeAt(i)
+ h = Math.imul(h, 0x01000193) >>> 0
+ }
+ // 1..RID_BLOCKS-1 — never block 0, which belongs to solo documents
+ return (h % (RID_BLOCKS - 1)) + 1
+}
+
+/** First rid in a block. Block 0 starts at 1, so a solo file numbers from 1. */
+export const ridBase = (block: number): number =>
+ block <= 0 ? 1 : block * RID_BLOCK
+
+export type Sheet = TableSheet | CanvasSheet | PivotSheet
/**
* A named measure. Measured at 7,289 bytes for a real six-entity model — 0.13%
@@ -254,7 +349,11 @@ export interface Measure {
}
export interface Tile {
- kind: 'chart' | 'kpi' | 'slice' | 'text' | 'gl'
+ /** Stable per-tile identity — a cross-filter click is attributed to its tile
+ * so a tile never filters ITSELF into a single bar. */
+ id?: string
+ title?: string
+ kind: 'chart' | 'kpi' | 'slice' | 'text' | 'gl' | 'table'
x: number
y: number
w: number
@@ -265,8 +364,16 @@ export interface Tile {
* does not double the file. */
bind?: {
sheet: string; x?: string; by?: string; series?: string[]
+ /** a single column, for a KPI or a one-column table */
+ col?: string
+ /** several, for a table tile */
+ cols?: string[]
measure?: string; agg?: string
}
+ /** chart kind for a chart tile — bar/line/pie, as chart.ts spells them */
+ chart?: string
+ /** what a KPI compares against: the whole sheet, its own column, or nothing */
+ compare?: 'all' | 'column' | null
option?: Record<string, unknown>
/** REQUIRED on `kind:'gl'`: what to draw where WebGL is unavailable. */
fallback?: 'heatmap' | 'scatter2d' | 'table'
@@ -276,6 +383,9 @@ export interface Tile {
export interface View {
id: string
name: string
+ /** GRID UNITS — columns and rows of the tile grid, never pixels. A pixel
+ * layout would lay out differently on every reader's screen, which is the
+ * one thing a shared document must not do. */
w: number
h: number
tiles: Tile[]
@@ -312,6 +422,8 @@ export interface DashDoc {
meta?: DocMeta
sheets: Sheet[]
measures?: Record<string, Measure>
+ /** the data story — see the Story block at the foot of this file */
+ story?: Story
names?: Record<string, { v: number | string; note?: string }>
views?: View[]
theme?: Theme
@@ -358,7 +470,7 @@ export const docBudget = (canWriteInPlace: boolean): number =>
// --- Parsing -------------------------------------------------------------
export interface Repair {
- what: 'sheet-id' | 'column-id' | 'duplicate-id' | 'missing-id'
+ what: 'sheet-id' | 'column-id' | 'duplicate-id' | 'missing-id' | 'doc-id'
id: string
became: string
}
@@ -385,6 +497,15 @@ export interface Repair {
* loss this type exists to prevent. The boot site decides it, because only the
* boot site can still see the DOM.
*/
+/**
+ * A fresh document identity. Never derived from anything in the document —
+ * two workbooks made from the same template must not collide.
+ */
+export const newDocId = (): string =>
+ typeof crypto !== 'undefined' && crypto.randomUUID
+ ? crypto.randomUUID()
+ : `d-${Math.random().toString(36).slice(2)}${Date.now().toString(36)}`
+
export type ParseResult =
| { ok: true; doc: DashDoc; repairs: Repair[]; frozen?: 'policy' | 'version' }
| { ok: false; err: 'empty' }
@@ -496,6 +617,20 @@ export function parseDoc(json: string): ParseResult {
return { ...s, id, kind: 'canvas', cells: isObj(s.cells) ? s.cells : {} } as unknown as CanvasSheet
}
+ // AN UNRECOGNISED KIND IS PRESERVED VERBATIM, not coerced to a table.
+ //
+ // This branch used to fall through, so every sheet that was not 'canvas'
+ // came back as `kind: 'table'` with empty rids/columns/data/steps bolted
+ // on. That is not a pivot-shaped problem, it is the additivity invariant
+ // (PLATFORM §3) failing for EVERY future sheet kind: a build that has never
+ // heard of one is required to keep the file intact, and instead it quietly
+ // rewrote the sheet into a different thing and dropped what made it one.
+ // Old builds are frozen code, so a file written by a newer dash has to
+ // survive a round trip through them untouched.
+ if (typeof s.kind === 'string' && s.kind !== 'table') {
+ return { ...s, id } as unknown as Sheet
+ }
+
const colIds = new Set<string>()
const renamed = new Map<string, string>()
const columns = Array.isArray(s.columns)
@@ -540,7 +675,16 @@ export function parseDoc(json: string): ParseResult {
} as unknown as TableSheet
})
- const doc = { ...raw, format: FORMAT, version, sheets } as unknown as DashDoc
+ // MINT A docId IF THE FILE HAS NONE. The field is declared required and was
+ // not enforced, so a document block without one parsed happily and booted
+ // with `docId: undefined` — and everything that keys off it (autosave
+ // recovery, the version timeline, every future merge) then shares ONE slot
+ // named "undefined" across every such workbook. Slides mints it here for the
+ // same reason. It persists from the next save on, so a file gains an
+ // identity once and keeps it.
+ const docId = typeof raw.docId === 'string' && raw.docId ? raw.docId : newDocId()
+ if (docId !== raw.docId) repairs.push({ what: 'doc-id', id: '', became: docId })
+ const doc = { ...raw, format: FORMAT, version, docId, sheets } as unknown as DashDoc
return frozen ? { ok: true, doc, repairs, frozen } : { ok: true, doc, repairs }
}
@@ -557,3 +701,112 @@ export const rowCount = (doc: DashDoc): number =>
(n, s) => n + (s.kind === 'table' ? s.rids.reduce((m, [, c]) => m + c, 0) : 0),
0,
)
+
+// The story references the chart and 3D binding shapes. Both imports are
+// TYPE-ONLY and therefore erased, so this does not create a runtime cycle with
+// chart.ts/viz3d.ts, which import model.ts back.
+import type { ChartBinding } from './chart.ts'
+import type { Viz3dBinding } from './viz3d.ts'
+
+// --- data story --------------------------------------------------------------
+//
+// An ADDITIVE top-level field (`DashDoc.story`). A build that has never heard of
+// stories keeps it on a round trip and simply does not present it — the format
+// rule PLATFORM §3 states, and the reason the field can ship before the
+// presenter is finished.
+
+/**
+ * A filter, in the form that survives JSON.
+ *
+ * filter.ts's `Predicate` carries a `Set` for the checkbox list, and a Set
+ * serializes as `{}` — the filter would come back from the file matching
+ * NOTHING, which reads as "this step's data vanished" rather than as a broken
+ * round trip. So the stored spelling is an array and `toPredicate` /
+ * `fromPredicate` are the only bridge. Everything else is passed through
+ * verbatim, including a predicate op this build does not know: it is dropped at
+ * USE time (`toFilters`) and kept in the document, which is the additive
+ * behaviour and not the same as deleting it.
+ */
+export type StoredPredicate =
+ | { op: 'equals' | 'notEquals' | 'greater' | 'less' | 'greaterOrEqual' | 'lessOrEqual'; v: unknown }
+ | { op: 'contains' | 'notContains' | 'startsWith' | 'endsWith'; v: string }
+ | { op: 'between'; lo: unknown; hi: unknown }
+ | { op: 'isBlank' | 'notBlank' }
+ /** the Excel checkbox list; `null` in the list is the "(Blanks)" box */
+ | { op: 'isOneOf'; values: unknown[] }
+ | { op: 'topN' | 'bottomN'; n: number }
+ /** a predicate a future build understands. Kept, not applied. */
+ | { op: string; [k: string]: unknown }
+
+export interface StoredFilter {
+ col: string
+ pred: StoredPredicate
+ [extra: string]: unknown
+}
+
+export interface SortKey {
+ col: string
+ dir: 'asc' | 'desc'
+}
+
+/**
+ * Where the 3D camera stands. Angles in radians, matching gl.ts's `Orbit`, so
+ * capture and restore are a field copy rather than a conversion nobody can
+ * check. `distance` is optional because `frameCamera` derives a sensible one
+ * from the scene radius, and a stored distance from a differently-sized slice
+ * of the data would frame the next step wrong.
+ */
+export interface StoryCamera {
+ azimuth: number
+ elevation: number
+ distance?: number
+ [extra: string]: unknown
+}
+
+/**
+ * The subset the step is ABOUT — category values on the chart's x axis.
+ *
+ * Carried in the format from commit one even though the renderer cannot paint
+ * it yet (see KNOWN GAPS): a field added later is permanently second-class,
+ * which is the same argument model.ts makes for `CanvasSheet` and for the
+ * reserved `bind` op.
+ */
+export interface StoryHighlight {
+ values: unknown[]
+ label?: string
+ [extra: string]: unknown
+}
+
+/**
+ * How to get here from the step before.
+ *
+ * An OPEN union, like model.ts's `Policy`. A value this build does not know
+ * must PARSE and must degrade to a cut — a story from a newer build has to
+ * play, less prettily, rather than throw in front of an audience.
+ */
+export type StoryTransition = 'morph' | 'cut' | (string & {})
+
+/** One saved view of the data. */
+export interface StoryStep {
+ id: string
+ /** sheet id. A step whose sheet was deleted is SKIPPED, never guessed at. */
+ sheet: string
+ caption?: string
+ filters?: StoredFilter[]
+ sorts?: SortKey[]
+ /** the same binding shape chart.ts uses — columns, not numbers */
+ chart?: ChartBinding
+ /** a 3D step. `chart` and `viz` are alternatives; `viz` wins if both are set. */
+ viz?: Viz3dBinding
+ camera?: StoryCamera
+ highlight?: StoryHighlight
+ transition?: StoryTransition
+ /** seconds. Clamped at use; a story that hangs for a minute is not a story. */
+ duration?: number
+ [extra: string]: unknown
+}
+
+export interface Story {
+ steps: StoryStep[]
+ [extra: string]: unknown
+}
diff --git a/dash/src/panels.css b/dash/src/panels.css
new file mode 100644
index 00000000..b3bd7223
--- /dev/null
+++ b/dash/src/panels.css
@@ -0,0 +1,339 @@
+/* SPDX-License-Identifier: MIT
+ Copyright (c) 2026 The Bento authors
+ Side panels — dash's half of the suite's shared chrome.
+
+ The geometry is slides' (slides/src/styles.css `.ed-sidebar` / `.ed-props` /
+ `.ed-section` / `.ed-row` / `.ed-resizer`), copied to the pixel: 11px
+ uppercase section headers at 0.07em, 12.5px rows with a 110px control, 8px
+ gaps, 6px control radii, a 5px resizer strip and a 16×44 chevron docked to
+ the screen edge when its panel is shut. The COLOURS come from dash's own
+ :root, so the panels sit against dash's grid rather than importing slides'
+ palette wholesale. Two apps that agree on spacing and differ on hue read as
+ one product; the reverse does not. */
+
+/* ————— layout ————— */
+
+/* Everything that was already in .dx-body — the grid and the chart — moves in
+ here at mount, so the panels bracket BOTH rather than just the grid. */
+.dp-centre {
+ flex: 1 1 auto;
+ min-width: 0;
+ min-height: 0;
+ display: flex;
+}
+
+/* styles.css stacks .dx-body on a narrow window so the chart sits UNDER the
+ grid. The panels are the columns now, so that flip moves down one level.
+ `#app` gives these the specificity to win regardless of stylesheet order —
+ which import order decides, and import order is not something a rule this
+ load-bearing should depend on. */
+@media (max-width: 760px) {
+ #app .dx-body { flex-direction: row; }
+ #app .dp-centre { flex-direction: column; }
+}
+
+/* ————— phones: the panels become DRAWERS —————
+ As flex siblings, two 220px panels plus their resizers claim 450px of a
+ 390px screen: MEASURED, document.body.scrollWidth was 460 against a
+ clientWidth of 390, so the whole app grew a horizontal scrollbar and the
+ grid — the thing you came for — was the smallest region on screen.
+ panels.ts already shuts both panels at BOOT on a narrow window, which is why
+ this never showed up on a real phone; it shows up the moment a desktop window
+ is narrowed or a tablet is rotated, because that path runs once and never
+ again. Overlaying costs no layout width at all, so the grid keeps the full
+ screen whether a drawer is open or shut. slides made the same move at the
+ same breakpoint, and for the same reason.
+
+ 699 and not 700, because panels.ts tests `vw < PHONE_W` with PHONE_W = 700 —
+ so 700 is a DESKTOP there. At `max-width: 700px` the two definitions
+ disagreed on exactly one pixel, and on that pixel a fresh load left both
+ panels open AND floating: two overlay drawers covering a 700px window, with
+ the grid a sliver between them. Breakpoints that mean the same thing have to
+ BE the same number. */
+@media (max-width: 699px) {
+ #app .dx-body { position: relative; }
+ #app .dp-panel {
+ position: absolute;
+ top: 0;
+ bottom: 0;
+ z-index: 40;
+ box-shadow: var(--shadow-pop);
+ }
+ #app .dp-left { left: 0; }
+ #app .dp-right { right: 0; }
+ /* a shut drawer casts no shadow, or the closed edge draws a grey smear */
+ #app .dp-panel.dp-shut { box-shadow: none; }
+
+ /* Both chevrons DOCK now, open or shut. With the panels floating, the two
+ resizer strips are the only things left in flow, so they sit hard against
+ the screen edges — and a 16px chevron centred on a 5px rail then hung 5.5px
+ past the viewport. Measured: body.scrollWidth 396 against clientWidth 390,
+ a horizontal scrollbar for six pixels of decoration. These are the same
+ rules the shut state already used; the phone just always wants them. */
+ #app .dp-panel + .dp-resizer .dp-toggle {
+ left: 0;
+ transform: translateY(-50%);
+ border-top-left-radius: 0;
+ border-bottom-left-radius: 0;
+ }
+ #app .dp-resizer:has(+ .dp-panel) .dp-toggle {
+ left: auto;
+ right: 0;
+ transform: translateY(-50%);
+ border-top-right-radius: 0;
+ border-bottom-right-radius: 0;
+ }
+}
+
+.dp-panel {
+ width: var(--dp-w, 220px);
+ flex: none;
+ overflow-y: auto;
+ overflow-x: hidden;
+ scrollbar-gutter: stable;
+ background: var(--surface);
+ padding: 12px;
+ transition: width 0.18s ease, padding 0.18s ease;
+}
+.dp-left { border-right: 1px solid var(--line); }
+.dp-right { border-left: 1px solid var(--line); padding: 14px; }
+
+.dp-panel.dp-shut {
+ width: 0;
+ min-width: 0; /* flex items floor at min-content without this */
+ padding-left: 0;
+ padding-right: 0;
+ border-width: 0;
+ overflow: hidden;
+}
+.dp-noanim { transition: none !important; }
+
+/* ————— resizer strips ————— */
+
+.dp-resizer {
+ position: relative;
+ flex: none;
+ width: 5px;
+ cursor: col-resize;
+ background: transparent;
+ transition: background 0.12s ease 0.08s;
+}
+.dp-resizer:hover,
+body.dp-resizing .dp-resizer { background: rgb(247 166 0 / 0.45); }
+body.dp-resizing { cursor: col-resize; user-select: none; }
+/* against a shut panel the strip carries nothing but the reopen chevron */
+.dp-panel.dp-shut + .dp-resizer,
+.dp-resizer:has(+ .dp-panel.dp-shut) { cursor: default; }
+.dp-panel.dp-shut + .dp-resizer:hover,
+.dp-resizer:has(+ .dp-panel.dp-shut):hover { background: transparent; }
+
+.dp-toggle {
+ position: absolute;
+ top: 50%;
+ left: 50%;
+ transform: translate(-50%, -50%);
+ width: 16px;
+ height: 44px;
+ border: 1px solid var(--line);
+ border-radius: 8px;
+ background: var(--surface);
+ color: var(--muted);
+ font: 11px/1 inherit;
+ padding: 0;
+ cursor: pointer;
+ z-index: 15;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ box-shadow: 0 1px 4px light-dark(rgb(20 30 45 / 0.12), rgb(0 0 0 / 0.45));
+}
+.dp-toggle:hover { color: var(--ink); border-color: var(--line-strong); }
+/* shut: the chevron pins fully on-screen, docked to the edge like a drawer pull */
+.dp-panel.dp-shut + .dp-resizer .dp-toggle {
+ left: 0;
+ transform: translateY(-50%);
+ border-top-left-radius: 0;
+ border-bottom-left-radius: 0;
+}
+.dp-resizer:has(+ .dp-panel.dp-shut) .dp-toggle {
+ left: auto;
+ right: 0;
+ transform: translateY(-50%);
+ border-top-right-radius: 0;
+ border-bottom-right-radius: 0;
+}
+
+/* ————— sections ————— */
+
+.dp-section {
+ font-size: 11px;
+ font-weight: 700;
+ text-transform: uppercase;
+ letter-spacing: 0.07em;
+ color: var(--muted);
+ margin: 18px 0 8px;
+}
+.dp-section:first-child { margin-top: 2px; }
+
+.dp-sec-toggle {
+ cursor: pointer;
+ user-select: none;
+ position: relative;
+ padding-left: 14px;
+}
+.dp-sec-toggle::before {
+ content: '';
+ position: absolute;
+ left: 1px;
+ top: 50%;
+ width: 0;
+ height: 0;
+ border-left: 5px solid currentColor;
+ border-top: 4px solid transparent;
+ border-bottom: 4px solid transparent;
+ transform: translateY(-50%) rotate(90deg);
+ transition: transform 0.12s ease;
+ opacity: 0.55;
+}
+.dp-sec-toggle.closed::before { transform: translateY(-50%); }
+.dp-sec-toggle:hover { color: var(--ink); }
+.dp-section-body { display: flex; flex-direction: column; }
+
+/* ————— rows ————— */
+
+.dp-row {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 8px;
+ margin-bottom: 8px;
+ font-size: 12.5px;
+ color: var(--ink);
+}
+.dp-row > span:first-child { flex: none; color: var(--muted); }
+.dp-row input[type='text'],
+.dp-row input[type='number'],
+.dp-row select {
+ width: 110px;
+ min-width: 0;
+ font: inherit;
+ font-size: 12.5px;
+ padding: 4px 6px;
+ border: 1px solid var(--line);
+ border-radius: 6px;
+ background: var(--surface);
+ color: var(--ink);
+}
+.dp-row input:focus,
+.dp-row select:focus { outline: none; border-color: var(--accent); }
+.dp-row .dp-mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+.dp-row input[type='checkbox'] { width: auto; accent-color: var(--accent); margin: 0; }
+.dp-row-ro { cursor: default; }
+.dp-value { color: var(--ink); font-variant-numeric: tabular-nums; }
+
+.dp-note {
+ margin: -2px 0 8px;
+ font-size: 11.5px;
+ line-height: 1.4;
+ color: var(--muted);
+}
+.dp-empty { font-size: 12.5px; color: var(--muted); }
+
+/* ————— buttons ————— */
+
+.dp-btn {
+ font: inherit;
+ font-size: 12.5px;
+ color: var(--ink);
+ background: var(--surface);
+ border: 1px solid var(--line-strong);
+ border-radius: 7px;
+ padding: 5px 10px;
+ cursor: pointer;
+ white-space: nowrap;
+}
+.dp-btn:hover { background: var(--hover); border-color: var(--muted); }
+.dp-btn[disabled] { opacity: 0.45; cursor: default; }
+.dp-block { display: block; width: 100%; text-align: left; margin-bottom: 6px; }
+.dp-add {
+ width: 100%;
+ margin-top: 8px;
+ border: 1.5px dashed var(--line-strong);
+ color: var(--muted);
+ text-align: center;
+}
+.dp-add:hover { color: var(--ink); }
+
+/* ————— the sheet list ————— */
+
+.dp-sheet {
+ position: relative;
+ border: 2px solid var(--line);
+ border-radius: 8px;
+ padding: 7px 9px;
+ margin-bottom: 8px;
+ cursor: pointer;
+ background: var(--surface);
+ user-select: none;
+}
+.dp-sheet:hover { border-color: var(--line-strong); }
+.dp-sheet.active { border-color: var(--accent); background: var(--accent-wash); }
+.dp-sheet-name {
+ font-size: 13px;
+ font-weight: 600;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ /* leave room for the hover tools, or a long name slides under the ✕ */
+ padding-right: 18px;
+}
+.dp-sheet-meta {
+ font-size: 11px;
+ color: var(--muted);
+ font-variant-numeric: tabular-nums;
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+/* MEASURED at 4.2:1 and fixed: --muted is sized for a white card, and on the
+ active card's warm wash it dropped under AA. The row count is the one thing
+ on that card a reader checks against the grid, so it takes full ink there —
+ the size difference still says it is a caption. */
+.dp-sheet.active .dp-sheet-meta { color: var(--ink); }
+
+/* a canvas sheet is really there and this build cannot open it — greyed, not
+ hidden, because a sheet that looks deleted is worse than one that looks inert */
+.dp-sheet-off { cursor: default; opacity: 0.55; }
+.dp-sheet-off:hover { border-color: var(--line); }
+
+.dp-sheet-tools {
+ position: absolute;
+ top: 4px;
+ right: 4px;
+ display: none;
+}
+.dp-sheet:hover .dp-sheet-tools { display: block; }
+.dp-icon {
+ padding: 0 5px;
+ line-height: 18px;
+ font-size: 11px;
+ color: var(--muted);
+ border-color: transparent;
+ /* the tools float OVER a sheet card, so the wash has to be the card's own
+ surface rather than a hard white that would punch a hole in a dark one */
+ background: color-mix(in srgb, var(--surface) 90%, transparent);
+}
+.dp-icon:hover { color: var(--err-ink); border-color: var(--line-strong); background: var(--surface); }
+
+.dp-sheet-rename {
+ width: 100%;
+ font: inherit;
+ font-size: 13px;
+ font-weight: 600;
+ padding: 1px 4px;
+ border: 1px solid var(--accent);
+ border-radius: 5px;
+ background: var(--surface);
+ color: var(--ink);
+}
+.dp-sheet-rename:focus { outline: none; }
diff --git a/dash/src/panels.ts b/dash/src/panels.ts
new file mode 100644
index 00000000..375518cf
--- /dev/null
+++ b/dash/src/panels.ts
@@ -0,0 +1,861 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The side panels: sheets on the left, properties on the right.
+//
+// THIS IS SLIDES' CHROME, DELIBERATELY. Two Bento apps that lay themselves out
+// differently read as two products, so the geometry here is copied rather than
+// reinvented: 11px uppercase section headers, 12.5px rows with the control
+// right-aligned at a fixed width, an accordion whose open state is remembered
+// per section TITLE, 5px resizer strips carrying a chevron that docks flush to
+// the screen edge when its panel is shut, and `[` / `]` to collapse them.
+// slides/src/editor/{editor,panels}.ts is the reference; where a rule is
+// arbitrary (a radius, a gap) it is copied to the pixel on purpose.
+//
+// IT OWNS NO STRUCTURE IT DID NOT BUILD. `mountPanels` re-parents `.dx-body`'s
+// existing children into a centre column and inserts itself around them, so the
+// boot sequence needs one call and no markup change. Nothing here reads or
+// writes another module's DOM: the grid keeps its host element, the chart keeps
+// its own, and both survive the move because moving a node keeps its subtree.
+//
+// EVERY WRITE IS A PATCH, none of them mutate. Same rule as rowcol.ts, for the
+// same reason — the Patch objects are the undo entries and the future CRDT ops,
+// so a panel that assigned to a column would be an edit with no inverse. The
+// two exceptions are `addSheet`/`removeSheet`, which have NO patch op to mint
+// (store.ts's union reaches cells, columns, sheet props and doc.title, never
+// the sheet LIST). They go through `replaceDoc`, which is what import already
+// does — and which clears the undo stack, so the delete asks first. That is the
+// one hook this module wants and cannot have yet.
+
+import './panels.css'
+import { t } from './i18n.ts'
+import { lsJson, lsSet } from '../../kernel/src/storage.ts'
+import { TYPE_LABEL } from './format.ts'
+import type { Column, ColumnType, DashDoc, TableSheet } from './model.ts'
+import type { Patch, Store } from './store.ts'
+import type { Grid } from './grid.ts'
+import {
+ freezeAt, hiddenSet, readFrozen, resizeColumn, setHidden,
+ type SetSheetProps,
+} from './rowcol.ts'
+
+export type Side = 'left' | 'right'
+
+/** Column-level totals, spelled as the sheet stores them. */
+export type TotalsAgg = NonNullable<TableSheet['totals']>[string]
+
+const TYPES: ColumnType[] = ['text', 'number', 'money', 'percent', 'date', 'bool', 'enum']
+const AGGS: Array<'sum' | 'avg' | 'count' | 'min' | 'max'> = ['sum', 'avg', 'count', 'min', 'max']
+
+// Widths are slides' bounds, nudged: a sheet name needs less room than a slide
+// thumbnail and a column's controls need a little more than an element's.
+const PANEL_BOUNDS = { left: [140, 380], right: [200, 440] } as const
+const PANEL_DEFAULTS = { left: 200, right: 250 } as const
+/** Below this the panels boot shut, so the GRID is what you see. Slides' rule. */
+const PHONE_W = 700
+
+const LS_WIDTHS = 'bento-dash-panels'
+const LS_SHUT = 'bento-dash-panels-shut'
+/** Per-app, NOT slides' 'bento-panel-open': same origin, different section names. */
+const LS_SECTIONS = 'bento-dash-panel-open'
+
+/** Sections that start closed until the reader opens one (then it is remembered). */
+const CLOSED_BY_DEFAULT = new Set(['Workbook'])
+
+const rowsOf = (s: TableSheet): number => s.rids.reduce((n, [, c]) => n + c, 0)
+
+const isTable = (s: { kind?: unknown }): s is TableSheet => s.kind === 'table'
+
+// --- patch factories --------------------------------------------------------
+//
+// Pure, so `scripts/test-dash-panels.ts` can hold them to the two rules that
+// are easy to get wrong from a UI and impossible to see afterwards: a cleared
+// setting must leave the file as it found it, and a delete must be spelled
+// `drop` rather than `props: {k: undefined}` — which rowcol's applySheetProps
+// refuses outright, because that spelling evaporates in `JSON.stringify` and
+// would reach every other replica as a no-op.
+
+/**
+ * Set or clear one column's totals aggregate.
+ *
+ * Clearing the LAST one drops `totals` entirely rather than storing `{}`: an
+ * additive field that means "no totals" should be ABSENT, or turning the row on
+ * and off again leaves the workbook changed, every reader diffs it, and collab
+ * ships an op for a document that is back where it started. Same argument
+ * `freezeAt` makes for frozen panes.
+ */
+export function totalsPatch(
+ sheet: TableSheet, colId: string, agg: TotalsAgg | null,
+): SetSheetProps {
+ const next: NonNullable<TableSheet['totals']> = { ...(sheet.totals ?? {}) }
+ if (agg === null) delete next[colId]
+ else next[colId] = agg
+ return Object.keys(next).length
+ ? { op: 'setSheetProps', sheet: sheet.id, props: { totals: next } }
+ : { op: 'setSheetProps', sheet: sheet.id, props: {}, drop: ['totals'] }
+}
+
+/**
+ * Freeze up to and including `colId`, or unfreeze if it is already the edge.
+ *
+ * The count is VISIBLE position, which is what the reader pointed at — a hidden
+ * column between the gutter and this one would otherwise freeze one column more
+ * than the control named. Frozen ROWS are carried through untouched; the filter
+ * menu's version of this drops them, which is a second setting silently reset
+ * by a first.
+ */
+export function freezeThroughPatch(sheet: TableSheet, colId: string): SetSheetProps {
+ const hidden = hiddenSet(sheet)
+ const at = sheet.columns.filter((c) => !hidden.has(c.id)).findIndex((c) => c.id === colId)
+ const now = readFrozen(sheet)
+ if (at < 0) return freezeAt(sheet, now.rows, now.cols) as SetSheetProps
+ const already = now.cols === at + 1
+ return freezeAt(sheet, now.rows, already ? 0 : at + 1) as SetSheetProps
+}
+
+/** Rename a sheet. An empty name is refused rather than stored — a nameless tab
+ * is unclickable, and the previous name is the only thing left to fall back to. */
+export function renameSheetPatch(sheet: TableSheet, name: string): SetSheetProps | null {
+ const n = name.trim()
+ if (!n || n === sheet.name) return null
+ return { op: 'setSheetProps', sheet: sheet.id, props: { name: n } }
+}
+
+/**
+ * A sheet id nothing in the workbook has taken.
+ *
+ * `seed` is a parameter so this is deterministic under test; the collision walk
+ * matters because a duplicate sheet id makes `doc.sheets.find` return the FIRST
+ * one and the second sheet becomes unreachable — its data still in the file,
+ * nothing able to open it.
+ */
+export function mintSheetId(doc: DashDoc, seed: number = Date.now()): string {
+ const taken = new Set(doc.sheets.map((s) => s.id))
+ let n = Math.floor(Math.abs(seed) % 1e8)
+ for (;;) {
+ const id = `sheet-${n.toString(36)}`
+ if (!taken.has(id)) return id
+ n++
+ }
+}
+
+/** "Sheet 2", "Sheet 3" — the first spelling nothing else is using. */
+export function mintSheetName(doc: DashDoc, base: string): string {
+ const taken = new Set(doc.sheets.map((s) => s.name))
+ if (!taken.has(base)) return base
+ for (let i = 2; ; i++) {
+ const n = `${base} ${i}`
+ if (!taken.has(n)) return n
+ }
+}
+
+/** Blank rows a new sheet starts with — enough to type into, few enough to save. */
+const NEW_ROWS = 20
+
+/**
+ * An empty table sheet.
+ *
+ * `steps[0]` is the provenance record, and it is present even here: a dash file
+ * always answers "where did this come from?", and "somebody typed it" is an
+ * answer. Column data is `raw` and exactly `NEW_ROWS` long, because a column
+ * shorter than the sheet is malformed to every OTHER reader of the JSON even
+ * though it reads correctly inside this build (rowcol.ts `fitToRows`).
+ */
+export function blankSheet(id: string, name: string, at: string): TableSheet {
+ const cols: Column[] = ['A', 'B', 'C'].map((letter, i) => ({
+ id: `${id}-c${i + 1}`, name: `${t('Column')} ${letter}`, type: 'text', w: 130,
+ }))
+ const data: TableSheet['data'] = {}
+ for (const c of cols) data[c.id] = { enc: 'raw', v: Array.from({ length: NEW_ROWS }, () => null) }
+ return {
+ id, name, kind: 'table',
+ rids: [[1, NEW_ROWS]],
+ columns: cols,
+ data,
+ steps: [{ op: 'import', from: 'created in dash', at, rows: 0, note: 'A blank sheet — nothing was imported.' }],
+ }
+}
+
+// --- mount ------------------------------------------------------------------
+
+export interface PanelsHost {
+ store: Store
+ grid: Grid
+ /** the `.dx-body` element — panels wrap whatever is already inside it */
+ body: HTMLElement
+}
+
+export interface Panels {
+ /** Collapse or reopen one panel (what `[` and `]` do). */
+ toggle(side: Side): void
+ /** Rebuild both panels now. */
+ refresh(): void
+}
+
+export function mountPanels(host: PanelsHost): Panels {
+ const { store, grid, body } = host
+
+ // DECLARED FIRST, and it has to be: `resizer()` writes into this while
+ // building the strips below, and the strips are built before any of the
+ // sections that follow. A `const` further down the closure is in its temporal
+ // dead zone at that point — mounting threw `Cannot access 'chevrons' before
+ // initialization`, which took the whole boot with it (the panels had already
+ // emptied `.dx-body`, so the grid vanished too).
+ const chevrons: Partial<Record<Side, HTMLElement>> = {}
+
+ // Everything that was in `.dx-body` — the grid and the chart pane — becomes
+ // the centre column, so the panels can sit either side of BOTH. Moving the
+ // nodes keeps their listeners and their subtrees, so the references main.ts
+ // captured at boot stay live.
+ const centre = document.createElement('div')
+ centre.className = 'dp-centre'
+ while (body.firstChild) centre.appendChild(body.firstChild)
+
+ const left = panelEl('dp-left')
+ const right = panelEl('dp-right')
+ const leftBar = resizer('left')
+ const rightBar = resizer('right')
+ body.append(left, leftBar, centre, rightBar, right)
+
+ // --- widths and collapse, both remembered ---------------------------------
+
+ const widths = { ...PANEL_DEFAULTS } as { left: number; right: number }
+ const saved = lsJson<Record<string, number>>(LS_WIDTHS, {})
+ for (const side of ['left', 'right'] as const) {
+ const [min, max] = PANEL_BOUNDS[side]
+ if (typeof saved[side] === 'number') widths[side] = Math.min(max, Math.max(min, saved[side]))
+ }
+ applyWidths()
+
+ // A phone boots with both shut so the grid is what you see — but only if the
+ // reader has never said otherwise, or opening one panel on a phone would be
+ // forgotten on every reload.
+ const shut = lsJson<Record<string, boolean>>(LS_SHUT, {})
+ for (const side of ['left', 'right'] as const) {
+ const el = side === 'left' ? left : right
+ const pref = shut[side]
+ // A width of ZERO means "not laid out yet", not "phone". A background or
+ // freshly-created tab reports 0 before first layout, and `0 < 700` then
+ // collapsed both panels on a desktop — with no stored preference to
+ // explain it, so it looked like the panels had simply not shipped.
+ const vw = window.innerWidth
+ const phone = vw > 0 && vw < PHONE_W
+ if (pref ?? phone) el.classList.add('dp-shut')
+ }
+ updateChevrons()
+
+ function panelEl(cls: string): HTMLElement {
+ const el = document.createElement('aside')
+ el.className = `dp-panel ${cls}`
+ return el
+ }
+
+ function applyWidths(): void {
+ left.style.setProperty('--dp-w', `${widths.left}px`)
+ right.style.setProperty('--dp-w', `${widths.right}px`)
+ }
+
+
+ function updateChevrons(): void {
+ for (const side of ['left', 'right'] as const) {
+ const btn = chevrons[side]
+ if (!btn) continue
+ const closed = (side === 'left' ? left : right).classList.contains('dp-shut')
+ // The arrow points where clicking moves the boundary, not at the panel.
+ btn.textContent = side === 'left' ? (closed ? '›' : '‹') : (closed ? '‹' : '›')
+ btn.title = side === 'left'
+ ? closed ? t('Show sheets ([)') : t('Hide sheets ([)')
+ : closed ? t('Show properties (])') : t('Hide properties (])')
+ }
+ }
+
+ function toggle(side: Side): void {
+ const el = side === 'left' ? left : right
+ const nowShut = el.classList.toggle('dp-shut')
+ shut[side] = nowShut
+ lsSet(LS_SHUT, JSON.stringify(shut))
+ updateChevrons()
+ }
+
+ function resizer(side: Side): HTMLElement {
+ const bar = document.createElement('div')
+ bar.className = 'dp-resizer'
+ bar.title = t('Drag to resize · double-click to reset')
+ const btn = document.createElement('button')
+ btn.className = 'dp-toggle'
+ btn.addEventListener('click', (e) => { e.stopPropagation(); toggle(side) })
+ chevrons[side] = btn
+ bar.appendChild(btn)
+
+ bar.addEventListener('mousedown', (down) => {
+ if (down.target === btn) return // the chevron is a click, not a drag
+ const panel = side === 'left' ? left : right
+ if (panel.classList.contains('dp-shut')) return
+ down.preventDefault()
+ const startX = down.clientX
+ const startW = widths[side]
+ const [min, max] = PANEL_BOUNDS[side]
+ panel.classList.add('dp-noanim')
+ document.body.classList.add('dp-resizing')
+ const move = (e: MouseEvent): void => {
+ const dx = e.clientX - startX
+ widths[side] = Math.min(max, Math.max(min, startW + (side === 'left' ? dx : -dx)))
+ applyWidths()
+ }
+ const up = (): void => {
+ window.removeEventListener('mousemove', move)
+ window.removeEventListener('mouseup', up)
+ panel.classList.remove('dp-noanim')
+ document.body.classList.remove('dp-resizing')
+ lsSet(LS_WIDTHS, JSON.stringify(widths))
+ }
+ window.addEventListener('mousemove', move)
+ window.addEventListener('mouseup', up)
+ })
+ bar.addEventListener('dblclick', () => {
+ widths[side] = PANEL_DEFAULTS[side]
+ applyWidths()
+ lsSet(LS_WIDTHS, JSON.stringify(widths))
+ })
+ return bar
+ }
+
+ // --- what is current ------------------------------------------------------
+
+ /**
+ * The sheet the grid is showing.
+ *
+ * Read from the grid rather than tracked here: `Grid.sheetId` is private and
+ * `setSheet` is called by import as well as by this panel, so a local copy
+ * goes stale the first time a CSV lands.
+ */
+ function currentSheet(): TableSheet | null {
+ try {
+ return grid.sheet
+ } catch {
+ return null // mid-replaceDoc, or a canvas sheet
+ }
+ }
+
+ function visibleColumns(sheet: TableSheet): Column[] {
+ const hidden = hiddenSet(sheet)
+ return sheet.columns.filter((c) => !hidden.has(c.id))
+ }
+
+ /** The column under the cursor. The selection counts VISIBLE positions. */
+ function currentColumn(sheet: TableSheet): Column | null {
+ return visibleColumns(sheet)[grid.sel.cursor.col] ?? null
+ }
+
+ // --- rendering ------------------------------------------------------------
+
+ const ro = (): boolean => store.readOnly
+
+ function renderSheets(): void {
+ left.textContent = ''
+ const head = document.createElement('h3')
+ head.className = 'dp-section dp-static'
+ head.textContent = t('Sheets')
+ left.appendChild(head)
+
+ const cur = currentSheet()
+ for (const sheet of store.doc.sheets) {
+ const item = document.createElement('div')
+ item.className = 'dp-sheet'
+ if (cur && sheet.id === cur.id) item.classList.add('active')
+
+ const name = document.createElement('div')
+ name.className = 'dp-sheet-name'
+ name.textContent = sheet.name || t('(untitled sheet)')
+ const meta = document.createElement('div')
+ meta.className = 'dp-sheet-meta'
+ // Read the discriminant BEFORE isTable() narrows it away — in the else
+ // branch the union has collapsed and `sheet.kind` is unreachable.
+ const kind = String((sheet as { kind?: unknown }).kind ?? '')
+
+ if (isTable(sheet)) {
+ meta.textContent = `${rowsOf(sheet)} × ${sheet.columns.length}`
+ item.addEventListener('click', () => {
+ if (cur && sheet.id === cur.id) return
+ grid.setSheet(sheet.id)
+ })
+ // Rename in place. The right panel has the same field; this is the one
+ // people reach for, because it is where the name already is.
+ item.addEventListener('dblclick', (e) => {
+ e.preventDefault()
+ if (ro()) return
+ startRename(name, sheet)
+ })
+ } else {
+ // A sheet this panel cannot edit. Showing it greyed is honest; hiding
+ // it would make a sheet that is really there look deleted.
+ //
+ // NAME THE KIND IT ACTUALLY IS. Everything non-table used to be
+ // labelled a canvas sheet, which was true until pivots existed — and
+ // then a pivot, generated by the app's own + Pivot button, sat in the
+ // list describing itself as something else entirely. A label that
+ // confidently states the wrong thing is worse than a vague one.
+ item.classList.add('dp-sheet-off')
+ meta.textContent = kind === 'pivot'
+ ? t('pivot table — open it from + Pivot')
+ : kind === 'canvas'
+ ? t('canvas sheet — not editable in this build')
+ : t('{kind} sheet — not editable in this build').replace('{kind}', kind)
+ }
+ item.append(name, meta)
+
+ if (!ro() && isTable(sheet)) {
+ const tools = document.createElement('div')
+ tools.className = 'dp-sheet-tools'
+ tools.appendChild(iconBtn('✕', t('Delete this sheet'), (e) => {
+ e.stopPropagation()
+ removeSheet(sheet)
+ }))
+ item.appendChild(tools)
+ }
+ left.appendChild(item)
+ }
+
+ if (!ro()) {
+ const add = document.createElement('button')
+ add.className = 'dp-btn dp-add'
+ add.textContent = t('+ New sheet')
+ add.addEventListener('click', addSheet)
+ left.appendChild(add)
+ }
+ }
+
+ function startRename(name: HTMLElement, sheet: TableSheet): void {
+ const input = document.createElement('input')
+ input.className = 'dp-sheet-rename'
+ input.value = sheet.name
+ name.replaceWith(input)
+ input.focus()
+ input.select()
+ let done = false
+ const finish = (write: boolean): void => {
+ if (done) return
+ done = true
+ if (write) {
+ const p = renameSheetPatch(sheet, input.value)
+ if (p) store.commit(p)
+ }
+ renderSheets()
+ }
+ input.addEventListener('blur', () => finish(true))
+ input.addEventListener('keydown', (e) => {
+ e.stopPropagation() // the grid owns bare keys otherwise
+ if (e.key === 'Enter') finish(true)
+ else if (e.key === 'Escape') finish(false)
+ })
+ // the double-click also selected the row's text; clear it or the two
+ // selections fight over the caret
+ getSelection()?.removeAllRanges()
+ }
+
+ /**
+ * Add a sheet — a PATCH, so it is undoable.
+ *
+ * This used to go through `replaceDoc`, which clears the undo stack: adding a
+ * sheet silently threw away every edit you could previously take back.
+ */
+ function addSheet(): void {
+ if (ro()) return
+ const doc = store.doc
+ const id = mintSheetId(doc)
+ store.commit({
+ op: 'setSheet', id,
+ sheet: blankSheet(id, mintSheetName(doc, t('Sheet')), new Date().toISOString()),
+ } as never)
+ grid.setSheet(id)
+ }
+
+ function removeSheet(sheet: TableSheet): void {
+ if (ro()) return
+ const doc = store.doc
+ if (doc.sheets.filter(isTable).length < 2) {
+ window.alert(t('A workbook needs at least one sheet.'))
+ return
+ }
+ // Undoable now, so the warning no longer has to say otherwise — but a
+ // sheet is a lot of rows to remove on one click, so it still asks.
+ const rows = rowsOf(sheet)
+ const msg = t('Delete "{name}" and its {n} rows?')
+ .replace('{name}', sheet.name)
+ .replace('{n}', String(rows))
+ if (!window.confirm(msg)) return
+ const cur = currentSheet()
+ store.commit({ op: 'setSheet', id: sheet.id, sheet: undefined } as never)
+ if (cur && cur.id === sheet.id) {
+ const next = doc.sheets.find(isTable)
+ if (next) grid.setSheet(next.id)
+ }
+ render()
+ }
+
+ // --- the properties panel -------------------------------------------------
+
+ function renderProps(): void {
+ right.textContent = ''
+ const sheet = currentSheet()
+ if (!sheet) {
+ const p = document.createElement('p')
+ p.className = 'dp-empty'
+ p.textContent = t('No table sheet is open.')
+ right.appendChild(p)
+ return
+ }
+ buildColumnSection(sheet)
+ buildSheetSection(sheet)
+ buildWorkbookSection()
+ applyAccordion(right)
+ }
+
+ function buildColumnSection(sheet: TableSheet): void {
+ section(right, t('Column'))
+ const col = currentColumn(sheet)
+ if (!col) {
+ note(right, t('Select a cell to see its column.'))
+ return
+ }
+
+ row(right, t('Name'), text(col.name, (v) => {
+ if (v.trim() && v !== col.name) commit({ op: 'setColumn', sheet: sheet.id, col: col.id, patch: { name: v.trim() } })
+ }))
+
+ row(right, t('Type'), select(
+ TYPES.map((tp) => [tp, t(TYPE_LABEL[tp])] as const),
+ col.type,
+ (v) => commit({ op: 'setColumn', sheet: sheet.id, col: col.id, patch: { type: v as ColumnType } }),
+ ))
+
+ // The Excel-style pattern (format.ts readPattern): a currency prefix,
+ // thousands grouping and a fixed number of decimals. The GLYPHS stay the
+ // viewer's, so this really is only "what to show".
+ const fmt = text(typeof col.format === 'string' ? col.format : '', (v) => {
+ const next = v.trim()
+ if (next === (col.format ?? '')) return
+ // `undefined` clears it: JSON.stringify drops the key, so the file comes
+ // back exactly as it was before anyone typed a pattern. (Over a wire that
+ // spelling would arrive as a no-op — the hazard rowcol.ts documents for
+ // `hidden` — which is a live concern the day dash gets collab.)
+ commit({ op: 'setColumn', sheet: sheet.id, col: col.id, patch: { format: next || undefined } })
+ })
+ fmt.placeholder = '£#,##0.00'
+ row(right, t('Format'), fmt)
+
+ // One expression for the WHOLE column. Editing it here beats the prompt()
+ // the grid falls back to, because you can see the column while you type.
+ const formula = text(typeof col.formula === 'string' ? col.formula : '', (v) => {
+ const next = v.trim()
+ if (next === (col.formula ?? '')) return
+ commit({ op: 'setColumn', sheet: sheet.id, col: col.id, patch: { formula: next || undefined } })
+ })
+ formula.placeholder = t('Value * Probability')
+ formula.classList.add('dp-mono')
+ row(right, t('Formula'), formula)
+
+ row(right, t('Width'), number(col.w ?? 130, 10, (v) => {
+ // resizeColumn clamps and rounds — a width is a drag's output, so out of
+ // range is ordinary and refusing it would be the bug.
+ commit(resizeColumn(sheet, col.id, v))
+ }))
+
+ const agg = sheet.totals?.[col.id]
+ const aggValue = typeof agg === 'string' ? agg : agg ? 'custom' : 'none'
+ const aggSel = select(
+ [['none', t('none')] as const, ...AGGS.map((a) => [a, t(a)] as const),
+ ...(aggValue === 'custom' ? [['custom', t('custom formula')] as const] : [])],
+ aggValue,
+ (v) => {
+ if (v === 'custom') return // a hand-written {f} is not ours to rewrite
+ commit(totalsPatch(sheet, col.id, v === 'none' ? null : v as TotalsAgg))
+ },
+ )
+ row(right, t('Total'), aggSel)
+
+ const frozen = readFrozen(sheet)
+ const upTo = visibleColumns(sheet).findIndex((c) => c.id === col.id) + 1
+ row(right, t('Freeze to here'), toggle_(frozen.cols === upTo, () =>
+ commit(freezeThroughPatch(sheet, col.id))))
+
+ row(right, t('Hidden'), toggle_(col.hidden === true, (on) =>
+ commit(setHidden(sheet, col.id, on))))
+
+ if (typeof col.failed === 'number' && col.failed > 0) {
+ note(right, t('{n} value(s) could not be read as this type.').replace('{n}', String(col.failed)))
+ }
+ }
+
+ function buildSheetSection(sheet: TableSheet): void {
+ section(right, t('Sheet'))
+ row(right, t('Name'), text(sheet.name, (v) => {
+ const p = renameSheetPatch(sheet, v)
+ if (p) commit(p)
+ }))
+ readonlyRow(right, t('Rows'), String(rowsOf(sheet)))
+ readonlyRow(right, t('Columns'), String(sheet.columns.length))
+
+ const frozen = readFrozen(sheet)
+ row(right, t('Frozen rows'), number(frozen.rows, 1, (v) =>
+ commit(freezeAt(sheet, v, frozen.cols) as Patch)))
+ row(right, t('Frozen columns'), number(frozen.cols, 1, (v) =>
+ commit(freezeAt(sheet, frozen.rows, v) as Patch)))
+
+ // The way BACK from "Hide this column". Without it a hidden column is
+ // unreachable from the interface — it is still in the file, and nothing on
+ // screen can say so or bring it back.
+ const hidden = sheet.columns.filter((c) => c.hidden === true)
+ if (hidden.length) {
+ note(right, t('Hidden columns'))
+ for (const c of hidden) {
+ const btn = document.createElement('button')
+ btn.className = 'dp-btn dp-block'
+ btn.textContent = `${c.name} — ${t('show')}`
+ btn.disabled = ro()
+ btn.addEventListener('click', () => commit(setHidden(sheet, c.id, false)))
+ right.appendChild(btn)
+ }
+ }
+
+ if (grid.filters.length || grid.sorts.length) {
+ const clear = document.createElement('button')
+ clear.className = 'dp-btn dp-block'
+ clear.textContent = t('Clear filters and sorts')
+ clear.addEventListener('click', () => { grid.clearView(); render() })
+ right.appendChild(clear)
+ }
+ }
+
+ function buildWorkbookSection(): void {
+ section(right, t('Workbook'))
+ const doc = store.doc
+ readonlyRow(right, t('Sheets'), String(doc.sheets.length))
+ readonlyRow(right, t('Rows'), String(
+ doc.sheets.reduce((n, s) => n + (isTable(s) ? rowsOf(s) : 0), 0)))
+ readonlyRow(right, t('Measures'), String(Object.keys(doc.measures ?? {}).length))
+ readonlyRow(right, t('Format'), `${doc.format} v${doc.version}`)
+ }
+
+ function commit(p: Patch | Patch[]): void {
+ if (ro()) return
+ store.commit(p)
+ }
+
+ // --- the accordion --------------------------------------------------------
+
+ /**
+ * Retrofit the flat panel into an accordion: every `.dp-section` header
+ * gathers the siblings that follow it into a collapsible body, and the open
+ * state is remembered by section TITLE. Copied from slides' `applyAccordion`
+ * including that detail — keying by title (not by index) is what lets a
+ * section keep its state when the panel above it changes shape.
+ *
+ * `.dp-static` opts a header out: the left panel's "Sheets" label is a
+ * heading, not a drawer.
+ */
+ function applyAccordion(hostEl: HTMLElement): void {
+ const open = lsJson<Record<string, boolean>>(LS_SECTIONS, {})
+ for (const h of [...hostEl.querySelectorAll<HTMLElement>('.dp-section:not(.dp-static)')]) {
+ const key = h.textContent ?? ''
+ const bodyEl = document.createElement('div')
+ bodyEl.className = 'dp-section-body'
+ let n: ChildNode | null = h.nextSibling
+ while (n && !(n instanceof HTMLElement && n.classList.contains('dp-section'))) {
+ const next: ChildNode | null = n.nextSibling
+ bodyEl.appendChild(n)
+ n = next
+ }
+ h.after(bodyEl)
+ const isOpen = open[key] ?? !CLOSED_BY_DEFAULT.has(key)
+ h.classList.add('dp-sec-toggle')
+ if (!isOpen) {
+ h.classList.add('closed')
+ bodyEl.style.display = 'none'
+ }
+ h.addEventListener('click', () => {
+ const nowClosed = h.classList.toggle('closed')
+ bodyEl.style.display = nowClosed ? 'none' : ''
+ open[key] = !nowClosed
+ lsSet(LS_SECTIONS, JSON.stringify(open))
+ })
+ }
+ }
+
+ // --- keeping up with the app ----------------------------------------------
+
+ let stale = false
+
+ /**
+ * True while the reader is mid-edit in a field a rebuild would rip out.
+ * Discrete controls (select, checkbox, button) commit atomically and want the
+ * rebuild immediately — that is how a type change reveals the rows it adds.
+ */
+ function editing(): boolean {
+ const a = document.activeElement as HTMLElement | null
+ if (!a || !right.contains(a) && !left.contains(a)) return false
+ if (a.tagName === 'TEXTAREA' || a.isContentEditable) return true
+ if (a.tagName === 'INPUT') {
+ const type = (a as HTMLInputElement).type
+ return type !== 'checkbox' && type !== 'radio' && type !== 'button'
+ }
+ return false
+ }
+
+ function render(force = false): void {
+ if (!force && editing()) { stale = true; return }
+ stale = false
+ renderSheets()
+ renderProps()
+ }
+
+ for (const el of [left, right]) {
+ el.addEventListener('focusout', () => {
+ setTimeout(() => {
+ if (stale && !left.matches(':focus-within') && !right.matches(':focus-within')) render()
+ }, 0)
+ })
+ }
+
+ store.on('doc', () => render())
+ store.on('view', () => render())
+
+ // The grid announces a selection change through ONE callback and main.ts owns
+ // it (formula bar + status bar). Chain, never replace.
+ const announced = grid.onSelectionChange
+ grid.onSelectionChange = (summary, ref, value) => {
+ announced?.(summary, ref, value)
+ render()
+ }
+
+ // Import switches sheets too, so the list has to follow the GRID rather than
+ // only its own clicks — otherwise it keeps highlighting the old sheet until
+ // the next unrelated document event.
+ grid.onSheetChange = () => render(true)
+
+ /**
+ * `[` and `]`, in the CAPTURE phase — and that is load-bearing. main.ts's
+ * document keydown handler feeds any bare printable key to `grid.typeInto`,
+ * which would open a cell editor seeded with "[". Capturing on `document`
+ * runs before every bubble listener on it, and `stopImmediatePropagation`
+ * (not `stopPropagation` — both handlers are on the same node) is what keeps
+ * the keystroke from reaching the grid at all.
+ */
+ document.addEventListener('keydown', (e) => {
+ if (e.key !== '[' && e.key !== ']') return
+ if (e.metaKey || e.ctrlKey || e.altKey) return
+ const target = e.target as HTMLElement | null
+ if (target && (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable)) return
+ e.preventDefault()
+ e.stopImmediatePropagation()
+ toggle(e.key === '[' ? 'left' : 'right')
+ }, true)
+
+ render(true)
+
+ return { toggle, refresh: () => render(true) }
+}
+
+// --- row builders -----------------------------------------------------------
+// Deliberately the same shapes slides' panel uses: a label on the left, one
+// control on the right at a fixed width. Anything wider than that reads as a
+// different application.
+
+function section(hostEl: HTMLElement, title: string): void {
+ const h = document.createElement('h3')
+ h.className = 'dp-section'
+ h.textContent = title
+ hostEl.appendChild(h)
+}
+
+function row(hostEl: HTMLElement, label: string, control: HTMLElement): void {
+ const r = document.createElement('label')
+ r.className = 'dp-row'
+ const span = document.createElement('span')
+ span.textContent = label
+ r.append(span, control)
+ hostEl.appendChild(r)
+}
+
+function readonlyRow(hostEl: HTMLElement, label: string, value: string): void {
+ const r = document.createElement('div')
+ r.className = 'dp-row dp-row-ro'
+ const span = document.createElement('span')
+ span.textContent = label
+ const v = document.createElement('span')
+ v.className = 'dp-value'
+ v.textContent = value
+ r.append(span, v)
+ hostEl.appendChild(r)
+}
+
+function note(hostEl: HTMLElement, message: string): void {
+ const p = document.createElement('p')
+ p.className = 'dp-note'
+ p.textContent = message
+ hostEl.appendChild(p)
+}
+
+/** Commits on `change` — blur or Enter — never per keystroke. */
+function text(value: string, onChange: (v: string) => void): HTMLInputElement {
+ const input = document.createElement('input')
+ input.type = 'text'
+ input.value = value
+ input.spellcheck = false
+ input.addEventListener('change', () => onChange(input.value))
+ input.addEventListener('keydown', (e) => {
+ e.stopPropagation() // the grid owns bare keys otherwise
+ if (e.key === 'Enter') input.blur()
+ })
+ return input
+}
+
+function number(value: number, step: number, onChange: (v: number) => void): HTMLInputElement {
+ const input = document.createElement('input')
+ input.type = 'number'
+ input.step = String(step)
+ input.value = String(value)
+ input.addEventListener('keydown', (e) => e.stopPropagation())
+ input.addEventListener('change', () => {
+ const v = parseFloat(input.value)
+ if (Number.isFinite(v)) onChange(v)
+ })
+ return input
+}
+
+/** Values stay MODEL words; only the labels are localized (PLATFORM §8). */
+function select(
+ options: ReadonlyArray<readonly [string, string]>,
+ value: string,
+ onChange: (v: string) => void,
+): HTMLSelectElement {
+ const sel = document.createElement('select')
+ for (const [v, label] of options) {
+ const o = document.createElement('option')
+ o.value = v
+ o.textContent = label
+ if (v === value) o.selected = true
+ sel.appendChild(o)
+ }
+ sel.addEventListener('change', () => onChange(sel.value))
+ return sel
+}
+
+// `toggle_`: `toggle` is the panel API's own verb, and shadowing it inside
+// mountPanels would silently make the checkbox collapse a panel.
+function toggle_(value: boolean, onChange: (v: boolean) => void): HTMLInputElement {
+ const cb = document.createElement('input')
+ cb.type = 'checkbox'
+ cb.className = 'dp-check'
+ cb.checked = value
+ cb.addEventListener('change', () => onChange(cb.checked))
+ return cb
+}
+
+function iconBtn(glyph: string, title: string, onClick: (e: MouseEvent) => void): HTMLElement {
+ const b = document.createElement('button')
+ b.className = 'dp-btn dp-icon'
+ b.textContent = glyph
+ b.title = title
+ b.addEventListener('click', onClick)
+ return b
+}
diff --git a/dash/src/pivot.css b/dash/src/pivot.css
new file mode 100644
index 00000000..841603e4
--- /dev/null
+++ b/dash/src/pivot.css
@@ -0,0 +1,234 @@
+/* SPDX-License-Identifier: MIT
+ Copyright (c) 2026 The Bento authors
+ Pivot table chrome. Co-located with pivot.ts, which imports it — the pattern
+ panels.ts already sets, so a rig stubs `.css` rather than the module moving
+ its import out (scripts/test-dash-panels.ts:42).
+
+ Variables come from styles.css and are never redefined here: a pivot that
+ carried its own palette would drift from the grid beside it on the first
+ theme change. In particular the rules use --grid-line and the header band
+ uses --grid-head, NOT the chrome greys: a pivot is a grid, it sits a few
+ hundred pixels from the real one, and the two have to be the same object at
+ a glance. It used --line and --panel, and read a shade lighter than the
+ sheet it summarised. */
+
+.dxp {
+ display: flex;
+ flex-direction: column;
+ min-height: 0;
+ font: 13px/1.4 var(--ui, system-ui, sans-serif);
+ color: var(--ink);
+ font-variant-numeric: tabular-nums;
+}
+
+.dxp-scroll {
+ overflow: auto;
+ min-height: 0;
+ flex: 1 1 auto;
+}
+
+.dxp-table {
+ border-collapse: separate;
+ border-spacing: 0;
+ /* not `width: 100%`: a pivot is as wide as it is, and stretching it spreads
+ four columns across a monitor so that reading a row means a head turn */
+ width: max-content;
+ min-width: 100%;
+}
+
+.dxp-table th,
+.dxp-table td {
+ border-right: 1px solid var(--grid-line);
+ border-bottom: 1px solid var(--grid-line);
+ padding: 0 10px;
+ height: var(--row-h);
+ white-space: nowrap;
+}
+
+.dxp-table thead th {
+ position: sticky;
+ top: 0;
+ z-index: 2;
+ background: var(--grid-head);
+ font-weight: 600;
+ text-align: left;
+ /* the sticky header loses its own border on scroll in every engine — the
+ shadow is what keeps the seam visible. 2px, matching .dg-head-row: this is
+ the same seam, and it has to be the same weight. */
+ box-shadow: inset 0 -2px 0 var(--line-strong);
+}
+
+.dxp-corner {
+ position: sticky;
+ left: 0;
+ z-index: 3;
+ background: var(--grid-head);
+ color: var(--muted);
+ font-weight: 600;
+ vertical-align: bottom;
+}
+
+.dxp-rh {
+ position: sticky;
+ left: 0;
+ z-index: 1;
+ background: var(--bg);
+ text-align: left;
+ font-weight: 400;
+}
+
+/* Numbers are right-aligned and TABULAR. Proportional digits make a column of
+ figures ragged, and a ragged column cannot be scanned for an order of
+ magnitude — which is the one thing a reader does with a pivot at a glance. */
+.dxp-c {
+ text-align: right;
+ font-variant-numeric: tabular-nums;
+}
+
+/* A GAP IS NOT A ZERO, and it must not read as one on screen either. An empty
+ cell tinted a shade off the background says "there is nothing here" where a
+ dash or a 0 would say something about the world. */
+.dxp-gap {
+ background: repeating-linear-gradient(
+ 135deg, transparent, transparent 5px,
+ color-mix(in srgb, var(--line) 60%, transparent) 5px,
+ color-mix(in srgb, var(--line) 60%, transparent) 6px);
+}
+
+/* Values that could not be read as numbers were counted and not summed; the
+ corner mark is the only thing on screen that says the number is short. */
+.dxp-skipped {
+ background-image: linear-gradient(
+ 225deg, color-mix(in srgb, var(--accent) 55%, transparent) 6px, transparent 6px);
+}
+
+.dxp-total,
+.dxp-subtotal,
+.dxp-grand {
+ font-weight: 600;
+ background: color-mix(in srgb, var(--panel) 70%, var(--bg));
+}
+
+.dxp-r.dxp-grand td,
+.dxp-r.dxp-grand th {
+ border-top: 2px solid var(--line-strong);
+}
+
+.dxp-c[tabindex] {
+ cursor: pointer;
+}
+
+.dxp-c[tabindex]:hover,
+.dxp-c[tabindex]:focus-visible {
+ background: var(--sel);
+ outline: 1px solid var(--sel-ring);
+ outline-offset: -1px;
+}
+
+/* --- findings + notes ---------------------------------------------------- */
+
+/* the same shape as the top-level findings banner (.dx-findings): amber on a
+ warm tint, because they answer the same question — what did this decide for
+ me? Two different treatments for one idea is how a suite stops reading as one. */
+.dxp-findings {
+ border-left: 3px solid var(--accent);
+ background: var(--warn-bg);
+ border-radius: 0 var(--radius) var(--radius) 0;
+ padding: 6px 10px;
+ margin: 0 0 6px;
+ font-size: var(--fs-ui);
+}
+
+.dxp-finding + .dxp-finding {
+ margin-top: 3px;
+}
+
+.dxp-note,
+.dxp-empty {
+ color: var(--muted);
+ margin: 6px 2px 0;
+ font-size: var(--fs-small);
+}
+
+/* --- drill-down ---------------------------------------------------------- */
+
+.dxp-drawer {
+ border-top: 2px solid var(--line-strong);
+ margin-top: 8px;
+ padding-top: 6px;
+ /* capped rather than free: the drawer explains the table above it, so it must
+ never push that table off screen */
+ max-height: 45vh;
+ display: flex;
+ flex-direction: column;
+ min-height: 0;
+}
+
+.dxp-drawer[hidden] {
+ display: none;
+}
+
+.dxp-drawer-head {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 0 2px 6px;
+}
+
+.dxp-drawer-title {
+ font-weight: 600;
+}
+
+.dxp-drawer-count {
+ color: var(--muted);
+ margin-inline-start: auto;
+}
+
+/* the same button as everywhere else in dash, at the same radius — this one
+ had grown its own 4px corners and a lighter border */
+.dxp-drawer-close {
+ font: inherit;
+ font-size: var(--fs-ui);
+ border: 1px solid var(--line-strong);
+ background: var(--bg);
+ color: var(--muted);
+ border-radius: var(--radius);
+ cursor: pointer;
+ padding: 2px 8px;
+}
+.dxp-drawer-close:hover { background: var(--panel); color: var(--ink); }
+
+.dxp-drill-scroll {
+ overflow: auto;
+ min-height: 0;
+}
+
+.dxp-drill {
+ border-collapse: separate;
+ border-spacing: 0;
+ width: max-content;
+ min-width: 100%;
+}
+
+.dxp-drill th,
+.dxp-drill td {
+ border-right: 1px solid var(--grid-line);
+ border-bottom: 1px solid var(--grid-line);
+ padding: 3px 8px;
+ white-space: nowrap;
+ text-align: left;
+}
+
+.dxp-drill thead th {
+ position: sticky;
+ top: 0;
+ background: var(--grid-head);
+ font-weight: 600;
+ box-shadow: inset 0 -2px 0 var(--line-strong);
+}
+
+.dxp-drill-n {
+ color: var(--muted);
+ text-align: right;
+ font-variant-numeric: tabular-nums;
+}
diff --git a/dash/src/pivot.ts b/dash/src/pivot.ts
new file mode 100644
index 00000000..f1d60c42
--- /dev/null
+++ b/dash/src/pivot.ts
@@ -0,0 +1,1204 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Pivot tables — grouped aggregation over the columnar store, and the drill-down
+// back to the rows behind a number.
+//
+// A PIVOT IS A DOCUMENT, NOT A VIEW, and the whole file hangs off that call.
+// dash has already drawn this line twice, in opposite directions:
+//
+// - SORTING AND FILTERING ARE VIEW STATE (filter.ts:3, store.ts:531). They
+// belong to the reader, they must not dirty the file, and two people looking
+// at one workbook may legitimately have different rows on screen.
+// - HIDING A COLUMN IS DOCUMENT STATE (rowcol.ts:526). It is an EDITORIAL act
+// — the author decided the working column is not part of the story — and two
+// people opening one file have to see the same grid or they are reading
+// different documents.
+//
+// "Revenue by region by quarter" is the second kind. It is a thing somebody
+// BUILT: the fields, the aggregations and the subtotal policy are an argument
+// about what the data means, and an argument that evaporated when the reader
+// closed the tab would not be worth making. It is also the thing a reader is
+// sent — "look at the pivot on sheet 3" has to name something that exists in the
+// file. So a pivot is a SHEET (`kind: 'pivot'`), it saves, it travels, and every
+// reader of the file sees the same one.
+//
+// WHAT THE SHEET STORES IS THE SPEC AND NEVER THE NUMBERS. That is chart.ts's
+// rule promoted again (chart.ts:5 — "a tile NAMES a sheet and columns"; slides
+// learned it the expensive way with `syncLinkedChart`): there is no code path
+// here that writes a computed cell into the document. A stored pivot could
+// disagree with the sheet beside it, go stale without saying so, and would
+// double the file for the privilege. A derived one cannot be wrong about its own
+// data — edit a cell and the pivot moves.
+//
+// The reader's own filters are deliberately NOT applied by default. The pivot
+// carries its own `filters` in the spec, because a document that changed shape
+// with each reader's grid filter would stop being one thing everybody sees —
+// exactly the property that made it a document. `runPivot`'s `rows` option is
+// the opt-in for "pivot what I am looking at", and it is the caller's choice.
+//
+// SEVEN THINGS ARE WRONG IN EVERY NAIVE PIVOT, and every one of them prints a
+// number that looks like an answer:
+//
+// 1. AN EMPTY GROUP THAT READS AS A ZERO. No rows for (South, Q3) is a GAP.
+// Printing 0 there says "South sold nothing in Q3", which is a claim about
+// the world made out of the absence of data. Cells carry `rows`, and a cell
+// with `rows: 0` has `v: null` and renders empty — never `0`, never `—`
+// beside a real zero.
+// 2. AN AVERAGE DIVIDED BY THE ROW COUNT. chart.ts:96 already settled it: the
+// divisor is the values PRESENT, not the rows in the group. Twelve rows
+// with four measurements average over four.
+// 3. TEXT COERCED TO ZERO. `Number('n/a')` is NaN, `Number('')` is 0, and the
+// convenient `|| 0` turns both into a silent deduction from the sum. This
+// is the bug filter.ts was written around (filter.ts:98) and it is worse in
+// a pivot, because the number is aggregated: nobody can see the row that
+// did it. Non-numeric values are COUNTED (`skipped`) and never summed.
+// 4. SUBTOTALS SUMMED FROM CHILDREN. Right for sum and count, WRONG for
+// average (an average of averages weights small groups equally), wrong for
+// median, wrong for count-distinct (distincts do not add — the same
+// customer in two regions counts twice). Every subtotal here is computed
+// from the source rows, not from the cells above it.
+// 5. ALPHABETICAL CATEGORIES. The first-seen order is the order the data is
+// in, which is usually the order that means something (a fiscal calendar
+// sorts to Apr, Aug, Dec). chart.ts:79 made this call; this file matches it.
+// 6. MATERIALISING THE ROWS. The whole storage argument is 4.8 bytes/cell
+// against 15.9 for array-of-objects (model.ts:17). A pivot that starts by
+// building an array of row objects spends the format's entire advantage in
+// the first ten lines. Nothing here allocates per row: grouping runs on
+// dictionary CODES, and a dictionary-encoded numeric column is parsed once
+// per DISTINCT VALUE rather than once per row.
+// 7. A DRILL-DOWN THAT DISAGREES WITH ITS OWN CELL. If the click re-derives
+// the group membership by some other route — re-parsing labels, matching
+// formatted strings — it will eventually return a different set of rows
+// than the ones that made the number. `drillDown` matches on the same
+// integer code planes the aggregation walked, so the two cannot drift.
+//
+// The engine half is pure and runs in node; the DOM half is at the bottom.
+
+import './pivot.css'
+import type { Column, ColumnData, Sheet, TableSheet } from './model.ts'
+import { readCell } from './store.ts'
+import { buildOrder, isBlank, type ColumnFilter, type Get } from './filter.ts'
+import { formatValue } from './format.ts'
+import { t } from './i18n.ts'
+
+// --- the spec --------------------------------------------------------------
+
+export type AggFn = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'median' | 'countDistinct'
+
+export const AGG_FNS: AggFn[] = ['sum', 'avg', 'count', 'min', 'max', 'median', 'countDistinct']
+
+/** English labels. Localised for DISPLAY only — the stored `fn` stays a model
+ * word, which is the rule `select()` follows across the suite (PLATFORM §8). */
+export const AGG_LABEL: Record<AggFn, string> = {
+ sum: 'Sum', avg: 'Average', count: 'Count', min: 'Min', max: 'Max',
+ median: 'Median', countDistinct: 'Distinct',
+}
+
+export interface PivotValue {
+ /** source column id */
+ col: string
+ fn: AggFn
+ /** display name override; absent means "Sum of Revenue" is generated */
+ as?: string
+ [extra: string]: unknown
+}
+
+/**
+ * What the author built. This is the whole of what a pivot sheet stores.
+ *
+ * Fields are COLUMN IDS, never names and never positions — the same identity
+ * every formula, override and tile keys off (model.ts:61), so renaming a column
+ * or dragging it somewhere else never breaks a pivot.
+ */
+export interface PivotSpec {
+ /** id of the source TABLE sheet */
+ from: string
+ /** row fields, outermost first */
+ rows: string[]
+ /** column fields, outermost first */
+ cols: string[]
+ values: PivotValue[]
+ /** the pivot's OWN filters — document state, unlike the grid's (filter.ts:3) */
+ filters?: ColumnFilter[]
+ /** default true */
+ subtotals?: boolean
+ /** default true */
+ grandTotals?: boolean
+ /**
+ * Include rows whose grouping field is blank, as a "(blank)" group. Default
+ * true, and the default matters: switching it off DROPS THE ROW ENTIRELY
+ * rather than merely hiding its group, because a grand total that no longer
+ * equals the sum of what is on screen is a worse lie than a "(blank)" label.
+ */
+ blanks?: boolean
+ [extra: string]: unknown
+}
+
+/**
+ * A pivot sheet.
+ *
+ * NOT YET A MEMBER OF `model.ts`'s `Sheet` UNION, and until it is, `parseDoc`
+ * rewrites `kind` to `'table'` for every sheet that is not `'canvas'`
+ * (model.ts:529) — so a saved pivot sheet comes back from a round trip
+ * kind-coerced, with empty `rids`/`columns`/`data` bolted on. That is why
+ * `isPivotSheet` below keys off the PRESENCE OF A WELL-FORMED `pivot` FIELD and
+ * not off `kind`: unknown top-level sheet fields survive the parse (the spread
+ * at model.ts:530 is the additivity promise of PLATFORM §3), so the spec makes
+ * it through intact and the pivot still opens. When model.ts adopts the kind,
+ * nothing here changes.
+ */
+export interface PivotSheet {
+ id: string
+ name: string
+ kind: 'pivot'
+ pivot: PivotSpec
+ [extra: string]: unknown
+}
+
+const isObj = (v: unknown): v is Record<string, unknown> =>
+ typeof v === 'object' && v !== null && !Array.isArray(v)
+
+const strings = (v: unknown): string[] =>
+ Array.isArray(v) ? v.filter((x): x is string => typeof x === 'string') : []
+
+/**
+ * Read a spec out of whatever is actually in the file, defensively — the same
+ * posture `readFrozen` takes (rowcol.ts:489). This is an additive field, so an
+ * older build, a hand edit or a newer one can put anything there, and anything
+ * unreadable has to mean "not a pivot" rather than throwing on open.
+ *
+ * `from` is required and the field lists are not: a pivot with no rows, no
+ * columns and one value is the legitimate degenerate case (one grand total),
+ * and it must open.
+ */
+export function readPivotSpec(sheet: unknown): PivotSpec | null {
+ if (!isObj(sheet)) return null
+ const p = sheet.pivot
+ if (!isObj(p)) return null
+ if (typeof p.from !== 'string' || !p.from) return null
+ const values = Array.isArray(p.values)
+ ? p.values.filter(isObj)
+ .filter((v) => typeof v.col === 'string')
+ .map((v) => ({
+ ...v,
+ col: v.col as string,
+ // an unrecognised fn is NOT silently a sum: it is preserved for a build
+ // that knows it, and `runPivot` reports it rather than answering
+ fn: v.fn as AggFn,
+ }))
+ : []
+ return {
+ ...p,
+ from: p.from,
+ rows: strings(p.rows),
+ cols: strings(p.cols),
+ values,
+ }
+}
+
+export function isPivotSheet(s: Sheet | PivotSheet | unknown): s is PivotSheet {
+ return readPivotSpec(s) !== null
+}
+
+// --- planes ----------------------------------------------------------------
+//
+// A "plane" is one column, prepared for one job, WITHOUT ever building a row
+// object. Two jobs, two shapes:
+//
+// GROUPING wants an integer per row, because grouping is a tree walk keyed by
+// that integer. For a dictionary column the integer already exists — `idx` IS
+// the code vector — so the whole preparation is an O(distinct-values) pass to
+// fold codes that mean the same thing onto one representative. Zero string
+// work per row, which is the point of the encoding.
+//
+// AGGREGATING wants a number per row, and here the dictionary pays twice: a
+// dict column of 100k rows over 40 distinct values is parsed FORTY TIMES, not
+// a hundred thousand. That parse is the expensive part (`asNumber` runs a
+// regex), so this is the difference between a pivot that lands in a frame and
+// one that does not.
+
+/** Blank has no code of its own in the source encoding, so it gets one here. */
+const BLANK = -1
+
+interface GroupPlane {
+ /** code per row; BLANK for an empty cell */
+ code: Int32Array
+ /** the value as it appears in the column, for labelling */
+ orig: (row: number) => unknown
+}
+
+interface ValuePlane {
+ /** the number in this cell, or null when there is not one */
+ num: (row: number) => number | null
+ /** is there anything here at all? (`count` counts these) */
+ present: (row: number) => boolean
+ /** canonical identity for `countDistinct`; null when blank */
+ key: (row: number) => string | null
+}
+
+/**
+ * The digit shape a string must have to be READ as a number. Copied verbatim
+ * from filter.ts:112 rather than imported, because filter.ts does not export it
+ * — and copied rather than loosened, which matters: `Number('')` is 0 (a blank
+ * becomes a zero), `Number('2026-01-15')` is NaN (an ISO date stays text, which
+ * is what makes it sort chronologically), and "50%" is refused because a percent
+ * column stores the FRACTION (import.ts:281), so reading it as 50 would be wrong
+ * by a factor of a hundred in every cell.
+ *
+ * ONE DELIBERATE DIVERGENCE: a boolean reads as 1/0 here and as null there. A
+ * bool column IS a measure in a pivot — "how many are flagged" is the obvious
+ * question to ask of one — and `count` cannot answer it, because `false` is a
+ * value that is present. filter.ts has no such use (it compares, it does not
+ * total) and its `rankable` already treats booleans as rankable, so the two are
+ * consistent in spirit. Every OTHER rule below is filter.ts's, unchanged.
+ *
+ * IF filter.ts EVER EXPORTS `asNumber`, TAKE IT AND KEEP ONLY THE BOOL CASE.
+ * Two copies of one rule is how a status bar and a pivot come to disagree about
+ * what a number is.
+ */
+const NUMERIC = /^[+-]?(?:(?:\d{1,3}(?:,\d{3})+|\d+)(?:\.\d+)?|\.\d+)$/
+
+function asNumber(v: unknown): number | null {
+ if (typeof v === 'number') return Number.isFinite(v) ? v : null
+ if (typeof v === 'boolean') return v ? 1 : 0
+ if (typeof v !== 'string') return null
+ const s = v.trim()
+ if (s === '' || !NUMERIC.test(s)) return null
+ const n = Number(s.replace(/,/g, ''))
+ return Number.isFinite(n) ? n : null
+}
+
+/**
+ * The one canonical key, matching filter.ts:146. Two values collapse into one
+ * pivot group exactly when they would collapse into one checkbox in the filter
+ * menu — so a reader who ticks "North" in the filter and sees "North" in the
+ * pivot is looking at the same set of rows both times. Numbers canonicalise
+ * through their value (10, "10" and " 10.0 " are one group); text
+ * canonicalises case- and whitespace-insensitively.
+ */
+function matchKey(v: unknown): string {
+ if (isBlank(v)) return ' blank'
+ const n = asNumber(v)
+ return n === null ? `t:${String(v).trim().toLowerCase()}` : `n:${n}`
+}
+
+/**
+ * `pack` is an opaque archive encoding and `readCell` answers null for every row
+ * of one (store.ts:196). Pivoting through that would silently produce ONE
+ * "(blank)" group holding the whole sheet and a grand total of nothing — a
+ * wrong answer with no symptom. rowcol.ts refuses packed columns for structural
+ * edits for the same reason; this refuses them for reads.
+ */
+function refusePacked(d: ColumnData | undefined, col: string): void {
+ if (d && d.enc === 'pack') {
+ throw new Error(`column "${col}" is packed and cannot be pivoted — promote it to raw first`)
+ }
+}
+
+function groupPlane(d: ColumnData | undefined, computed: unknown[] | undefined, n: number, col: string): GroupPlane {
+ const code = new Int32Array(n)
+ if (!computed && d && d.enc === 'dict') {
+ refusePacked(d, col)
+ // O(distinct), not O(rows): fold every dictionary entry onto the first entry
+ // sharing its canonical key, so the row loop below is an array index and a
+ // null test. This is the entire reason the format is dictionary-encoded.
+ const rep = new Int32Array(d.dict.length)
+ const seen = new Map<string, number>()
+ for (let k = 0; k < d.dict.length; k++) {
+ const s = d.dict[k]
+ if (isBlank(s)) { rep[k] = BLANK; continue }
+ const mk = matchKey(s)
+ const first = seen.get(mk)
+ if (first === undefined) { seen.set(mk, k); rep[k] = k } else rep[k] = first
+ }
+ for (let i = 0; i < n; i++) {
+ const k = d.idx[i]
+ code[i] = k == null ? BLANK : (rep[k] ?? BLANK)
+ }
+ return { code, orig: (row) => readCell(d, row) }
+ }
+
+ refusePacked(d, col)
+ // `raw` and computed columns have no dictionary to lean on, so this interns
+ // one — the same cost `buildOrder`'s column cache already pays per sort.
+ const read = computed
+ ? (row: number) => computed[row] ?? null
+ : (row: number) => readCell(d, row)
+ const seen = new Map<string, number>()
+ for (let i = 0; i < n; i++) {
+ const v = read(i)
+ if (isBlank(v)) { code[i] = BLANK; continue }
+ const mk = matchKey(v)
+ let c = seen.get(mk)
+ if (c === undefined) { c = seen.size; seen.set(mk, c) }
+ code[i] = c
+ }
+ return { code, orig: read }
+}
+
+function valuePlane(d: ColumnData | undefined, computed: unknown[] | undefined, col: string): ValuePlane {
+ if (!computed && d && d.enc === 'dict') {
+ refusePacked(d, col)
+ const nums = d.dict.map(asNumber)
+ const pres = d.dict.map((s) => !isBlank(s))
+ const keys = d.dict.map((s) => (isBlank(s) ? null : matchKey(s)))
+ const at = (row: number): number | null => {
+ const k = d.idx[row]
+ return k == null ? null : k
+ }
+ return {
+ num: (row) => { const k = at(row); return k == null ? null : (nums[k] ?? null) },
+ present: (row) => { const k = at(row); return k == null ? false : (pres[k] ?? false) },
+ key: (row) => { const k = at(row); return k == null ? null : (keys[k] ?? null) },
+ }
+ }
+ refusePacked(d, col)
+ const read = computed
+ ? (row: number) => computed[row] ?? null
+ : (row: number) => readCell(d, row)
+ return {
+ num: (row) => asNumber(read(row)),
+ present: (row) => !isBlank(read(row)),
+ key: (row) => { const v = read(row); return isBlank(v) ? null : matchKey(v) },
+ }
+}
+
+// --- accumulators ----------------------------------------------------------
+
+interface Acc {
+ /** non-blank values seen — what `count` reports */
+ present: number
+ /** how many of those were numbers — the DIVISOR of `avg` (chart.ts:96) */
+ numeric: number
+ /** present values that are not numbers. Recorded, never coerced to zero. */
+ skipped: number
+ sum: number
+ min: number | null
+ max: number | null
+ /** median is not a streaming aggregate; allocated only when one is asked for */
+ vals: number[] | null
+ /** distinct is not a streaming aggregate either */
+ keys: Set<string> | null
+}
+
+/** A (row group × column group) intersection. ABSENT means the pair never
+ * occurred, which is a gap — the reason the map is sparse rather than a dense
+ * matrix filled with zeroes. */
+interface Bucket {
+ rows: number
+ accs: Acc[]
+}
+
+const newAcc = (fn: AggFn): Acc => ({
+ present: 0, numeric: 0, skipped: 0, sum: 0, min: null, max: null,
+ vals: fn === 'median' ? [] : null,
+ keys: fn === 'countDistinct' ? new Set<string>() : null,
+})
+
+interface Node {
+ id: number
+ depth: number
+ code: number
+ label: unknown
+ kids: Map<number, Node>
+ /** first-seen order, which is the order the data is in (chart.ts:79) */
+ order: Node[]
+ parent: Node | null
+ /** column-node id → bucket. Only ROW nodes use this. */
+ cells: Map<number, Bucket>
+}
+
+// --- the result ------------------------------------------------------------
+
+export interface PivotCell {
+ /**
+ * NULL IS NOT ZERO. `rows === 0` means the combination does not occur — a gap.
+ * `rows > 0` with `v === null` means the rows are there and hold nothing this
+ * function can answer (a text column asked for a sum). Both render empty; a
+ * real zero renders "0".
+ */
+ v: number | null
+ /** source rows behind this cell — the number the drill-down will show */
+ rows: number
+ /** non-blank values among them */
+ present: number
+ /** how many of those were numbers */
+ numeric: number
+ /** present values that could not be read as numbers, and were NOT summed */
+ skipped: number
+}
+
+export type GroupKind = 'leaf' | 'subtotal' | 'grand'
+
+export interface PivotGroup {
+ /** one code per level pinned, root-relative. Shorter than the field list for
+ * a subtotal; empty for the grand total. */
+ codes: number[]
+ /** first-seen ORIGINAL values, one per pinned level — what the reader sees */
+ path: unknown[]
+ kind: GroupKind
+}
+
+export interface PivotColumn extends PivotGroup {
+ value: PivotValue
+ /** index into `spec.values` */
+ vi: number
+}
+
+export interface PivotRow extends PivotGroup {
+ /** one per entry in `columns`, same order */
+ cells: PivotCell[]
+}
+
+export interface PivotHeaderCell {
+ label: unknown
+ span: number
+ kind: GroupKind
+ /** true for the generated "… total" caption above a subtotal column */
+ total: boolean
+}
+
+/**
+ * Something the reader has to be told, rather than silently absorbed. The model
+ * takes this line everywhere (a mistyped value is `Column.failed`, an unknown
+ * step marks its descendants unresolved) and the reason is always the same: a
+ * pivot that quietly dropped a field still prints a full set of numbers.
+ */
+export interface PivotFinding {
+ kind: 'missing-column' | 'unknown-agg' | 'no-values' | 'empty-source'
+ detail: string
+}
+
+export interface PivotResult {
+ spec: PivotSpec
+ /** the fields that SURVIVED — a field naming a deleted column is dropped and
+ * reported, never grouped as one big blank */
+ rowFields: string[]
+ colFields: string[]
+ values: PivotValue[]
+ /** one row per column FIELD, plus a value-name row when it is needed */
+ header: PivotHeaderCell[][]
+ columns: PivotColumn[]
+ rows: PivotRow[]
+ /**
+ * Source rows that actually reached an accumulator — the denominator of
+ * everything on screen, and NOT simply the count the filters admitted. With
+ * `blanks: false` those two differ, and reporting the larger one would put a
+ * footer under the table that disagrees with the grand total directly above
+ * it. Invariant: with any row field, this equals the grand-total cell's `rows`.
+ */
+ scanned: number
+ findings: PivotFinding[]
+ /** retained so a drill-down cannot disagree with the number it explains */
+ source: PivotScan
+}
+
+/** The prepared source, kept on the result so `drillDown` re-uses the very code
+ * planes the aggregation walked instead of re-deriving membership some other
+ * way (see failure 7 in the header). */
+export interface PivotScan {
+ sheetId: string
+ /** the source row indices the filters admitted, in sheet order */
+ rows: number[]
+ rowPlanes: GroupPlane[]
+ colPlanes: GroupPlane[]
+}
+
+// --- the engine ------------------------------------------------------------
+
+export interface PivotOpts {
+ /** formula columns the grid just recomputed, as chart.ts takes them: a pivot
+ * over a derived column must show the numbers on screen, not the empty
+ * storage underneath them */
+ computed?: Map<string, unknown[]>
+ /**
+ * Restrict to these source row indices — the grid's order vector, if the
+ * caller wants "pivot what I am looking at". OFF by default and deliberately:
+ * a document whose numbers changed with each reader's grid filter would stop
+ * being one thing everyone sees, which is the property that made it a
+ * document in the first place (see the header).
+ */
+ rows?: number[]
+}
+
+const rowsOf = (sheet: TableSheet): number => sheet.rids.reduce((n, [, c]) => n + c, 0)
+
+const KNOWN_AGG = new Set<string>(AGG_FNS)
+
+/**
+ * Run a pivot.
+ *
+ * Cost is one pass over the admitted rows, touching (rowDepth + 1) ×
+ * (colDepth + 1) buckets each — nine map operations per row for the common
+ * two-by-two pivot. No row object is ever built.
+ *
+ * Measured: 200,000 rows, two row fields × one column field × two value fields
+ * (dictionary-encoded groups, raw measure with 2% text in it) — 74 ms to build,
+ * 18 MB heap, 2 ms to drill 2,062 rows out of a grand-total cell. A click, not
+ * a frame, which is the trade filter.ts:352 already made for sorting.
+ */
+export function runPivot(sheet: TableSheet, spec: PivotSpec, opts: PivotOpts = {}): PivotResult {
+ const n = rowsOf(sheet)
+ const findings: PivotFinding[] = []
+ const has = (id: string): boolean =>
+ sheet.columns.some((c) => c.id === id) || opts.computed?.has(id) === true
+ const nameOf = (id: string): string => sheet.columns.find((c) => c.id === id)?.name ?? id
+
+ // A field naming a column that is gone is DROPPED and reported. Keeping it
+ // would group every row under one "(blank)", which looks like a pivot and is
+ // a pivot of nothing; grouping silently by the remaining fields would change
+ // every number on screen without saying so.
+ const keep = (ids: string[], where: string): string[] => ids.filter((id) => {
+ if (has(id)) return true
+ findings.push({
+ kind: 'missing-column',
+ detail: `the ${where} field "${id}" names a column this sheet no longer has, so it is not being grouped by`,
+ })
+ return false
+ })
+
+ const rowFields = keep(spec.rows, 'row')
+ const colFields = keep(spec.cols, 'column')
+ const values = spec.values.filter((v) => {
+ if (!has(v.col)) {
+ findings.push({
+ kind: 'missing-column',
+ detail: `the value "${v.col}" names a column this sheet no longer has`,
+ })
+ return false
+ }
+ if (!KNOWN_AGG.has(v.fn)) {
+ // Preserved in the document (readPivotSpec spreads it through) and refused
+ // HERE, because inventing an answer for a function this build cannot
+ // perform is the "unresolved" failure model.ts:174 exists to prevent.
+ findings.push({
+ kind: 'unknown-agg',
+ detail: `"${String(v.fn)}" is not an aggregation this build knows, so ${nameOf(v.col)} is not summarised`,
+ })
+ return false
+ }
+ return true
+ })
+ if (!values.length) {
+ findings.push({ kind: 'no-values', detail: 'this pivot has nothing to summarise yet' })
+ }
+ if (!n) findings.push({ kind: 'empty-source', detail: 'the source sheet has no rows' })
+
+ const col = (id: string): ColumnData | undefined => sheet.data[id]
+ const comp = (id: string): unknown[] | undefined => opts.computed?.get(id)
+
+ const rowPlanes = rowFields.map((id) => groupPlane(col(id), comp(id), n, id))
+ const colPlanes = colFields.map((id) => groupPlane(col(id), comp(id), n, id))
+ const valPlanes = values.map((v) => valuePlane(col(v.col), comp(v.col), v.col))
+
+ // The pivot's OWN filters, through filter.ts — one implementation of "less
+ // than 10", not two. `topN` works here too, and ranks the whole source.
+ let rows: number[]
+ if (spec.filters?.length) {
+ const get: Get = (c, row) => {
+ const cv = comp(c)
+ return cv ? cv[row] ?? null : readCell(col(c), row)
+ }
+ rows = buildOrder(n, get, spec.filters, [])
+ } else {
+ rows = Array.from({ length: n }, (_, i) => i)
+ }
+ if (opts.rows) {
+ const allowed = new Set(opts.rows)
+ rows = rows.filter((r) => allowed.has(r))
+ }
+
+ let nextId = 0
+ const mkNode = (depth: number, code: number, label: unknown, parent: Node | null): Node => ({
+ id: nextId++, depth, code, label, kids: new Map(), order: [], parent, cells: new Map(),
+ })
+ const rowRoot = mkNode(0, BLANK, null, null)
+ const colRoot = mkNode(0, BLANK, null, null)
+
+ const descend = (node: Node, code: number, label: unknown): Node => {
+ let k = node.kids.get(code)
+ if (!k) {
+ // The label is captured HERE, at first sight, so it is the original as it
+ // appears in the first row of the group — matching the order the groups
+ // come out in. Reading it off the dictionary instead would show whichever
+ // spelling happened to be interned first, which is not always the same.
+ k = mkNode(node.depth + 1, code, label, node)
+ node.kids.set(code, k)
+ node.order.push(k)
+ }
+ return k
+ }
+
+ const includeBlanks = spec.blanks !== false
+ const rowChain: Node[] = new Array(rowFields.length + 1)
+ const colChain: Node[] = new Array(colFields.length + 1)
+ let scanned = 0
+
+ scan: for (const r of rows) {
+ // EXCLUDING BLANKS EXCLUDES THE ROW, not merely its group. Hiding the group
+ // while still feeding its rows into the totals leaves a grand total that
+ // does not equal the sum of what is on screen, and a reader who adds the
+ // column up by hand is right and the pivot is wrong.
+ if (!includeBlanks) {
+ for (const p of rowPlanes) if (p.code[r] === BLANK) continue scan
+ for (const p of colPlanes) if (p.code[r] === BLANK) continue scan
+ }
+ scanned++
+ rowChain[0] = rowRoot
+ for (let l = 0; l < rowPlanes.length; l++) {
+ const c = rowPlanes[l].code[r]
+ rowChain[l + 1] = descend(rowChain[l], c, c === BLANK ? null : rowPlanes[l].orig(r))
+ }
+ colChain[0] = colRoot
+ for (let l = 0; l < colPlanes.length; l++) {
+ const c = colPlanes[l].code[r]
+ colChain[l + 1] = descend(colChain[l], c, c === BLANK ? null : colPlanes[l].orig(r))
+ }
+
+ // EVERY ancestor pair, not just the leaf pair. This is what makes subtotals
+ // computed rather than summed (failure 4): the (region, ·) bucket sees the
+ // same rows the leaves do, so its average divides by its own values and its
+ // distinct count is a distinct count.
+ for (const rn of rowChain) {
+ for (const cn of colChain) {
+ let b = rn.cells.get(cn.id)
+ if (!b) { b = { rows: 0, accs: values.map((v) => newAcc(v.fn)) }; rn.cells.set(cn.id, b) }
+ b.rows++
+ for (let vi = 0; vi < valPlanes.length; vi++) {
+ const p = valPlanes[vi]
+ if (!p.present(r)) continue
+ const a = b.accs[vi]
+ a.present++
+ if (a.keys) { const k = p.key(r); if (k !== null) a.keys.add(k) }
+ const num = p.num(r)
+ if (num === null) { a.skipped++; continue }
+ a.numeric++
+ a.sum += num
+ if (a.min === null || num < a.min) a.min = num
+ if (a.max === null || num > a.max) a.max = num
+ if (a.vals) a.vals.push(num)
+ }
+ }
+ }
+ }
+
+ const subtotals = spec.subtotals !== false
+ const grand = spec.grandTotals !== false
+ const rowGroups = flatten(rowRoot, rowFields.length, subtotals, grand)
+ const colGroups = flatten(colRoot, colFields.length, subtotals, grand)
+
+ const columns: PivotColumn[] = []
+ const colNodes: Node[] = []
+ for (const g of colGroups) {
+ for (let vi = 0; vi < values.length; vi++) {
+ columns.push({ codes: g.codes, path: g.path, kind: g.kind, value: values[vi], vi })
+ colNodes.push(g.node)
+ }
+ }
+
+ const out: PivotRow[] = rowGroups.map((g) => ({
+ codes: g.codes,
+ path: g.path,
+ kind: g.kind,
+ cells: columns.map((c, i) => finish(g.node.cells.get(colNodes[i].id), c.value.fn, c.vi)),
+ }))
+
+ return {
+ spec,
+ rowFields,
+ colFields,
+ values,
+ header: buildHeader(columns, colFields.length, values, nameOf),
+ columns,
+ rows: out,
+ scanned,
+ findings,
+ source: { sheetId: sheet.id, rows, rowPlanes, colPlanes },
+ }
+}
+
+interface FlatGroup extends PivotGroup { node: Node }
+
+/**
+ * Depth-first, children before their own subtotal, grand total last — Excel's
+ * outline order, and the only one where a subtotal reads as summarising the
+ * lines above it.
+ *
+ * A node at full depth is a LEAF even if `depth` is 0: a pivot with no column
+ * fields has exactly one column group, which is the root, and it is a leaf
+ * rather than a grand total. Emitting a grand total there as well would print
+ * the same numbers twice under two different captions.
+ */
+function flatten(root: Node, depth: number, subtotals: boolean, grand: boolean): FlatGroup[] {
+ const out: FlatGroup[] = []
+ const codes: number[] = []
+ const path: unknown[] = []
+ const walk = (node: Node): void => {
+ if (node.depth === depth) {
+ out.push({ codes: codes.slice(), path: path.slice(), kind: 'leaf', node })
+ return
+ }
+ for (const k of node.order) {
+ codes.push(k.code)
+ path.push(k.label)
+ walk(k)
+ codes.pop()
+ path.pop()
+ }
+ // A node with one child gets a subtotal identical to that child's row. Excel
+ // prints it anyway and so does this: suppressing it makes the outline depth
+ // depend on the data, so two regions of the same report indent differently.
+ if (node.depth > 0 && subtotals) {
+ out.push({ codes: codes.slice(), path: path.slice(), kind: 'subtotal', node })
+ }
+ }
+ walk(root)
+ if (depth > 0 && grand) out.push({ codes: [], path: [], kind: 'grand', node: root })
+ return out
+}
+
+/** Shared and FROZEN: it is returned by reference for every gap in the table,
+ * so a caller that decorated it in place would decorate all of them. */
+const EMPTY_CELL: PivotCell = Object.freeze({ v: null, rows: 0, present: 0, numeric: 0, skipped: 0 })
+
+/**
+ * One accumulator into one cell.
+ *
+ * `count` and `countDistinct` return 0 when the group HAS rows and none of them
+ * carry a value — that zero is an answer ("nothing was recorded here"), and it
+ * is distinguishable from the gap because the gap has `rows: 0` and no bucket at
+ * all. Every other function returns null instead of 0, for filter.ts's reason
+ * (filter.ts:498): a sum of nothing printed as `0` reads as "these add up to
+ * nothing", `Math.min()` of an empty list is Infinity, and 0/0 is NaN.
+ */
+function finish(b: Bucket | undefined, fn: AggFn, vi: number): PivotCell {
+ if (!b) return EMPTY_CELL
+ const a = b.accs[vi]
+ const base = { rows: b.rows, present: a.present, numeric: a.numeric, skipped: a.skipped }
+ switch (fn) {
+ case 'count': return { ...base, v: a.present }
+ case 'countDistinct': return { ...base, v: a.keys ? a.keys.size : 0 }
+ case 'sum': return { ...base, v: a.numeric ? a.sum : null }
+ case 'avg': return { ...base, v: a.numeric ? a.sum / a.numeric : null }
+ case 'min': return { ...base, v: a.min }
+ case 'max': return { ...base, v: a.max }
+ case 'median': return { ...base, v: a.numeric && a.vals ? median(a.vals) : null }
+ }
+}
+
+/** Numeric sort, then the middle — `Array.sort`'s default is LEXICAL, which
+ * would put 100 before 9 and hand back a median that is not one. */
+function median(vals: number[]): number {
+ const s = vals.slice().sort((x, y) => x - y)
+ const m = s.length >> 1
+ return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2
+}
+
+/**
+ * The column header, one row per column field plus a value row.
+ *
+ * The value row exists when there is more than one value field — or when there
+ * are no column fields at all, because otherwise the table would have a header
+ * with nothing in it and the reader could not tell a sum from a count.
+ */
+function buildHeader(
+ columns: PivotColumn[], depth: number, values: PivotValue[], nameOf: (id: string) => string,
+): PivotHeaderCell[][] {
+ const out: PivotHeaderCell[][] = []
+ for (let l = 0; l < depth; l++) {
+ const row: PivotHeaderCell[] = []
+ let key: string | null = null
+ for (const c of columns) {
+ // A subtotal column pins fewer levels than the header is deep, so past
+ // its own depth it carries the "… total" caption. Its identity at level
+ // `l` is just its pinned prefix — a subtotal DOES belong under its
+ // parent's caption at the levels above it, and it can never merge with a
+ // sibling leaf at the level where the two differ, because one prefix is
+ // then a strict prefix of the other. An earlier draft also appended a
+ // total marker here; it turned out to change no output for any shape,
+ // and dead defence that nothing can distinguish is how a file rots.
+ //
+ // SEPARATED, not concatenated: codes are integers, so `[1,2]` and `[12]`
+ // join to the same string without a separator, and two unrelated groups
+ // sharing a header key would merge into one cell whose colspan then lies
+ // about what is under it. Codes are handed out in first-seen order, so
+ // adjacent groups get adjacent numbers and the collision is probably not
+ // reachable today — but this is a comma, and the alternative is re-running
+ // that reachability argument every time the coding changes.
+ const k = c.codes.slice(0, Math.min(l + 1, c.codes.length)).join(',')
+ if (k === key && row.length) { row[row.length - 1].span++; continue }
+ key = k
+ const total = l >= c.codes.length
+ row.push({
+ label: total
+ ? (c.kind === 'grand' ? t('Grand total') : totalCaption(c.path))
+ : c.path[l],
+ span: 1,
+ kind: c.kind,
+ total,
+ })
+ }
+ out.push(row)
+ }
+ if (values.length > 1 || depth === 0) {
+ out.push(columns.map((c) => ({
+ label: valueName(c.value, nameOf),
+ span: 1,
+ kind: c.kind,
+ total: false,
+ })))
+ }
+ return out
+}
+
+const totalCaption = (path: unknown[]): string =>
+ t('{name} total').replace('{name}', label(path[path.length - 1]))
+
+/** The caption for a value field. Generated rather than stored, so renaming the
+ * source column renames the pivot's header with it. */
+export const valueName = (v: PivotValue, nameOf: (id: string) => string): string =>
+ v.as ?? `${t(AGG_LABEL[v.fn] ?? String(v.fn))} ${t('of')} ${nameOf(v.col)}`
+
+/** A group label for display. A blank group is "(blank)" and NOT an empty
+ * string: an unlabelled row in the middle of an outline reads as a rendering
+ * bug, and the reader cannot tell it from the subtotal above it. */
+export const label = (v: unknown): string =>
+ isBlank(v) ? t('(blank)') : String(v)
+
+// --- drill-down ------------------------------------------------------------
+
+export interface Drill {
+ /** source row indices, in sheet order */
+ rows: number[]
+ /** how many there are in total, when `rows` was capped */
+ total: number
+ truncated: boolean
+}
+
+/**
+ * The rows behind one number.
+ *
+ * This is the thing dash can do that Excel cannot do honestly: the source rows
+ * are in the same file, so "why is this 4,812?" is a click rather than an export
+ * and a VLOOKUP. Excel's own drill-down materialises a COPY of the rows onto a
+ * new sheet — a snapshot that is wrong the moment anything upstream changes, and
+ * that quietly doubles the workbook. This returns indices into the live sheet.
+ *
+ * MATCHED ON THE CODE PLANES, not on labels and not on formatted text. Anything
+ * that re-derives group membership by a second route will eventually disagree
+ * with the aggregation that produced the number — the rig checks that summing a
+ * drill-down reproduces its own cell, which is the check that would catch it.
+ *
+ * O(admitted rows) per click, with no state kept per cell. At 100k rows that is
+ * a few milliseconds: a click, not a frame — the same trade filter.ts:352 makes.
+ */
+export function drillDown(
+ res: PivotResult, rowIndex: number, colIndex: number, cap = 500,
+): Drill {
+ const r = res.rows[rowIndex]
+ const c = res.columns[colIndex]
+ if (!r || !c) return { rows: [], total: 0, truncated: false }
+ const { rows, rowPlanes, colPlanes } = res.source
+ const includeBlanks = res.spec.blanks !== false
+ const out: number[] = []
+ let total = 0
+ scan: for (const i of rows) {
+ if (!includeBlanks) {
+ for (const p of rowPlanes) if (p.code[i] === BLANK) continue scan
+ for (const p of colPlanes) if (p.code[i] === BLANK) continue scan
+ }
+ for (let l = 0; l < r.codes.length; l++) if (rowPlanes[l].code[i] !== r.codes[l]) continue scan
+ for (let l = 0; l < c.codes.length; l++) if (colPlanes[l].code[i] !== c.codes[l]) continue scan
+ total++
+ if (out.length < cap) out.push(i)
+ }
+ return { rows: out, total, truncated: total > out.length }
+}
+
+// --- authoring -------------------------------------------------------------
+
+/**
+ * A first pivot that takes no configuration, the way `defaultBinding`
+ * (chart.ts:154) gives the first chart one. The first low-cardinality text
+ * column becomes the rows, the second becomes the columns, and the first
+ * magnitude column is summed.
+ *
+ * Returns null rather than an empty pivot when the sheet cannot support one:
+ * an empty pivot is indistinguishable from a broken one.
+ */
+export function defaultPivot(sheet: TableSheet): PivotSpec | null {
+ const n = rowsOf(sheet)
+ const cat = sheet.columns.filter((c) => c.type === 'text' || c.type === 'enum' || c.type === 'bool')
+ // A near-unique column (an id, a note) makes one group per row, which is the
+ // source table with extra lines. Cardinality is measured off the DICTIONARY
+ // where there is one — free, and the reason the encoding is worth having.
+ const wide = (c: Column): boolean => {
+ const d = sheet.data[c.id]
+ const distinct = d && d.enc === 'dict' ? d.dict.length : n
+ // The floor keeps a small sheet groupable at all — at eight rows, eight
+ // groups is still a table you can read, and refusing it would leave a new
+ // workbook with no default pivot for no reason a user could see.
+ return n >= 8 && distinct > Math.max(8, n / 2)
+ }
+ const usable = cat.filter((c) => !wide(c))
+ const nums = sheet.columns.filter((c) => c.type === 'number' || c.type === 'money' || c.type === 'percent')
+ if (!usable.length || !nums.length) return null
+ return {
+ from: sheet.id,
+ rows: [usable[0].id],
+ cols: usable[1] ? [usable[1].id] : [],
+ values: [{ col: nums[0].id, fn: 'sum' }],
+ }
+}
+
+/**
+ * Mint a pivot sheet.
+ *
+ * NOT A PATCH FACTORY, unlike every other authoring helper in this codebase
+ * (rowcol.ts:5), and not by choice: `Patch` reaches cells, columns, sheet props
+ * and `doc.title` — never the sheet LIST (store.ts:55). panels.ts hit the same
+ * wall and routes `addSheet` through `replaceDoc`, which clears the undo stack.
+ * This returns the object; the call site pushes it and calls `replaceDoc`, and
+ * adding a pivot is therefore not undoable. See the report — an `addSheet` patch
+ * op is the hook this file wants.
+ */
+export function newPivotSheet(id: string, name: string, spec: PivotSpec): PivotSheet {
+ return { id, name, kind: 'pivot', pivot: spec }
+}
+
+// --- rendering -------------------------------------------------------------
+//
+// One table, drawn whole. There is no virtualisation here and that is a
+// deliberate limit rather than an oversight: a pivot with more rows than fit on
+// screen has failed as a pivot — it is a summary, and a summary you have to
+// scroll for a minute is the source table wearing a hat. The renderer caps and
+// SAYS SO instead of quietly drawing the first thousand.
+
+/** Past this a pivot has stopped summarising. Rendered, then capped with a note. */
+export const PIVOT_ROW_CAP = 2000
+
+export interface PivotViewOpts {
+ /** the source sheet, for column names, number formats and the drill-down table */
+ sheet: TableSheet
+ /** formula columns, as `runPivot` takes them */
+ computed?: Map<string, unknown[]>
+ /** clicked a cell — the host may take over instead of the built-in drawer */
+ onDrill?: (drill: Drill, row: PivotRow, col: PivotColumn) => void
+}
+
+const el = <K extends keyof HTMLElementTagNameMap>(
+ tag: K, cls?: string, text?: string,
+): HTMLElementTagNameMap[K] => {
+ const e = document.createElement(tag)
+ if (cls) e.className = cls
+ if (text !== undefined) e.textContent = text
+ return e
+}
+
+/**
+ * Format an aggregated number.
+ *
+ * A COUNT IS NOT MONEY. Counting a currency column and printing "$14.00" for
+ * fourteen rows is the kind of wrong that a reader believes, so counts take a
+ * plain integer format and everything else inherits the source column's — an
+ * average of a money column is money, a sum of a percent column is a percent.
+ */
+function formatAgg(v: number | null, fn: AggFn, source: Column | undefined): string {
+ if (v === null) return ''
+ if (fn === 'count' || fn === 'countDistinct') {
+ return new Intl.NumberFormat(undefined, { maximumFractionDigits: 0 }).format(v)
+ }
+ return formatValue(v, source ?? { type: 'number' })
+}
+
+/**
+ * Draw a pivot into a host element. Returns a teardown, as `renderChart` does.
+ *
+ * Re-renders whole. The tables here are small by construction (see the cap
+ * above), and a diffing renderer would be a lot of machinery guarding a repaint
+ * that costs under a millisecond.
+ */
+export function mountPivot(host: HTMLElement, res: PivotResult, opts: PivotViewOpts): () => void {
+ const { sheet } = opts
+ const colOf = (id: string): Column | undefined => sheet.columns.find((c) => c.id === id)
+ const nameOf = (id: string): string => colOf(id)?.name ?? id
+
+ host.textContent = ''
+ const wrap = el('div', 'dxp')
+
+ if (res.findings.length) {
+ const box = el('div', 'dxp-findings')
+ for (const f of res.findings) box.append(el('div', 'dxp-finding', f.detail))
+ wrap.append(box)
+ }
+
+ if (!res.values.length) {
+ wrap.append(el('p', 'dxp-empty', t('Add a value field to summarise.')))
+ host.append(wrap)
+ return () => { host.textContent = '' }
+ }
+
+ const scroll = el('div', 'dxp-scroll')
+ const table = el('table', 'dxp-table')
+ const thead = el('thead')
+ const rowSpan = res.header.length || 1
+
+ // The row-field captions sit in the top-left corner block, spanning every
+ // header row — the one place in the table where the ROW axis gets named at
+ // all. Without it a two-level pivot is two columns of words with no clue
+ // which is which.
+ const corner = el('th', 'dxp-corner')
+ corner.rowSpan = rowSpan
+ corner.colSpan = Math.max(1, res.rowFields.length)
+ corner.textContent = res.rowFields.map(nameOf).join(' · ')
+
+ res.header.forEach((hrow, i) => {
+ const tr = el('tr')
+ if (i === 0) tr.append(corner)
+ for (const cell of hrow) {
+ const th = el('th', `dxp-h dxp-${cell.kind}${cell.total ? ' dxp-total' : ''}`)
+ th.colSpan = cell.span
+ th.textContent = cell.total ? String(cell.label) : label(cell.label)
+ tr.append(th)
+ }
+ thead.append(tr)
+ })
+ if (!res.header.length) {
+ const tr = el('tr')
+ tr.append(corner)
+ thead.append(tr)
+ }
+ table.append(thead)
+
+ const tbody = el('tbody')
+ const shown = Math.min(res.rows.length, PIVOT_ROW_CAP)
+ for (let ri = 0; ri < shown; ri++) {
+ const row = res.rows[ri]
+ const tr = el('tr', `dxp-r dxp-${row.kind}`)
+
+ // Row headers: one cell per row field, with the ancestors that repeat from
+ // the previous line left blank. Repeating "North" down forty lines is how a
+ // pivot stops looking like an outline and starts looking like a export.
+ const prev = ri > 0 ? res.rows[ri - 1] : null
+ if (row.kind === 'grand') {
+ const th = el('th', 'dxp-rh dxp-total')
+ th.colSpan = Math.max(1, res.rowFields.length)
+ th.textContent = t('Grand total')
+ tr.append(th)
+ } else if (row.kind === 'subtotal') {
+ const th = el('th', 'dxp-rh dxp-total')
+ th.colSpan = Math.max(1, res.rowFields.length)
+ th.textContent = totalCaption(row.path)
+ tr.append(th)
+ } else {
+ for (let l = 0; l < Math.max(1, res.rowFields.length); l++) {
+ const same = prev && prev.kind === 'leaf' && prev.codes[l] === row.codes[l]
+ && prev.codes.slice(0, l).join(',') === row.codes.slice(0, l).join(',')
+ tr.append(el('th', 'dxp-rh', same ? '' : label(row.path[l])))
+ }
+ }
+
+ row.cells.forEach((cell, ci) => {
+ const c = res.columns[ci]
+ const td = el('td', `dxp-c dxp-${c.kind}${row.kind !== 'leaf' ? ' dxp-total' : ''}`)
+ td.textContent = formatAgg(cell.v, c.value.fn, colOf(c.value.col))
+ if (cell.rows === 0) {
+ td.classList.add('dxp-gap')
+ // A gap is titled, because an empty cell and a cell holding an empty
+ // string look identical and mean opposite things.
+ td.title = t('no rows')
+ } else {
+ td.title = t('{n} source rows').replace('{n}', String(cell.rows))
+ if (cell.skipped) {
+ // Never folded into the number and never hidden: this is `Column.failed`
+ // (model.ts:87) at the aggregate level.
+ td.classList.add('dxp-skipped')
+ td.title += ` · ${t('{n} value(s) are not numbers and were not counted').replace('{n}', String(cell.skipped))}`
+ }
+ td.tabIndex = 0
+ td.addEventListener('click', () => openDrill(ri, ci))
+ td.addEventListener('keydown', (e) => {
+ if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); openDrill(ri, ci) }
+ })
+ }
+ tr.append(td)
+ })
+ tbody.append(tr)
+ }
+ table.append(tbody)
+ scroll.append(table)
+ wrap.append(scroll)
+
+ if (res.rows.length > shown) {
+ wrap.append(el('p', 'dxp-note',
+ t('{n} more rows are not shown — this pivot has stopped summarising.')
+ .replace('{n}', String(res.rows.length - shown))))
+ }
+ wrap.append(el('p', 'dxp-note',
+ t('{n} source rows').replace('{n}', String(res.scanned))))
+
+ const drawer = el('div', 'dxp-drawer')
+ drawer.hidden = true
+ wrap.append(drawer)
+ host.append(wrap)
+
+ function openDrill(ri: number, ci: number): void {
+ const d = drillDown(res, ri, ci)
+ const row = res.rows[ri]
+ const c = res.columns[ci]
+ if (opts.onDrill) { opts.onDrill(d, row, c); return }
+ drawer.textContent = ''
+ drawer.hidden = false
+
+ const head = el('div', 'dxp-drawer-head')
+ const parts = [
+ ...row.path.map(label),
+ ...c.path.map(label),
+ valueName(c.value, nameOf),
+ ]
+ head.append(el('span', 'dxp-drawer-title', parts.join(' · ')))
+ head.append(el('span', 'dxp-drawer-count',
+ t('{n} rows').replace('{n}', String(d.total))))
+ const close = el('button', 'dxp-drawer-close', '✕')
+ close.title = t('Close')
+ close.addEventListener('click', () => { drawer.hidden = true })
+ head.append(close)
+ drawer.append(head)
+
+ const dt = el('table', 'dxp-drill')
+ const htr = el('tr')
+ // The source ROW NUMBER is shown, because the whole point is to be able to
+ // go and look at it. Positions are 1-based here to match the grid gutter.
+ htr.append(el('th', 'dxp-drill-n', '#'))
+ for (const sc of sheet.columns) htr.append(el('th', '', sc.name))
+ const dhead = el('thead')
+ dhead.append(htr)
+ dt.append(dhead)
+ const body = el('tbody')
+ for (const r of d.rows) {
+ const tr = el('tr')
+ tr.append(el('td', 'dxp-drill-n', String(r + 1)))
+ for (const sc of sheet.columns) {
+ const v = opts.computed?.get(sc.id)?.[r] ?? readCell(sheet.data[sc.id], r)
+ tr.append(el('td', '', formatValue(v, sc)))
+ }
+ body.append(tr)
+ }
+ dt.append(body)
+ const dscroll = el('div', 'dxp-drill-scroll')
+ dscroll.append(dt)
+ drawer.append(dscroll)
+ if (d.truncated) {
+ drawer.append(el('p', 'dxp-note',
+ t('Showing the first {n} of {total}.')
+ .replace('{n}', String(d.rows.length))
+ .replace('{total}', String(d.total))))
+ }
+ drawer.scrollIntoView({ block: 'nearest' })
+ }
+
+ return () => { host.textContent = '' }
+}
+
+/** Exposed for the rig, as store.ts and rowcol.ts do — not part of the app's surface. */
+export const _internals = { asNumber, matchKey, median, groupPlane, valuePlane, flatten, BLANK }
diff --git a/dash/src/preview.ts b/dash/src/preview.ts
new file mode 100644
index 00000000..fd62547d
--- /dev/null
+++ b/dash/src/preview.ts
@@ -0,0 +1,547 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The static first-sheet preview: what a bento/dash workbook looks like to
+// something that renders its HTML but never runs its JavaScript.
+//
+// WHY THIS EXISTS. Thumbnailers — iOS Files, macOS QuickLook/Finder, the Bento
+// Tray app — render HTML with scripting OFF. Until the runtime boots, every
+// workbook is the same bytes plus the same splash, so a folder of dash files
+// thumbnails as a wall of identical white boxes with `bento/dash` in the
+// middle. A spreadsheet is the document type where recognition matters most:
+// people find last quarter's model by remembering what its first screen looked
+// like, not by reading a filename.
+//
+// The kernel (kernel/src/save.ts) owns the placement, the replace-never-append
+// rule, the encryption veto and the output-safety check. What lives here is the
+// drawing, and the three dash-specific decisions the kernel cannot make:
+//
+// 1. NEVER SHOW A NUMBER WE DID NOT COMPUTE, AND NEVER SHOW ZERO FOR ONE WE
+// COULD NOT. A formula column has no stored values — the file holds the
+// EXPRESSION (store.ts) — so a preview that printed `0` where it could not
+// recalculate would be publishing a wrong number in the one artefact
+// nobody proofreads. Small sheets are recalculated properly; big ones show
+// the `fx` chip and an empty cell, which reads as "computed elsewhere".
+// model.ts states the rule for unresolved steps in the same words: an
+// empty bar chart reads as ZERO, which is a number, which is a lie.
+// 2. A PARTIAL TOTAL IS WORSE THAN NO TOTAL. The totals row is dash's answer
+// to `=SUM(B2:B41)` falling out of range, so summing only the rows the
+// preview happens to draw would put exactly the failure it refuses into
+// the thumbnail. Past TOTALS_SCAN_ROWS the row is omitted entirely.
+// 3. THEME COLOURS ARE AUTHOR DATA AND REACH A <style> BLOCK. Escaping `<`
+// is enough for markup and is NOT enough inside a stylesheet: a theme
+// accent of `#fff}body{display:none` closes the rule and writes new ones.
+// Every colour that reaches CSS goes through `cssColor()` first.
+//
+// HOW IT SCALES. `transform: scale(calc(100vw / <table width>px))` with a
+// `transform: none` declaration in front of it. CSS Values 4 length-over-length
+// division yields the plain <number> scale() needs; a renderer that rejects it
+// drops the second declaration and keeps the first, showing the table at 1:1
+// (cropped, but the workbook) instead of nothing. This is slides' measured
+// recipe (slides/src/preview.ts) — verified there in the real macOS
+// thumbnailer, `qlmanage -t` — with the fixed 1280×720 page swapped for the
+// table's own width, because a grid has no aspect ratio of its own.
+//
+// WHY MARKUP AS A STRING, not DOM built and serialized. Two reasons, both
+// practical: the byte budget is then measured on the exact bytes that reach the
+// file rather than on a re-serialization of them, and every decision in here
+// stays testable in node with no DOM at all — which is what
+// `scripts/test-dash-preview.ts` exercises. The DOM appears once, in
+// `buildSheetPreview`, which is the only function the kernel calls.
+
+import { isEncryptionActive } from '../../kernel/src/save.ts'
+import { formatValue, alignFor, TYPE_LABEL } from './format.ts'
+import { readCell } from './store.ts'
+import { hiddenSet } from './rowcol.ts'
+import { colToLetters } from './a1.ts'
+import { recalc, isErr, type Vec } from './formula.ts'
+import { FORMAT } from './model.ts'
+import type {
+ CanvasSheet, Column, ColumnType, DashDoc, Sheet, TableSheet,
+} from './model.ts'
+
+/**
+ * What the preview may cost, in bytes of markup.
+ *
+ * It is paid in EVERY saved file and it cannot be compressed: the shell's
+ * deflate trick is unavailable to an audience that never runs the loader. It
+ * lives here rather than beside the budgets in model.ts because those all bound
+ * the DOCUMENT — the thing the format promises to carry — and this bounds shell
+ * furniture that no reader of the format ever sees.
+ *
+ * 40KB buys roughly 16 rows × 8 columns of real data with room to spare; the
+ * tiers below spend it down rather than overrun it.
+ */
+export const PREVIEW_BUDGET = 40 * 1024
+
+/**
+ * How much of the sheet to draw, cheapest acceptable tier first. Each is tried
+ * whole and measured; the first that fits wins, and the title card below cannot
+ * exceed the budget, so this always terminates with something.
+ */
+const TIERS: Array<{ rows: number; cols: number }> = [
+ { rows: 16, cols: 8 },
+ { rows: 10, cols: 6 },
+ { rows: 6, cols: 4 },
+]
+
+/**
+ * Recalculate formula columns only up to here.
+ *
+ * `recalc` (formula.ts) materializes EVERY column as a full Vec and computes
+ * every formula column over every row — the right thing for a grid that is
+ * about to paint, and absurd for the fourteen rows a thumbnail shows. A save
+ * must never stall on its own decoration, so past this the formula columns draw
+ * empty with an `fx` chip instead. 5,000 rows is ~2ms and covers the workbooks
+ * people actually eyeball in a file manager.
+ */
+const RECALC_ROWS = 5_000
+
+/** Totals are computed over the WHOLE column or not at all — see (2) above. */
+const TOTALS_SCAN_ROWS = 100_000
+
+/** Longest cell text kept. CSS clips the overflow anyway; this is about bytes.
+ * Column names get their own, larger cap for the same reason: nothing in the
+ * format bounds a name, and eight of them are drawn at every tier. */
+const CELL_CHARS = 40
+const NAME_CHARS = 60
+
+const cap = (s: string, n: number): string => (s.length > n ? `${s.slice(0, n - 1)}…` : s)
+
+/** The design width the whole preview is scaled from, clamped either side so a
+ * two-column sheet is not blown up to billboard size nor a wide one shrunk to
+ * a grey texture. */
+const MIN_W = 720
+const MAX_W = 1600
+
+const GUTTER_W = 44
+const ROW_H = 34
+/** The collapsed table border that lives outside the column widths. */
+const EDGE = 2
+
+/**
+ * Fallbacks matching styles.css. A document's `theme` is optional (model.ts),
+ * and a workbook that never set one must still thumbnail like the app.
+ */
+const INK = '#1e2a3a'
+const MUTED = '#64748b'
+const LINE = '#e3e8ef'
+const PANEL = '#f8fafc'
+const ACCENT = '#f7a600'
+const PAPER = '#ffffff'
+
+const esc = (s: string): string =>
+ s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+ .replace(/"/g, '&quot;').replace(/'/g, '&#39;')
+
+/**
+ * A colour string safe to paste into a stylesheet, or the fallback.
+ *
+ * ESCAPING HTML DOES NOT COVER THIS. `esc()` protects markup; a value landing
+ * inside a `<style>` block or a `style=""` attribute is in CSS, where `}` and
+ * `;` are the dangerous characters and `<` is not. `theme.accent` is ordinary
+ * author data — an agent writes it through `window.bento`, an import could
+ * carry it — so `#fff}body{display:none` is a preview that blanks the page it
+ * is embedded in, and `url(https://…)` is a preview that phones home from a
+ * file the reader believed was self-contained (PLATFORM §1).
+ *
+ * So: an allowlist of the characters colour notations actually use, with no
+ * `url(`, and a length cap. Anything else falls back rather than being
+ * "cleaned" — a colour we do not recognise is not worth guessing at.
+ */
+export function cssColor(v: unknown, fallback: string): string {
+ if (typeof v !== 'string') return fallback
+ const s = v.trim()
+ if (!s || s.length > 32) return fallback
+ if (!/^[#a-zA-Z0-9(),.%\s/-]+$/.test(s)) return fallback
+ if (/url|expression|@|\\/i.test(s)) return fallback
+ return s
+}
+
+// --- reading the sheet -------------------------------------------------------
+
+const rowsOf = (sheet: TableSheet): number =>
+ sheet.rids.reduce((n, [, c]) => n + c, 0)
+
+/**
+ * A column width safe to put in a stylesheet.
+ *
+ * `Column.w` is `number` in the type and ANY value in a file — the format is
+ * additive and hand-edited (model.ts), and `[extra: string]: unknown` means
+ * nothing validates it. A NaN reaches the frame's `scale(calc(100vw / NaNpx))`
+ * and takes the whole preview down with it, silently, in every saved file.
+ */
+const colW = (c: Column): number =>
+ typeof c.w === 'number' && Number.isFinite(c.w) ? Math.min(600, Math.max(40, Math.round(c.w))) : 130
+
+/**
+ * The first `n` rids in canonical order.
+ *
+ * CANONICAL, never the grid's order vector: sorting and filtering are VIEW
+ * state that never enters the document (store.ts `view()`), so the file cannot
+ * know about them and a second reader of the same file would thumbnail
+ * differently. Stops as soon as it has enough — a 250k-row sheet must not be
+ * expanded to draw sixteen rows.
+ */
+function firstRids(sheet: TableSheet, n: number): number[] {
+ const out: number[] = []
+ for (const [start, count] of sheet.rids) {
+ for (let i = 0; i < count && out.length < n; i++) out.push(start + i)
+ if (out.length >= n) break
+ }
+ return out
+}
+
+/** Formula columns, computed, when that is cheap enough to be free. Never
+ * throws: a preview is a nicety and a broken expression is not its business. */
+function computeFormulas(sheet: TableSheet): Map<string, Vec> | null {
+ if (!sheet.columns.some((c) => c.formula)) return null
+ if (rowsOf(sheet) > RECALC_ROWS) return null
+ try {
+ return recalc(sheet).values
+ } catch {
+ return null
+ }
+}
+
+/**
+ * One cell, in the grid's own precedence order (grid.ts `valueAt`): a computed
+ * column beats a hand override, which beats the stored value. Per-cell formulas
+ * (`cells["<col>:<rid>"].f`) are deliberately NOT evaluated — they need the
+ * whole cell-formula graph, and an unevaluated one draws blank, which is the
+ * honest answer under rule (1).
+ */
+function cellValue(
+ sheet: TableSheet, col: Column, rid: number, row: number, computed: Map<string, Vec> | null,
+): unknown {
+ const comp = computed?.get(col.id)
+ if (comp) return comp[row] ?? null
+ const over = sheet.cells?.[`${col.id}:${rid}`]
+ if (over && 'v' in over) return over.v
+ return readCell(sheet.data[col.id], row)
+}
+
+/** Display text for a value, bounded in length. */
+function text(v: unknown, col: Pick<Column, 'type' | 'format'>): string {
+ if (v == null || v === '') return ''
+ if (isErr(v)) return v.code
+ return cap(formatValue(v, col), CELL_CHARS)
+}
+
+const AGG_LABEL: Record<string, string> = {
+ sum: 'SUM', avg: 'AVG', count: 'COUNT', min: 'MIN', max: 'MAX',
+}
+
+/**
+ * The totals row, or null.
+ *
+ * Scans the WHOLE column — see rule (2). A custom `{f}` total is a formula we
+ * are not evaluating here, so it shows its label and no number rather than a
+ * number that might be wrong.
+ */
+function totalsRow(
+ sheet: TableSheet, columns: Column[], computed: Map<string, Vec> | null,
+): Array<{ label: string; value: string }> | null {
+ const totals = sheet.totals
+ if (!totals) return null
+ const n = rowsOf(sheet)
+ if (n > TOTALS_SCAN_ROWS) return null
+
+ return columns.map((col) => {
+ const spec = totals[col.id]
+ if (!spec) return { label: '', value: '' }
+ if (typeof spec !== 'string') return { label: 'ƒ', value: '' }
+ const comp = computed?.get(col.id)
+ const data = sheet.data[col.id]
+ let sum = 0, count = 0, min = Infinity, max = -Infinity
+ for (let r = 0; r < n; r++) {
+ const raw = comp ? comp[r] : readCell(data, r)
+ if (raw == null || raw === '' || isErr(raw)) continue
+ const num = typeof raw === 'number' ? raw : Number(raw)
+ if (!Number.isFinite(num)) { count++; continue }
+ sum += num; count++
+ if (num < min) min = num
+ if (num > max) max = num
+ }
+ const value = spec === 'count' ? String(count)
+ : count === 0 ? ''
+ : spec === 'sum' ? formatValue(sum, col)
+ : spec === 'avg' ? formatValue(sum / count, col)
+ : spec === 'min' ? formatValue(min, col)
+ : spec === 'max' ? formatValue(max, col)
+ : ''
+ return { label: AGG_LABEL[spec] ?? spec.toUpperCase(), value }
+ })
+}
+
+// --- drawing -----------------------------------------------------------------
+
+interface Palette {
+ ink: string; muted: string; line: string; panel: string; accent: string; paper: string
+}
+
+const paletteOf = (doc: DashDoc): Palette => ({
+ ink: cssColor(doc.theme?.color, INK),
+ muted: MUTED,
+ line: LINE,
+ panel: PANEL,
+ accent: cssColor(doc.theme?.accent, ACCENT),
+ paper: cssColor(doc.theme?.background, PAPER),
+})
+
+/**
+ * The one stylesheet, scoped to `.dxp`.
+ *
+ * A `<style>` inside the preview is document-global for the audience that sees
+ * it — a thumbnailer runs no script, so nothing removes it — which is the same
+ * leak render.ts's `scopeCss` exists for on svg elements. Every selector is
+ * therefore prefixed, and every class name carries the `dxp-` prefix so it can
+ * collide with nothing the app or another Bento app paints.
+ */
+const sheetCss = (p: Palette): string =>
+ // The app's `* { box-sizing: border-box }` (styles.css) is in the compressed
+ // payload, which this audience never inflates — so the preview restates it
+ // for its own subtree. Not cosmetic: `table-layout:fixed` honours the
+ // colgroup widths, and without border-box each cell's 16px of padding and 1px
+ // of border are added OUTSIDE them, so the table renders wider than the width
+ // the frame was scaled from and the right-hand column is sliced off. Measured
+ // in Chrome at 914px: the last column lost its type chip.
+ `.dxp *{box-sizing:border-box}` +
+ `.dxp{position:fixed;left:0;top:0;width:100%;height:100%;z-index:2147483000;` +
+ `overflow:hidden;background:${p.paper};` +
+ `font:14px/1.45 -apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Helvetica,Arial,sans-serif;` +
+ `color:${p.ink};-webkit-font-smoothing:antialiased}` +
+ `.dxp-bar{display:flex;align-items:baseline;gap:10px;padding:14px 16px 12px;` +
+ `border-bottom:1px solid ${p.line};background:${p.panel}}` +
+ `.dxp-rule{width:34px;height:5px;border-radius:3px;background:${p.accent}}` +
+ `.dxp-title{font-weight:700;font-size:19px;white-space:nowrap;overflow:hidden}` +
+ `.dxp-sheet{color:${p.muted};font-size:13px;white-space:nowrap;overflow:hidden}` +
+ `.dxp-count{margin-left:auto;color:${p.muted};font-size:12px;white-space:nowrap}` +
+ `.dxp-t{border-collapse:collapse;table-layout:fixed;width:100%;` +
+ `font-variant-numeric:tabular-nums}` +
+ `.dxp-t td,.dxp-t th{height:${ROW_H}px;padding:0 8px;border-right:1px solid ${p.line};` +
+ `border-bottom:1px solid ${p.line};overflow:hidden;white-space:nowrap;text-align:left;` +
+ `font-weight:400}` +
+ `.dxp-t th{background:${p.panel};font-weight:600;border-bottom:1px solid ${p.line}}` +
+ `.dxp-g{width:${GUTTER_W}px;background:${p.panel};color:${p.muted};text-align:center;` +
+ `font-size:12px}` +
+ `.dxp-t tr:nth-child(even) td{background:#fcfdfe}` +
+ `.dxp-t tr:nth-child(even) td.dxp-g{background:${p.panel}}` +
+ `.dxp-r{text-align:right}` +
+ `.dxp-type{font-size:10px;letter-spacing:.04em;text-transform:uppercase;color:${p.muted};` +
+ `border:1px solid ${p.line};border-radius:5px;padding:0 4px;margin-left:6px;background:${p.paper}}` +
+ `.dxp-fx{font-size:9px;font-weight:600;color:${p.accent};border:1px solid ${p.accent};` +
+ `border-radius:4px;padding:0 3px;margin-left:6px}` +
+ `.dxp-tot td{background:${p.panel};font-weight:600;border-top:1px solid ${p.line}}` +
+ `.dxp-agg{color:${p.muted};font-weight:400;font-size:11px;margin-right:6px}` +
+ `.dxp-card{padding:64px 16px;text-align:center;color:${p.muted}}` +
+ `.dxp-card b{display:block;font-size:34px;color:${p.ink};margin:14px 0 6px}`
+
+/**
+ * The fixed overlay + the width-fitting wrapper. `w` is the table's own width,
+ * so the grid always fills the thumbnail regardless of the viewport it is
+ * rendered into.
+ */
+function frame(inner: string, p: Palette, w: number): string {
+ // BUILT BY CONCATENATION, never as a literal `<style>` in the source. The
+ // same rule save.ts follows for `</script>`, and for the same reason: this
+ // string ends up inside the JS bundle, and postbuild-compress.mjs finds the
+ // app stylesheet by scanning the built HTML for the first big `<style>`. A
+ // literal one here is matched FIRST — the whole runtime CSS was then left
+ // uncompressed and unregistered, and the app booted completely unstyled.
+ const OPEN = `<${'style'}>`
+ const CLOSE = `</${'style'}>`
+ return `<div class="dxp">${OPEN}${sheetCss(p)}${CLOSE}` +
+ // Two `transform` declarations on purpose: a renderer that rejects CSS
+ // Values 4 length division keeps the first and shows the table at 1:1.
+ `<div style="width:${w}px;transform-origin:0 0;transform:none;` +
+ `transform:scale(calc(100vw / ${w}px))">${inner}</div></div>`
+}
+
+const headline = (doc: DashDoc, sheet: Sheet, note: string): string =>
+ `<div class="dxp-bar"><span class="dxp-rule"></span>` +
+ `<span class="dxp-title">${esc(doc.title || 'Untitled workbook')}</span>` +
+ `<span class="dxp-sheet">${esc(sheet.name || '')}</span>` +
+ `<span class="dxp-count">${esc(note)}</span></div>`
+
+const nf = (n: number): string => n.toLocaleString('en-US')
+
+/** A table sheet, at one tier. */
+function tableMarkup(
+ doc: DashDoc, sheet: TableSheet, tier: { rows: number; cols: number }, p: Palette,
+): string {
+ const hidden = hiddenSet(sheet)
+ const all = sheet.columns.filter((c) => !hidden.has(c.id))
+ const columns = all.slice(0, tier.cols)
+ const total = rowsOf(sheet)
+ const rids = firstRids(sheet, tier.rows)
+ const computed = computeFormulas(sheet)
+
+ // +EDGE for the collapsed outer border: measured at 914px the table's own
+ // scrollWidth was 915, so the scale was computed from a width one pixel
+ // narrower than the thing being scaled and the last column lost a hairline.
+ const width = Math.min(MAX_W, Math.max(MIN_W,
+ GUTTER_W + EDGE + columns.reduce((n, c) => n + colW(c), 0)))
+
+ const cols = `<colgroup><col style="width:${GUTTER_W}px">` +
+ columns.map((c) => `<col style="width:${colW(c)}px">`).join('') +
+ '</colgroup>'
+
+ const head = `<tr><th class="dxp-g"></th>` + columns.map((c) =>
+ `<th>${esc(cap(c.name || c.id, NAME_CHARS))}` +
+ `<span class="dxp-type">${esc(TYPE_LABEL[c.type as ColumnType] ?? String(c.type))}</span>` +
+ // The fx chip is not decoration: it is what makes an empty computed cell
+ // read as "derived", not as "blank" (rule 1).
+ (c.formula ? `<span class="dxp-fx">fx</span>` : '') +
+ `</th>`).join('') + '</tr>'
+
+ const body = rids.map((rid, i) =>
+ `<tr><td class="dxp-g">${i + 1}</td>` + columns.map((c) => {
+ const v = cellValue(sheet, c, rid, i, computed)
+ const cls = alignFor(c.type) === 'right' ? ' class="dxp-r"' : ''
+ return `<td${cls}>${esc(text(v, c))}</td>`
+ }).join('') + '</tr>').join('')
+
+ const totals = totalsRow(sheet, columns, computed)
+ const foot = totals && totals.some((t) => t.label || t.value)
+ ? `<tr class="dxp-tot"><td class="dxp-g"></td>` + totals.map((t, i) => {
+ const cls = alignFor(columns[i].type) === 'right' ? ' class="dxp-r"' : ''
+ return `<td${cls}>${t.label ? `<span class="dxp-agg">${esc(t.label)}</span>` : ''}` +
+ `${esc(t.value)}</td>`
+ }).join('') + '</tr>'
+ : ''
+
+ const more = all.length > columns.length ? ` · +${all.length - columns.length} more` : ''
+ const note = `${nf(total)} row${total === 1 ? '' : 's'} × ${nf(all.length)} column${all.length === 1 ? '' : 's'}${more}`
+
+ return frame(
+ headline(doc, sheet, note) + `<table class="dxp-t">${cols}${head}${body}${foot}</table>`,
+ p, width,
+ )
+}
+
+/**
+ * A canvas sheet — the sparse A1 map. Drawn with letter and number headers,
+ * because that IS what a canvas sheet looks like and it is how a reader tells
+ * one apart from a table sheet at thumbnail size.
+ */
+function canvasMarkup(
+ doc: DashDoc, sheet: CanvasSheet, tier: { rows: number; cols: number }, p: Palette,
+): string {
+ const keys = Object.keys(sheet.cells ?? {})
+ // The used range, from the keys themselves: a canvas sheet has no row count
+ // to read, and parsing is cheaper than being wrong about where it starts.
+ let maxRow = 1, maxCol = 1
+ for (const k of keys) {
+ const m = /^\$?([A-Za-z]+)\$?(\d+)$/.exec(k)
+ if (!m) continue
+ let c = 0
+ for (const ch of m[1].toUpperCase()) c = c * 26 + (ch.charCodeAt(0) - 64)
+ maxCol = Math.max(maxCol, c)
+ maxRow = Math.max(maxRow, Number(m[2]))
+ }
+ const nc = Math.min(tier.cols, Math.max(1, maxCol))
+ const nr = Math.min(tier.rows, Math.max(1, maxRow))
+ const width = Math.min(MAX_W, Math.max(MIN_W, GUTTER_W + EDGE + nc * 130))
+
+ const head = `<tr><th class="dxp-g"></th>` +
+ Array.from({ length: nc }, (_, c) => `<th class="dxp-g">${colToLetters(c)}</th>`).join('') + '</tr>'
+
+ const body = Array.from({ length: nr }, (_, r) =>
+ `<tr><td class="dxp-g">${r + 1}</td>` + Array.from({ length: nc }, (_, c) => {
+ const cell = sheet.cells?.[`${colToLetters(c)}${r + 1}`]
+ // `f` with no `v` is a formula whose value lives nowhere in the file:
+ // blank, never a guess (rule 1).
+ const v = cell && 'v' in cell ? cell.v : null
+ const numeric = typeof v === 'number'
+ return `<td${numeric ? ' class="dxp-r"' : ''}>` +
+ esc(text(v, { type: numeric ? 'number' : 'text', format: cell?.format })) + '</td>'
+ }).join('') + '</tr>').join('')
+
+ const note = `${nf(keys.length)} cell${keys.length === 1 ? '' : 's'}`
+ return frame(
+ headline(doc, sheet, note) +
+ `<table class="dxp-t"><colgroup><col style="width:${GUTTER_W}px">` +
+ Array.from({ length: nc }, () => '<col style="width:130px">').join('') +
+ `</colgroup>${head}${body}</table>`,
+ p, width,
+ )
+}
+
+/** Last resort: the workbook's identity in its own colours, a few hundred bytes.
+ * Bounded by construction — the title is capped — so this can never overrun. */
+function cardMarkup(doc: DashDoc, p: Palette): string {
+ const sheets = doc.sheets?.length ?? 0
+ const rows = (doc.sheets ?? []).reduce(
+ (n, s) => n + (s.kind === 'table' ? rowsOf(s) : 0), 0)
+ const title = (doc.title || 'Untitled workbook').slice(0, 80)
+ return frame(
+ `<div class="dxp-card"><span class="dxp-rule" style="margin:0 auto"></span>` +
+ `<b>${esc(title)}</b>` +
+ `${esc(`${nf(sheets)} sheet${sheets === 1 ? '' : 's'} · ${nf(rows)} row${rows === 1 ? '' : 's'}`)}` +
+ `</div>`, p, MIN_W)
+}
+
+// --- the provider ------------------------------------------------------------
+
+/**
+ * The preview markup for this workbook, or null for "no preview".
+ *
+ * Pure: no DOM, no side effects, bytes measured on exactly what reaches the
+ * file. `scripts/test-dash-preview.ts` drives this directly.
+ *
+ * THE ENCRYPTION CHECK HERE IS BELT AND BRACES, not the gate. The kernel's
+ * `previewAllowed` is the real one and it has two signals — the in-memory
+ * password flag AND the re-parsed `bento/enc` body — of which a provider can
+ * only ever see the first, because it is handed a document and never the block
+ * that will be written. It is repeated anyway because the cost is one function
+ * call and the failure is publishing the first sheet of every password-
+ * protected workbook: rows of real numbers, in plaintext, beside the ciphertext
+ * that exists to hide them. A missing thumbnail is the correct price of a
+ * password.
+ */
+export function previewMarkup(doc: DashDoc): string | null {
+ if (isEncryptionActive()) return null
+ const sheet = doc.sheets?.[0]
+ if (!sheet) return null
+ const p = paletteOf(doc)
+
+ for (const tier of TIERS) {
+ const html = sheet.kind === 'canvas'
+ ? canvasMarkup(doc, sheet, tier, p)
+ : tableMarkup(doc, sheet as TableSheet, tier, p)
+ if (byteLength(html) <= PREVIEW_BUDGET) return html
+ }
+ return cardMarkup(doc, p)
+}
+
+export const byteLength = (s: string): number => new TextEncoder().encode(s).length
+
+/**
+ * Build the static preview of the workbook's first sheet. Registered with the
+ * kernel from main.ts (`registerPreview`).
+ *
+ * The kernel imports this node into the shell clone, checks it with
+ * `previewIsSafe` and writes it followed IMMEDIATELY by a parser-blocking
+ * remover script — so a reader with scripting never paints a frame containing
+ * it, and a thumbnailer, which runs no script, keeps it. Nothing here enters
+ * `#bento-doc`: the preview is shell furniture, and a file saved by a build
+ * without one opens identically.
+ */
+const isDashDoc = (d: unknown): d is DashDoc =>
+ typeof d === 'object' && d !== null
+ && (d as { format?: unknown }).format === FORMAT
+ && Array.isArray((d as { sheets?: unknown }).sheets)
+
+export function buildSheetPreview(doc: unknown): HTMLElement | null {
+ // The kernel types this as `KernelDoc` and can hand over anything a future
+ // build embeds. DECLINE rather than cast: this runs inside serialization, so
+ // a throw here does not fail the thumbnail, it fails the SAVE.
+ if (!isDashDoc(doc)) return null
+ const html = previewMarkup(doc)
+ if (!html) return null
+ const host = document.createElement('div')
+ // innerHTML on a detached div, so the string above is what the file carries.
+ // The kernel re-checks the result with previewIsSafe; this is not the gate.
+ host.innerHTML = html
+ return (host.firstElementChild as HTMLElement | null) ?? null
+}
diff --git a/dash/src/rowcol.ts b/dash/src/rowcol.ts
new file mode 100644
index 00000000..00d3b1de
--- /dev/null
+++ b/dash/src/rowcol.ts
@@ -0,0 +1,617 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Row and column STRUCTURE: insert, delete, move, resize, freeze, hide.
+//
+// EVERY FUNCTION HERE IS A PATCH FACTORY. It reads a sheet and returns what the
+// store should commit — it never writes. That is not tidiness: the same Patch
+// objects are the undo entries, the future CRDT ops and the agent API
+// (store.ts:26-29), so a structural edit that mutated the document directly
+// would be an edit with no inverse, no op and no way to undo it. The one
+// function that writes is `applySheetProps`, and it is a store CASE BODY rather
+// than a helper — it says so where it is declared.
+//
+// A RID IS NEVER REUSED. Row ids are what overrides (`cells["<colId>:<rid>"]`),
+// notes and — soon — CRDT node identity attach to, so handing a fresh row the
+// number of a deleted one resurrects the deleted row's corrections onto data
+// that has nothing to do with them. That is a wrong number wearing a right
+// number's clothes, which is the failure class this app exists to refuse. The
+// same reasoning runs down the COLUMN axis and is sharper there, because column
+// ids are not random: import mints them by slugging the header (import.ts:270),
+// so re-importing a CSV after deleting a column produces the SAME id — and any
+// override left behind by that delete lands on the fresh column silently. So a
+// delete here takes its overrides with it, in the same commit, so undo restores
+// both.
+//
+// BOUNDS CLAMP, IDENTITY REFUSES. A drag can legitimately run past the end of
+// the sheet, so positions, counts and widths are clamped rather than thrown —
+// an exception mid-gesture is a broken UI. A duplicate column id, a missing
+// column, or column data whose length disagrees with the row count are caller
+// bugs that corrupt the file quietly, so those throw. `applyPatch` takes the
+// same line ("refusing loudly is the point").
+
+import { RID_BLOCK } from './model.ts'
+import type { Column, ColumnData, ColumnType, TableSheet } from './model.ts'
+import type { Patch, Touched } from './store.ts'
+import { formatValue, TYPE_LABEL } from './format.ts'
+
+// --- shared -----------------------------------------------------------------
+
+const rowsOf = (sheet: TableSheet): number => sheet.rids.reduce((n, [, c]) => n + c, 0)
+
+/**
+ * Every rid in row order. The run-length encoding is what makes 4200 rows cost
+ * 20 bytes, but structural edits are far easier to get RIGHT on a flat list and
+ * they are rare (an import, an insert, a delete) rather than per-keystroke —
+ * store.ts expands for the same reason.
+ */
+const ridsInOrder = (sheet: TableSheet): number[] => {
+ const out: number[] = []
+ for (const [start, count] of sheet.rids) for (let i = 0; i < count; i++) out.push(start + i)
+ return out
+}
+
+// An override key is "<colId>:<rid>", split at the FIRST colon — the same split
+// applyPatch uses, so a colon in a column id cannot make these two disagree.
+const colOfKey = (k: string): string => {
+ const i = k.indexOf(':')
+ return i < 0 ? k : k.slice(0, i)
+}
+const ridOfKey = (k: string): number => {
+ const i = k.indexOf(':')
+ return i < 0 ? NaN : Number(k.slice(i + 1))
+}
+
+const clamp = (v: number, lo: number, hi: number): number =>
+ !Number.isFinite(v) ? lo : v < lo ? lo : v > hi ? hi : v
+
+const clampInt = (v: number, lo: number, hi: number): number => Math.floor(clamp(v, lo, hi))
+
+/**
+ * `pack` is an opaque archive encoding, and applyPatch's row splices skip it
+ * (store.ts:263-270 handles `raw` and `dict` only). A row inserted into a sheet
+ * holding a packed column therefore shifts every OTHER column by one against
+ * it: every value below the insert reads off the wrong row, invisibly, forever.
+ * So this refuses at mint time. The call site promotes to `raw` first, which is
+ * the policy `writeCell` already states for single-cell writes.
+ */
+function refusePacked(sheet: TableSheet, doing: string): void {
+ for (const [id, d] of Object.entries(sheet.data)) {
+ if (d.enc === 'pack') {
+ throw new Error(
+ `cannot ${doing} sheet "${sheet.id}": column "${id}" is packed — promote it to raw first`,
+ )
+ }
+ }
+}
+
+// --- rows -------------------------------------------------------------------
+
+/**
+ * The next rid this sheet may mint, as a floor over everything the file can
+ * still be shown to have used:
+ *
+ * - the live rows;
+ * - every rid still NAMED by an override, even if its row is gone. A row
+ * deleted by a raw `deleteRows` patch (or by an older build) leaves its
+ * `cells` entries behind, and that orphan is exactly the override a reused
+ * rid would resurrect. Reading it is what makes reuse safe rather than
+ * merely unlikely;
+ * - an explicit `nextRid` stamp, if the document carries one.
+ *
+ * `deleteRowsAt` clears the overrides it orphans, so after a delete through
+ * this module there is nothing left to resurrect and the numbers may be minted
+ * again without harm. That is a TODAY argument, not a forever one: once row
+ * identity is also a CRDT node key, two replicas must never mint the same rid
+ * for different rows, and the water mark has to be durable. `nextRid` is read
+ * here so that stamping it is a one-line change at the call site the moment a
+ * patch op can write a sheet field — see SetSheetProps below.
+ */
+/**
+ * This replica's rid block while a collaborative session is live, or `null`
+ * when the document is solo.
+ *
+ * Module state rather than a threaded argument because minting happens deep
+ * inside patch construction and the block belongs to the SESSION, not to any
+ * one sheet or edit — the same shape the kernel uses for the encryption
+ * password. `setRidBlock(null)` restores the solo numbering exactly.
+ */
+let ridBlock: { base: number; high: number } | null = null
+
+/**
+ * Point minting at an actor's block. See model.ts's rid-partitioning note.
+ *
+ * `high` is an in-memory high-water mark for THIS session, and it is what stops
+ * a rid being reused after a delete inside the block: the durable
+ * `sheet.nextRid` watermark cannot serve here, because it is a maximum across
+ * every actor's rids and would push this replica straight out of its own block
+ * and into someone else's.
+ *
+ * Across sessions the question does not arise — an actor id is fresh per
+ * session instance, so a reconnecting replica gets a different block and cannot
+ * collide with what it minted before.
+ */
+export function setRidBlock(base: number | null): void {
+ ridBlock = base === null || base <= 1 ? null : { base, high: base - 1 }
+}
+
+function nextRidFloor(sheet: TableSheet): number {
+ const blk = ridBlock
+ if (blk) {
+ // The maximum WITHIN this block. Other replicas' rids live in other blocks
+ // and are irrelevant — taking a global maximum is exactly what would break
+ // the partition.
+ const top = blk.base + RID_BLOCK - 1
+ let hi = blk.high
+ const inBlock = (rid: number) => rid >= blk.base && rid <= top
+ for (const [start, count] of sheet.rids) {
+ const last = start + count - 1
+ if (inBlock(last)) hi = Math.max(hi, last)
+ else if (inBlock(start)) hi = Math.max(hi, start)
+ }
+ for (const k of Object.keys(sheet.cells ?? {})) {
+ const rid = ridOfKey(k)
+ if (Number.isFinite(rid) && inBlock(rid)) hi = Math.max(hi, rid)
+ }
+ blk.high = hi
+ return hi + 1
+ }
+
+ let hi = 0
+ for (const [start, count] of sheet.rids) hi = Math.max(hi, start + count - 1)
+ for (const k of Object.keys(sheet.cells ?? {})) {
+ const rid = ridOfKey(k)
+ if (Number.isFinite(rid)) hi = Math.max(hi, rid)
+ }
+ const stamped = sheet.nextRid
+ if (typeof stamped === 'number' && Number.isFinite(stamped)) hi = Math.max(hi, stamped - 1)
+ return hi + 1
+}
+
+/**
+ * Insert `count` blank rows so the first lands at row position `at`.
+ *
+ * `at` is a DATA position, not a screen row: when a sort is active the grid
+ * reads through `store.order`, and "insert above the row I am looking at" has
+ * to be mapped through that vector by the caller. Inserting at the position the
+ * user is scrolled to would otherwise put the row somewhere else entirely.
+ */
+export function insertRowsAt(sheet: TableSheet, at: number, count: number): Patch[] {
+ const n = Math.floor(count)
+ // Nothing to do returns NOTHING, rather than an empty patch: `commit([])`
+ // still pushes an undo entry, and a ⌘Z that visibly does nothing is a bug
+ // report.
+ if (!(n > 0)) return []
+ refusePacked(sheet, 'insert rows into')
+
+ const pos = clampInt(at, 0, rowsOf(sheet))
+ const first = nextRidFloor(sheet)
+ if (ridBlock) ridBlock.high = Math.max(ridBlock.high, first + n - 1)
+ const rids: number[] = []
+ const ats: number[] = []
+ // Contiguous and ascending, so `at[i]` stays valid as earlier splices land
+ // (applyPatch sorts by position) and the run-length encoding stays one run.
+ for (let i = 0; i < n; i++) { rids.push(first + i); ats.push(pos + i) }
+ return [{ op: 'insertRows', sheet: sheet.id, rids, at: ats }]
+}
+
+/**
+ * Delete `count` rows starting at data position `at`, and every cell override
+ * attached to them.
+ *
+ * The overrides go in the SAME commit, before the rows, so undo (which applies
+ * inverses in reverse) puts the rows back first and then their corrections.
+ * Leaving them behind would keep a deleted row's note, `was` value and author
+ * in the shared file, and would leave a live orphan for a later rid to inherit.
+ */
+export function deleteRowsAt(sheet: TableSheet, at: number, count: number): Patch[] {
+ const rows = rowsOf(sheet)
+ const from = clampInt(at, 0, rows)
+ const n = Math.min(Math.floor(count), rows - from)
+ if (!(n > 0)) return []
+ refusePacked(sheet, 'delete rows from')
+
+ const rids = ridsInOrder(sheet).slice(from, from + n)
+ const doomed = new Set(rids)
+ const keys = Object.keys(sheet.cells ?? {}).filter((k) => doomed.has(ridOfKey(k)))
+
+ const out: Patch[] = []
+ if (keys.length) {
+ out.push({
+ op: 'setOverrides', sheet: sheet.id, keys,
+ v: keys.map(() => undefined),
+ // an apply-then-undo that leaves `"cells": {}` behind is not a round trip
+ dropEmpty: true,
+ })
+ }
+ out.push({ op: 'deleteRows', sheet: sheet.id, rids })
+ return out
+}
+
+// --- columns ----------------------------------------------------------------
+
+const dataLength = (d: ColumnData): number =>
+ d.enc === 'raw' ? d.v.length : d.enc === 'dict' ? d.idx.length : d.n
+
+/**
+ * A column's stored values must be exactly as long as the sheet has rows.
+ *
+ * Short is ordinary — a column added to an existing sheet is blank in the rows
+ * that already exist — so it is padded. Measured, a short `raw` column READS
+ * the same as a padded one inside this build, because `readCell` answers `??
+ * null` past the end and `splice` past the end appends; the length is what
+ * differs, and the length is what leaves the building. The file is the product:
+ * a column with 2 values on a 4-row sheet is malformed to every other reader of
+ * that JSON — an agent, a chart binding, a re-encode to `pack`, whose `n` is
+ * authoritative — and each of them has to guess whether the tail is missing or
+ * blank. Padding here means nothing downstream ever has to guess.
+ *
+ * LONG is refused rather than trimmed. It means the values came from a
+ * different sheet, a different sort or a stale read, and trimming would pick an
+ * arbitrary prefix of someone's data and call it the column.
+ */
+function fitToRows(d: ColumnData, rows: number, colId: string): ColumnData {
+ const len = dataLength(d)
+ if (len === rows) return d
+ if (len > rows) {
+ throw new Error(`column "${colId}" carries ${len} values for a sheet with ${rows} rows`)
+ }
+ if (d.enc === 'pack') {
+ throw new Error(`packed column "${colId}" is ${len} values short; promote it to raw first`)
+ }
+ const pad = Array.from({ length: rows - len }, () => null)
+ // copied, never appended in place — the caller's object is not ours to grow
+ return d.enc === 'raw'
+ ? { enc: 'raw', v: [...d.v, ...pad] }
+ : { enc: 'dict', dict: [...d.dict], idx: [...d.idx, ...pad] }
+}
+
+/**
+ * Insert a column at index `at`.
+ *
+ * The id is refused if the sheet already has it, because `data`, `cells` and
+ * `totals` are all keyed by column id: a duplicate does not collide loudly, it
+ * makes two columns share one set of values and one set of overrides, and the
+ * second one to be edited overwrites the first.
+ */
+export function insertColumn(
+ sheet: TableSheet, at: number, col: Column, data?: ColumnData,
+): Patch[] {
+ if (sheet.columns.some((c) => c.id === col.id)) {
+ throw new Error(`sheet "${sheet.id}" already has a column "${col.id}"`)
+ }
+ // A formula column has no stored values by design (store.ts:83-85): storing
+ // them would let the file carry a number that disagrees with the expression
+ // that is supposed to produce it.
+ if (col.formula && data) {
+ throw new Error(`column "${col.id}" has a formula, so it cannot also carry stored data`)
+ }
+ const pos = clampInt(at, 0, sheet.columns.length)
+ const fitted = data ? fitToRows(data, rowsOf(sheet), col.id) : undefined
+ return [{
+ op: 'addColumn', sheet: sheet.id, column: col, at: pos,
+ ...(fitted ? { data: fitted } : {}),
+ }]
+}
+
+/**
+ * Delete a column, its values AND its cell overrides.
+ *
+ * `removeColumn` alone drops `columns[i]` and `data[colId]` and stops there, so
+ * every `"<colId>:<rid>"` override survives the column that gave them meaning.
+ * They are not merely dead bytes: import derives column ids from the header
+ * text (import.ts:270), so the very next import of the same CSV re-creates the
+ * id — and the ghosts attach to fresh data as hand-made corrections, complete
+ * with an author and a reason. Clearing them here, in the same commit, makes
+ * the delete undoable as a whole.
+ *
+ * KNOWN GAP: `totals[colId]` cannot be cleared, because no patch op reaches
+ * `sheet.totals`. An orphan there is invisible (the grid iterates columns) but
+ * would come back with a re-imported id, so it wants the same treatment once
+ * there is an op that can write it.
+ */
+export function deleteColumn(sheet: TableSheet, colId: string): Patch[] {
+ if (!sheet.columns.some((c) => c.id === colId)) {
+ throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
+ }
+ const keys = Object.keys(sheet.cells ?? {}).filter((k) => colOfKey(k) === colId)
+ const out: Patch[] = []
+ if (keys.length) {
+ out.push({
+ op: 'setOverrides', sheet: sheet.id, keys,
+ v: keys.map(() => undefined), dropEmpty: true,
+ })
+ }
+ out.push({ op: 'removeColumn', sheet: sheet.id, col: colId })
+ return out
+}
+
+/**
+ * Move a column so that it ENDS UP at index `toIndex`.
+ *
+ * The off-by-one lives here. Moving right and moving left are not symmetric if
+ * you think in terms of the original array — remove-then-insert-at-toIndex on
+ * the ORIGINAL indices lands one short when the column came from the left of
+ * the target. Taking the column out FIRST and splicing into the shortened list
+ * makes `toIndex` mean the same thing in both directions: the index the column
+ * occupies when the move is done, which is the only definition a drag can
+ * express.
+ *
+ * The emitted order is always a FULL permutation. `reorderColumns` rebuilds
+ * `sheet.columns` from the ids it is given and filters out what it cannot find
+ * (store.ts:353), so an order that omits a column DELETES it — its data stays
+ * behind orphaned, and undo cannot bring it back, because the inverse is
+ * rebuilt from the columns that survived.
+ */
+export function moveColumn(sheet: TableSheet, colId: string, toIndex: number): Patch[] {
+ const ids = sheet.columns.map((c) => c.id)
+ const from = ids.indexOf(colId)
+ if (from < 0) throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
+ // `splice` clamps its own index, so this is not what makes the move land —
+ // it is what stops `to === from` being compared against NaN or a fraction,
+ // which would emit a patch that reorders nothing.
+ const to = clampInt(toIndex, 0, ids.length - 1)
+ if (to === from) return []
+ // spliced by POSITION, not filtered by id: a frozen document is never id-
+ // repaired (model.ts:470), so duplicate ids exist and a filter would remove
+ // both of them.
+ const order = ids.slice()
+ order.splice(from, 1)
+ order.splice(to, 0, colId)
+ return [{ op: 'reorderColumns', sheet: sheet.id, order }]
+}
+
+/** Below this a column cannot show its own sort arrow; above it, nothing fits beside it. */
+const MIN_W = 56
+const MAX_W = 420
+
+/**
+ * Set a column's rendered width.
+ *
+ * Clamped and rounded rather than validated: this arrives from a live drag, so
+ * a value out of range is normal and an exception is a broken gesture. A
+ * non-finite width from a drag computation is clamped for a sharper reason —
+ * `JSON.stringify(NaN)` is `null`, so it would reach the file as `"w": null`
+ * and the grid would emit `width:nullpx`. Integers keep the JSON small and make
+ * a resize idempotent.
+ */
+export function resizeColumn(sheet: TableSheet, colId: string, w: number): Patch {
+ if (!sheet.columns.some((c) => c.id === colId)) {
+ throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
+ }
+ return {
+ op: 'setColumn', sheet: sheet.id, col: colId,
+ patch: { w: Math.round(clamp(w, MIN_W, MAX_W)) },
+ }
+}
+
+// --- auto-fit ---------------------------------------------------------------
+//
+// THIS IS AN ESTIMATE, and deliberately a pure one. There is no DOM here — the
+// rigs run in node and this file is the half of the app that has to stay
+// testable — so width is counted in characters against a per-type weight
+// instead of measured. The UI may and should refine it with a real measurement
+// (a canvas `measureText` over the visible rows costs nothing at 40 rows); it
+// is one number and nothing downstream depends on how it was arrived at.
+// Weights are biased HIGH by roughly a character, because a column a few pixels
+// too wide looks fine and a column a few pixels too narrow clips a digit — and
+// a clipped digit is a wrong number.
+
+/** px per character at the grid's body size. Digits are wider than lowercase. */
+const CHAR_W: Record<ColumnType, number> = {
+ text: 7.2, enum: 7.2, date: 7.4, bool: 8, number: 8, money: 8, percent: 8,
+}
+/** The header is the name plus the type control, and it must not clip either. */
+const HEAD_CHAR_W = 7.6
+const HEAD_CHROME = 34
+/** left + right cell padding, plus a character of slack */
+const CELL_PAD = 20
+/**
+ * Rows read per column. A full pass over 250k rows to fit one column is a
+ * visible stall, and the sample is spread by STRIDE rather than taken off the
+ * top: a CSV sorted by date or name keeps its longest values at the end, and a
+ * first-N sample gets those columns wrong every time. The last row is always
+ * read, because that is where an appended total or a "grand total" label sits.
+ */
+const SAMPLE = 500
+
+export function autoFitWidth(
+ get: (row: number) => unknown,
+ col: Column,
+ rows: number,
+ opts?: { max?: number },
+): number {
+ // TYPE_LABEL is the English label; a localized one is a few px different and
+ // that is inside the slack this estimate already carries.
+ let widest = col.name.length * HEAD_CHAR_W
+ + (TYPE_LABEL[col.type] ?? String(col.type ?? '')).length * 6.2 + HEAD_CHROME
+ + (col.formula ? 18 : 0) + (col.failed ? 14 : 0)
+
+ const n = Math.max(0, Math.floor(rows))
+ const stride = Math.max(1, Math.ceil(n / SAMPLE))
+ const w = CHAR_W[col.type] ?? CHAR_W.text
+ const measure = (row: number): void => {
+ const v = get(row)
+ if (v == null) return
+ // formatted, not raw: the reader sees "$1,234.50" where the model holds
+ // 1234.5, and it is the rendered string that has to fit
+ const s = formatValue(v, col)
+ const px = s.length * w + CELL_PAD
+ if (px > widest) widest = px
+ }
+ for (let i = 0; i < n; i += stride) measure(i)
+ if (n > 0) measure(n - 1)
+
+ return Math.ceil(clamp(widest, MIN_W, Math.max(MIN_W, opts?.max ?? MAX_W)))
+}
+
+// --- sheet-level state: freeze --------------------------------------------
+//
+// THE ONE OP THIS MODULE NEEDS THAT `Patch` DOES NOT HAVE. Freeze is sheet
+// state — frozen ROWS cannot be expressed as a column field — and `Patch`
+// reaches exactly four places in the document: cell values, cell overrides,
+// column objects and `doc.measures`/`doc.title`. Nothing writes a sheet field.
+//
+// So `setSheetProps` is declared here rather than faked. It is one case in
+// `applyPatch`, whose whole body is `applySheetProps` below:
+//
+// case 'setSheetProps': return applySheetProps(table(doc, p.sheet), p)
+//
+// and one member on the `Patch` union. Until it lands, `SheetPatch` is the
+// honest return type — a union that COLLAPSES to `Patch` the moment store.ts
+// adopts the op, so nothing has to change here or at the call sites. The
+// alternative was casting a foreign op to `Patch`, which compiles and then
+// throws at commit time: an edit the user believes landed.
+
+export interface SetSheetProps {
+ op: 'setSheetProps'
+ sheet: string
+ /** keys to SET */
+ props: Record<string, unknown>
+ /**
+ * keys to DELETE, listed rather than set to `undefined`, because these
+ * objects are also the wire format: `JSON.stringify({frozen: undefined})`
+ * drops the key entirely and the delete would arrive as a no-op.
+ */
+ drop?: string[]
+}
+
+export type SheetPatch = Patch | SetSheetProps
+
+/**
+ * Sheet keys `setSheetProps` refuses. Structure moves through the typed patches
+ * that know how to invert it — a props op that could rewrite `data` or `rids`
+ * would be an unbounded edit carrying an unbounded inverse, and the byte-capped
+ * history exists precisely to prevent that.
+ */
+const STRUCTURAL = new Set(['id', 'kind', 'columns', 'data', 'rids', 'cells', 'steps'])
+
+/**
+ * The store case body for `setSheetProps` — the ONLY function in this file that
+ * writes, and it writes because `applyPatch` does. Returns the inverse, built
+ * from what it displaced, in the shape `applyPatch` returns.
+ */
+export function applySheetProps(
+ sheet: TableSheet, p: SetSheetProps,
+): { inverse: SetSheetProps; touched: Touched } {
+ const s = sheet as unknown as Record<string, unknown>
+ const props: Record<string, unknown> = {}
+ const drop: string[] = []
+ const dropping = new Set(p.drop ?? [])
+
+ const displace = (k: string): void => {
+ if (STRUCTURAL.has(k)) {
+ throw new Error(`setSheetProps may not write "${k}" — structure moves through typed patches`)
+ }
+ // absent, so the inverse must DELETE rather than restore `undefined`:
+ // apply-then-undo has to leave the file byte-identical, and a key holding
+ // undefined is a key the next writer sees
+ if (k in s) props[k] = s[k]
+ else drop.push(k)
+ }
+
+ for (const k of Object.keys(p.props)) {
+ if (dropping.has(k)) throw new Error(`setSheetProps sets and drops "${k}" in one patch`)
+ if (p.props[k] === undefined) {
+ // Deleting has exactly ONE spelling, and it is `drop`. Accepting this as
+ // a delete too would mean the same intent travels two ways, one of which
+ // (`JSON.stringify({k: undefined})`) evaporates on the wire — the delete
+ // would land locally and reach no other replica. Refusing is how that
+ // stays impossible rather than merely discouraged.
+ throw new Error(`setSheetProps: to remove "${k}" list it in \`drop\`, not props`)
+ }
+ displace(k)
+ s[k] = p.props[k]
+ }
+ for (const k of dropping) {
+ displace(k)
+ delete s[k]
+ }
+ return {
+ inverse: { op: 'setSheetProps', sheet: p.sheet, props, ...(drop.length ? { drop } : {}) },
+ touched: { sheet: p.sheet, structural: true },
+ }
+}
+
+export interface Frozen {
+ rows: number
+ cols: number
+}
+
+/**
+ * Read the frozen panes, defensively: this is an additive field, so an older
+ * build, a hand edit or a future one can put anything there and the grid still
+ * has to draw. Anything unreadable means "not frozen", which is the state every
+ * reader can agree on.
+ */
+export function readFrozen(sheet: TableSheet): Frozen {
+ const f = sheet.frozen
+ if (typeof f !== 'object' || f === null || Array.isArray(f)) return { rows: 0, cols: 0 }
+ const o = f as Record<string, unknown>
+ const num = (v: unknown): number =>
+ typeof v === 'number' && Number.isFinite(v) && v > 0 ? Math.floor(v) : 0
+ return { rows: num(o.rows), cols: num(o.cols) }
+}
+
+/**
+ * Freeze `rows` rows and `cols` columns of this sheet.
+ *
+ * Clamped to leave at least one row and one column FREE, which is Excel's rule
+ * and, here, a correctness fix rather than politeness: a pane that freezes
+ * everything leaves nothing to scroll, so a stray `frozen.rows` of 1e9 (a bad
+ * drag, a hand-edited file) would render a grid that cannot move.
+ *
+ * Freezing nothing DROPS the field instead of storing zeroes. An additive field
+ * that means "no" should be absent — otherwise freezing and unfreezing leaves
+ * the file changed, every reader diffs it, and collab ships an op for a
+ * document that is back where it started.
+ */
+export function freezeAt(sheet: TableSheet, rows: number, cols: number): SheetPatch {
+ const r = clampInt(rows, 0, Math.max(0, rowsOf(sheet) - 1))
+ const c = clampInt(cols, 0, Math.max(0, sheet.columns.length - 1))
+ return r === 0 && c === 0
+ ? { op: 'setSheetProps', sheet: sheet.id, props: {}, drop: ['frozen'] }
+ : { op: 'setSheetProps', sheet: sheet.id, props: { frozen: { rows: r, cols: c } } }
+}
+
+// --- hidden columns ---------------------------------------------------------
+//
+// Hiding is DOCUMENT data, not view state, and that is the opposite call from
+// sorting. A sort belongs to the reader (store.ts's `view()`), but hiding a
+// column is an editorial act — the author decided the working column is not
+// part of the story — and two people opening one file have to see the same
+// grid or they are reading different documents. It rides on the COLUMN, where
+// unknown fields survive a round trip (model.ts:90), so a build that has never
+// heard of hiding still preserves it.
+
+export function hiddenSet(sheet: TableSheet): Set<string> {
+ const out = new Set<string>()
+ for (const c of sheet.columns) if (c.hidden === true) out.add(c.id)
+ return out
+}
+
+/**
+ * Show or hide one column.
+ *
+ * Showing writes `undefined`, not `false`: `JSON.stringify` omits an undefined
+ * value, so a column that was hidden and shown again leaves the file exactly as
+ * it found it. `false` would be honest in memory and would accumulate a dead
+ * flag on every column anyone ever touched, in every saved copy, forever.
+ */
+export function setHidden(sheet: TableSheet, colId: string, hidden: boolean): Patch {
+ if (!sheet.columns.some((c) => c.id === colId)) {
+ throw new Error(`no column "${colId}" on sheet "${sheet.id}"`)
+ }
+ // `undefined` is NOT a value JSON can carry: JSON.stringify drops the key,
+ // so `{hidden: undefined}` arrives as `{}` and the un-hide becomes a silent
+ // no-op over any wire — a saved file, a collaboration op, the agent API.
+ // Send `false`. (This file solves the identical hazard for `w` above.)
+ return {
+ op: 'setColumn', sheet: sheet.id, col: colId,
+ patch: { hidden },
+ }
+}
+
+/** Exposed for the rig, as store.ts does — not part of the app's surface. */
+export const _internals = {
+ nextRidFloor, ridsInOrder, fitToRows, MIN_W, MAX_W, SAMPLE, CHAR_W,
+}
diff --git a/dash/src/saveui.css b/dash/src/saveui.css
new file mode 100644
index 00000000..1d5d2de8
--- /dev/null
+++ b/dash/src/saveui.css
@@ -0,0 +1,91 @@
+/* SPDX-License-Identifier: MIT
+ Copyright (c) 2026 The Bento authors
+ The Save split button and its menu. Prefixed `dxs-` so it can be dropped in
+ beside styles.css without either file having to know about the other.
+
+ It knows about styles.css's TOKENS, though, and that is the point: this menu,
+ the top bar's own dropdowns, the right-click popovers and the pivot were each
+ written separately and each chose its own radius and shadow. They are one
+ floating-surface style now, spelled --radius-lg / --shadow-pop, and nothing
+ here restates a number that lives there. */
+
+.dxs-wrap { position: relative; display: inline-flex; align-items: stretch; }
+
+/* The caret sits FLUSH against the Save button so the pair reads as one
+ control. It is its own button rather than a click zone inside Save, because a
+ miss on a split control that saves is a save to the wrong file. */
+.dxs-caret {
+ padding: 4px 6px;
+ font-size: 11px;
+ line-height: 1.4;
+ border-left: 0;
+ border-top-left-radius: 0;
+ border-bottom-left-radius: 0;
+ margin-left: -1px;
+}
+/* …and Save loses its right corners to meet it. Without this the pair read as
+ two buttons that happened to touch. */
+.dxs-wrap > .dx-btn:first-child {
+ border-top-right-radius: 0;
+ border-bottom-right-radius: 0;
+}
+.dxs-wrap .dxs-caret { align-self: stretch; }
+
+.dxs-menu {
+ position: absolute;
+ top: calc(100% + 6px);
+ right: 0;
+ z-index: 60;
+ min-width: 260px;
+ /* capped at the viewport: this menu hangs off a button in the right half of
+ the bar, and on a phone a 260px start-anchored panel walks off the screen */
+ max-width: calc(100vw - 16px);
+ padding: 5px;
+ background: var(--surface);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-lg);
+ box-shadow: var(--shadow-pop);
+ display: none;
+}
+.dxs-wrap.dxs-open .dxs-menu { display: block; }
+
+.dxs-item {
+ display: block;
+ width: 100%;
+ text-align: left;
+ padding: 6px 9px;
+ border: 0;
+ border-radius: var(--radius);
+ background: transparent;
+ color: inherit;
+ font: inherit;
+ font-size: var(--fs-ui);
+ cursor: pointer;
+}
+.dxs-item:hover:not(:disabled) { background: var(--hover); }
+.dxs-item:disabled { opacity: 0.45; cursor: default; }
+.dxs-item small {
+ display: block;
+ color: var(--muted);
+ font-size: var(--fs-small);
+ line-height: 1.35;
+ margin-top: 1px;
+}
+.dxs-sep { height: 1px; margin: 4px 6px; background: var(--line); }
+
+/* Toast: the only feedback these actions have. A share export leaves the open
+ file untouched, so without a line of text nothing visibly happened at all. */
+.dxs-toast {
+ position: fixed;
+ left: 50%;
+ bottom: 26px;
+ transform: translateX(-50%);
+ z-index: 200;
+ max-width: min(92vw, 460px);
+ padding: 9px 14px;
+ border-radius: 999px;
+ background: var(--toast-bg);
+ color: var(--toast-ink);
+ font-size: var(--fs-ui);
+ box-shadow: var(--shadow-pop);
+}
diff --git a/dash/src/saveui.ts b/dash/src/saveui.ts
new file mode 100644
index 00000000..19b556e8
--- /dev/null
+++ b/dash/src/saveui.ts
@@ -0,0 +1,251 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The Save split button: save, copy, new workbook, template, read-only copy.
+//
+// WHY A MENU AT ALL. One Save button can only mean "write this file", and a
+// workbook is the document type people fork constantly — a copy before a risky
+// restructure, a blank version of the model to hand to someone else, a frozen
+// snapshot for the board pack. Every one of those was previously "save, then
+// find the file in Finder, then duplicate it, then reopen it", and the last two
+// were not expressible at all.
+//
+// THE THREE RULES THIS FILE EXISTS TO HOLD, all of them learned in slides:
+//
+// 1. A SHARE EXPORT MUST NOT BECOME THE ⌘S TARGET. `writeUpdatedFileAs`
+// only retains the picked File System Access handle when told to
+// (`keepHandle`, kernel/src/save.ts). It used to retain it always, and the
+// consequence was measured and ugly: export a read-only copy, keep
+// working, press ⌘S — and the FULL document overwrites the locked copy you
+// just handed someone. Templates and read-only copies below pass no
+// `keepHandle`. "Save a copy" deliberately does keep it (it goes through
+// `saveFile(doc, true)`, which is the copy purpose): a copy is a file you
+// continue in, an export is a file you hand over.
+// 2. IDENTITY CHANGES IN EXACTLY ONE PLACE. `docId` is minted once and never
+// regenerated (PLATFORM §3); "Save as new workbook" is the only sanctioned
+// exception, and it mints a fresh id AND drops any collaboration
+// credentials in the same breath, so the fork can never rejoin its
+// ancestor's room.
+// 3. AN EXPORT PATH MUST NOT SILENTLY DECRYPT. Every write below goes through
+// `serializeAuto`, which is encryption-aware, so a password-protected
+// workbook exports as a password-protected template. (Slides' template
+// path uses the plain `serializeFile`; that is the older code and it means
+// a template of an encrypted deck ships in cleartext. A password is the
+// author's standing instruction about this content, and an export that
+// quietly countermands it is precisely the leak the preview's encryption
+// veto exists to prevent.)
+//
+// READ-ONLY IS ENFORCED HERE TOO, not merely offered: `adoptOpenedDoc` locks
+// the store when a file arrives carrying `readonly`. A tier you can mint and
+// nobody honours is worse than no tier at all.
+
+import './saveui.css'
+import {
+ saveFile, serializeAuto, writeUpdatedFileAs, canWriteInPlace,
+} from '../../kernel/src/save.ts'
+import { docBytes, docBudget, type DashDoc } from './model.ts'
+import type { Store } from './store.ts'
+import { t } from './i18n.ts'
+
+export interface SaveMenuHost {
+ /** The app's existing Save button — the caret is inserted beside it. */
+ button: HTMLElement
+ store: Store
+ /**
+ * The app's in-place save. Taken rather than reimplemented because it also
+ * owns the dirty flag and the over-budget confirmation; two copies of "what
+ * ⌘S does" is how the button and the keystroke drift apart.
+ */
+ save: () => void | Promise<void>
+}
+
+/** A uuid, with the same fallback shape starter.ts uses for old runtimes. */
+const newDocId = (): string =>
+ typeof crypto !== 'undefined' && crypto.randomUUID
+ ? crypto.randomUUID()
+ : `doc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`
+
+const clone = (doc: DashDoc): DashDoc => JSON.parse(JSON.stringify(doc)) as DashDoc
+
+let toastTimer: number | undefined
+
+export function toast(message: string): void {
+ document.querySelector('.dxs-toast')?.remove()
+ const el = document.createElement('div')
+ el.className = 'dxs-toast'
+ el.textContent = message
+ document.body.appendChild(el)
+ clearTimeout(toastTimer)
+ toastTimer = window.setTimeout(() => el.remove(), 3600)
+}
+
+/**
+ * The over-budget confirmation, in the same words the app's own save uses.
+ *
+ * Not a refusal (model.ts: "dash budgets BYTES with consent, not rows with a
+ * refusal") — the user is told what will actually break in THIS browser and
+ * decides. It is repeated on the export paths because they write a whole file
+ * too: a 30MB workbook exported as a template downloads 30MB just as surely.
+ */
+function confirmBudget(doc: DashDoc): boolean {
+ const bytes = docBytes(doc)
+ if (bytes <= docBudget(canWriteInPlace())) return true
+ const mb = (bytes / 1024 / 1024).toFixed(1)
+ const how = canWriteInPlace()
+ ? t('Saving will take a moment.')
+ : t('This browser has no in-place save, so every save downloads the whole file.')
+ return window.confirm(
+ `${t('This workbook is {mb} MB.').replace('{mb}', mb)} ${how} ${t('Save anyway?')}`)
+}
+
+/**
+ * What a file carrying `template` or `readonly` means at open time.
+ *
+ * Call once at boot, right after the Store is constructed and BEFORE anything
+ * reads `store.readOnly` or writes an autosave snapshot.
+ *
+ * · `template: true` — every open starts a FRESH workbook: the flag is
+ * dropped and a new `docId` minted. Without this a template is just a file
+ * that keeps overwriting itself, and — worse — every copy anyone makes of
+ * it shares one `docId`, which is the key autosave recovery and all future
+ * sync are stored under. model.ts already documents this as the format's
+ * meaning ("`template: true` re-mints docId on every open"); this is where
+ * it becomes true.
+ * · `readonly: true` — a locked copy. The store refuses commits, which is
+ * what actually stops an edit: the grid checks `store.readOnly` on every
+ * write path, and the title field is disabled from the same flag.
+ */
+export function adoptOpenedDoc(doc: DashDoc, store: Store): void {
+ if (doc.template) {
+ delete doc.template
+ doc.docId = newDocId()
+ }
+ if (doc.readonly) store.readOnly = true
+}
+
+/**
+ * Hang the save menu off the app's Save button.
+ *
+ * The Save button keeps its own click handler; this only adds the caret beside
+ * it. That is deliberate — the most-used control in the header is not rewired
+ * to add four occasional ones.
+ */
+export function installSaveMenu(host: SaveMenuHost): void {
+ const { button, store } = host
+
+ const wrap = document.createElement('span')
+ wrap.className = 'dxs-wrap'
+ button.replaceWith(wrap)
+ wrap.appendChild(button)
+
+ const caret = document.createElement('button')
+ caret.className = 'dx-btn dxs-caret'
+ caret.type = 'button'
+ caret.textContent = '▾'
+ caret.title = t('Save as… — copy, new workbook, template, read-only')
+ caret.setAttribute('aria-label', caret.title)
+
+ const menu = document.createElement('div')
+ menu.className = 'dxs-menu'
+ wrap.append(caret, menu)
+
+ const close = () => wrap.classList.remove('dxs-open')
+ caret.addEventListener('click', () => {
+ const opening = !wrap.classList.contains('dxs-open')
+ wrap.classList.toggle('dxs-open', opening)
+ // Rebuilt on every open because it reflects live state — a read-only file
+ // offers nothing, and the labels name the file we would actually write.
+ if (opening) build()
+ })
+ document.addEventListener('pointerdown', (ev) => {
+ if (!wrap.contains(ev.target as Node)) close()
+ })
+ document.addEventListener('keydown', (ev) => {
+ if (ev.key === 'Escape') close()
+ })
+
+ const item = (label: string, why: string, run: () => void | Promise<void>) => {
+ const b = document.createElement('button')
+ b.className = 'dxs-item'
+ b.type = 'button'
+ b.appendChild(Object.assign(document.createElement('span'), { textContent: label }))
+ b.appendChild(Object.assign(document.createElement('small'), { textContent: why }))
+ if (store.readOnly) {
+ b.disabled = true
+ b.title = t('This workbook is open read-only, so this build will not write it.')
+ } else {
+ b.addEventListener('click', () => { close(); void run() })
+ }
+ menu.appendChild(b)
+ }
+
+ const build = () => {
+ menu.textContent = ''
+
+ item(t('Save'), t('Write this workbook back to its own file.'),
+ () => host.save())
+
+ item(t('Save a copy…'), t('A second file you carry on working in — same workbook, same identity.'),
+ async () => {
+ if (!confirmBudget(store.doc)) return
+ const r = await saveFile(store.doc, true)
+ if (r !== 'cancelled') toast(t('Copy saved'))
+ })
+
+ item(t('Save as new workbook…'), t('A separate workbook — same data, new identity. Nothing links it back to this one.'),
+ async () => {
+ if (!confirmBudget(store.doc)) return
+ const next = clone(store.doc)
+ next.docId = newDocId()
+ // A fork must not inherit a live room: the file IS the capability
+ // (PLATFORM §5), so a copied credential is a copied invitation.
+ delete next.collab
+ store.replaceDoc(next)
+ const r = await saveFile(store.doc, true)
+ toast(r === 'cancelled'
+ ? t('This is now a new workbook — save it under a new name')
+ : t('Saved as a new workbook'))
+ })
+
+ menu.appendChild(Object.assign(document.createElement('div'), { className: 'dxs-sep' }))
+
+ item(t('Save as template…'), t('A starting point: every open of it becomes a fresh workbook of its own.'),
+ async () => {
+ if (!confirmBudget(store.doc)) return
+ const next = clone(store.doc)
+ next.template = true
+ delete next.collab
+ // No docId: `adoptOpenedDoc` mints one per open, which is what makes
+ // each instance a separate workbook rather than N files fighting over
+ // one recovery slot.
+ delete (next as { docId?: string }).docId
+ await writeExport(next, 'template',
+ t('Template saved — every open of it starts a fresh workbook'))
+ })
+
+ item(t('Save read-only copy…'), t('A locked copy for handing out: it opens, it does not edit.'),
+ async () => {
+ if (!confirmBudget(store.doc)) return
+ const next = clone(store.doc)
+ next.readonly = true
+ delete next.collab
+ await writeExport(next, 'viewonly',
+ t('Read-only copy saved — it opens locked'))
+ })
+ }
+
+ build()
+}
+
+/**
+ * Write a share export: a NEW file, chosen by the user, that never becomes the
+ * ⌘S target (rule 1 at the top of this file — no `keepHandle`).
+ */
+async function writeExport(doc: DashDoc, suffix: string, done: string): Promise<void> {
+ try {
+ const ok = await writeUpdatedFileAs(await serializeAuto(doc), doc, { suffix })
+ if (ok) toast(done)
+ } catch (err) {
+ console.error(err)
+ toast(t('Save failed — see console'))
+ }
+}
diff --git a/dash/src/select.ts b/dash/src/select.ts
new file mode 100644
index 00000000..7cd2f0f3
--- /dev/null
+++ b/dash/src/select.ts
@@ -0,0 +1,764 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// Selection, keyboard motion, the clipboard's TSV, and the fill handle.
+//
+// A SELECTION IS DATA. Nothing here touches the DOM: the grid renders what this
+// says, and this never reads what the grid drew. That is what makes every rule
+// below provable in node — which matters more here than anywhere else in the
+// app, because these are the behaviours nobody writes down and everybody
+// notices the instant they are wrong.
+//
+// COORDINATES ARE VISIBLE POSITIONS, not row ids. The grid reads through an
+// order vector (grid.ts: sorting sorts the vector, not the data), so row 3 of a
+// sorted view is not rid 3. A selection that stored rids would silently
+// re-target the moment somebody clicked a column header — the cells stay
+// selected, the highlight jumps. The grid maps position → rid at the edge;
+// everything in here is (row, col) into what the reader can see.
+//
+// THE CURSOR IS NOT THE HEAD, and conflating them is what breaks Tab inside a
+// selected block. A range has an anchor and a head — the end shift+arrow moves
+// — and, SEPARATELY, one active cell where typing lands. Tab inside a block
+// walks the active cell while the block stays perfectly still; if Tab moved the
+// head, the selection would grow by one cell per keystroke.
+//
+// THE TAB RUN is the piece implementations miss. Tab across a row, press Enter,
+// and you must land under the cell the run STARTED in — not under the last one
+// you typed. Without it, entering a table row by row walks diagonally down and
+// to the right, and the grid feels broken in a way people cannot name.
+//
+// A JUMP IS BOUNDED. ⌘↓ runs to the far end of the data BLOCK, and where there
+// is no more data it stops at the last row of the sheet. This grid HAS a last
+// row — that is the point of a columnar sheet over an infinite canvas — so
+// there is no Excel row 1,048,576 to fall into and no way back from.
+//
+// TSV IS NOT CSV, and this is deliberately not import.ts's parser. Clipboard
+// text is the one format every spreadsheet on earth speaks and it has to
+// round-trip EXACTLY. import.ts sniffs a delimiter (wrong here: the delimiter
+// is a tab, always, and a column of "a,b" values must not become two columns)
+// and drops a trailing empty row (right for a file, wrong here: a copied blank
+// cell must paste as a blank and CLEAR what it lands on, and a paste that
+// quietly does nothing is an edit the user believes landed).
+
+// --- Ranges ----------------------------------------------------------------
+
+export interface CellRef { row: number; col: number }
+
+/**
+ * `anchor` is where the drag began and `head` is where it is now; either may be
+ * the smaller. Storing them un-normalised is what lets shift+arrow shrink a
+ * selection back through its anchor instead of flipping it inside out.
+ *
+ * NOTE this shadows the DOM's `Range` inside any module that imports it. That
+ * is the name the whole spreadsheet world uses and renaming it to `CellRange`
+ * would be a worse trade than the shadow.
+ */
+export interface Range { anchor: CellRef; head: CellRef }
+
+export interface Box { top: number; left: number; bottom: number; right: number }
+
+export const normalize = (r: Range): Box => ({
+ top: Math.min(r.anchor.row, r.head.row),
+ left: Math.min(r.anchor.col, r.head.col),
+ bottom: Math.max(r.anchor.row, r.head.row),
+ right: Math.max(r.anchor.col, r.head.col),
+})
+
+export function contains(r: Range, row: number, col: number): boolean {
+ const b = normalize(r)
+ return row >= b.top && row <= b.bottom && col >= b.left && col <= b.right
+}
+
+export function size(r: Range): { rows: number; cols: number } {
+ const b = normalize(r)
+ return { rows: b.bottom - b.top + 1, cols: b.right - b.left + 1 }
+}
+
+/** A range from a box, for callers that think in corners (row/col headers). */
+export const rangeOf = (top: number, left: number, bottom: number, right: number): Range =>
+ ({ anchor: { row: top, col: left }, head: { row: bottom, col: right } })
+
+// --- Keys ------------------------------------------------------------------
+
+/**
+ * What a key MEANS, decided once and away from the DOM.
+ *
+ * Split from what a key DOES so the mapping is testable without a grid and so
+ * the clipboard and history verbs — which are not selection operations at all —
+ * come out of the same switch instead of a second one that drifts from it.
+ */
+export type Action =
+ /** `unit` is the distance: one cell, one screen, or to the edge of the data
+ * block. `dr`/`dc` stay ±1 and the caller multiplies, because only the grid
+ * knows how many rows a page is. */
+ | { kind: 'move'; dr: number; dc: number; unit: 'cell' | 'page' | 'edge'; extend: boolean }
+ | { kind: 'tab'; back: boolean }
+ | { kind: 'enter'; back: boolean }
+ /** `whole` is the ⌘ variant: ⌘Home is the first cell of the sheet, not of the row. */
+ | { kind: 'home'; whole: boolean; extend: boolean }
+ | { kind: 'end'; whole: boolean; extend: boolean }
+ | { kind: 'selectAll' }
+ | { kind: 'selectRow' }
+ | { kind: 'selectCol' }
+ | { kind: 'clear' }
+ | { kind: 'edit' }
+ | { kind: 'cancel' }
+ | { kind: 'copy' }
+ | { kind: 'cut' }
+ | { kind: 'paste' }
+ | { kind: 'undo' }
+ | { kind: 'redo' }
+
+/** Structurally a KeyboardEvent, so a real event passes straight in. */
+export interface KeyLike {
+ key: string
+ shiftKey?: boolean
+ metaKey?: boolean
+ ctrlKey?: boolean
+ altKey?: boolean
+}
+
+const ARROWS: Record<string, [number, number]> = {
+ ArrowUp: [-1, 0], ArrowDown: [1, 0], ArrowLeft: [0, -1], ArrowRight: [0, 1],
+}
+
+/**
+ * The real spreadsheet key set, or null for a key this model does not own.
+ *
+ * NULL IS THE IMPORTANT RETURN. A grid that claims every keystroke swallows the
+ * ones that should start an edit (typing a digit), and one that claims a
+ * modified key it does not implement turns a shortcut into a cursor move.
+ */
+export function keyToAction(e: KeyLike): Action | null {
+ const shift = e.shiftKey === true
+ // ⌘ on a Mac, ctrl everywhere else. Treating them as one is right for every
+ // binding here — there is no combination where they must differ.
+ const cmd = e.metaKey === true || e.ctrlKey === true
+
+ // A modifier we do not own is NOT the unmodified key. Alt+↓ opens the filter
+ // menu in every spreadsheet on earth; reading it as "move down" is how a
+ // shortcut silently becomes a cursor move.
+ if (e.altKey === true) return null
+
+ const arrow = ARROWS[e.key]
+ if (arrow) {
+ return { kind: 'move', dr: arrow[0], dc: arrow[1], unit: cmd ? 'edge' : 'cell', extend: shift }
+ }
+
+ switch (e.key) {
+ case 'Tab': return { kind: 'tab', back: shift }
+ case 'Enter': return { kind: 'enter', back: shift }
+ case 'Home': return { kind: 'home', whole: cmd, extend: shift }
+ case 'End': return { kind: 'end', whole: cmd, extend: shift }
+ case 'PageUp': return { kind: 'move', dr: -1, dc: 0, unit: 'page', extend: shift }
+ case 'PageDown': return { kind: 'move', dr: 1, dc: 0, unit: 'page', extend: shift }
+ case 'Escape': return { kind: 'cancel' }
+ // Mac keyboards send Backspace where a PC sends Delete, and both mean
+ // "empty these cells" in a grid.
+ case 'Delete': case 'Backspace': return { kind: 'clear' }
+ case 'F2': return { kind: 'edit' }
+ // A bare space types a space; only the modified forms select.
+ case ' ': return shift ? { kind: 'selectRow' } : cmd ? { kind: 'selectCol' } : null
+ }
+
+ if (!cmd) return null
+ // Shift changes the KEY, not just the flag: ⌘⇧Z arrives as 'Z'. Comparing
+ // against 'z' without folding case is why redo stops working on the one
+ // shortcut users reach for after an undo they did not mean.
+ switch (e.key.toLowerCase()) {
+ case 'a': return { kind: 'selectAll' }
+ case 'c': return { kind: 'copy' }
+ case 'x': return { kind: 'cut' }
+ case 'v': return { kind: 'paste' }
+ case 'z': return shift ? { kind: 'redo' } : { kind: 'undo' }
+ case 'y': return { kind: 'redo' }
+ }
+ return null
+}
+
+// --- Selection -------------------------------------------------------------
+
+export interface MoveOpts {
+ /** shift held: move the head and leave the anchor and the cursor where they are */
+ extend?: boolean
+ /** ⌘/ctrl held: run to the edge of the data block rather than one cell */
+ jump?: boolean
+ /**
+ * What counts as data, for a jump. Absent, a jump runs to the grid boundary —
+ * the honest degenerate, and a bounded one, because this sheet has a last row.
+ */
+ filled?: (row: number, col: number) => boolean
+}
+
+export class Selection {
+ rows: number
+ cols: number
+ /** the live range: the one shift+arrow extends and ⌘-click replaces */
+ active: Range
+ /** earlier ⌘-clicked ranges, oldest first. The active range is not in here. */
+ extra: Range[]
+ /** the one cell typing lands in — inside the active range, never the head */
+ cursor: CellRef
+
+ /**
+ * Where the current Tab run began, or null when there is no run.
+ *
+ * This is the whole of Enter's "return home" behaviour and it is one field.
+ * Any navigation that is not a Tab or an Enter clears it, because a run is a
+ * sequence of entries and a click or an arrow ends the sequence.
+ */
+ private run: CellRef | null
+
+ constructor(rows: number, cols: number) {
+ this.rows = Math.max(0, rows)
+ this.cols = Math.max(0, cols)
+ this.active = { anchor: { row: 0, col: 0 }, head: { row: 0, col: 0 } }
+ this.extra = []
+ this.cursor = { row: 0, col: 0 }
+ this.run = null
+ }
+
+ /** Rows/columns changed under us (an import, a delete). Nothing may point off the grid. */
+ resize(rows: number, cols: number): this {
+ this.rows = Math.max(0, rows)
+ this.cols = Math.max(0, cols)
+ const fix = (r: Range): Range => ({
+ anchor: this.clamp(r.anchor.row, r.anchor.col),
+ head: this.clamp(r.head.row, r.head.col),
+ })
+ this.active = fix(this.active)
+ this.extra = this.extra.map(fix)
+ this.cursor = this.clamp(this.cursor.row, this.cursor.col)
+ this.run = null
+ return this
+ }
+
+ clamp(row: number, col: number): CellRef {
+ return {
+ row: Math.max(0, Math.min(this.rows - 1, row)),
+ col: Math.max(0, Math.min(this.cols - 1, col)),
+ }
+ }
+
+ /** Every selected range, oldest first, with the active one last. */
+ ranges(): Range[] { return [...this.extra, this.active] }
+
+ /** More than one cell is selected — the test Tab and Enter branch on. */
+ isRange(): boolean {
+ const b = normalize(this.active)
+ return b.top !== b.bottom || b.left !== b.right
+ }
+
+ /** Collapse to one cell. This is a click. */
+ moveTo(row: number, col: number): this {
+ const p = this.clamp(row, col)
+ this.active = { anchor: { ...p }, head: { ...p } }
+ this.extra = []
+ this.cursor = { ...p }
+ this.run = null
+ return this
+ }
+
+ /** Drag or shift+click: the anchor stays, the head goes here. */
+ extendTo(row: number, col: number): this {
+ this.active = { anchor: { ...this.active.anchor }, head: this.clamp(row, col) }
+ // The active cell must stay inside the selection. Shrinking a range back
+ // past the cursor would otherwise leave typing landing outside the
+ // highlight — visible nowhere, wrong everywhere.
+ if (!contains(this.active, this.cursor.row, this.cursor.col)) {
+ this.cursor = { ...this.active.anchor }
+ }
+ this.run = null
+ return this
+ }
+
+ move(dr: number, dc: number, opts: MoveOpts = {}): this {
+ const from = opts.extend ? this.active.head : this.cursor
+ const to = opts.jump
+ ? this.edge(from, dr, dc, opts.filled)
+ : this.clamp(from.row + dr, from.col + dc)
+ return opts.extend ? this.extendTo(to.row, to.col) : this.moveTo(to.row, to.col)
+ }
+
+ extend(dr: number, dc: number): this { return this.move(dr, dc, { extend: true }) }
+
+ /**
+ * Excel's ⌘↓, exactly: three cases, and the third is the one that matters.
+ *
+ * next cell filled → run to the LAST filled cell of that block
+ * next cell blank → skip the blanks and land on the first filled cell
+ * nothing ahead → stop at the sheet's boundary
+ *
+ * The naive version — "walk until blank" — collapses the second case: from a
+ * blank cell it never moves at all, which is the half of the shortcut people
+ * use to get from the end of one block to the start of the next.
+ */
+ private edge(
+ from: CellRef, dr: number, dc: number,
+ filled?: (row: number, col: number) => boolean,
+ ): CellRef {
+ // Stepping a whole grid's worth and clamping IS the far edge, in any
+ // direction, without a second sign-dependent branch to get wrong.
+ const boundary = this.clamp(
+ from.row + dr * Math.max(1, this.rows),
+ from.col + dc * Math.max(1, this.cols),
+ )
+ if (!filled) return boundary
+
+ const inside = (p: CellRef): boolean =>
+ p.row >= 0 && p.row < this.rows && p.col >= 0 && p.col < this.cols
+ const step = (p: CellRef): CellRef => ({ row: p.row + dr, col: p.col + dc })
+
+ let p = step(from)
+ if (!inside(p)) return { ...from }
+
+ if (filled(p.row, p.col)) {
+ for (;;) {
+ const next = step(p)
+ if (!inside(next) || !filled(next.row, next.col)) return p
+ p = next
+ }
+ }
+ while (inside(p)) {
+ if (filled(p.row, p.col)) return p
+ p = step(p)
+ }
+ return boundary
+ }
+
+ /**
+ * Tab.
+ *
+ * With a RANGE selected it walks the active cell inside the block and wraps —
+ * that is how a person fills in a form-shaped selection, and the block must
+ * not move while they do it. With a SINGLE cell it moves plainly and stops at
+ * the last column: there is no range to wrap inside, and teleporting to the
+ * next row's first cell would be a jump the typist did not ask for.
+ */
+ tab(back = false): this {
+ const step = back ? -1 : 1
+ if (this.isRange()) return this.cycle(0, step)
+ // The run starts at the cell Tab was pressed FROM, and survives the move —
+ // moveTo clears it, so it is restored deliberately rather than by accident.
+ const start = this.run ?? { ...this.cursor }
+ const col = this.cursor.col + step
+ if (col >= 0 && col < this.cols) this.moveTo(this.cursor.row, col)
+ this.run = start
+ return this
+ }
+
+ /**
+ * Enter.
+ *
+ * Down one, except that after a Tab run it comes home to the column the run
+ * started in — and the landing cell becomes the new run start, so the next
+ * Tab/Tab/Enter lands under it too. Inside a selected range it cycles the
+ * range instead, wrapping into the next column at the bottom.
+ */
+ enter(back = false): this {
+ const step = back ? -1 : 1
+ if (this.isRange()) return this.cycle(step, 0)
+ if (this.run) {
+ const row = this.run.row + step
+ if (row < 0 || row >= this.rows) return this
+ const home = { row, col: this.run.col }
+ this.moveTo(home.row, home.col)
+ this.run = home
+ return this
+ }
+ const row = this.cursor.row + step
+ if (row >= 0 && row < this.rows) this.moveTo(row, this.cursor.col)
+ return this
+ }
+
+ /**
+ * Walk the active cell inside the active range, wrapping at the edge and
+ * again at the corner. The range itself never moves.
+ *
+ * Only the ACTIVE range cycles. ⌘-clicked extras are left out because
+ * ordering disjoint rectangles is a decision with no obvious right answer,
+ * and guessing it would be worse than not having it.
+ */
+ private cycle(dr: number, dc: number): this {
+ const b = normalize(this.active)
+ let { row, col } = this.cursor
+ if (!contains(this.active, row, col)) { row = b.top; col = b.left }
+ if (dc) {
+ col += dc
+ if (col > b.right) { col = b.left; row = row + 1 > b.bottom ? b.top : row + 1 }
+ else if (col < b.left) { col = b.right; row = row - 1 < b.top ? b.bottom : row - 1 }
+ } else {
+ row += dr
+ if (row > b.bottom) { row = b.top; col = col + 1 > b.right ? b.left : col + 1 }
+ else if (row < b.top) { row = b.bottom; col = col - 1 < b.left ? b.right : col - 1 }
+ }
+ this.cursor = { row, col }
+ this.run = null
+ return this
+ }
+
+ /** ⌘A. The active cell stays put — you selected everything to act on it, not to move. */
+ selectAll(): this {
+ this.active = { anchor: { row: 0, col: 0 }, head: this.clamp(this.rows - 1, this.cols - 1) }
+ this.extra = []
+ this.cursor = this.clamp(this.cursor.row, this.cursor.col)
+ this.run = null
+ return this
+ }
+
+ selectRow(r: number): this {
+ const { row } = this.clamp(r, 0)
+ this.active = { anchor: { row, col: 0 }, head: this.clamp(row, this.cols - 1) }
+ this.extra = []
+ this.cursor = this.clamp(row, this.cursor.col)
+ this.run = null
+ return this
+ }
+
+ selectCol(c: number): this {
+ const { col } = this.clamp(0, c)
+ this.active = { anchor: { row: 0, col }, head: this.clamp(this.rows - 1, col) }
+ this.extra = []
+ this.cursor = this.clamp(this.cursor.row, col)
+ this.run = null
+ return this
+ }
+
+ /**
+ * ⌘-click a second block.
+ *
+ * The NEW range becomes the active one and the old active joins `extra`,
+ * because the range you just drew is the one the next shift+arrow must
+ * extend. Pushing the new one into `extra` instead reads the same on screen
+ * and behaves wrongly the moment a key is pressed.
+ */
+ addRange(r: Range): this {
+ this.extra.push(this.active)
+ this.active = {
+ anchor: this.clamp(r.anchor.row, r.anchor.col),
+ head: this.clamp(r.head.row, r.head.col),
+ }
+ this.cursor = { ...this.active.anchor }
+ this.run = null
+ return this
+ }
+
+ /**
+ * Every selected cell, row-major within each range.
+ *
+ * Deduplication costs a Set the size of the selection, and ⌘A on a 250k-row
+ * sheet is millions of keys — so it is paid ONLY when there is more than one
+ * range, since a single rectangle cannot overlap itself.
+ */
+ *cells(): Generator<CellRef> {
+ const all = this.ranges()
+ const seen = all.length > 1 ? new Set<string>() : null
+ for (const r of all) {
+ const b = normalize(r)
+ for (let row = b.top; row <= b.bottom; row++) {
+ for (let col = b.left; col <= b.right; col++) {
+ if (seen) {
+ const k = `${row}:${col}`
+ if (seen.has(k)) continue
+ seen.add(k)
+ }
+ yield { row, col }
+ }
+ }
+ }
+ }
+
+ /** The bounding box over every range — what a paste or a chart binds to. */
+ bounds(): Box {
+ const boxes = this.ranges().map(normalize)
+ return {
+ top: Math.min(...boxes.map((b) => b.top)),
+ left: Math.min(...boxes.map((b) => b.left)),
+ bottom: Math.max(...boxes.map((b) => b.bottom)),
+ right: Math.max(...boxes.map((b) => b.right)),
+ }
+ }
+}
+
+// --- Driving a selection from an Action ------------------------------------
+
+export interface MotionCtx {
+ /** rows a PageUp/PageDown covers — the grid's visible row count */
+ page?: number
+ filled?: (row: number, col: number) => boolean
+}
+
+/**
+ * Apply the motion half of an Action, and report whether it was consumed.
+ *
+ * FALSE IS A REAL ANSWER: copy, paste, undo and clear are not selection
+ * operations, and this returning true for them would let a caller believe the
+ * selection had handled a paste.
+ */
+export function applyMotion(sel: Selection, a: Action, ctx: MotionCtx = {}): boolean {
+ switch (a.kind) {
+ case 'move': {
+ const k = a.unit === 'page' ? Math.max(1, Math.floor(ctx.page ?? 1)) : 1
+ sel.move(a.dr * k, a.dc * k, {
+ extend: a.extend, jump: a.unit === 'edge', filled: ctx.filled,
+ })
+ return true
+ }
+ case 'tab': sel.tab(a.back); return true
+ case 'enter': sel.enter(a.back); return true
+ case 'home': {
+ const row = a.whole ? 0 : sel.cursor.row
+ if (a.extend) sel.extendTo(row, 0)
+ else sel.moveTo(row, 0)
+ return true
+ }
+ case 'end': {
+ const row = a.whole ? sel.rows - 1 : sel.cursor.row
+ if (a.extend) sel.extendTo(row, sel.cols - 1)
+ else sel.moveTo(row, sel.cols - 1)
+ return true
+ }
+ case 'selectAll': sel.selectAll(); return true
+ case 'selectRow': sel.selectRow(sel.cursor.row); return true
+ case 'selectCol': sel.selectCol(sel.cursor.col); return true
+ default: return false
+ }
+}
+
+// --- The clipboard ---------------------------------------------------------
+
+const NEEDS_QUOTE = /[\t\n\r"]/
+
+const quoteTsv = (v: unknown): string => {
+ const s = v == null ? '' : String(v)
+ return NEEDS_QUOTE.test(s) ? `"${s.replace(/"/g, '""')}"` : s
+}
+
+/**
+ * The selection as clipboard text.
+ *
+ * `get` is a callback rather than a grid because this must serialise DISPLAYED
+ * values — a formula column's computed number, an override's corrected value —
+ * and only the caller knows which layer wins.
+ */
+export function tsvFromRange(get: (row: number, col: number) => unknown, r: Range): string {
+ const b = normalize(r)
+ const lines: string[] = []
+ for (let row = b.top; row <= b.bottom; row++) {
+ const cells: string[] = []
+ for (let col = b.left; col <= b.right; col++) cells.push(quoteTsv(get(row, col)))
+ lines.push(cells.join('\t'))
+ }
+ return lines.join('\n')
+}
+
+/**
+ * Clipboard text back into a grid of strings.
+ *
+ * A quote only OPENS a field at the start of one: Excel writes bare `5" pipe`
+ * unquoted, and treating that quote as an opener eats the rest of the row into
+ * one field. Same rule as import.ts, and it is the rule for the same reason.
+ */
+export function parseTsv(text: string): string[][] {
+ const rows: string[][] = []
+ let row: string[] = []
+ let field = ''
+ let inQ = false
+ let i = 0
+ const push = (): void => { row.push(field); field = '' }
+ const endRow = (): void => { push(); rows.push(row); row = [] }
+
+ while (i < text.length) {
+ const c = text[i]
+ if (inQ) {
+ if (c === '"') {
+ if (text[i + 1] === '"') { field += '"'; i += 2; continue } // doubled = literal
+ inQ = false; i++; continue
+ }
+ // A line break INSIDE a cell is one character, whichever pair of bytes
+ // the source used. Excel writes CRLF; a cell that came back carrying a
+ // stray CR compares unequal to the one that was copied.
+ if (c === '\r') {
+ if (text[i + 1] === '\n') i++
+ field += '\n'; i++; continue
+ }
+ field += c; i++; continue
+ }
+ if (c === '"' && field === '') { inQ = true; i++; continue }
+ if (c === '\t') { push(); i++; continue }
+ if (c === '\r') { if (text[i + 1] === '\n') i++; endRow(); i++; continue }
+ if (c === '\n') { endRow(); i++; continue }
+ field += c; i++
+ }
+
+ // A trailing newline ends the last row rather than starting an empty one —
+ // but EMPTY INPUT is one empty cell, not nothing. A copied blank cell has to
+ // paste as a blank and clear what it lands on; returning [] here makes that
+ // paste a silent no-op, and the old value stays while the user believes it
+ // went.
+ if (field !== '' || row.length || !rows.length) endRow()
+ return rows
+}
+
+// --- The fill handle -------------------------------------------------------
+//
+// `target` is the TOTAL length of the result, seeds included — a drag covers
+// rows 5..20, so the caller asks for 16 and gets 16, with no off-by-one
+// arithmetic at the call site. Asking for fewer than there are seeds truncates.
+
+/** Repeat the seeds until the target is covered. The fill handle's plain drag. */
+export function fillDown(values: unknown[], target: number): unknown[] {
+ if (target <= 0 || !values.length) return []
+ const out: unknown[] = []
+ for (let i = 0; i < target; i++) out.push(values[i % values.length])
+ return out
+}
+
+/**
+ * Continue the seeds as a series where one can be read out of them, and repeat
+ * where one cannot.
+ *
+ * ONE NUMBER IS NOT ONE DATE, deliberately. Dragging a lone `1` gives 1, 1, 1;
+ * a lone `2026-01-01` gives consecutive days and a lone `Q1` gives Q2, Q3. It
+ * reads as inconsistent written down and it is exactly right in the hand — a
+ * lone number is as likely to be a constant as the start of a count, while a
+ * lone date or a numbered label almost never is. Excel and Sheets both make
+ * this distinction, and users have twenty years of muscle memory in it.
+ */
+export function fillSeries(values: unknown[], target: number): unknown[] {
+ if (target <= 0 || !values.length) return []
+ const term = detectSeries(values)
+ if (!term) return fillDown(values, target)
+ const out = values.slice(0, target)
+ for (let i = values.length; i < target; i++) out.push(term(i))
+ return out
+}
+
+/** How many decimals a number is written with — the precision to round back to. */
+function decimals(n: number): number {
+ const s = String(n)
+ const dot = s.indexOf('.')
+ return dot < 0 || s.includes('e') ? 0 : s.length - dot - 1
+}
+
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/
+const TRAILING_NUM = /^(.*?)(\d+)$/
+
+const pad2 = (n: number): string => String(n).padStart(2, '0')
+const iso = (y: number, m: number, d: number): string =>
+ `${String(y).padStart(4, '0')}-${pad2(m)}-${pad2(d)}`
+
+const DAY_MS = 86_400_000
+/** UTC throughout: a local-time Date turns 2026-01-01 into 2025-12-31 west of Greenwich. */
+const dayNumber = (y: number, m: number, d: number): number => Date.UTC(y, m - 1, d) / DAY_MS
+function fromDayNumber(n: number): string {
+ const t = new Date(n * DAY_MS)
+ return iso(t.getUTCFullYear(), t.getUTCMonth() + 1, t.getUTCDate())
+}
+
+/** Month arithmetic clamps: one month after 31 January is 28 February, not 3 March. */
+function addMonths(y: number, m: number, d: number, k: number): string {
+ const t = y * 12 + (m - 1) + k
+ const ny = Math.floor(t / 12)
+ const nm = ((t % 12) + 12) % 12 + 1
+ const last = new Date(Date.UTC(ny, nm, 0)).getUTCDate()
+ return iso(ny, nm, Math.min(d, last))
+}
+
+/** Every gap is the same one, within float slop. */
+function constantStep(xs: number[]): number | null {
+ if (xs.length < 2) return null
+ const d = xs[1] - xs[0]
+ for (let i = 2; i < xs.length; i++) {
+ // Exact equality refuses an obviously arithmetic column: 0.3 - 0.2 and
+ // 0.2 - 0.1 are different doubles, so [0.1, 0.2, 0.3] would fill by
+ // repetition. A relative tolerance is the whole fix.
+ if (Math.abs((xs[i] - xs[i - 1]) - d) > 1e-9 * Math.max(1, Math.abs(d))) return null
+ }
+ return d
+}
+
+/**
+ * A function giving the i-th term (i is a 0-based index into the FILLED range,
+ * so i >= values.length for everything this produces), or null when the seeds
+ * are not a series and the honest answer is to repeat them.
+ */
+function detectSeries(values: unknown[]): ((i: number) => unknown) | null {
+ // --- numbers
+ if (values.every((v) => typeof v === 'number' && Number.isFinite(v))) {
+ const xs = values as number[]
+ const d = constantStep(xs)
+ // A single number, or a flat run, is a CONSTANT until something says
+ // otherwise — filling 5,5,5 with 5,6,7 invents data nobody asked for.
+ if (d === null || d === 0) return null
+ // Precision comes from the SEEDS, never from the step. 0.9 - 0.8 is
+ // 0.09999999999999998 in binary floating point, so decimals(step) reports
+ // 17 and the fill emits "1.000000000000" — a float artefact presented to
+ // the user as significant figures.
+ const dp = Math.min(12, xs.reduce((n, x) => Math.max(n, decimals(x)), 0))
+ const f = 10 ** dp
+ // Multiply rather than accumulate: repeated addition drifts, and the drift
+ // shows up as 0.30000000000000004 in a cell somebody is about to total.
+ return (i) => Math.round((xs[0] + i * d) * f) / f
+ }
+
+ if (!values.every((v) => typeof v === 'string' && v !== '')) return null
+ const ss = values as string[]
+
+ // --- ISO dates: months first, because a month step is not a constant number
+ // of days and the day check would happily "fit" 31 to a January→February pair
+ // and then land on 4 March.
+ const parts: Array<{ y: number; m: number; d: number }> = []
+ for (const s of ss) {
+ const m = ISO_DATE.exec(s)
+ if (!m) { parts.length = 0; break }
+ parts.push({ y: +m[1], m: +m[2], d: +m[3] })
+ }
+ if (parts.length === ss.length) {
+ const first = parts[0]
+ const day0 = dayNumber(first.y, first.m, first.d)
+ if (parts.length === 1) return (i) => fromDayNumber(day0 + i)
+ if (parts.every((p) => p.d === first.d)) {
+ const km = constantStep(parts.map((p) => p.y * 12 + p.m))
+ if (km !== null && km !== 0) return (i) => addMonths(first.y, first.m, first.d, i * km)
+ }
+ const kd = constantStep(parts.map((p) => dayNumber(p.y, p.m, p.d)))
+ if (kd === null || kd === 0) return null
+ return (i) => fromDayNumber(day0 + i * kd)
+ }
+
+ // --- numeric STRINGS. A text column can still hold numbers — an import that
+ // could not settle a type leaves them as text, which is the case this whole
+ // app is built around. They must be continued NUMERICALLY, because the label
+ // path below splits on a trailing digit run and would read "0.8" as the label
+ // "0." followed by 8: the fill then emits 0.10, 0.11, which is not merely
+ // wrong, it is SMALLER than the value it follows.
+ if (ss.every((x) => x.trim() !== '' && Number.isFinite(Number(x.trim())))) {
+ const xs = ss.map((x) => Number(x.trim()))
+ const d = constantStep(xs)
+ if (d === null || d === 0) return null
+ const dp = Math.min(12, xs.reduce((n, x) => Math.max(n, decimals(x)), 0))
+ const f = 10 ** dp
+ // back to a STRING, at the seeds' own precision: the column is text, and a
+ // fill must not change what type the cells hold
+ return (i) => (Math.round((xs[0] + i * d) * f) / f).toFixed(dp)
+ }
+
+ // --- text ending in a number: "Q1" → "Q2", "Item 01" → "Item 02"
+ const nums: number[] = []
+ let prefix: string | null = null
+ let digits = ''
+ for (const s of ss) {
+ const m = TRAILING_NUM.exec(s)
+ if (!m) return null
+ if (prefix === null) prefix = m[1]
+ else if (m[1] !== prefix) return null // "Q1" then "P2" is two labels, not a series
+ nums.push(Number(m[2]))
+ digits = m[2]
+ }
+ const k = nums.length === 1 ? 1 : constantStep(nums)
+ if (k === null || k === 0) return null
+ // Zero padding is part of the label: "item09" continues "item10", not "item1 0".
+ const width = digits.startsWith('0') ? digits.length : 0
+ const head = prefix ?? ''
+ return (i) => `${head}${String(nums[0] + i * k).padStart(width, '0')}`
+}
diff --git a/dash/src/splash.ts b/dash/src/splash.ts
new file mode 100644
index 00000000..e607c02b
--- /dev/null
+++ b/dash/src/splash.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The boot splash — its dismissal, which is the half with the failure modes.
+//
+// The MARKUP is not here and must not be: a splash that waits for this bundle
+// to parse has already failed at its job. It is inline in index.html, and
+// postbuild-compress lifts it (with its own <style>) ahead of the compressed
+// payloads, so it paints from the first bytes of the file while ~500KB of
+// deflated runtime is still inflating.
+//
+// Removing it is the LIVE document's business only. `capturePristine()` has
+// already cloned the shell by the time anything here runs, so a saved workbook
+// keeps its splash for its own next boot — which is the whole point, since the
+// file people receive has to paint something before it can run.
+
+/** index.html declares `transition: opacity .45s`; outlive it by a frame. */
+const FADE_MS = 500
+
+/**
+ * How long the mark stays up, measured from page start rather than from the
+ * call — a boot that took 900ms has already shown it long enough.
+ *
+ * Short on purpose. Slides holds 1250ms because its splash ANIMATES and there
+ * is something to watch; dash's is a wordmark on white against an app that is
+ * also white, so the only thing a hold buys is not flashing a word for one
+ * frame.
+ */
+const HOLD_MS = 450
+
+/**
+ * A boot that THROWS never reaches dismissSplash, and the splash is fixed,
+ * opaque and z-index 9999 — the app runs underneath it, unreachable, forever.
+ * Slides defends this in CSS (`bsAuto`, a 9s auto-fade in the splash's own
+ * inline style, so it works even when the bundle never parses); dash's
+ * index.html carries no such rule, so the backstop is armed here instead.
+ *
+ * Weaker than the CSS one, and knowingly: it covers "the module graph loaded
+ * and boot then failed", not "the bundle never ran". Adding the keyframe to
+ * index.html would cover both.
+ */
+const FAILSAFE_MS = 9000
+
+const splash = (): HTMLElement | null => document.getElementById('bento-splash')
+
+const reduced = (): boolean => {
+ try {
+ return matchMedia('(prefers-reduced-motion: reduce)').matches
+ } catch {
+ return false
+ }
+}
+
+/** Take the splash away NOW. For the gates: an error surface must not wait
+ * behind branding, and a password prompt the reader cannot see is a bug. */
+export function dismissSplashNow(): void {
+ splash()?.remove()
+}
+
+/** Take the splash away once it has been up long enough to read. */
+export function dismissSplash(): void {
+ const el = splash()
+ if (!el) return
+ if (reduced()) { el.remove(); return }
+ setTimeout(() => {
+ el.classList.add('done')
+ // Removed, not just faded: it is `position: fixed; inset: 0`, and while it
+ // exists it eats every click on the grid underneath it.
+ setTimeout(() => el.remove(), FADE_MS)
+ }, Math.max(0, HOLD_MS - performance.now()))
+}
+
+setTimeout(dismissSplashNow, FAILSAFE_MS)
diff --git a/dash/src/store.ts b/dash/src/store.ts
index ff70d2e1..541fb1f5 100644
--- a/dash/src/store.ts
+++ b/dash/src/store.ts
@@ -28,7 +28,8 @@
// agent API. That is why this lands at commit one: retrofitting op-minting
// means rewriting the store.
-import type { CellOverride, Column, ColumnData, DashDoc, Measure, Sheet, Step, TableSheet } from './model.ts'
+import { applySheetProps } from './rowcol.ts'
+import type { CellOverride, View, Column, ColumnData, DashDoc, Measure, Sheet, Step, TableSheet } from './model.ts'
type Listener = () => void
export type StoreEvent = 'doc' | 'view' | 'selection'
@@ -61,12 +62,17 @@ export type Patch =
* apply-then-undo that leaves `"cells": {}` behind is not a round trip. */
| {
op: 'setOverrides'; sheet: string; keys: string[]
- v: Array<CellOverride | undefined>; dropEmpty?: boolean
+ /** `null` and `undefined` both DELETE; null is the one that survives JSON. */
+ v: Array<CellOverride | null | undefined>; dropEmpty?: boolean
}
/**
* `at[i]` is the row POSITION rids[i] takes; omitted means append.
* `values` is colId → one value per rid.
*
+ * `overrides` puts a deleted row's `cells` entries back with it. Without it
+ * the inverse of a delete restored the row's VALUES and dropped every hand
+ * correction, note and per-cell formula attached to it.
+ *
* Both exist because this is the inverse of a delete, and a delete has to be
* undoable exactly. Without `values` the rows come back EMPTY; without `at`
* they come back at the END — and in a spreadsheet, order is data. Measured
@@ -76,6 +82,14 @@ export type Patch =
| {
op: 'insertRows'; sheet: string; rids: number[]
at?: number[]; values?: Record<string, unknown[]>
+ /**
+ * A deleted row's `cells` entries, put back with it. Without this the
+ * inverse of a delete restored the row's VALUES and silently dropped
+ * every hand correction, note and per-cell formula attached to it.
+ */
+ overrides?: Record<string, CellOverride>
+ /** the sheet had no `cells` container before; do not leave one behind */
+ dropEmptyCells?: boolean
}
| { op: 'deleteRows'; sheet: string; rids: number[] }
| { op: 'setColumn'; sheet: string; col: string; patch: Record<string, unknown> }
@@ -88,6 +102,61 @@ export type Patch =
| { op: 'reorderColumns'; sheet: string; order: string[] }
| { op: 'setMeasure'; name: string; measure?: Measure; dropEmpty?: boolean }
| { op: 'setTitle'; title: string }
+ /**
+ * Sheet-level properties — conditional formats, frozen panes, the sheet name.
+ *
+ * Needed because nothing else in this union can write above the column: the
+ * row/column helpers had to declare their own patch type for want of one.
+ * Keyed like `setColumn` so the inverse is the displaced values, and a key
+ * whose new value is `undefined` is REMOVED rather than set — the un-hide
+ * hazard, met once already in rowcol.ts.
+ */
+ /**
+ * Sheet-level fields (frozen panes, conditional formats, filters) — the only
+ * op that writes ABOVE the column level.
+ *
+ * Deletes are a LISTED `drop`, never `props: {k: undefined}`, because these
+ * objects are also the collab wire format and `JSON.stringify` drops an
+ * undefined value entirely: the delete would arrive at every other replica as
+ * a no-op, and one editor would be looking at frozen panes nobody else has.
+ * The same trap sits on the INVERSE — undoing a newly-added key has to say
+ * "remove it", which is a `drop`, not a `props` entry that vanishes in
+ * transit. `props: {k: undefined}` is REFUSED rather than treated as a
+ * second spelling of delete.
+ */
+ | { op: 'setSheetProps'; sheet: string; props: Record<string, unknown>; drop?: string[] }
+ /**
+ * Top-level document fields — the story, a dashboard layout, anything
+ * additive that belongs to the WORKBOOK rather than to a sheet.
+ *
+ * Same discipline as `setSheetProps`, for the same reason: deletes are a
+ * listed `drop`, and `props: {k: undefined}` is refused rather than accepted
+ * as a second spelling, because `JSON.stringify` erases it and the delete
+ * would reach no other replica.
+ */
+ | { op: 'setDocProps'; props: Record<string, unknown>; drop?: string[] }
+ /**
+ * One dashboard view, by id. `view: undefined` removes it.
+ *
+ * Per-view rather than a whole-`views` write, so editing one tile carries an
+ * inverse the size of one view instead of every dashboard in the workbook —
+ * the same argument the byte-capped history makes everywhere else. `views` is
+ * an ARRAY (order is the tab order and readers must agree on it), so a
+ * replacement keeps its position and only a genuinely new id appends.
+ */
+ | { op: 'setView'; id: string; view?: View; at?: number; dropEmpty?: boolean }
+ /**
+ * Add or remove a whole sheet. `sheet: undefined` removes the one named.
+ *
+ * Adding and deleting a sheet used to go through `replaceDoc`, because
+ * nothing in this union reached the sheet LIST — and `replaceDoc` CLEARS THE
+ * UNDO STACK. So creating a pivot, or importing a CSV, silently threw away
+ * every edit you could previously take back, and deleting a sheet could not
+ * be undone at all. It is a whole-sheet assignment either way, so the inverse
+ * carries the sheet and its POSITION: sheet order is the tab order, and
+ * readers must agree on it.
+ */
+ | { op: 'setSheet'; id: string; sheet?: Sheet; at?: number }
/**
* RESERVED. Both need the transform engine, which does not exist yet. They
* are in the union now because the discriminant cannot be retrofitted once
@@ -97,6 +166,30 @@ export type Patch =
| { op: 'applySteps'; sheet: string; steps: Step[] }
| { op: 'refreshBinding'; sheet: string; cols: Record<string, ColumnData> }
+/**
+ * Document keys `setDocProps` refuses. `sheets` and `measures` have typed
+ * patches that know how to invert them; `docId` is identity and must never be
+ * rewritten by a props op (PLATFORM: it is the merge key).
+ */
+const STRUCTURAL_DOC_KEYS = new Set([
+ 'sheets', 'measures', 'docId', 'format', 'version', 'policy',
+])
+
+/**
+ * Raise a sheet's rid watermark past every rid in `rids`.
+ *
+ * MONOTONIC, and never lowered — not by undo either. A rid that has existed
+ * must never be minted again, because everything that attaches to one
+ * (overrides, comments, a peer's CRDT node) assumes it names one row forever.
+ * This is why insert and delete are the ops whose apply→undo is not
+ * byte-identical: the watermark is precisely the part that must survive.
+ */
+function raiseWatermark(sheet: TableSheet, rids: number[]): void {
+ const hi = rids.reduce((m, r) => Math.max(m, r), 0) + 1
+ const cur = (sheet as { nextRid?: number }).nextRid
+ if (typeof cur !== 'number' || !Number.isFinite(cur) || cur < hi) sheet.nextRid = hi
+}
+
/**
* What a patch touched, so undo can invalidate precisely.
*
@@ -235,14 +328,26 @@ export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: T
p.keys.forEach((k, i) => {
was.push(sheet.cells![k])
const v = p.v[i]
- if (v === undefined) delete sheet.cells![k]
+ // `null` deletes as well as `undefined`, and it is the spelling that
+ // SURVIVES: this is an array, and `JSON.stringify([undefined])` is
+ // `[null]`, so a delete sent over collab arrives as a null. Checking
+ // only for undefined would write that null in as an override — junk in
+ // the file, `dropEmpty` never firing, and the two replicas disagreeing
+ // about whether the cell has one.
+ if (v === undefined || v === null) delete sheet.cells![k]
else sheet.cells![k] = v
})
if (p.dropEmpty && Object.keys(sheet.cells).length === 0) delete sheet.cells
return {
inverse: {
op: 'setOverrides', sheet: p.sheet, keys: p.keys, v: was,
- dropEmpty: !existed,
+ // `dropEmpty` BOTH WAYS. Undoing the removal of the last override used
+ // to leave `cells: {}` behind on the undoing replica, while every peer
+ // received the change through a path that drops the container. Twelve
+ // bytes in the file, and a document that no longer matches its own
+ // collaborators — the engine normalised it afterwards, but the store
+ // should not create the divergence in the first place.
+ dropEmpty: !existed || p.dropEmpty === true,
},
touched: {
sheet: p.sheet,
@@ -255,8 +360,19 @@ export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: T
case 'insertRows': {
const sheet = table(doc, p.sheet)
const flat = expandRids(sheet)
- // ascending, so each splice index stays valid as earlier ones land
- const order = p.rids.map((rid, i) => ({ rid, at: p.at?.[i] ?? flat.length + i, i }))
+ // ascending, so each splice index stays valid as earlier ones land.
+ //
+ // CLAMPED, and it has to be. `splice` past the end APPENDS, but the
+ // `writeCell` below writes at the literal index — so an `at` beyond the
+ // sheet put the row at position 3 and its value at position 10, leaving
+ // the column longer than the sheet has rows with a hole of nulls
+ // between. Measured on a 3-row sheet: rids said 4 rows, the column held
+ // 11 entries. rowcol.ts clamps before it builds the patch, so the UI
+ // never produced this — but `window.bento.commit` is a public API and a
+ // remote op is another producer, and applyPatch is where the invariant
+ // has to hold.
+ const order = p.rids
+ .map((rid, i) => ({ rid, at: Math.max(0, Math.min(p.at?.[i] ?? flat.length + i, flat.length + i)), i }))
.sort((a, b) => a.at - b.at)
for (const { rid, at, i } of order) {
flat.splice(at, 0, rid)
@@ -270,6 +386,12 @@ export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: T
}
}
sheet.rids = compressRids(flat)
+ raiseWatermark(sheet, p.rids)
+ // put back whatever the delete took with it
+ if (p.overrides) {
+ sheet.cells ??= {}
+ for (const [k, v] of Object.entries(p.overrides)) sheet.cells[k] = v
+ }
return {
inverse: { op: 'deleteRows', sheet: p.sheet, rids: p.rids },
touched: { sheet: p.sheet, rids: p.rids, structural: true },
@@ -278,6 +400,12 @@ export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: T
case 'deleteRows': {
const sheet = table(doc, p.sheet)
+ // ON DELETE TOO — this is the half that matters. Raising the mark only on
+ // insert leaves nothing remembering that a DELETED rid ever existed, so
+ // the floor (derived from the current maximum) drops back and the next
+ // insert mints it again. Measured before this line: rid 3 deleted, then
+ // minted for a different row.
+ raiseWatermark(sheet, p.rids)
// capture position AND value before anything moves — the inverse has to
// put each row back exactly where it was, because order is data
const taken = p.rids
@@ -298,10 +426,36 @@ export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: T
}
}
sheet.rids = compressRids(flat)
+
+ // TAKE THE ROW'S OVERRIDES WITH IT, and hand them to the inverse.
+ //
+ // A deleted row's `cells` entries used to be left behind — orphaned, keyed
+ // to a rid that no longer names anything, and resurrected on top of
+ // whatever came back. rowcol.deleteRowsAt clears them, so the UI path was
+ // safe; but `insertRows`' own inverse is a BARE deleteRows, so undoing an
+ // insert went through here and stranded any override added to that row in
+ // the meantime — on the undoing replica only, since the sync engine strips
+ // them everywhere else. That is a divergence, and it is invisible.
+ const doomed = new Set(taken.map((r) => r.rid))
+ const overKeys: string[] = []
+ const overWas: Array<CellOverride | null> = []
+ for (const k of Object.keys(sheet.cells ?? {})) {
+ const i = k.indexOf(':')
+ if (i < 0 || !doomed.has(Number(k.slice(i + 1)))) continue
+ overKeys.push(k)
+ overWas.push(sheet.cells![k])
+ delete sheet.cells![k]
+ }
+ const hadCells = sheet.cells !== undefined
+ if (sheet.cells && !Object.keys(sheet.cells).length) delete sheet.cells
+
+ const overrides: Record<string, CellOverride> = {}
+ overKeys.forEach((k, i) => { const v = overWas[i]; if (v) overrides[k] = v })
return {
inverse: {
op: 'insertRows', sheet: p.sheet,
rids: taken.map((r) => r.rid), at: taken.map((r) => r.at), values: restore,
+ ...(overKeys.length ? { overrides, dropEmptyCells: !hadCells } : {}),
},
touched: { sheet: p.sheet, rids: p.rids, structural: true },
}
@@ -370,6 +524,74 @@ export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: T
}
}
+ case 'setSheet': {
+ const at = doc.sheets.findIndex((sh) => sh.id === p.id)
+ const was = at < 0 ? undefined : doc.sheets[at]
+ if (p.sheet === undefined) { if (at >= 0) doc.sheets.splice(at, 1) }
+ else if (at >= 0) doc.sheets[at] = p.sheet
+ else if (typeof p.at === 'number' && p.at >= 0 && p.at <= doc.sheets.length) {
+ doc.sheets.splice(p.at, 0, p.sheet)
+ } else doc.sheets.push(p.sheet)
+ return {
+ inverse: { op: 'setSheet', id: p.id, sheet: was, at: at < 0 ? undefined : at },
+ touched: { all: true },
+ }
+ }
+
+ case 'setView': {
+ const existed = doc.views !== undefined
+ doc.views ??= []
+ const at = doc.views.findIndex((v) => v.id === p.id)
+ const was = at < 0 ? undefined : doc.views[at]
+ if (p.view === undefined) { if (at >= 0) doc.views.splice(at, 1) }
+ else if (at >= 0) doc.views[at] = p.view
+ // `at` on the way IN is how the inverse of a removal restores POSITION.
+ // Without it undo appended the view to the end, so undoing the deletion
+ // of the first dashboard silently reordered the tabs — a change nobody
+ // asked for, arriving inside the operation meant to undo one.
+ else if (typeof p.at === 'number' && p.at >= 0 && p.at <= doc.views.length) {
+ doc.views.splice(p.at, 0, p.view)
+ } else doc.views.push(p.view)
+ if (p.dropEmpty && doc.views.length === 0) delete doc.views
+ return {
+ inverse: { op: 'setView', id: p.id, view: was, at: at < 0 ? undefined : at, dropEmpty: !existed },
+ touched: { all: true },
+ }
+ }
+
+ case 'setDocProps': {
+ const bag = doc as unknown as Record<string, unknown>
+ const props: Record<string, unknown> = {}
+ const drop: string[] = []
+ const dropping = new Set(p.drop ?? [])
+ const displace = (k: string): void => {
+ if (STRUCTURAL_DOC_KEYS.has(k)) {
+ throw new Error(`setDocProps may not write "${k}" — structure moves through typed patches`)
+ }
+ if (k in bag) props[k] = bag[k]
+ else drop.push(k)
+ }
+ for (const k of Object.keys(p.props)) {
+ if (dropping.has(k)) throw new Error(`setDocProps sets and drops "${k}" in one patch`)
+ if (p.props[k] === undefined) {
+ throw new Error(`setDocProps: to remove "${k}" list it in \`drop\`, not props`)
+ }
+ displace(k)
+ bag[k] = p.props[k]
+ }
+ for (const k of dropping) { displace(k); delete bag[k] }
+ return {
+ inverse: { op: 'setDocProps', props, ...(drop.length ? { drop } : {}) },
+ touched: { all: true },
+ }
+ }
+
+ case 'setSheetProps':
+ // The writer lives in rowcol.ts beside `freezeAt`, which is what emits
+ // these, and is covered there. Two copies of one op is how the inverse
+ // and the forward drift apart.
+ return applySheetProps(table(doc, p.sheet), p)
+
case 'setTitle': {
const was = doc.title
doc.title = p.title
@@ -415,6 +637,27 @@ export class Store {
for (const fn of this.listeners.get(ev) ?? []) fn()
}
+ /**
+ * The document changed UNDERNEATH this store — a collaborator's edit applied
+ * surgically, not an edit made here.
+ *
+ * It is deliberately not `commit`: somebody else's change is not an entry in
+ * your undo history, and routing it through the undo stack would let you
+ * "undo" a keystroke you never made. But every listener still has to repaint,
+ * so this stamps `modified`, invalidates everything and emits the same events
+ * an edit does.
+ *
+ * The alternative, which is what the sync session did before this existed,
+ * was to reach through `unknown` and call the PRIVATE `emit`. That works
+ * until the day the event names change, and nothing tells you.
+ */
+ changedRemotely(touched: Touched = { all: true }): void {
+ this.doc.modified = new Date().toISOString()
+ this.lastTouched = touched
+ this.emit('doc')
+ this.emit('view')
+ }
+
/** The last invalidation, for a listener that wants to repaint precisely. */
lastTouched: Touched = {}
@@ -423,10 +666,58 @@ export class Store {
* Closes any open typing run first, so a run's text and a structural edit
* never merge into one entry.
*/
+ /**
+ * Listeners that see every patch BEFORE it is applied, and may replace the
+ * list — collaboration's entry point.
+ *
+ * WHY A HOOK RATHER THAN WRAPPING THE VERBS. The sync session used to
+ * decorate `commit` and `runEdit` on the instance, which covers every edit
+ * the UI makes and cannot see UNDO and REDO — those apply their inverses
+ * through a private path. Undo therefore fell back to broadcasting a whole
+ * state snapshot: correct, and enormously heavier than the two ops it
+ * stands in for. `invert` calls this too, so an undo now ships as ops.
+ *
+ * The listener runs BEFORE the document changes because the CRDT reads what
+ * a delete is about to displace; `afterPatch` is the other half.
+ */
+ beforePatch(fn: (patches: Patch[]) => Patch[] | void): () => void {
+ this.patchHooks.push(fn)
+ return () => { this.patchHooks = this.patchHooks.filter((f) => f !== fn) }
+ }
+
+ /** Listeners that run once the document HAS changed. */
+ afterPatch(fn: () => void): () => void {
+ this.appliedHooks.push(fn)
+ return () => { this.appliedHooks = this.appliedHooks.filter((f) => f !== fn) }
+ }
+
+ private patchHooks: Array<(p: Patch[]) => Patch[] | void> = []
+ private appliedHooks: Array<() => void> = []
+
+ /**
+ * Run the before-hooks. `substitute` is false for undo/redo: a hook may
+ * REFUSE a patch it cannot express, and dropping one there would apply half
+ * an inverse and leave the undo stack describing a document that no longer
+ * exists. An undo must land whole or not at all.
+ */
+ private runBefore(list: Patch[], substitute = true): Patch[] {
+ let out = list
+ for (const fn of this.patchHooks) {
+ const next = fn(out)
+ if (substitute && Array.isArray(next)) out = next
+ }
+ return out
+ }
+
+ private runAfter(): void {
+ for (const fn of this.appliedHooks) fn()
+ }
+
commit(patches: Patch | Patch[]): void {
if (this.readOnly) return
this.endRun()
- const list = Array.isArray(patches) ? patches : [patches]
+ const list = this.runBefore(Array.isArray(patches) ? patches : [patches])
+ if (!list.length) return
const inverse: Patch[] = []
const touched: Touched = {}
let bytes = 0
@@ -440,6 +731,7 @@ export class Store {
this.touch()
this.lastTouched = touched
this.emit('doc')
+ this.runAfter()
}
/**
@@ -447,24 +739,39 @@ export class Store {
* every later one extends it in place, so a cell typed into forty times is
* one undo step carrying one inverse — not forty.
*/
- runEdit(cellKey: string, patch: Patch): void {
+ runEdit(cellKey: string, patch: Patch | Patch[]): void {
if (this.readOnly) return
if (this.runCell !== cellKey) {
this.endRun()
this.runCell = cellKey
this.pending = { inverse: [], touched: {}, bytes: 0 }
}
- const r = applyPatch(this.doc, patch)
- // keep only the FIRST inverse for this cell: it holds the value the run
- // started from, which is what undo must restore
- if (this.pending!.inverse.length === 0) {
- this.pending!.inverse.push(r.inverse)
- this.pending!.bytes = patchBytes(r.inverse)
+ // Keep only the FIRST edit's inverse for this cell: it holds the value the
+ // run started from, which is what undo must restore. Forty keystrokes are
+ // one step back to where the typing began.
+ const first = this.pending!.inverse.length === 0
+ // One EDIT may be several patches — writing a value and clearing the
+ // formula it replaced is two, and they have to undo as ONE step. Their
+ // inverses go on REVERSED, because `invert` replays the list forward.
+ const list = this.runBefore(Array.isArray(patch) ? patch : [patch])
+ if (!list.length) return
+ const inverses: Patch[] = []
+ const r = { touched: {} as Touched }
+ for (const p of list) {
+ const one = applyPatch(this.doc, p)
+ if (first) inverses.push(one.inverse)
+ merge(r.touched, one.touched)
+ this.lastTouched = one.touched
+ }
+ if (first) {
+ inverses.reverse()
+ this.pending!.inverse.push(...inverses)
+ this.pending!.bytes = inverses.reduce((n, p) => n + patchBytes(p), 0)
}
merge(this.pending!.touched, r.touched)
this.touch()
- this.lastTouched = r.touched
this.emit('doc')
+ this.runAfter()
clearTimeout(this.runTimer)
this.runTimer = setTimeout(() => this.endRun(), RUN_IDLE_MS)
}
@@ -517,6 +824,11 @@ export class Store {
const inverse: Patch[] = []
const touched: Touched = {}
let bytes = 0
+ // THE POINT OF THE HOOK. Undo and redo change the document exactly as an
+ // edit does, and a collaborator has to hear about it. Without this the
+ // session could not see them at all and fell back to broadcasting a whole
+ // state snapshot. `substitute: false` — see runBefore.
+ this.runBefore(e.inverse, false)
for (const p of e.inverse) {
const r = applyPatch(this.doc, p)
inverse.unshift(r.inverse)
@@ -526,6 +838,7 @@ export class Store {
this.touch()
this.lastTouched = touched
this.emit('doc')
+ this.runAfter()
return { inverse, touched, bytes }
}
diff --git a/dash/src/story.css b/dash/src/story.css
new file mode 100644
index 00000000..00e84fa9
--- /dev/null
+++ b/dash/src/story.css
@@ -0,0 +1,226 @@
+/* SPDX-License-Identifier: MIT
+ Copyright (c) 2026 The Bento authors
+ Data story mode — the present overlay and the little authoring panel.
+
+ The overlay is DARK on BOTH themes, deliberately: the moment the room dims, a
+ white 1400px rectangle is the brightest object in it. slides' present overlay
+ makes the same call, and the two surfaces share this palette so a deck and a
+ workbook presented back to back do not flash at the audience. So the values
+ below are literal rather than tokens — this surface does not follow the
+ viewer's theme, it follows the room, and a `light-dark()` here would make a
+ presenter's light-theme preference reach the audience's screen.
+
+ The AUTHORING panel at the bottom of the file is the opposite: it belongs to
+ the editor, never to the show, so it is tokens throughout and it does follow
+ the theme.
+
+ Everything here is `position: fixed` and mounted on <body>, so it is immune
+ to the app's flex layout — and it carries `direction: ltr` because it renders
+ DOCUMENT content: PLATFORM §8's invariant is that a document never mirrors,
+ and every new document-rendering surface has to pin it for itself. */
+
+.ds-overlay {
+ position: fixed;
+ inset: 0;
+ z-index: 9000;
+ direction: ltr;
+ display: flex;
+ flex-direction: column;
+ background: #0e1420;
+ color: #e8edf5;
+ font: 14px/1.45 ui-sans-serif, system-ui, -apple-system, 'Segoe UI', sans-serif;
+ outline: none;
+}
+
+.ds-stage {
+ flex: 1 1 auto;
+ min-height: 0;
+ position: relative;
+ padding: 24px 32px 8px;
+ /* the chart is measured from this box, so it must not be a scroller —
+ a scrollbar appearing mid-morph would resize every remaining frame */
+ overflow: hidden;
+}
+.ds-stage > svg { width: 100%; height: 100%; display: block; }
+/* The stage is dark in every theme, and charts-lite defaults its label colour
+ to a mid grey sized for white paper — 3.3:1 against #0e1420. `fill` is a
+ presentation attribute, so this rule wins; the marks keep the document's own
+ palette. Literal, like everything else on this surface. */
+/* Same rule as the chart panel's, and for the same reason: override the
+ kernel's DEFAULT text colour, never a colour somebody chose. The presenter
+ stage is deliberately dark in both themes, so this value is literal. */
+.ds-stage svg text[fill="#6B7280"] { fill: #b9c4d3; }
+
+.ds-empty {
+ display: grid;
+ place-items: center;
+ height: 100%;
+ color: #7c8899;
+}
+
+/* ————— caption ————— */
+
+.ds-caption {
+ flex: 0 0 auto;
+ padding: 4px 40px 10px;
+ display: flex;
+ flex-direction: column;
+ gap: 6px;
+ align-items: center;
+ text-align: center;
+}
+.ds-cap-text {
+ font-size: clamp(15px, 2.2vw, 26px);
+ font-weight: 600;
+ letter-spacing: -0.01em;
+ max-width: 60ch;
+ /* Reserve the line even when empty, so stepping onto an uncaptioned step
+ does not jolt the chart upward by a line height. */
+ min-height: 1.4em;
+}
+.ds-cap-text.empty { opacity: 0; }
+
+.ds-chips { display: flex; gap: 6px; flex-wrap: wrap; justify-content: center; }
+.ds-chip {
+ font-size: var(--fs-small);
+ padding: 2px 9px;
+ border-radius: 999px;
+ background: rgba(247, 166, 0, 0.16);
+ border: 1px solid rgba(247, 166, 0, 0.5);
+ color: #ffcf72;
+}
+
+/* ————— the bar ————— */
+
+.ds-bar {
+ flex: 0 0 auto;
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 8px 16px max(8px, env(safe-area-inset-bottom));
+ border-top: 1px solid rgba(255, 255, 255, 0.08);
+}
+.ds-bar .ds-dots { flex: 1 1 auto; display: flex; gap: 6px; align-items: center; }
+.ds-dot {
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: rgba(255, 255, 255, 0.22);
+ cursor: pointer;
+ transition: background 0.18s, transform 0.18s;
+}
+.ds-dot:hover { background: rgba(255, 255, 255, 0.45); }
+.ds-dot.on { background: var(--accent); transform: scale(1.35); }
+.ds-count { font-variant-numeric: tabular-nums; color: #8c99ad; font-size: var(--fs-small); }
+
+/* Same metrics as .dx-btn in styles.css — padding, radius, type size — and a
+ dark skin instead of a light one. The presenter overlay is the one surface in
+ dash that inverts, and inverting is ALL it should do: a button that also
+ changed shape and size would read as a different kind of control. */
+.ds-btn {
+ font: inherit;
+ font-size: var(--fs-ui);
+ line-height: 1;
+ padding: 5px 10px;
+ border-radius: var(--radius);
+ border: 1px solid rgba(255, 255, 255, 0.16);
+ background: rgba(255, 255, 255, 0.06);
+ color: inherit;
+ cursor: pointer;
+}
+.ds-btn:hover { background: rgba(255, 255, 255, 0.14); }
+.ds-btn[disabled] { opacity: 0.4; cursor: default; }
+
+/* Reduced motion is a VIEWER preference (see story.ts). The class kills CSS
+ motion as well as the tweens — a dot that still springs is motion the reader
+ asked not to have. */
+.ds-overlay.reduce-motion .ds-dot { transition: none; }
+.ds-overlay.reduce-motion .ds-dot.on { transform: none; }
+.ds-overlay.reduce-motion [data-nav='motion'] {
+ background: rgba(247, 166, 0, 0.22);
+ border-color: rgba(247, 166, 0, 0.55);
+}
+
+/* ————— the authoring panel ————— */
+
+/* The AUTHORING panel is light — it belongs to the editor, not to the show —
+ so it is styled as a floating surface exactly like the save menu and the
+ right-click popovers: same radius, same shadow, same 13px rows. */
+.ds-editor {
+ position: fixed;
+ right: 16px;
+ bottom: 16px;
+ z-index: 8500;
+ width: min(420px, calc(100vw - 32px));
+ max-height: min(60vh, 560px);
+ display: flex;
+ flex-direction: column;
+ background: var(--surface);
+ color: var(--ink);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-lg);
+ box-shadow: var(--shadow-pop);
+ font-size: var(--fs-ui);
+}
+.ds-ed-head {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ padding: 10px 12px;
+ border-bottom: 1px solid var(--line);
+}
+.ds-ed-head .ds-btn,
+.ds-ed-foot .ds-btn,
+.ds-step .ds-btn {
+ background: var(--surface);
+ color: inherit;
+ border-color: var(--line-strong);
+}
+.ds-ed-head .ds-btn:hover,
+.ds-ed-foot .ds-btn:hover,
+.ds-step .ds-btn:hover { background: var(--hover); }
+.ds-primary { border-color: var(--accent) !important; }
+
+.ds-steps {
+ list-style: none;
+ margin: 0;
+ padding: 6px;
+ overflow: auto;
+ flex: 1 1 auto;
+}
+.ds-step {
+ display: flex;
+ align-items: center;
+ gap: 6px;
+ padding: 5px 6px;
+ border-radius: var(--radius);
+}
+.ds-step:hover { background: var(--hover); }
+.ds-n {
+ flex: 0 0 auto;
+ width: 20px;
+ text-align: right;
+ color: var(--muted);
+ font-variant-numeric: tabular-nums;
+}
+.ds-fields { flex: 1 1 auto; min-width: 0; display: flex; flex-direction: column; gap: 2px; }
+.ds-cap-in {
+ font: inherit;
+ width: 100%;
+ padding: 3px 6px;
+ border: 1px solid transparent;
+ border-radius: var(--radius);
+ background: transparent;
+ color: inherit;
+}
+.ds-cap-in:hover { border-color: var(--line-strong); }
+.ds-cap-in:focus { outline: none; border-color: var(--accent); background: var(--surface); }
+.ds-meta { font-size: var(--fs-micro); color: var(--muted); padding-left: 6px; }
+.ds-warn { color: var(--err-ink); font-weight: 600; }
+.ds-hint { margin: 0; padding: 14px 14px 6px; color: var(--muted); }
+.ds-ed-foot {
+ display: flex;
+ gap: 8px;
+ padding: 10px 12px;
+ border-top: 1px solid var(--line);
+}
diff --git a/dash/src/story.ts b/dash/src/story.ts
new file mode 100644
index 00000000..734efb39
--- /dev/null
+++ b/dash/src/story.ts
@@ -0,0 +1,985 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// DATA STORY MODE — a workbook that presents itself.
+//
+// This is slides' MORPH idea, moved onto data. In slides both frames of a
+// transition live in the document, so a shape animates from one slide to the
+// next MODEL-driven, with no DOM measuring (slides/src/present.ts). Here both
+// frames of a chart live in the document too — not as two copies of the
+// numbers, but as two SAVED VIEWS of one dataset. A step names a sheet, a
+// filter, a sort, a chart binding, a camera and a caption; the series are
+// derived from the sheet at render, exactly as chart.ts derives them. Stepping
+// from one to the next interpolates the two derived options, so bars grow and
+// shrink to their real new values and the categories slide into their new
+// order.
+//
+// The pitch is the file: Tableau needs a server to do this and Excel has
+// nothing like it, and the whole thing runs offline from an attachment someone
+// emailed you.
+//
+// FOUR RULES SHAPE EVERY DECISION BELOW.
+//
+// 1. A STEP IS DOCUMENT DATA; THE READER'S POSITION IS NOT. The steps travel in
+// the file so everyone sees the same story. Which step you are ON is
+// per-viewer state and lives in the player's closure — the same split
+// store.ts draws between `commit` (document) and `view` (order vector), and
+// the same split slides draws for reduced motion (a VIEWER preference in
+// localStorage, never in the doc — a document whose appearance depends on
+// who opened it is a format-level bug, PLATFORM §8).
+//
+// 2. SERIES ARE DERIVED, NEVER STORED. chart.ts promoted slides' painful
+// `syncLinkedChart` lesson to a rule: there is no code path that writes
+// series data into the document. A story would be the obvious place to break
+// it — "just snapshot the numbers for each step" — and that is exactly how a
+// presentation ends up disagreeing with the table behind it. Every step
+// re-derives from the sheet through `optionFor`, so editing a cell moves
+// every step of the story at once.
+//
+// 3. A NUMBER NEVER ANIMATES THROUGH A VALUE THAT IS NOT IN THE DATA. Zero is
+// such a value. `morphOption` interpolates numeric leaves and CUTS
+// everything else, so a gap (null) stays a gap for the whole tween and never
+// slides to or from the axis. See the long note on `morphOption`, and the
+// MEASURED renderer limitation recorded on `canMorph` — which is why a
+// line chart refuses a morph that a bar chart accepts.
+//
+// 4. PRESENTING MUTATES NOTHING. The player computes its own order vectors and
+// its own options; it never calls `store.commit`, never writes
+// `store.order`, and never touches the grid. Closing the overlay leaves the
+// workbook byte-identical to how it opened.
+//
+// WHAT DOES NOT PRESENT YET, and why, is recorded at the bottom of this file
+// under KNOWN GAPS rather than left for someone to discover.
+
+import './story.css'
+import { anim } from '../../kernel/src/anim.ts'
+import { chartSnapshotSvg, mountChart } from '../../kernel/src/charts.ts'
+import { optionFor, type ChartBinding } from './chart.ts'
+import { buildOrder, type ColumnFilter, type Predicate } from './filter.ts'
+import { buildScene, mountViz3d, type Viz3dBinding } from './viz3d.ts'
+import type { DashDoc, TableSheet, Story, StoryStep, StoredFilter, StoredPredicate, StoryCamera, SortKey } from './model.ts'
+import { readCell, type Store } from './store.ts'
+import { t } from './i18n.ts'
+
+type Opt = Record<string, unknown>
+
+const isObj = (v: unknown): v is Record<string, unknown> =>
+ typeof v === 'object' && v !== null && !Array.isArray(v)
+
+// --- the model ---------------------------------------------------------------
+//
+// DECLARED HERE, TO BE MOVED INTO model.ts. `doc.story` is an ADDITIVE
+// top-level field: `parseDoc` spreads the raw object at every level, so a build
+// that has never heard of a story preserves one through parse → serialize, and
+// this build preserves unknown fields inside a story through `normalizeStory`.
+// That is PLATFORM §3 and it is not negotiable — there is no server to migrate
+// the files already on disk.
+
+/** Longest a transition may run. Past this the reader is waiting, not reading. */
+const MAX_DURATION = 5
+const DEFAULT_DURATION = 0.7
+
+/**
+ * Data points above which a morph CUTS instead.
+ *
+ * The morph re-renders the whole chart every frame (that is what makes it
+ * model-driven rather than a DOM trick), and each frame serializes an SVG. At
+ * a few thousand points that stops fitting in a frame, and a morph that
+ * stutters reads as a broken app — worse than the cut it was trying to improve
+ * on. Measured budget, not a guess about correctness.
+ */
+const MORPH_POINT_BUDGET = 4000
+
+let stepSeq = 0
+/** Authoring-time only, so randomness is fine (unlike model.ts's id repair,
+ * which must be identical for two readers of one file). */
+export const mintStepId = (): string =>
+ `st-${Date.now().toString(36)}${(stepSeq++).toString(36)}${Math.random().toString(36).slice(2, 6)}`
+
+// --- reading and writing the field -------------------------------------------
+
+/**
+ * Normalise a story out of a document, KEEPING every field this build does not
+ * know — at the story level and at the step level. That spread is the whole
+ * additivity guarantee, and the rig asserts it because it is one careless
+ * object literal away from being lost forever.
+ */
+export function normalizeStory(raw: Record<string, unknown>): Story {
+ const steps = Array.isArray(raw.steps)
+ ? (raw.steps as unknown[]).filter(isObj).map(normalizeStep)
+ : []
+ return { ...raw, steps }
+}
+
+function normalizeStep(raw: Record<string, unknown>): StoryStep {
+ return {
+ ...raw,
+ // A step with no id cannot be reordered or referred to; mint one rather
+ // than drop the step, because the step is somebody's work and the id is
+ // bookkeeping.
+ id: typeof raw.id === 'string' && raw.id ? raw.id : mintStepId(),
+ sheet: typeof raw.sheet === 'string' ? raw.sheet : '',
+ }
+}
+
+export function readStory(doc: DashDoc): Story | null {
+ const raw = (doc as DashDoc).story
+ return isObj(raw) ? normalizeStory(raw as unknown as Record<string, unknown>) : null
+}
+
+/**
+ * THE PATCH OP THIS MODULE NEEDS AND DOES NOT HAVE.
+ *
+ * `Patch` (store.ts) can write a column, a sheet, a measure and the title —
+ * there is nothing that writes a top-level document field. `setSheetProps`
+ * exists for exactly this shape one level down, deletes spelled as a listed
+ * `drop` rather than `{k: undefined}` because JSON.stringify drops an undefined
+ * value and the delete would reach every other replica as a no-op. The
+ * document-level twin is the same op with the sheet argument removed.
+ *
+ * Until it lands, `writeStory` falls back (see there). The factory is exported
+ * now so the call sites do not move when the op arrives.
+ */
+export const STORY_OP = 'setDocProps'
+
+export interface SetDocPropsPatch {
+ op: typeof STORY_OP
+ props: Record<string, unknown>
+ drop?: string[]
+}
+
+export const storyPatch = (story: Story | null): SetDocPropsPatch =>
+ story && story.steps.length
+ ? { op: STORY_OP, props: { story } }
+ : { op: STORY_OP, props: {}, drop: ['story'] }
+
+/**
+ * Write the story into the document as ONE undoable change.
+ *
+ * INTERIM. `applyPatch` refuses an op it does not implement — loudly, and
+ * before it mutates anything, which is what makes the catch below safe for a
+ * single-patch commit. The fallback mutates the field directly and then commits
+ * a no-op `setTitle` purely to raise the `doc` event: that is the same
+ * checkpoint-boundary idiom main.ts uses after pushing an imported sheet, and
+ * it is what keeps the dirty flag and autosave honest. The cost is that one
+ * undo after editing a caption restores the title rather than the caption; it
+ * disappears the moment `setDocProps` exists.
+ */
+export function writeStory(store: Store, story: Story | null): void {
+ if (store.readOnly) return
+ const doc = store.doc as DashDoc
+ try {
+ store.commit(storyPatch(story) as never)
+ return
+ } catch {
+ if (story && story.steps.length) doc.story = story
+ else delete doc.story
+ store.commit({ op: 'setTitle', title: doc.title })
+ }
+}
+
+// --- filters: the JSON bridge ------------------------------------------------
+
+/** Stored → live. Returns null for an op this build cannot evaluate. */
+export function toPredicate(p: StoredPredicate): Predicate | null {
+ switch (p.op) {
+ case 'equals': case 'notEquals':
+ case 'greater': case 'less': case 'greaterOrEqual': case 'lessOrEqual':
+ return { op: p.op, v: (p as { v: unknown }).v } as Predicate
+ case 'contains': case 'notContains': case 'startsWith': case 'endsWith':
+ return { op: p.op, v: String((p as { v: unknown }).v ?? '') } as Predicate
+ case 'between':
+ return { op: 'between', lo: (p as { lo: unknown }).lo, hi: (p as { hi: unknown }).hi }
+ case 'isBlank': case 'notBlank':
+ return { op: p.op }
+ case 'isOneOf': {
+ const values = (p as { values?: unknown }).values
+ return { op: 'isOneOf', set: new Set(Array.isArray(values) ? values : []) }
+ }
+ case 'topN': case 'bottomN': {
+ const n = Number((p as { n?: unknown }).n)
+ return Number.isFinite(n) ? { op: p.op, n } : null
+ }
+ default:
+ // Kept in the document by `normalizeStep`'s spread, not applied here.
+ return null
+ }
+}
+
+/** Live → stored. The `Set` is the only thing that actually changes shape. */
+export function fromPredicate(p: Predicate): StoredPredicate {
+ if (p.op === 'isOneOf') return { op: 'isOneOf', values: [...p.set] }
+ return p as unknown as StoredPredicate
+}
+
+export const toFilters = (stored: StoredFilter[] | undefined): ColumnFilter[] =>
+ (stored ?? [])
+ .map((f) => ({ col: f.col, pred: toPredicate(f.pred) }))
+ .filter((f): f is ColumnFilter => f.pred !== null)
+
+export const fromFilters = (live: ColumnFilter[]): StoredFilter[] =>
+ live.map((f) => ({ col: f.col, pred: fromPredicate(f.pred) }))
+
+// --- deriving a step ---------------------------------------------------------
+
+export const sheetOf = (doc: DashDoc, id: string): TableSheet | null => {
+ const s = doc.sheets.find((x) => x.id === id)
+ return s && s.kind === 'table' ? s : null
+}
+
+const rowsOf = (sheet: TableSheet): number => sheet.rids.reduce((a, [, c]) => a + c, 0)
+
+/**
+ * The visible rows for one step, in order.
+ *
+ * VIEW state, computed on demand and thrown away — the player never writes
+ * `store.order`, because the reader watching a story and the author editing the
+ * grid behind it must not fight over one vector.
+ */
+export function stepOrder(
+ sheet: TableSheet,
+ step: StoryStep,
+ computed?: Map<string, unknown[]>,
+): number[] {
+ const rows = rowsOf(sheet)
+ const get = (col: string, row: number): unknown => {
+ const c = computed?.get(col)
+ return c ? c[row] : readCell(sheet.data[col], row)
+ }
+ return buildOrder(rows, get, toFilters(step.filters), step.sorts ?? [])
+}
+
+/**
+ * The bound columns, restricted to the visible rows.
+ *
+ * This is how a step's filter reaches the chart WITHOUT chart.ts growing an
+ * order argument: `optionFor` already reads a column through `computed` if the
+ * caller supplies one, so supplying the filtered slice for every bound column
+ * derives the series from exactly the rows the step shows.
+ *
+ * EVERY BOUND COLUMN OR NONE. `optionFor` zips the x column against each series
+ * column by index; if one of them came through this map (k rows) and another
+ * came from the sheet (n rows), the chart pairs the wrong label with the wrong
+ * number and looks entirely plausible doing it. `stepOption` is the only caller
+ * and it passes the full binding, which is what makes that unrepresentable.
+ */
+export function viewColumns(
+ sheet: TableSheet,
+ order: number[],
+ cols: string[],
+ computed?: Map<string, unknown[]>,
+): Map<string, unknown[]> {
+ const out = new Map<string, unknown[]>()
+ for (const col of cols) {
+ if (!col || out.has(col)) continue
+ const c = computed?.get(col)
+ out.set(col, order.map((row) => (c ? c[row] : readCell(sheet.data[col], row))))
+ }
+ return out
+}
+
+/**
+ * A step's chart option — derived, every time, from the sheet.
+ *
+ * `computed` is the grid's freshly recalculated formula columns, handed through
+ * unchanged from chart.ts's contract: a story about a computed column must show
+ * the numbers on screen, not the raw column underneath them.
+ */
+export function stepOption(
+ sheet: TableSheet,
+ step: StoryStep,
+ computed?: Map<string, unknown[]>,
+): Opt | null {
+ const bind = step.chart
+ if (!bind || !bind.x || !bind.series?.length) return null
+ const order = stepOrder(sheet, step, computed)
+ const view = viewColumns(sheet, order, [bind.x, ...bind.series], computed)
+ return optionFor(sheet, bind, view)
+}
+
+// --- alignment ---------------------------------------------------------------
+//
+// Two steps of one story almost never produce the same-shaped option: that is
+// the POINT — a filter drops categories, a sort reorders them, a new binding
+// adds a series. Interpolating requires a common frame, so alignment rewrites
+// both options over the union of their categories and series, filling the
+// absences with `null`.
+//
+// `null` and not `0`, and that distinction is the whole reason this function
+// exists rather than a `JSON.stringify` comparison. See `morphOption`.
+
+const catsOf = (opt: Opt): string[] | null => {
+ const x = opt.xAxis as { data?: unknown } | undefined
+ return Array.isArray(x?.data) ? (x.data as unknown[]).map((v) => String(v)) : null
+}
+
+const seriesOf = (opt: Opt): Opt[] =>
+ Array.isArray(opt.series) ? (opt.series as Opt[]).filter(isObj) : []
+
+const hasDupes = (xs: string[]): boolean => new Set(xs).size !== xs.length
+
+/**
+ * The union of two category axes, keeping BOTH orders.
+ *
+ * `to`'s order is the spine, because that is where the reader is going. A
+ * category that only `from` has is emitted just before the `from`-neighbour
+ * that survived, so a bar about to disappear does not jump across the chart on
+ * its way out — it leaves from where it was standing.
+ */
+export function mergeCats(a: string[], b: string[]): string[] {
+ const inB = new Set(b)
+ const out: string[] = []
+ const seen = new Set<string>()
+ let ai = 0
+ const drainA = (until: number) => {
+ for (; ai < until; ai++) {
+ const c = a[ai]
+ if (!inB.has(c) && !seen.has(c)) { out.push(c); seen.add(c) }
+ }
+ }
+ for (const c of b) {
+ const at = a.indexOf(c)
+ if (at >= 0) drainA(at)
+ if (!seen.has(c)) { out.push(c); seen.add(c) }
+ if (at >= 0) ai = Math.max(ai, at + 1)
+ }
+ drainA(a.length)
+ return out
+}
+
+export interface Aligned {
+ from: Opt
+ to: Opt
+ /** true when the union put a `null` where a source option had a value at
+ * every position — i.e. a category or series exists at only one end. */
+ introduced: boolean
+ /** why alignment was refused, for the caller's cut path. '' when it worked. */
+ refused: string
+}
+
+/**
+ * Rewrite two cartesian options over a common category axis and series list.
+ *
+ * REFUSES rather than guesses:
+ * - a pie (its data is `{name,value}` objects on a different axis entirely);
+ * - an option with no category axis;
+ * - DUPLICATE CATEGORIES. With `aggregate: 'none'` there is one bar per ROW,
+ * so two rows may carry the same x label — and then matching by label is
+ * ambiguous and would swap two bars' values silently. A cut is right here;
+ * an arbitrary pairing is not.
+ * A refusal is not a failure: the caller cuts, which is honest and instant.
+ */
+export function alignOptions(from: Opt, to: Opt): Aligned {
+ const fail = (why: string): Aligned => ({ from, to, introduced: false, refused: why })
+ const fs = seriesOf(from)
+ const ts = seriesOf(to)
+ if (fs.some((s) => s.type === 'pie') || ts.some((s) => s.type === 'pie')) return fail('pie')
+ const fc = catsOf(from)
+ const tc = catsOf(to)
+ if (!fc || !tc) return fail('no category axis')
+ if (hasDupes(fc) || hasDupes(tc)) return fail('duplicate categories')
+
+ const cats = mergeCats(fc, tc)
+ let introduced = false
+
+ // Series are matched by NAME, which is the column's display name — the one
+ // thing a reader can see. Matching by index would pair "Revenue" with "Cost"
+ // the moment a step drops a series, and the bars would tween between two
+ // different measures.
+ const names: string[] = []
+ const push = (n: string) => { if (!names.includes(n)) names.push(n) }
+ for (const s of ts) push(String(s.name ?? ''))
+ for (const s of fs) push(String(s.name ?? ''))
+
+ const remap = (side: Opt[], sideCats: string[], name: string): { s: Opt | null; data: Array<number | null> } => {
+ const s = side.find((x) => String(x.name ?? '') === name) ?? null
+ if (!s) return { s: null, data: cats.map(() => null) }
+ const at = new Map(sideCats.map((c, i) => [c, i]))
+ const src = Array.isArray(s.data) ? (s.data as Array<number | null>) : []
+ return {
+ s,
+ data: cats.map((c) => {
+ const i = at.get(c)
+ if (i === undefined) return null
+ const v = src[i]
+ return typeof v === 'number' && Number.isFinite(v) ? v : null
+ }),
+ }
+ }
+
+ const build = (side: Opt[], sideCats: string[], other: Opt[], base: Opt): Opt => {
+ const series = names.map((name) => {
+ const mine = remap(side, sideCats, name)
+ const theirs = other.find((x) => String(x.name ?? '') === name)
+ // A series only one side has still needs a TYPE, or the two options have
+ // different shapes and nothing can tween. Borrow the other side's.
+ const proto = mine.s ?? theirs ?? {}
+ // A series only one side has is entirely gaps on the other — the same
+ // "introduced null" as a category the union added, and it has to be
+ // reported for the same reason (see canMorph). Nulls the SOURCE already
+ // carried are not introduced: chart.ts emits them for an empty aggregate
+ // bucket, and they are the honest answer, not this function's doing.
+ if (!mine.s) introduced = true
+ return { ...proto, name, data: mine.data }
+ })
+ return {
+ ...base,
+ xAxis: { ...(base.xAxis as Opt | undefined), type: 'category', data: cats },
+ series,
+ }
+ }
+
+ const outFrom = build(fs, fc, ts, from)
+ const outTo = build(ts, tc, fs, to)
+ // A category the union added is a null on the side that lacks it, whether or
+ // not the loop above noticed it through a series' own data.
+ if (cats.length !== fc.length || cats.length !== tc.length) introduced = true
+ return { from: outFrom, to: outTo, introduced, refused: '' }
+}
+
+const typeSig = (opt: Opt): string => seriesOf(opt).map((s) => String(s.type ?? '')).join(',')
+
+const optionPoints = (opt: Opt): number =>
+ seriesOf(opt).reduce((n, s) => n + (Array.isArray(s.data) ? s.data.length : 0), 0)
+
+/**
+ * Can these two options be tweened, or must the step cut?
+ *
+ * The second half of this is a MEASURED renderer limitation and the single
+ * most surprising thing in this file. charts-lite reads every cartesian series
+ * value through `num(v, 0)` (kernel/src/charts.ts, the bar, line and scatter
+ * paths alike). For BARS that is harmless — a null becomes a zero-height rect,
+ * which is what "absent" looks like anyway. For a LINE or a SCATTER it is the
+ * exact lie this whole module is built to avoid: the polyline dives to the axis
+ * and back, and a reader sees a month where sales collapsed.
+ *
+ * So a morph that would INTRODUCE a null — a filter that drops a category, a
+ * step that adds a series — is refused for anything but bars, and the step
+ * cuts. Bars morph; lines cut, until the kernel learns to break a polyline at a
+ * gap. Refusing the animation is a smaller cost than animating a fiction.
+ */
+export function canMorph(a: Aligned): boolean {
+ if (a.refused) return false
+ if (typeSig(a.from) !== typeSig(a.to)) return false
+ if (optionPoints(a.to) > MORPH_POINT_BUDGET || optionPoints(a.from) > MORPH_POINT_BUDGET) return false
+ if (a.introduced) {
+ const nonBar = [...seriesOf(a.from), ...seriesOf(a.to)].some((s) => s.type !== 'bar')
+ if (nonBar) return false
+ }
+ return true
+}
+
+/**
+ * One frame of a morph, at `t` in [0, 1].
+ *
+ * Numeric leaves interpolate. EVERYTHING ELSE CUTS, and the fallback is
+ * `t < 1 ? a : b` rather than the kernel's `t < 1 ? a ?? b : b` — the one
+ * character that separates this from a lie.
+ *
+ * With `a ?? b`, a category that does not exist yet (`null` on the from side)
+ * takes the destination's number for the whole tween: a bar that stands at its
+ * final height before its data exists. With `t < 1 ? a : b`, a gap stays a gap
+ * until the transition ends and then appears at its true value. Neither
+ * spelling ever produces a number BETWEEN a gap and a value, which is the rule
+ * that matters: `morphOption(null, 100, 0.5)` is `null`, never `50` and never
+ * `0`. A bar that grows out of the floor is a claim that the value used to be
+ * zero, and the data never said that.
+ *
+ * The same fallback is what makes category labels, colours and axis types cut
+ * cleanly instead of half-interpolating into nonsense.
+ */
+export function morphOption(a: unknown, b: unknown, t: number): unknown {
+ if (typeof a === 'number' && typeof b === 'number') {
+ return Number.isFinite(a) && Number.isFinite(b) ? a + (b - a) * t : (t < 1 ? a : b)
+ }
+ if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) {
+ return b.map((v, i) => morphOption(a[i], v, t))
+ }
+ if (isObj(a) && isObj(b)) {
+ const out: Record<string, unknown> = { ...b }
+ for (const k of Object.keys(b)) if (k in a) out[k] = morphOption(a[k], b[k], t)
+ return out
+ }
+ return t < 1 ? a : b
+}
+
+// --- authoring ---------------------------------------------------------------
+
+export interface CaptureSource {
+ sheet: string
+ filters?: ColumnFilter[]
+ sorts?: SortKey[]
+ chart?: ChartBinding | null
+ viz?: Viz3dBinding | null
+ camera?: StoryCamera | null
+ caption?: string
+}
+
+/**
+ * The current view, frozen as a step.
+ *
+ * Empty collections are OMITTED rather than stored as `[]`. An additive field
+ * where absent means "none" has to be absent when there is none, or every
+ * reader diffs a document that is semantically unchanged — the same rule
+ * panels.ts follows for `totals` and `frozen`, and the reason the rig's
+ * round-trip check is byte-exact.
+ */
+export function captureStep(src: CaptureSource): StoryStep {
+ const step: StoryStep = { id: mintStepId(), sheet: src.sheet }
+ if (src.caption) step.caption = src.caption
+ const filters = fromFilters(src.filters ?? [])
+ if (filters.length) step.filters = filters
+ if (src.sorts?.length) step.sorts = src.sorts.map((s) => ({ col: s.col, dir: s.dir }))
+ // A 3D binding wins: the two cannot both be on screen, and `viz` is the one
+ // the author was looking at when they pressed capture.
+ if (src.viz) step.viz = { ...src.viz }
+ else if (src.chart) step.chart = { ...src.chart, series: [...src.chart.series] }
+ if (src.camera) step.camera = { ...src.camera }
+ return step
+}
+
+/** Move a step. Out-of-range indices are a no-op, never a silent reshuffle. */
+export function moveStep(story: Story, from: number, to: number): Story {
+ const steps = story.steps
+ if (from < 0 || from >= steps.length || to < 0 || to >= steps.length || from === to) return story
+ const next = steps.slice()
+ const [s] = next.splice(from, 1)
+ next.splice(to, 0, s)
+ return { ...story, steps: next }
+}
+
+export const addStep = (story: Story | null, step: StoryStep, at?: number): Story => {
+ const steps = (story?.steps ?? []).slice()
+ steps.splice(at ?? steps.length, 0, step)
+ return { ...(story ?? {}), steps }
+}
+
+export const removeStep = (story: Story, id: string): Story =>
+ ({ ...story, steps: story.steps.filter((s) => s.id !== id) })
+
+export const editStep = (story: Story, id: string, patch: Partial<StoryStep>): Story => ({
+ ...story,
+ steps: story.steps.map((s) => {
+ if (s.id !== id) return s
+ const next: StoryStep = { ...s, ...patch }
+ // An empty caption is an ABSENT caption, for the same reason an empty
+ // filter list is absent: a key holding "" is a document that differs from
+ // one that never had the key.
+ for (const k of Object.keys(patch) as Array<keyof StoryStep>) {
+ const v = next[k]
+ if (v === undefined || v === '') delete next[k]
+ }
+ return next
+ }),
+})
+
+// --- reduced motion (a VIEWER preference, never in the document) -------------
+//
+// Same localStorage key as slides — `bento-reduce-motion` — because it is one
+// PERSON's preference about motion, not one app's setting, and a reader who
+// turned motion off in a deck should not have to find the switch again in a
+// workbook. Defaults to the OS `prefers-reduced-motion`; an explicit toggle
+// overrides it and persists per browser. It never enters the format
+// (PLATFORM §8): a document whose appearance depends on the viewer is a
+// format-level bug.
+
+const MOTION_KEY = 'bento-reduce-motion'
+
+export function readMotionPref(): boolean | null {
+ try {
+ const v = localStorage.getItem(MOTION_KEY)
+ return v === 'on' ? true : v === 'off' ? false : null
+ } catch { return null }
+}
+
+export function reduceMotionNow(): boolean {
+ const explicit = readMotionPref()
+ if (explicit !== null) return explicit
+ try { return window.matchMedia('(prefers-reduced-motion: reduce)').matches } catch { return false }
+}
+
+export function setMotionPref(on: boolean): void {
+ try { localStorage.setItem(MOTION_KEY, on ? 'on' : 'off') } catch { /* private mode */ }
+}
+
+// --- the player --------------------------------------------------------------
+
+export interface PresentOpts {
+ store: Store
+ story: Story
+ /** where to start; clamped */
+ from?: number
+ /** the grid's freshly recalculated formula columns for a sheet, if it has any */
+ computed?: (sheetId: string) => Map<string, unknown[]> | undefined
+}
+
+export interface StoryPlayer {
+ close(): void
+ next(): void
+ prev(): void
+ goTo(i: number): void
+ readonly index: number
+}
+
+const clampDuration = (v: unknown): number => {
+ const n = typeof v === 'number' && Number.isFinite(v) ? v : DEFAULT_DURATION
+ return Math.min(MAX_DURATION, Math.max(0.05, n))
+}
+
+const esc = (s: string): string =>
+ String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+/**
+ * Present the story full screen.
+ *
+ * Returns null when there is nothing to present — a caller must not have to
+ * open an empty black rectangle to discover that.
+ *
+ * NOTHING IN HERE COMMITS. The player derives its own order vectors and options
+ * and drops them on close; the workbook it was reading is byte-identical
+ * afterwards.
+ */
+export function presentStory(opts: PresentOpts): StoryPlayer | null {
+ const { store, story } = opts
+ const steps = story.steps.filter((s) => sheetOf(store.doc, s.sheet))
+ if (!steps.length) return null
+
+ let index = Math.min(Math.max(opts.from ?? 0, 0), steps.length - 1)
+ let reduce = reduceMotionNow()
+
+ const overlay = document.createElement('div')
+ overlay.className = 'ds-overlay'
+ overlay.tabIndex = -1
+ overlay.innerHTML =
+ `<div class="ds-stage"></div>` +
+ `<div class="ds-caption"><div class="ds-cap-text"></div><div class="ds-chips"></div></div>` +
+ `<div class="ds-bar">` +
+ `<button class="ds-btn" data-nav="prev" title="${esc(t('Previous'))}">‹</button>` +
+ `<div class="ds-dots"></div>` +
+ `<button class="ds-btn" data-nav="next" title="${esc(t('Next'))}">›</button>` +
+ `<span class="ds-count"></span>` +
+ `<button class="ds-btn" data-nav="motion" title="${esc(t('Reduced motion (M)'))}">⏸</button>` +
+ `<button class="ds-btn" data-nav="close" title="${esc(t('Close (Esc)'))}">✕</button>` +
+ `</div>`
+ document.body.appendChild(overlay)
+ overlay.classList.toggle('reduce-motion', reduce)
+
+ const stage = overlay.querySelector<HTMLElement>('.ds-stage')!
+ const capText = overlay.querySelector<HTMLElement>('.ds-cap-text')!
+ const chips = overlay.querySelector<HTMLElement>('.ds-chips')!
+ const dots = overlay.querySelector<HTMLElement>('.ds-dots')!
+ const count = overlay.querySelector<HTMLElement>('.ds-count')!
+
+ // Real fullscreen if the browser allows it; a denied request degrades to a
+ // fixed overlay filling the tab, which is the same bargain slides makes and
+ // is a perfectly good sharing/testing mode.
+ void overlay.requestFullscreen?.().catch(() => {})
+
+ const clock = { t: 0 }
+ let teardown: (() => void) | null = null
+ /** the option currently on screen, for the next transition to morph FROM */
+ let showing: Opt | null = null
+ let closed = false
+
+ const size = () => ({ w: stage.clientWidth || 960, h: stage.clientHeight || 540 })
+
+ const paintFrame = (opt: Opt) => {
+ const { w, h } = size()
+ stage.innerHTML = chartSnapshotSvg({ w, h, option: opt })
+ }
+
+ /** Land on an option: a LIVE chart, so tooltips and wheel-zoom work at rest. */
+ const settle = (opt: Opt, fromOpt?: Opt) => {
+ teardown?.()
+ const { w, h } = size()
+ teardown = mountChart({ w, h, option: opt }, stage, fromOpt)
+ showing = opt
+ }
+
+ const settle3d = (sheet: TableSheet, step: StoryStep) => {
+ teardown?.()
+ const computed = opts.computed?.(sheet.id)
+ // The 3D scene reads the whole sheet: `buildScene` takes columns, not an
+ // order vector, so a step's filter cannot narrow it. Recorded under KNOWN
+ // GAPS rather than faked by pre-filtering into a synthetic sheet, which
+ // would be a second copy of the data — rule 2.
+ const scene = buildScene(sheet, step.viz!, computed)
+ teardown = mountViz3d(stage, scene, {
+ azimuth: step.camera?.azimuth,
+ elevation: step.camera?.elevation,
+ background: '#0e1420',
+ })
+ showing = null
+ }
+
+ const render = (animate: boolean) => {
+ const step = steps[index]
+ const sheet = sheetOf(store.doc, step.sheet)!
+ anim.killTweensOf(clock)
+
+ capText.textContent = step.caption ?? ''
+ capText.classList.toggle('empty', !step.caption)
+ chips.innerHTML = (step.highlight?.values ?? [])
+ .map((v) => `<span class="ds-chip">${esc(v == null ? t('(blank)') : String(v))}</span>`)
+ .join('')
+ count.textContent = `${index + 1} / ${steps.length}`
+ dots.innerHTML = steps
+ .map((_, i) => `<i class="ds-dot${i === index ? ' on' : ''}" data-go="${i}"></i>`)
+ .join('')
+
+ if (step.viz) { settle3d(sheet, step); return }
+
+ const to = stepOption(sheet, step, opts.computed?.(sheet.id))
+ if (!to) {
+ teardown?.(); teardown = null
+ showing = null
+ stage.innerHTML = `<div class="ds-empty">${esc(t('This step has no chart binding.'))}</div>`
+ return
+ }
+
+ const wantsMorph = animate && !reduce && (step.transition ?? 'morph') === 'morph' && showing
+ if (!wantsMorph) { settle(to); return }
+
+ const aligned = alignOptions(showing!, to)
+ if (!canMorph(aligned)) {
+ // A shape the interpolator refuses — a pie, a type change, too many
+ // points, or a null a line chart would draw as a plunge to zero. Hand
+ // both options to the kernel, which cross-fades and sweeps the new type
+ // in without ever claiming a number.
+ settle(to, showing!)
+ return
+ }
+ clock.t = 0
+ const a = aligned.from
+ const b = aligned.to
+ anim.to(clock, {
+ t: 1,
+ duration: clampDuration(step.duration),
+ ease: 'power2.inOut',
+ onUpdate: () => { if (!closed) paintFrame(morphOption(a, b, clock.t) as Opt) },
+ onComplete: () => { if (!closed) settle(to) },
+ })
+ }
+
+ const goTo = (i: number) => {
+ if (closed) return
+ const n = Math.min(Math.max(i, 0), steps.length - 1)
+ if (n === index) return
+ index = n
+ render(true)
+ }
+
+ const onKey = (e: KeyboardEvent) => {
+ const k = e.key
+ if (k === 'Escape') { e.preventDefault(); close(); return }
+ if (k === 'ArrowRight' || k === ' ' || k === 'PageDown') { e.preventDefault(); goTo(index + 1); return }
+ if (k === 'ArrowLeft' || k === 'PageUp') { e.preventDefault(); goTo(index - 1); return }
+ if (k === 'Home') { e.preventDefault(); goTo(0); return }
+ if (k === 'End') { e.preventDefault(); goTo(steps.length - 1); return }
+ if (k === 'm' || k === 'M') { e.preventDefault(); toggleMotion() }
+ }
+
+ const toggleMotion = () => {
+ reduce = !reduce
+ setMotionPref(reduce)
+ overlay.classList.toggle('reduce-motion', reduce)
+ // Re-settle: a killed tween would otherwise strand the chart mid-morph, at
+ // numbers that are in no step of the story. slides re-settles for exactly
+ // this reason (present.ts setReduceMotion).
+ anim.killTweensOf(clock)
+ render(false)
+ }
+
+ overlay.addEventListener('click', (e) => {
+ const el = e.target as HTMLElement
+ const nav = el.closest<HTMLElement>('[data-nav]')?.dataset.nav
+ if (nav === 'next') goTo(index + 1)
+ else if (nav === 'prev') goTo(index - 1)
+ else if (nav === 'close') close()
+ else if (nav === 'motion') toggleMotion()
+ const go = el.closest<HTMLElement>('[data-go]')?.dataset.go
+ if (go !== undefined) goTo(Number(go))
+ })
+
+ // A resize changes the chart's pixel box, and every rendered frame is sized
+ // to it. Re-settling without animation is right: the reader did not ask for a
+ // transition by dragging a window edge.
+ const onResize = () => { if (!closed) render(false) }
+ window.addEventListener('resize', onResize)
+ document.addEventListener('keydown', onKey, true)
+
+ const onFsChange = () => {
+ // Leaving fullscreen ENDS the show, the way it does in slides — dropping
+ // silently into a tab-filling overlay leaves the reader in a mode nobody
+ // asked for.
+ if (!document.fullscreenElement && !closed) close()
+ }
+ document.addEventListener('fullscreenchange', onFsChange)
+
+ function close(): void {
+ if (closed) return
+ closed = true
+ anim.killTweensOf(clock)
+ teardown?.()
+ teardown = null
+ document.removeEventListener('keydown', onKey, true)
+ document.removeEventListener('fullscreenchange', onFsChange)
+ window.removeEventListener('resize', onResize)
+ if (document.fullscreenElement === overlay) void document.exitFullscreen?.().catch(() => {})
+ overlay.remove()
+ }
+
+ render(false)
+ overlay.focus()
+
+ return {
+ close,
+ next: () => goTo(index + 1),
+ prev: () => goTo(index - 1),
+ goTo,
+ get index() { return index },
+ }
+}
+
+// --- authoring UI ------------------------------------------------------------
+
+export interface StorySource {
+ store: Store
+ /** the sheet the grid is showing */
+ sheetId: () => string
+ filters: () => ColumnFilter[]
+ sorts: () => SortKey[]
+ /** the 2D binding on screen, if any */
+ chart: () => ChartBinding | null
+ /** the 3D binding on screen, if any */
+ viz?: () => Viz3dBinding | null
+ computed?: (sheetId: string) => Map<string, unknown[]> | undefined
+}
+
+/**
+ * The story panel: capture, reorder, caption, present.
+ *
+ * DELIBERATELY MODEST. Presenting is the feature; this is the four verbs that
+ * make presenting reachable. Every edit goes through `writeStory`, so the story
+ * is document data and rides in the file like everything else.
+ */
+export function openStoryEditor(src: StorySource): HTMLElement {
+ document.querySelector('.ds-editor')?.remove()
+ const el = document.createElement('div')
+ el.className = 'ds-editor'
+ document.body.appendChild(el)
+
+ const read = (): Story => readStory(src.store.doc) ?? { steps: [] }
+
+ const draw = () => {
+ const story = read()
+ const rows = story.steps.map((s, i) => {
+ const sheet = sheetOf(src.store.doc, s.sheet)
+ const what = s.viz ? `3D ${esc(String(s.viz.kind))}` : s.chart ? esc(String(s.chart.kind)) : t('no chart')
+ const bits = [
+ sheet ? esc(sheet.name) : `<b class="ds-warn">${esc(t('missing sheet'))}</b>`,
+ what,
+ s.filters?.length ? `${s.filters.length}f` : '',
+ s.sorts?.length ? `${s.sorts.length}↕` : '',
+ ].filter(Boolean).join(' · ')
+ return (
+ `<li class="ds-step" data-id="${esc(s.id)}">` +
+ `<span class="ds-n">${i + 1}</span>` +
+ `<div class="ds-fields">` +
+ `<input class="ds-cap-in" placeholder="${esc(t('Caption'))}" value="${esc(s.caption ?? '')}">` +
+ `<span class="ds-meta">${bits}</span>` +
+ `</div>` +
+ `<button class="ds-btn" data-act="up" title="${esc(t('Move up'))}">↑</button>` +
+ `<button class="ds-btn" data-act="down" title="${esc(t('Move down'))}">↓</button>` +
+ `<button class="ds-btn" data-act="del" title="${esc(t('Remove step'))}">✕</button>` +
+ `</li>`
+ )
+ }).join('')
+
+ el.innerHTML =
+ `<div class="ds-ed-head"><b>${esc(t('Data story'))}</b>` +
+ `<button class="ds-btn" data-act="shut">✕</button></div>` +
+ (story.steps.length
+ ? `<ol class="ds-steps">${rows}</ol>`
+ : `<p class="ds-hint">${esc(t('Filter, sort and chart the sheet, then capture it as the first step.'))}</p>`) +
+ `<div class="ds-ed-foot">` +
+ `<button class="ds-btn ds-primary" data-act="capture">${esc(t('Capture current view'))}</button>` +
+ `<button class="ds-btn" data-act="present"${story.steps.length ? '' : ' disabled'}>${esc(t('Present ▸'))}</button>` +
+ `</div>`
+ }
+
+ el.addEventListener('click', (e) => {
+ const btn = (e.target as HTMLElement).closest<HTMLElement>('[data-act]')
+ if (!btn) return
+ const act = btn.dataset.act
+ const id = btn.closest<HTMLElement>('.ds-step')?.dataset.id
+ const story = read()
+ const at = id ? story.steps.findIndex((s) => s.id === id) : -1
+
+ if (act === 'shut') { el.remove(); return }
+ if (act === 'capture') {
+ writeStory(src.store, addStep(story, captureStep({
+ sheet: src.sheetId(),
+ filters: src.filters(),
+ sorts: src.sorts(),
+ chart: src.chart(),
+ viz: src.viz?.() ?? null,
+ })))
+ draw()
+ return
+ }
+ if (act === 'present') {
+ el.remove()
+ presentStory({ store: src.store, story: read(), computed: src.computed })
+ return
+ }
+ if (at < 0) return
+ if (act === 'up') writeStory(src.store, moveStep(story, at, at - 1))
+ else if (act === 'down') writeStory(src.store, moveStep(story, at, at + 1))
+ else if (act === 'del') writeStory(src.store, removeStep(story, id!))
+ draw()
+ })
+
+ // Captions commit on change, not on every keystroke: the store's typing run
+ // covers a CELL, and a document-level write per character would push an undo
+ // entry per character with it.
+ el.addEventListener('change', (e) => {
+ const input = e.target as HTMLInputElement
+ if (!input.classList.contains('ds-cap-in')) return
+ const id = input.closest<HTMLElement>('.ds-step')?.dataset.id
+ if (!id) return
+ writeStory(src.store, editStep(read(), id, { caption: input.value.trim() }))
+ })
+
+ draw()
+ return el
+}
+
+/** Wire a topbar button. Returns a detach, for symmetry with the rest of dash. */
+export function installStory(src: StorySource & { button: HTMLElement }): () => void {
+ const onClick = () => { openStoryEditor(src) }
+ src.button.addEventListener('click', onClick)
+ return () => src.button.removeEventListener('click', onClick)
+}
+
+// --- KNOWN GAPS --------------------------------------------------------------
+//
+// Written down rather than left to be discovered:
+//
+// * THE 3D CAMERA CUTS; IT DOES NOT FLY. `mountViz3d` builds its camera
+// internally (`frameCamera(scene, opts)`) and returns only a teardown, so
+// there is no handle to tween. A step's `camera` is applied at mount, which
+// is a cut. Flying it needs viz3d.ts to hand back the `Orbit` and a redraw
+// request; remounting per frame would recompile shaders and rebuild every
+// buffer sixty times a second, which is not a transition, it is a stall.
+// * A 3D STEP IGNORES ITS FILTER. `buildScene` reads the sheet's columns
+// whole. Narrowing it honestly needs the same `computed`-map trick the 2D
+// path uses, which needs `buildScene` to accept an order vector.
+// * HIGHLIGHT IS NAMED, NOT PAINTED. charts-lite colours by SERIES, not by
+// item, so a subset cannot be tinted inside one series. The two workarounds
+// are both worse than saying so: splitting into two series halves every bar
+// (grouped-bar layout reserves a slot per series) and, for a line or
+// scatter, writes nulls that the renderer draws as a plunge to zero. So the
+// highlighted values are listed under the caption and the chart is left
+// truthful.
+// * LINE AND SCATTER STEPS CUT when a filter changes the categories. See
+// `canMorph`.
diff --git a/dash/src/styles.css b/dash/src/styles.css
index 353034c5..c0e98134 100644
--- a/dash/src/styles.css
+++ b/dash/src/styles.css
@@ -2,16 +2,182 @@
Copyright (c) 2026 The Bento authors
bento/dash — the whole interface. One stylesheet; it ships deflated. */
+/* ————— THE PALETTE, AND THE THEME SWITCH —————
+ Two grounds, one set of names. Every colour in dash — here, in panels.css,
+ pivot.css, dashboard.css, story.css, saveui.css and about.css — resolves
+ through a token below, and no component file states a colour inside a media
+ query. Adding a surface means reaching for a token; if none fits, add one
+ HERE with both of its values rather than writing a hex where it is used.
+
+ THE THEME IS A VIEWER PREFERENCE AND NEVER ENTERS THE WORKBOOK — the same
+ rule as the interface language and reduced motion (PLATFORM §8). Two people
+ opening one file may sit in different themes exactly as they may read it in
+ different languages. `doc.theme` in model.ts is a DIFFERENT thing: that is
+ the document's own palette, it travels in the file, and it colours the
+ charts and the static preview. Do not conflate them; nothing here is ever
+ read from or written to the document.
+
+ HOW THE SWITCH WORKS. `light-dark()` resolves against the element's used
+ `color-scheme`, so a token's two values sit on ONE line where they can be
+ compared — and there is no second copy of the palette inside a
+ `prefers-color-scheme` block to fall out of step with the first. The default
+ `light dark` follows the OS; an explicit choice pins `color-scheme` through
+ a single rule about.ts injects, and it wins in BOTH directions (a reader on
+ a dark desktop who wants a light sheet is as real a case as the reverse).
+
+ `color-scheme` is also what turns the scrollbars, the caret, the native
+ selects and the resize grippers dark, and it is declared HERE rather than in
+ index.html's <meta name="color-scheme"> because a CSS declaration on the
+ root element beats that meta — verified in the browser, both directions.
+
+ WHICH TOKENS VARY: exactly the ones written as a `light-dark()` pair. The
+ plain values — the brand amber, the radii, the type scale, the row height —
+ are the same object on both grounds and are deliberately NOT paired. The
+ amber is the interesting one: it reads ON the dark ground at 9.25:1, so the
+ accent does not change when the lights go out. It is 2.02:1 on white, which
+ is why it is only ever a border, a badge or a mark there and never body
+ text — that was already true and the dark ground does not change it. */
:root {
- --ink: #1e2a3a;
- --muted: #64748b;
- --line: #e3e8ef;
- --line-strong: #cbd5e1;
+ color-scheme: light dark;
+
+ /* ————— ground and chrome ————— */
+ --bg: light-dark(#ffffff, #0e1319); /* the page, and the sheet itself */
+ --panel: light-dark(#f8fafc, #161c24); /* chrome bands: top bar, status bar */
+ /* Raised opaque surfaces — menus, dialogs, popovers, inputs, buttons, the
+ side panels. On white it IS the page colour; on dark it has to lift off
+ the page or a menu floating over the grid has no edge but its shadow, and
+ shadows barely read on a dark ground. */
+ --surface: light-dark(#ffffff, #1b222c);
+ --hover: light-dark(#f1f5f9, #26303d); /* menu rows, buttons, list items */
+ /* A wash for hover states drawn OVER unknown content (a chart band, a table
+ row that may already be tinted). Alpha, not a colour, for that reason. */
+ --wash: light-dark(rgb(0 0 0 / 0.04), rgb(255 255 255 / 0.07));
+ --line: light-dark(#e3e8ef, #1f2731);
+ --line-strong: light-dark(#cbd5e1, #2f3a49);
+ --ink: light-dark(#1e2a3a, #d6dee9);
+ --muted: light-dark(#64748b, #93a0b2);
--accent: #f7a600;
- --bg: #ffffff;
- --panel: #f8fafc;
- --sel: #fff7e6;
- --row-h: 30px;
+ --slash: #ff9e8a; /* the wordmark's peach */
+ --scrim: light-dark(rgb(20 30 45 / 0.42), rgb(2 5 9 / 0.66));
+ --shadow-pop: light-dark(0 12px 32px rgb(15 23 42 / 0.16), 0 12px 32px rgb(0 0 0 / 0.55));
+ --shadow-dialog: light-dark(0 24px 64px rgb(15 23 42 / 0.34), 0 24px 64px rgb(0 0 0 / 0.7));
+
+ /* ————— semantic ————— */
+ --warn-bg: light-dark(#fffbeb, #221b0d); /* the findings strip */
+ --warn-ink: light-dark(#b45309, #f0b357);
+ --warn-chip: light-dark(#fef3c7, #3a2e10);
+ --err-ink: light-dark(#b91c1c, #ff9b8f);
+ --err-bg: light-dark(#fef2f2, #2b1618);
+ --up-ink: light-dark(#1f8a5b, #4fbf8b);
+ --down-ink: light-dark(#c0503c, #f08a78);
+ /* The toast inverts against the app on light and merely lifts on dark:
+ a white slab on a dark sheet is a flashbulb, not a status line. */
+ --toast-bg: light-dark(#1e2a3a, #2b3543);
+ --toast-ink: light-dark(#ffffff, #e8edf5);
+ /* Accent-tinted surfaces — the active sheet, a filter chip. Distinct from
+ --sel: this one means "this is the chosen one", not "this is selected
+ data", and the two stopped being the same colour when selection went
+ blue. */
+ --accent-wash: light-dark(#fdf0d6, #38290c);
+ /* NOT theme-varying, deliberately: the ink that goes over a cell the
+ DOCUMENT has coloured. See the conditional-formatting section below. */
+ --ink-on-fill: #1e2a3a;
+ /* How much of the sheet a data bar lets through. MEASURED: at 0.55 the
+ default amber bar over #0e1319 comes to rgb(142,100,11) and the sheet's
+ own ink on top of it is 3.9:1 — under AA on the one figure a data bar
+ exists to draw attention to. At 0.45 the same bar is 5.0:1 and still reads
+ as the same bar. (A rule may name any colour it likes, so this makes the
+ DEFAULT safe; it cannot promise anything about an arbitrary one.)
+
+ WRITTEN THE LONG WAY, and it is the only token that is: `light-dark()` is
+ a <color> function and nothing else. Fed a number it does not fail
+ loudly — the declaration is simply invalid, `opacity` falls back to its
+ initial 1, and the bar goes fully opaque. That is exactly what happened
+ here, and the audit caught it at 1.49:1. Any future NON-COLOUR token that
+ varies by theme needs this shape too. */
+ --bar-opacity: 0.55;
+ /* Chart text. charts-lite (kernel/src/charts.ts) bakes a literal #6B7280
+ into every axis label, legend entry and pie label unless the OPTION says
+ otherwise, and dash's chart.ts does not say otherwise — so on the dark
+ ground the labels came out at 3.6:1 and the axis was unreadable. The light
+ value here IS the kernel's default, so light-theme charts are untouched;
+ see the rule near .dx-chart-body for why CSS can reach them at all. */
+ --chart-ink: light-dark(#6b7280, #a7b3c4);
+
+ /* COUPLED TO grid.ts `ROW_H`, and there is no mechanism keeping them honest.
+ The body is virtualised: JS positions every row at `top: i * ROW_H` as an
+ inline style, so this variable only sizes the cell that lands there.
+ Setting it to 26 to get Excel's density left the rows 30px apart with a
+ 4px transparent band between them — the gridlines stopped meeting and the
+ grid looked perforated. Change one and you must change the other. */
+ /* FALLBACK ONLY — grid.ts writes this from its ROW_H constant when it
+ mounts, because the row boxes are positioned from that constant and the
+ two must never disagree. Editing it here alone changes nothing. */
+ --row-h: 20px;
+
+ /* ————— the grid's own greys —————
+ Split out from --line because they answer a different question. --line is
+ chrome: the edge of a panel, where one surface stops. These are the GRID,
+ and a spreadsheet's gridlines are the strongest signal that what you are
+ looking at is a spreadsheet and not a table on a web page. At #e3e8ef
+ dash's grid had vertical rules only, no horizontal ones at all, and read as
+ a web table with zebra striping — which is what it was. Excel and Sheets
+ both rule both axes and neither stripes.
+
+ THE WEIGHT CAME DOWN. A full 1px lattice at #d8dee7 on both axes is the
+ look of a spreadsheet from 2006: at that contrast the rules compete with
+ the figures, and a screen of numbers reads as a screen of boxes. Measured
+ against the paper, the rule drops from 1.35:1 to 1.14:1 — still a lattice
+ at any zoom, no longer a cage. The header band
+ came down with it: hierarchy in the header is carried by TYPE (11.5px
+ semibold, tracked, darker ink) rather than by a grey fill, which is the
+ one change that dates a spreadsheet fastest.
+
+ On the dark ground the pair invert about the sheet: lines slightly ABOVE
+ the page, the header band slightly above the lines. Ruling a dark sheet
+ with a darker line would work, but every scrolled seam then disappears
+ into the background the moment a shadow lands on it. */
+ --grid-line: light-dark(#edf0f4, #212a35);
+ --grid-head: light-dark(#fbfcfd, #151c25); /* the header/gutter band */
+ --grid-head-ink: light-dark(#4a5568, #a9b6c7);
+ --grid-head-on: light-dark(#dbe7fb, #1d3050); /* a selected row/column header */
+
+ /* ————— selection —————
+ Cool, and deliberately NOT the brand amber. The amber tint used to sit on
+ top of amber conditional-format data bars, so a selected cell and a cell
+ the document had coloured were the same warm smear; the two things are
+ unrelated and now cannot be confused. --sel-ring is the cursor cell's ring
+ and the range outline; --sel is the range fill. */
+ --sel: light-dark(#eef4ff, #16243c);
+ --sel-ring: light-dark(#2563eb, #3b82f6);
+
+ /* ————— one scale, five surfaces —————
+ The pivot, the dashboard, the story editor, the save menu and the About
+ dialog were each written separately and each picked its own radii, shadows
+ and caption size. These are the agreed values; every one of those files
+ now reads them rather than restating a number. */
+ --radius: 7px; /* controls: buttons, inputs, chips */
+ --radius-lg: 10px; /* floating surfaces: menus, popovers, cards */
+ --radius-xl: 14px; /* dialogs */
+ /* the two shadows are theme-varying and live in the palette block above */
+ --fs-ui: 13px; /* control and menu text */
+ --fs-small: 11.5px; /* captions, sub-labels, meta */
+ --fs-micro: 11px; /* section headers, badges */
+}
+
+/* THE EXPLICIT OVERRIDE IS NOT IN THIS FILE, and that is not an oversight.
+ It is a `:root:root{color-scheme:…}` rule injected at boot by about.ts
+ inside a `data-bento-transient` <style>, because the natural version — an
+ attribute on <html> plus `:root[data-theme=…]` rules here — is CLONED INTO
+ EVERY SAVED FILE by capturePristine() and would force one reader's
+ preference on everyone who opened the workbook afterwards. The whole story
+ is in about.ts; what matters here is that flipping `color-scheme` is all an
+ override does, and every `light-dark()` pair above follows it.
+
+ What DOES belong here is the OS default for the one token light-dark()
+ cannot carry. */
+@media (prefers-color-scheme: dark) {
+ :root { --bar-opacity: 0.45; }
}
* { box-sizing: border-box; }
@@ -31,50 +197,251 @@ html, body {
.dx-bar {
display: flex;
align-items: center;
- gap: 10px;
- padding: 8px 12px;
- border-bottom: 1px solid var(--line);
+ gap: 8px;
+ padding: 7px 12px;
+ border-bottom: 1px solid var(--line-strong);
background: var(--panel);
flex: 0 0 auto;
+ min-width: 0;
/* the notch: the app positions its own chrome and never asks the browser to pad it */
- padding-top: max(8px, env(safe-area-inset-top));
+ padding-top: max(7px, env(safe-area-inset-top));
+}
+.dx-mark {
+ font-weight: 650;
+ letter-spacing: -0.01em;
+ white-space: nowrap;
+ flex: 0 0 auto;
}
-.dx-mark { font-weight: 650; letter-spacing: -0.01em; white-space: nowrap; }
-.dx-mark span { color: #ff9e8a; }
+.dx-slash { color: var(--slash); }
.dx-title {
font: inherit;
font-weight: 600;
border: 1px solid transparent;
- border-radius: 6px;
+ border-radius: var(--radius);
padding: 4px 8px;
- min-width: 8ch;
- flex: 1 1 auto;
+ /* `flex: 0 1` and never `1 1`: the title is elastic, but it is not entitled
+ to the slack — the buttons to its right are, and a growing title is what
+ pushes them off the end. */
+ flex: 0 1 240px;
+ min-width: 60px;
background: transparent;
color: inherit;
}
.dx-title:hover { border-color: var(--line-strong); }
-.dx-title:focus { outline: none; border-color: var(--accent); background: #fff; }
+.dx-title:focus { outline: none; border-color: var(--accent); background: var(--surface); }
+
+.dx-group { display: flex; align-items: center; gap: 6px; flex: 0 0 auto; }
+/* everything after the insert group is pushed to the far end */
+.dx-bar-end { margin-inline-start: auto; }
+
.dx-btn {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
font: inherit;
- padding: 5px 11px;
+ font-size: var(--fs-ui);
+ padding: 5px 10px;
border: 1px solid var(--line-strong);
- border-radius: 7px;
- background: #fff;
+ border-radius: var(--radius);
+ background: var(--surface);
color: inherit;
cursor: pointer;
white-space: nowrap;
+ flex: 0 0 auto;
}
-.dx-btn:hover { background: var(--panel); border-color: var(--muted); }
+.dx-btn:hover { background: var(--hover); border-color: var(--muted); }
.dx-btn:active { transform: translateY(0.5px); }
.dx-btn[disabled] { opacity: 0.45; cursor: default; }
-.dx-ver { color: var(--muted); font-size: 12px; font-variant-numeric: tabular-nums; }
-.dx-dirty { color: var(--accent); font-size: 18px; line-height: 1; }
+.dx-btn:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+.dx-i { flex: 0 0 auto; }
+/* the caret on a dropdown trigger is a hint, not a peer of the icon */
+.dx-dd-trig > .dx-i:last-child { opacity: 0.5; margin-inline-start: -2px; }
+
+.dx-ver {
+ color: var(--muted);
+ font-size: 12px;
+ font-variant-numeric: tabular-nums;
+ flex: 0 0 auto;
+}
+
+/* Unsaved-changes dot: it badges SAVE rather than floating in the bar, where
+ an amber bullet next to the title explained nothing. Absolutely positioned,
+ so it costs the button no width — which matters, because Save is the control
+ that has to survive every width. */
+.dx-btn-save { position: relative; }
+/* Scoped through .dx-bar .dx-btn-save, not written bare, because the dot IS a
+ <span> inside a bar button and the narrow-window rule below hides exactly
+ that. A bare `.dx-dirty { display: block }` lost the specificity duel and the
+ dot measured 0×0 at every width under 1280 — i.e. the unsaved-changes signal
+ silently vanished on the widths that need it most. */
+.dx-bar .dx-btn-save > .dx-dirty {
+ display: block;
+ position: absolute;
+ top: 3px;
+ inset-inline-end: 3px;
+ width: 7px;
+ height: 7px;
+ border-radius: 50%;
+ background: var(--accent);
+ pointer-events: none;
+}
+.dx-bar .dx-btn-save > .dx-dirty[hidden] { display: none; }
+
+/* ————— top-bar dropdowns —————
+ One panel style, shared with .dx-pop and the save menu. */
+.dx-dd { position: relative; flex: 0 0 auto; }
+.dx-menu {
+ display: none;
+ position: absolute;
+ top: calc(100% + 6px);
+ inset-inline-start: 0;
+ z-index: 60;
+ min-width: 200px;
+ flex-direction: column;
+ gap: 1px;
+ padding: 5px;
+ background: var(--surface);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-lg);
+ box-shadow: var(--shadow-pop);
+}
+.dx-dd.open > .dx-menu { display: flex; }
+.dx-menu .dx-btn {
+ width: 100%;
+ justify-content: flex-start;
+ border: 0;
+ background: transparent;
+ padding: 6px 9px;
+}
+.dx-menu .dx-btn:hover { background: var(--hover); }
+.dx-menu .dx-i { color: var(--muted); }
+/* Labels ALWAYS show inside an OPEN menu panel. The narrow-window rule below
+ strips them from bar buttons, and the first pass stripped them here too —
+ which left an icon-only mystery menu. slides hit this and wrote the same
+ exception; what slides did NOT have is dash's insert group, whose buttons
+ live inside a .dx-menu that is a plain inline row until 900px. Written with
+ `!important` the exception forced labels back on in that row too, so the bar
+ never actually shrank (measured: the group stayed 516px wide at 1100px).
+ Keying on `.open` says the real thing — a FLOATING PANEL is what needs
+ words — and wins on specificity without reaching for !important. */
+.dx-bar .dx-dd.open > .dx-menu .dx-btn > span { display: inline; }
+.dx-menu-sep { height: 1px; background: var(--line); margin: 4px 6px; }
+/* the data menu hangs off a button near the right edge, so it grows inward */
+.dx-data-dd > .dx-menu { inset-inline-start: auto; inset-inline-end: 0; }
+
+/* ————— responsive top bar —————
+ LABELS GIVE WAY, THEN GROUPS FOLD. Never a scrollbar, and never a
+ horizontally scrolling body — the bar carries Save, and a control you have
+ to scroll to reach is a control that is missing.
+
+ Wide: the six insert buttons sit in the bar as a plain row; the same markup
+ is the dropdown's contents below 900px, so nothing is reparented and no
+ listener is ever rebound. */
+.dx-insert-dd { display: flex; align-items: center; gap: 6px; }
+.dx-insert-dd > .dx-dd-trig { display: none; }
+.dx-insert-dd > .dx-menu {
+ display: flex;
+ flex-direction: row;
+ position: static;
+ gap: 6px;
+ min-width: 0;
+ padding: 0;
+ border: 0;
+ background: none;
+ box-shadow: none;
+}
+/* …and as a row they are ordinary bar buttons again, not menu rows */
+.dx-insert-dd > .dx-menu > .dx-btn {
+ width: auto;
+ border: 1px solid var(--line-strong);
+ background: var(--surface);
+ padding: 5px 10px;
+}
+.dx-insert-dd > .dx-menu > .dx-btn:hover { background: var(--hover); border-color: var(--muted); }
+.dx-insert-dd > .dx-menu .dx-i { color: inherit; }
+
+/* 1280, not slides' 1200. MEASURED: with every label showing, the insert group
+ ends at x=860 and the end group starts at x=1031 — 171px of slack in a
+ 1440px window, so the fully-labelled bar needs ~1270px. A 1200px breakpoint
+ would have let the two groups collide for the 70px in between. Breakpoints
+ are measurements, not round numbers. */
+@media (max-width: 1280px) {
+ /* icons and tooltips take over. Save keeps its word: it is the control the
+ user names when it goes missing, and an unlabelled floppy is a guess. */
+ .dx-bar .dx-btn > span { display: none; }
+ .dx-bar .dx-btn-save > .dx-save-lab { display: inline; }
+ .dx-bar { gap: 6px; }
+ .dx-btn { padding: 5px 8px; }
+ .dx-title { flex: 0 1 200px; }
+}
+
+/* 900, and again it is a measurement: at 1041px the icon-only insert row still
+ left 214px of slack, so folding it there threw away a whole toolbar for
+ nothing. The row needs 827px; 900 keeps ~73px of margin over that. */
+@media (max-width: 900px) {
+ /* below this the six icon buttons no longer clear the end group, so they
+ become one + menu. Their labels come back inside it. */
+ .dx-insert-dd { display: block; position: relative; }
+ .dx-insert-dd > .dx-dd-trig { display: inline-flex; }
+ .dx-insert-dd > .dx-menu {
+ display: none;
+ position: absolute;
+ flex-direction: column;
+ gap: 1px;
+ min-width: 200px;
+ padding: 5px;
+ border: 1px solid var(--line-strong);
+ background: var(--surface);
+ box-shadow: var(--shadow-pop);
+ }
+ .dx-insert-dd.open > .dx-menu { display: flex; }
+ .dx-insert-dd > .dx-menu > .dx-btn {
+ width: 100%;
+ border: 0;
+ background: transparent;
+ padding: 6px 9px;
+ }
+ .dx-insert-dd > .dx-menu .dx-i { color: var(--muted); }
+}
+
+@media (max-width: 860px) {
+ /* the version chip is the least load-bearing thing in the bar, and About is
+ now a real button, so the chip is no longer anybody's only way in */
+ .dx-ver { display: none; }
+}
+
+@media (max-width: 760px) {
+ .dx-mark-b { display: none; } /* "/dash" — the peach slash IS the mark */
+}
+
+@media (max-width: 700px) {
+ .dx-bar { gap: 4px; padding-left: 8px; padding-right: 8px; }
+ /* HIG touch targets. A 30px icon button is a mis-tap on glass. */
+ .dx-bar > .dx-group > .dx-btn,
+ .dx-bar > .dx-group .dx-dd-trig,
+ .dx-bar > .dx-insert-dd > .dx-dd-trig { min-height: 38px; justify-content: center; }
+ .dx-bar .dx-btn:not(.dx-btn-save):not(.dxs-caret) { min-width: 38px; }
+ .dx-bar .dx-menu .dx-btn { min-width: 0; min-height: 0; } /* menu rows are text */
+ /* the trigger carets are the first thing to go: at this width the panel that
+ opens is explanation enough, and 15px each is a whole button's worth */
+ .dx-dd-trig > .dx-i:last-child { display: none; }
+ .dx-title { flex: 0 1 90px; min-width: 36px; }
+}
+
+/* The smallest screen anyone still ships (320px). MEASURED there: the bar came
+ to 348px and ⓘ hung 28px past the edge. The wordmark is the only thing left
+ on the bar that does no work — and About, which is where "what IS this file"
+ lives, is precisely what it was standing in front of. So the brand goes and
+ the button stays. Everything else here is load-bearing. */
+@media (max-width: 380px) {
+ .dx-mark { display: none; }
+}
/* ————— findings: what import refused to decide ————— */
.dx-findings {
flex: 0 0 auto;
border-bottom: 1px solid var(--line);
- background: #fffbeb;
+ background: var(--warn-bg);
padding: 8px 12px;
font-size: 13px;
display: grid;
@@ -96,7 +463,7 @@ html, body {
border-left: 1px solid var(--line);
display: flex;
flex-direction: column;
- background: #fff;
+ background: var(--bg);
min-width: 0;
}
.dx-chart[hidden] { display: none; }
@@ -118,8 +485,42 @@ html, body {
white-space: nowrap;
}
.dx-chart-head .dx-btn { padding: 3px 8px; font-size: 12px; }
-.dx-chart-body { flex: 1 1 auto; min-height: 0; padding: 6px; }
+/* A COLUMN, not a block. This panel hosts three different things — a chart, a
+ 3D scene and a whole pivot table — and only the chart is happy sizing itself
+ from a 100% height. `.dxp` is a flex column that caps its own scroller at the
+ panel height; in a block parent it had no height to cap against and the pivot
+ ran off the bottom of the panel instead of scrolling inside it. */
+.dx-chart-body {
+ flex: 1 1 auto;
+ min-height: 0;
+ padding: 6px;
+ display: flex;
+ flex-direction: column;
+}
+.dx-chart-body > * { flex: 1 1 auto; min-height: 0; }
.dx-chart-body svg { display: block; width: 100%; height: 100%; }
+/* CHART TEXT IS REACHABLE FROM CSS, and this is the only reason the dark theme
+ did not need a change inside the chart engine: charts-lite writes its label
+ colour as the `fill` PRESENTATION ATTRIBUTE, and any author rule beats a
+ presentation attribute. Every piece of text in a charts-lite plot takes the
+ same colour (axis labels, legend, pie labels all default to one grey), so a
+ blanket rule cannot recolour something that was meant to differ. Marks are
+ `rect`/`path`/`circle` and are never touched — the series palette is
+ DOCUMENT data and must not move with the viewer's theme.
+ The proper fix lives in dash/src/chart.ts, which owns the option and should
+ set axisLabel/legend.textStyle colours; this rule is the half that fits in a
+ stylesheet. */
+/* charts-lite writes `fill` as a presentation ATTRIBUTE, which loses to a
+ stylesheet — that is what lets the theme reach chart text at all, and it is
+ the right layer, because the theme is a VIEWER preference and the chart
+ option is derived from the DOCUMENT. Baking a theme colour into the option
+ would put one reader's preference into everyone's chart.
+
+ Matched on the kernel's default (#6B7280) rather than on every `text`, so a
+ colour somebody CHOSE — `legend.textStyle.color`, an axis label, a future
+ per-series colour — still wins. A blanket rule would flatten all three, and
+ would do it silently. */
+.dx-chart-body svg text[fill="#6B7280"] { fill: var(--chart-ink); }
/* stack on a phone rather than squeezing both */
@media (max-width: 760px) {
@@ -127,7 +528,13 @@ html, body {
.dx-chart { flex: 0 0 45%; border-left: 0; border-top: 1px solid var(--line); }
}
.dg-scroll { position: absolute; inset: 0; overflow: auto; }
-.dg-table { position: relative; min-width: max-content; }
+/* 12.5px, not the 14px the rest of the UI runs at. A grid is read a hundred
+ cells at a time and a spreadsheet's type is always a step smaller than its
+ chrome's — Excel's default is 11pt against a 12pt UI, Sheets' 10pt against
+ 13px. At 14px in a 30px row the type filled the row and the grid read as
+ prose; at 12.5 in a 20px row the figures have air on both sides, which is
+ what makes a dense grid legible rather than merely small. */
+.dg-table { position: relative; min-width: max-content; font-size: 12.5px; }
/* the sizer is the ONLY absolutely-positioned region: header and totals stay in
flow so `position: sticky` resolves against the scroller */
.dg-sizer { position: relative; }
@@ -139,25 +546,35 @@ html, body {
position: sticky;
z-index: 3;
height: var(--row-h);
- background: var(--panel);
+ background: var(--grid-head);
}
-.dg-head-row { top: 0; border-bottom: 1px solid var(--line-strong); }
-.dg-foot-row { bottom: 0; border-top: 1px solid var(--line-strong); font-weight: 600; }
+/* 2px, and --line-strong: the seam under the header is the one edge in the
+ grid that has to survive being scrolled under. A 1px --line rule there read
+ as one more gridline. */
+.dg-head-row { top: 0; border-bottom: 2px solid var(--line-strong); }
+.dg-foot-row { bottom: 0; border-top: 2px solid var(--line-strong); font-weight: 600; }
+/* BOTH AXES. The grid drew vertical rules only and separated rows with a zebra
+ stripe — the arrangement of a web table, not of a spreadsheet, and the single
+ biggest reason dash did not read as one. Excel and Sheets both rule every
+ cell on all four sides and neither stripes; with real horizontal lines the
+ stripe is redundant AND busy, so it is gone.
+ box-sizing is border-box globally, so the 1px bottom border eats into the
+ row height — hence the line-height below, or the text sits a pixel low. */
.dg-cell {
flex: 0 0 auto;
padding: 0 8px;
height: var(--row-h);
- line-height: var(--row-h);
- border-right: 1px solid var(--line);
+ line-height: calc(var(--row-h) - 1px);
+ border-right: 1px solid var(--grid-line);
+ border-bottom: 1px solid var(--grid-line);
overflow: hidden;
white-space: nowrap;
text-overflow: ellipsis;
font-variant-numeric: tabular-nums;
}
-.dg-sizer .dg-row:nth-child(even) .dg-cell { background: #fcfdfe; }
.dg-cell.dg-editing {
- background: #fff;
+ background: var(--bg);
box-shadow: inset 0 0 0 2px var(--accent);
overflow: visible;
cursor: text;
@@ -172,7 +589,7 @@ html, body {
text-transform: uppercase;
letter-spacing: 0.04em;
color: var(--muted);
- background: #fff;
+ background: var(--surface);
border: 1px solid var(--line);
border-radius: 5px;
padding: 0 5px;
@@ -181,8 +598,8 @@ html, body {
}
.dg-type:hover { border-color: var(--accent); color: var(--ink); }
.dg-warn {
- color: #b45309;
- background: #fef3c7;
+ color: var(--warn-ink);
+ background: var(--warn-chip);
border-radius: 50%;
width: 15px;
height: 15px;
@@ -191,7 +608,7 @@ html, body {
flex: 0 0 auto;
cursor: help;
}
-.dg-err { color: #b91c1c; background: #fef2f2; font-weight: 600; }
+.dg-err { color: var(--err-ink); background: var(--err-bg); font-weight: 600; }
.dg-fx {
font: 600 9px/1.6 inherit;
color: var(--accent);
@@ -228,3 +645,405 @@ html, body {
@media (prefers-reduced-motion: reduce) {
* { transition: none !important; }
}
+
+/* ————— formula bar —————
+ Excel and Sheets both build this out of three parts with visible seams: the
+ name box, a rule, then the entry field running the full width. dash had the
+ three parts floating in whitespace, which reads as a search bar. The rule and
+ the fixed 30px height are what make it furniture. */
+.dx-formula {
+ display: flex;
+ align-items: stretch;
+ gap: 0;
+ padding: 4px 10px;
+ border-bottom: 1px solid var(--line-strong);
+ background: var(--bg);
+ flex: 0 0 auto;
+ min-height: 32px;
+}
+.dx-ref {
+ min-width: 82px;
+ font: 600 12px/22px ui-monospace, SFMono-Regular, Menlo, monospace;
+ color: var(--ink);
+ background: var(--grid-head);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius);
+ padding: 0 8px;
+ text-align: center;
+ flex: 0 0 auto;
+ align-self: center;
+}
+/* the seam between "where you are" and "what is in it" */
+.dx-fx-mark {
+ color: var(--muted);
+ font: italic 600 13px/1 serif;
+ flex: 0 0 auto;
+ align-self: stretch;
+ display: flex;
+ align-items: center;
+ padding: 0 10px;
+ margin-inline-start: 8px;
+ border-inline-start: 1px solid var(--line);
+}
+.dx-fx-input {
+ flex: 1 1 auto;
+ font: 13px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace;
+ border: 1px solid transparent;
+ border-radius: var(--radius);
+ padding: 3px 8px;
+ background: transparent;
+ color: inherit;
+ min-width: 0;
+ align-self: center;
+}
+.dx-fx-input:hover { border-color: var(--line); }
+.dx-fx-input:focus { outline: none; border-color: var(--accent); background: var(--surface); }
+
+/* ————— status bar —————
+ Excel's reads left: what you are looking at; right: what the selection adds
+ up to. The sum is the half people actually use, so it gets the ink — grid
+ figures on the app's own surface, not muted like the label beside it. */
+.dx-status {
+ display: flex;
+ align-items: center;
+ gap: 16px;
+ padding: 3px 12px;
+ border-top: 1px solid var(--line-strong);
+ background: var(--panel);
+ font-size: 12px;
+ color: var(--muted);
+ flex: 0 0 auto;
+ min-height: 26px;
+ font-variant-numeric: tabular-nums;
+ padding-bottom: max(3px, env(safe-area-inset-bottom));
+}
+.dx-status-view { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.dx-status-sum {
+ margin-left: auto;
+ color: var(--ink);
+ font-weight: 500;
+ white-space: nowrap;
+ padding-inline-start: 16px;
+ border-inline-start: 1px solid var(--line-strong);
+}
+.dx-status-sum:empty { border: 0; padding: 0; }
+
+/* ————— row gutter and column letters ————— */
+/* Row numbers and the corner: one band, but a QUIET one. A grey header slab is
+ the second thing that dated this grid — Excel 2007 painted one and every
+ spreadsheet since has been walking it back. What has to be true is that the
+ header reads as not-data; a fill two shades off the sheet plus a heavier
+ bottom edge does that, and the rest of the separation is carried by type
+ (see .dg-hmain below). Row numbers are 10.5px: they are a coordinate, and
+ a coordinate should never out-weigh the figure it is pointing at. */
+.dg-gutter {
+ width: 52px;
+ flex: 0 0 52px;
+ background: var(--grid-head);
+ color: var(--grid-head-ink);
+ text-align: right;
+ font-size: 10.5px;
+ font-weight: 500;
+ border-right: 2px solid var(--line-strong);
+ position: sticky;
+ left: 0;
+ z-index: 2;
+ cursor: pointer;
+ user-select: none;
+}
+.dg-gutter:hover { background: var(--hover); color: var(--ink); }
+.dg-gutter-on { background: var(--grid-head-on); color: var(--ink); font-weight: 700; }
+.dg-corner {
+ width: 52px;
+ flex: 0 0 52px;
+ background: var(--grid-head);
+ border-right: 2px solid var(--line-strong);
+ position: sticky;
+ left: 0;
+ z-index: 4;
+ cursor: pointer;
+}
+.dg-letter {
+ font: 600 10px/1.6 inherit;
+ color: var(--grid-head-ink);
+ letter-spacing: 0.05em;
+ flex: 0 0 auto;
+ cursor: pointer;
+ padding: 0 3px;
+ border-radius: 4px;
+}
+.dg-letter:hover { background: var(--hover); color: var(--ink); }
+
+/* ————— selection —————
+ COOL, not the brand amber. The old amber tint landed on top of amber
+ conditional-format data bars — two unrelated meanings in one warm smear, and
+ the reader had no way to tell "I selected this" from "the document coloured
+ this". Selection is chrome; conditional formatting is data; they no longer
+ share a hue.
+
+ `!important` on the fill because a conditional-format background is written
+ INLINE by grid.ts, and an inline style beats any selector. Selection has to
+ win: a selected cell that does not look selected is a lost cursor. */
+.dg-cell.dg-sel { background: var(--sel) !important; }
+.dg-cell.dg-cursor {
+ box-shadow: inset 0 0 0 2px var(--sel-ring);
+ background: var(--bg) !important;
+ z-index: 1;
+}
+.dg-cell { position: relative; }
+/* …but NOT the pinned ones. `.dg-cell` and `.dg-gutter` have the same
+ specificity, so this later rule silently won and the row numbers scrolled
+ away with the data — measured: after scrolling 500px right, the gutter sat at
+ left −495, entirely off screen. A spreadsheet whose row numbers leave when
+ you scroll sideways has lost the thing they are for. Frozen columns are
+ restated for the same reason. */
+.dg-cell.dg-gutter { position: sticky; left: 0; }
+.dg-cell.dg-frozen { position: sticky; }
+/* and the gutter wins the overlap: equal z-index leaves it to DOM order, and
+ the gutter comes first, so a frozen column would slide over the numbers. */
+.dg-cell.dg-gutter { z-index: 3; }
+/* The HEADER's corner is the same pin one row up. It was not sticky at all, so
+ a scrolled column header slid straight under it and showed through where the
+ row numbers' heading should be — the corner read "age", the tail of "Stage".
+ It is the one cell that has to outrank both axes: the row gutter slides
+ beneath it and so does every column header. */
+.dg-head-row .dg-cell.dg-corner { position: sticky; left: 0; z-index: 6; }
+.dg-head-row .dg-cell.dg-gutter { z-index: 6; }
+.dg-v { position: relative; z-index: 1; }
+
+/* ————— conditional formatting —————
+ THESE COLOURS ARE DATA, NOT CHROME. A colour scale and a data bar are
+ computed from the numbers by condfmt.ts and travel in the file, so the theme
+ does NOT recolour them: two people looking at one workbook have to be
+ looking at the same encoding, or the colours stop meaning anything that can
+ be discussed. What the theme changes is the INK ON TOP of them.
+
+ A data bar is drawn behind the figure at 55% over whatever ground the sheet
+ has, so it tints rather than replaces and the sheet's own ink still reads.
+ The bar therefore needs nothing here. A colour-SCALE fill does: it is an
+ opaque wash written inline onto the cell, and the fills a scale produces are
+ pale by construction (they interpolate between two or three chosen colours,
+ and every preset picks light ones for a white sheet). Light ink on a pale
+ green cell is invisible, so a cell carrying a data-driven fill takes the
+ LIGHT theme's ink on both themes — which also means one cell reads the same
+ in both, and that is the right answer for a cell whose colour is data.
+
+ `[style*='background']` is how a cell announces one: grid.ts appends
+ `;background:<colour>` to the inline style for exactly this case and for
+ nothing else (a frozen column gets position/left, every cell gets a width).
+ A rule that also sets an explicit text colour still wins — it is written
+ inline too, and the author meant it. Selection replaces the fill with the
+ selection tint, so a selected cell opts back out and takes the theme's ink
+ again. */
+.dg-cell[style*='background'] { color: var(--ink-on-fill); }
+.dg-cell.dg-sel[style*='background'] { color: var(--ink); }
+
+.dg-bar {
+ position: absolute;
+ top: 5px;
+ bottom: 5px;
+ border-radius: 2px;
+ opacity: var(--bar-opacity);
+ z-index: 0;
+}
+
+/* ————— header controls ————— */
+.dg-filter {
+ color: var(--muted);
+ cursor: pointer;
+ flex: 0 0 auto;
+ padding: 0 2px;
+ font-size: 10px;
+}
+.dg-filter:hover { color: var(--accent); }
+/* A filtered column is amber and a SELECTED one is blue — the two states are
+ unrelated and used to share --grid-head-on, so a filter looked like a
+ selection that would not go away. */
+.dg-h.dg-filtered { background: var(--accent-wash); }
+.dg-h.dg-filtered .dg-filter { color: var(--accent); }
+/* THE SELECTED COLUMN'S HEADER — the counterpart to .dg-gutter-on, and
+ deliberately the SAME strength: same band colour, same step up to full ink.
+ Two headers marking one selection have to look like one gesture; a column
+ header lit differently from the row gutter reads as a second, competing
+ thing being selected.
+
+ The `.dg-hstrip` rule is not optional. The header is two stacked boxes and
+ the letter strip paints its OWN --grid-head background, so tinting only
+ .dg-h lights the name row and leaves the letter — the part the eye actually
+ tracks a column by — sitting on the unselected band.
+
+ It also outranks .dg-filtered above (later, same specificity), which is the
+ right way round: the filter is a persistent state and the selection is the
+ one the hand is on. Nothing is lost by yielding — the filter caret keeps its
+ amber, and that is the mark that says a filter exists. */
+.dg-h.dg-h-on,
+.dg-h.dg-h-on .dg-hstrip { background: var(--grid-head-on); }
+.dg-h.dg-h-on .dg-letter,
+.dg-h.dg-h-on .dg-name { color: var(--ink); }
+.dg-grip {
+ position: absolute;
+ right: -3px;
+ top: 0;
+ bottom: 0;
+ width: 7px;
+ cursor: col-resize;
+ z-index: 5;
+}
+.dg-grip:hover { background: var(--accent); opacity: 0.5; }
+.dg-h { position: relative; }
+
+/* ————— popover menus ————— */
+/* Same panel as .dx-menu and the save menu — one floating-surface style for
+ the whole app, so a right-click menu and a top-bar menu are recognisably
+ the same object. */
+.dx-pop {
+ position: fixed;
+ z-index: 9999;
+ min-width: 210px;
+ background: var(--surface);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius-lg);
+ box-shadow: var(--shadow-pop);
+ padding: 5px;
+ display: flex;
+ flex-direction: column;
+ gap: 1px;
+}
+.dx-pop button {
+ font: inherit;
+ font-size: var(--fs-ui);
+ text-align: left;
+ border: 0;
+ background: transparent;
+ border-radius: var(--radius);
+ padding: 6px 9px;
+ cursor: pointer;
+ color: inherit;
+}
+.dx-pop button:hover { background: var(--hover); }
+.dx-pop-sep { height: 1px; background: var(--line); margin: 4px 6px; }
+.dx-pop-row {
+ display: flex;
+ flex-direction: column;
+ gap: 3px;
+ padding: 4px 9px 6px;
+ font-size: var(--fs-micro);
+ color: var(--muted);
+}
+.dx-pop-in {
+ font: inherit;
+ font-size: var(--fs-ui);
+ border: 1px solid var(--line-strong);
+ border-radius: var(--radius);
+ padding: 4px 7px;
+ color: var(--ink);
+}
+.dx-pop-in:focus { outline: none; border-color: var(--accent); }
+
+/* ————— selection outline and fill handle ————— */
+.dg-outline {
+ position: absolute;
+ pointer-events: none;
+ border: 2px solid var(--sel-ring);
+ border-radius: 2px;
+ z-index: 4;
+}
+.dg-handle {
+ position: absolute;
+ right: -4px;
+ bottom: -4px;
+ width: 8px;
+ height: 8px;
+ background: var(--sel-ring);
+ border: 1px solid var(--bg);
+ border-radius: 1px;
+ cursor: crosshair;
+ pointer-events: auto;
+}
+/* the cursor cell no longer needs its own ring — the outline draws it */
+.dg-cell.dg-cursor { box-shadow: none; background: var(--bg) !important; }
+.dg-scroll:focus { outline: none; }
+
+/* Frozen columns stay put while the rest scrolls under them, so they need an
+ opaque background (the cells behind would show through) and an edge that
+ says where the frozen pane ends. */
+/* --surface and --sel-bg were never declared anywhere in dash: a frozen cell
+ resolved to `background: <invalid>` and stayed TRANSPARENT — the exact
+ failure the rule above exists to prevent — and a frozen cell inside a
+ selection fell back to a hard-coded blue while the rest of the selection was
+ amber. Both now read dash's own tokens. */
+.dg-cell.dg-frozen { background: var(--bg); z-index: 2; }
+.dg-head-row .dg-cell.dg-frozen { background: var(--grid-head); }
+.dg-head-row .dg-cell.dg-frozen { z-index: 5; }
+/* …and it still lights with the selection. This rule exists only to out-rank
+ the one above it, which is more specific than the .dg-h-on pair and would
+ otherwise leave the frozen columns as the one place a selected header stays
+ grey. */
+.dg-head-row .dg-cell.dg-frozen.dg-h-on { background: var(--grid-head-on); }
+.dg-cell.dg-frozen.dg-freeze-edge { border-right: 2px solid var(--line-strong); }
+.dg-cell.dg-sel.dg-frozen { background: var(--sel); }
+
+/* ————— two-line column header —————
+ The letter strip on top (Excel's position, and the click target for
+ selecting the column), the name and its controls below. One line could not
+ hold both: the name was being clipped to a single character. */
+.dg-head-row { height: calc(var(--row-h) + 20px); }
+.dg-head-row .dg-cell { height: calc(var(--row-h) + 20px); line-height: normal; padding: 0; }
+.dg-h { flex-direction: column; align-items: stretch; gap: 0; }
+/* --line, not --line-strong: this is a seam INSIDE the header, and at the
+ heavier weight the two-line header read as two stacked bands. */
+.dg-hstrip {
+ position: relative;
+ display: block;
+ height: 19px;
+ border-bottom: 1px solid var(--line);
+ background: var(--grid-head);
+}
+.dg-h .dg-letter {
+ display: block;
+ height: 19px;
+ line-height: 19px;
+ text-align: center;
+ border-radius: 0;
+ padding: 0;
+}
+/* absolute, so the letter stays centred on the COLUMN rather than on whatever
+ space the badge leaves it */
+.dg-hstrip .dg-type {
+ position: absolute;
+ right: 3px;
+ top: 0;
+ height: 19px;
+ line-height: 17px;
+ border: 0;
+ background: transparent;
+ font-size: 9px;
+ padding: 0 2px;
+ opacity: 0.75;
+}
+.dg-hstrip .dg-type:hover { opacity: 1; color: var(--accent); }
+/* HIERARCHY FROM TYPE, NOT FROM FILL. The column name is the one piece of
+ furniture that has to out-rank the data without a heavy band under it:
+ 11.5px (a step below the 12.5px figures), semibold, tracked slightly open,
+ and a darker ink than the muted grey the rest of the header runs at. Tracking
+ is what makes a smaller, quieter label still read as a heading — it is the
+ move that separates a 2024 spreadsheet from a 2006 one. */
+.dg-hmain {
+ display: flex;
+ align-items: center;
+ gap: 5px;
+ flex: 1 1 auto;
+ min-width: 0;
+ padding: 0 8px;
+ font-size: 11.5px;
+ font-weight: 600;
+ letter-spacing: 0.02em;
+ color: var(--grid-head-ink);
+}
+.dg-head-row .dg-corner { padding: 0; }
+.dx-pop-on { color: var(--accent); font-weight: 600; }
+
+/* The ruled empty space past the last row — see grid.ts paintEmptyGrid. The
+ inner table must fill the scroller for the lattice to reach the bottom when
+ there are only a few rows, which is exactly the case it exists for. */
+.dg-table { min-height: 100%; }
diff --git a/dash/src/sync.css b/dash/src/sync.css
new file mode 100644
index 00000000..dc4206d7
--- /dev/null
+++ b/dash/src/sync.css
@@ -0,0 +1,134 @@
+/* SPDX-License-Identifier: MIT
+ * Copyright (c) 2026 The Bento authors
+ * The live-session / People panel. Imported by src/sync/people.ts, so it only
+ * reaches the bundle when collaboration is wired in.
+ *
+ * Deliberately its own file rather than an addition to styles.css: sync is one
+ * feature with one owner, and a panel that never mounts should not cost the
+ * shell any bytes it cannot explain. Variables come from styles.css. */
+
+.dx-people {
+ font: inherit;
+ padding: 8px 10px;
+}
+
+.dx-people-head {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ margin-bottom: 6px;
+}
+
+/* Grey until the relay is actually open. A "Live" label that is only an
+ * intention is the one thing this dot must never be. */
+.dx-people-dot {
+ width: 8px;
+ height: 8px;
+ border-radius: 50%;
+ background: #8FA3BF;
+ flex: none;
+}
+
+.dx-people-dot.on {
+ background: #7FC8A9;
+ box-shadow: 0 0 0 3px rgba(127, 200, 169, 0.22);
+}
+
+.dx-people-title {
+ font-weight: 600;
+ margin-inline-end: auto;
+}
+
+.dx-people-list {
+ list-style: none;
+ margin: 0;
+ padding: 0;
+ display: flex;
+ flex-direction: column;
+ gap: 2px;
+}
+
+.dx-people-list li {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+ padding: 3px 2px;
+ min-width: 0;
+}
+
+.dx-people-chip {
+ width: 10px;
+ height: 10px;
+ border-radius: 50%;
+ flex: none;
+}
+
+/* The name is a claim, so it gets no more visual weight than the key that
+ * actually proves something. */
+.dx-people-name {
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+}
+
+.dx-people-role,
+.dx-people-key {
+ font-size: 0.82em;
+ opacity: 0.65;
+ flex: none;
+}
+
+.dx-people-key {
+ font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+}
+
+.dx-people-x {
+ margin-inline-start: auto;
+ border: 0;
+ background: none;
+ cursor: pointer;
+ opacity: 0.5;
+ font: inherit;
+ padding: 0 2px;
+}
+
+.dx-people-x:hover {
+ opacity: 1;
+}
+
+.dx-people-empty {
+ margin: 6px 2px 0;
+ font-size: 0.9em;
+ opacity: 0.6;
+}
+
+/* ————— the People panel, docked in the topbar —————
+ mountPeople renders a full card: a heading, a toggle, a member list and an
+ empty-state line. Dropped straight into the bar that is 103px of block
+ content, and it pushed the toolbar from 56px to 118px.
+ In the bar it is a CHIP: the live dot, the state, the toggle, and a colour
+ swatch per collaborator. "You" and the nobody-else line are not news to the
+ person reading them, and the full list belongs in a panel, not a strip. */
+.dx-bar .dx-people { display: flex; align-items: center; gap: 8px; margin-left: 6px; }
+.dx-bar .dx-people-head { display: flex; align-items: center; gap: 6px; margin: 0; padding: 0; border: 0; }
+.dx-bar .dx-people-empty { display: none; }
+.dx-bar .dx-people-list {
+ display: flex; align-items: center; gap: 3px;
+ margin: 0; padding: 0; list-style: none;
+}
+.dx-bar .dx-people-me { display: none; }
+.dx-bar .dx-people-list li { display: flex; align-items: center; }
+.dx-bar .dx-people-name { display: none; }
+.dx-bar .dx-people-title { font-size: var(--fs-small); color: var(--muted); white-space: nowrap; }
+/* and it collapses with everything else — see the topbar ladder in styles.css */
+@media (max-width: 1280px) { .dx-bar .dx-people-title { display: none; } }
+@media (max-width: 900px) { .dx-bar .dx-people-toggle { display: none; } }
+/* On a phone the chip stands down UNLESS somebody else is actually here.
+ Measured at 390px: the dot and its toggle cost 20px more than the bar had,
+ and About went off the edge — a presence indicator must not push the
+ controls off a screen it is reporting nothing on. Peer swatches still show,
+ because at that point it is saying something. */
+@media (max-width: 700px) {
+ .dx-bar .dx-people:not(:has(.dx-people-list li:not(.dx-people-me))) { display: none; }
+ .dx-bar .dx-people-toggle { display: none; }
+}
diff --git a/dash/src/sync/crdt.ts b/dash/src/sync/crdt.ts
new file mode 100644
index 00000000..775d343a
--- /dev/null
+++ b/dash/src/sync/crdt.ts
@@ -0,0 +1,2313 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento-sync for dash — the CRDT engine. Pure data, no DOM, no imports beyond
+// the model types and the store's own writer, so the same file runs in the
+// browser session layer and in the node convergence rig
+// (scripts/test-dash-sync.ts, node --experimental-strip-types).
+//
+// Design, rationale and the honest list of what LOSES DATA: docs/dash-collab.md.
+// Read that before changing anything here.
+//
+// WHY THIS IS NOT slides/src/sync/crdt.ts
+//
+// Slides' engine keys per-element nodes and diffs two whole-document snapshots.
+// Neither transfers. A dash workbook is COLUMNAR and dictionary-encoded: cell
+// values live in per-column arrays addressed by ROW POSITION, and the document
+// is routinely 10-25 MB. Two consequences set the whole shape of this file:
+//
+// 1. NO SNAPSHOT DIFFING. `JSON.stringify(doc)` costs ~10 ms on a 12 MB
+// workbook (store.ts measured it, which is why history here is typed
+// inverses rather than snapshots) and a shadow copy doubles resident
+// memory. So ops are minted from the store's `Patch` objects, which are
+// already a complete, position-independent description of every mutation.
+// The store's comment predicted this: "The same Patch objects are the undo
+// entries, the future CRDT ops and the agent API."
+//
+// 2. STATE MUST BE O(EDITS), NEVER O(ROWS). Anything per-row — an order key,
+// a birth stamp, a shadow value — is multiplied by a million. The saved
+// state also rides in the FILE (`collab.sync`), so O(rows) state would
+// undo the entire point of the 4.8-bytes-per-cell encoding. Therefore a
+// row that nobody has touched costs ZERO bytes here: rows get state only
+// when an op inserts or deletes them, and cells only when an op writes
+// them.
+//
+// THE ALGEBRA
+//
+// - Node identity. `@doc`; `s␟<sheet>`; `c␟<sheet>␟<col>`; `r␟<sheet>␟<rid>`.
+// Column ids are SHEET-scoped (model.ts:478 — two sheets may both call a
+// column `c1`) and so are rids, so both are composite. This is slides'
+// lesson (bare ids collapsed the morph idiom) applied before it could bite.
+//
+// - Cells are PROPERTIES OF THE ROW NODE, keyed by column id: register
+// `r␟s1␟7 ⟹ v␟price`. That is per-cell last-writer-wins for free, out of
+// exactly the same (lamport, actor) register machinery slides uses for
+// `x`/`fill`. Cell overrides (the `cells` overlay) are a second key space
+// on the same node, `o␟price`.
+//
+// - Row ORDER is a FRACTIONAL INDEX over rids, and the trick that makes it
+// affordable is that most rows never get one. rids are minted at insert
+// and NEVER reused (rowcol.ts is emphatic about this), which is what makes
+// them usable as identity at all. A row that came with the file takes its
+// key from its position in the adopted baseline sequence (`base`, one
+// run-length list per sheet — 20 bytes for 4200 rows), so it costs
+// nothing; only an INSERTED row stores an explicit key, minted between its
+// neighbours' keys. Order is then `sort by (key, rid)`, a pure function of
+// converged state. Cost: O(inserts) + O(sheets).
+//
+// Two earlier designs failed here and the rig caught both, which is why
+// the third is spelled out. (1) An LWW register over the whole `rids`
+// list: concurrent structural edits silently drop one side's rows.
+// (2) An RGA whose inserts name an ANCHOR RID, with deleted anchors
+// resolved by walking back to the anchor's own anchor — that walk lands a
+// row ahead of rows which used to sit in between, and two replicas that
+// applied the deletes in different orders disagreed (seed 16 of 20).
+// A fractional key needs neither tombstone nor chain: neighbours may die
+// without moving anything, because the key already sits between them.
+//
+// - Sheets and columns are few, so they get slides' fractional `pos` keys
+// verbatim (keyBetween/spreadKey copied below — dash cannot import from
+// slides/, and PLATFORM §9 says genericizing the engine is its own
+// project).
+//
+// - Liveness is births vs tombs, highest (l,a) wins — delete beats
+// concurrent edits, an insert is a whole-node assignment that resurrects
+// by out-stamping the tomb. Values displaced during a node's dead window
+// park in `stash` and replay on resurrection only while their register is
+// still the winner. All three rules are slides', which earned them.
+//
+// - Delivery is per-actor contiguous `s` with a gap buffer, plus a `pending`
+// buffer for ops naming a node we have not seen yet. Also slides'.
+//
+// WHAT WRITES THE DOCUMENT. Structural changes and cell writes go through the
+// store's own `applyPatch` — deliberately, because rowcol.ts already names the
+// failure: "Two copies of one op is how the inverse and the forward drift
+// apart." A second row-splicer here would have to know about run-length rids,
+// dictionary interning and dictLen truncation, and would silently diverge from
+// the local path the first time either changed. Plain property sets are
+// assigned directly (there is no patch that can express "delete this key" —
+// `setSheetProps` refuses `undefined` on purpose — and the CRDT must be able
+// to.)
+
+import { applyPatch, readCell, type Patch } from '../store.ts'
+import type { CellOverride, Column, ColumnData, DashDoc, Sheet, TableSheet } from '../model.ts'
+
+/**
+ * Sync format version — stamped into SyncStateJSON (`v`) and every wire frame
+ * (`pv`). Mismatched state and frames are DISCARDED on sight rather than
+ * misread: the file still opens, it simply rejoins as a fresh adopt. Same rule
+ * as slides' SYNC_V and model.ts's frozen-policy handling.
+ */
+export const SYNC_V = 1
+
+export const DOC_NODE = '@doc'
+
+/** node-id separator. U+001F cannot appear in a sheet/column id: import mints
+ * them by slugging (import.ts) and the parser repairs anything else. */
+const NS = '\u001f'
+
+export const shNode = (sheet: string): string => `s${NS}${sheet}`
+export const colNode = (sheet: string, col: string): string => `c${NS}${sheet}${NS}${col}`
+export const rowNode = (sheet: string, rid: number): string => `r${NS}${sheet}${NS}${rid}`
+/** cell-value key on a row node */
+const vKey = (col: string): string => `v${NS}${col}`
+/** cell-override key on a row node */
+const oKey = (col: string): string => `o${NS}${col}`
+const isVKey = (k: string): boolean => k.charCodeAt(0) === 118 /* 'v' */ && k[1] === NS
+const keyCol = (k: string): string => k.slice(2)
+
+/** sheet id out of a sheet/column/row node id */
+const nodeSheet = (node: string): string => {
+ const i = node.indexOf(NS)
+ const j = node.indexOf(NS, i + 1)
+ return j < 0 ? node.slice(i + 1) : node.slice(i + 1, j)
+}
+const nodeTail = (node: string): string => node.slice(node.indexOf(NS, node.indexOf(NS) + 1) + 1)
+
+/* eslint-disable no-console */
+const dbg = (id: string, msg: string) => {
+ const g = globalThis as unknown as { __dbgNode?: string; __dbgTag?: string }
+ // comma-separated so one run can watch a row and the column that fights it
+ if (g.__dbgNode && g.__dbgNode.split(',').includes(id)) console.log(` [dbg ${g.__dbgTag ?? ''} ${msg}]`)
+}
+
+// ---------------------------------------------------------------------------
+// fractional order keys — base-62 midstrings (copied from slides/src/sync/crdt.ts;
+// pure functions, no behaviour change, and the two engines must agree on
+// nothing so the duplication is inert)
+// ---------------------------------------------------------------------------
+
+const DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+const D = (c: string) => DIGITS.indexOf(c)
+
+/** A key strictly between `a` and `b` ('' = unbounded on that side). */
+export function keyBetween(a: string, b: string): string {
+ let out = ''
+ for (let i = 0; ; i++) {
+ const da = i < a.length ? D(a[i]) : 0
+ const db = i < b.length ? D(b[i]) : 62
+ if (da === db) { out += DIGITS[da]; continue }
+ if (db - da > 1) return out + DIGITS[Math.floor((da + db) / 2)]
+ out += DIGITS[da]
+ for (let j = i + 1; ; j++) {
+ const ta = j < a.length ? D(a[j]) : 0
+ if (62 - ta > 1) return out + DIGITS[Math.floor((ta + 62) / 2)]
+ out += DIGITS[ta]
+ }
+ }
+}
+
+/** Deterministic evenly-spread key for index i of n (file adoption). */
+export function spreadKey(i: number, n: number): string {
+ let v = (i + 1) / (n + 1)
+ let out = ''
+ const need = Math.max(2, Math.ceil(Math.log(n + 2) / Math.log(62)) + 1)
+ for (let k = 0; k < need; k++) {
+ v *= 62
+ const d = Math.min(61, Math.floor(v))
+ out += DIGITS[d]
+ v -= d
+ }
+ while (out.length > 1 && out.endsWith('0')) out = out.slice(0, -1)
+ return out === '0' ? '1' : out
+}
+
+// ---------------------------------------------------------------------------
+// run-length rid helpers
+// ---------------------------------------------------------------------------
+
+export type Rle = Array<[number, number]>
+
+const rleCount = (rle: Rle): number => rle.reduce((n, [, c]) => n + c, 0)
+
+const rleExpand = (rle: Rle): number[] => {
+ const out: number[] = []
+ for (const [start, count] of rle) for (let i = 0; i < count; i++) out.push(start + i)
+ return out
+}
+
+const rleCompress = (flat: number[]): Rle => {
+ const out: Rle = []
+ for (const rid of flat) {
+ const tail = out[out.length - 1]
+ if (tail && tail[0] + tail[1] === rid) tail[1]++
+ else out.push([rid, 1])
+ }
+ return out
+}
+
+/** position of `rid`, or -1. Walks runs, so it is O(runs) not O(rows). */
+const rleIndex = (rle: Rle, rid: number): number => {
+ let i = 0
+ for (const [start, count] of rle) {
+ if (rid >= start && rid < start + count) return i + (rid - start)
+ i += count
+ }
+ return -1
+}
+
+/** rid at position `i`, or 0. */
+const rleAt = (rle: Rle, i: number): number => {
+ if (i < 0) return 0
+ let seen = 0
+ for (const [start, count] of rle) {
+ if (i < seen + count) return start + (i - seen)
+ seen += count
+ }
+ return 0
+}
+
+const rleHas = (rle: Rle, rid: number): boolean => rleIndex(rle, rid) >= 0
+
+// ---------------------------------------------------------------------------
+// ops
+// ---------------------------------------------------------------------------
+
+export type Reg = [number, string] // [lamport, actor]
+
+const newer = (l: number, a: string, r: Reg | undefined): boolean =>
+ !r || l > r[0] || (l === r[0] && a > r[1])
+/**
+ * Strictly older than the register — the test a property write must use.
+ *
+ * Not `!newer(...)`: that also rejects the register's OWN op, and an op can be
+ * re-applied legitimately. A value gated behind a dead node advances the
+ * register and parks, and when the node comes back the parked op replays with
+ * exactly the stamp already recorded. `!newer` swallowed it, so the value
+ * arrived nowhere while a replica that saw the resurrection first kept it.
+ * Re-applying an op is idempotent by construction — same stamp, same value.
+ */
+const older = (l: number, a: string, r: Reg | undefined): boolean =>
+ !!r && (l < r[0] || (l === r[0] && a < r[1]))
+const regNewer = (x: Reg, y: Reg | undefined): boolean => newer(x[0], x[1], y)
+const cmpReg = (x: Reg, y: Reg): number => x[0] - y[0] || (x[1] < y[1] ? -1 : x[1] > y[1] ? 1 : 0)
+
+export interface OpBase {
+ a: string // actor
+ s: number // per-actor contiguous sequence (delivery / version vector)
+ l: number // lamport (conflict order)
+}
+
+/** per-(node, key) LWW register. `n` absent = the document node. `v` absent =
+ * delete the key — the one spelling of a delete, because `JSON.stringify`
+ * erases `{k: undefined}` and a delete that evaporates on the wire lands on
+ * one replica only (rowcol.ts met this hazard twice and says so). */
+export interface SetOp extends OpBase { op: 'set'; n?: string; k: string; v?: unknown }
+
+/** cell VALUES for one column: per-(row, column) LWW. Many rids per op because
+ * a paste or a fill-down is one gesture and must be one undo step, one op. */
+export interface CellOp extends OpBase { op: 'cell'; sh: string; col: string; rids: number[]; v: unknown[] }
+
+/** cell OVERRIDES (the `cells` overlay), keys `<colId>:<rid>` exactly as the
+ * document stores them. `null` deletes (and is what survives JSON). */
+export interface OvrOp extends OpBase { op: 'ovr'; sh: string; keys: string[]; v: Array<CellOverride | null> }
+
+/**
+ * Row insert. `ord[i]` is the row's fractional key, never a position:
+ * positions shift under concurrency and a key does not. `vals` is colId → one
+ * value per rid, the shape store.ts's insertRows patch already carries.
+ */
+export interface RinsOp extends OpBase {
+ op: 'rins'; sh: string; rids: number[]; ord: string[]
+ vals?: Record<string, unknown[]>
+}
+
+/** Row delete. Carries nothing but the rids: a fractional key needs no
+ * tombstone to stay meaningful, so a dead row leaves nothing behind but its
+ * tombstone stamp. */
+export interface RdelOp extends OpBase { op: 'rdel'; sh: string; rids: number[] }
+
+/**
+ * Sheet or column insert (the node id says which).
+ *
+ * A COLUMN insert carries metadata only — never its values. Its values follow
+ * as an ordinary `cell` op, minted in the same commit. That is a deliberate
+ * narrowing: while a column payload assigned cells, every cell in the sheet
+ * had TWO possible owners (the column's payload and the row's), the answer
+ * depended on which insert out-stamped the other, and the rig kept finding
+ * orderings where two replicas disagreed about a number. With values riding as
+ * cell ops there is exactly one writer per cell and the register decides, as
+ * it does for everything else.
+ *
+ * The price, stated plainly: adding a fully-populated column mints one
+ * register per cell, so a 100k-row column costs ~100k register entries in the
+ * sync state (and in `collab.sync` if the file is saved mid-session). Adding
+ * columns in bulk is what IMPORT does, and import creates a whole SHEET, whose
+ * insert does carry its rows wholesale. See docs/dash-collab.md.
+ */
+export interface InsOp extends OpBase {
+ op: 'ins'; n: string; ord: string
+ node: Sheet | Column
+ /**
+ * A column's storage ENCODING (never its values). The receiver creates the
+ * column empty in this encoding and the cell op fills it. Without it a
+ * re-created column could come back `raw` on one replica and `dict` on
+ * another, and then the same write lands as the number 5795 here and the
+ * string "5795" there — dictionary storage interns through String().
+ */
+ enc?: 'raw' | 'dict'
+}
+export interface DelOp extends OpBase { op: 'del'; n: string }
+export interface OrdOp extends OpBase { op: 'ord'; n: string; ord: string }
+
+export type Op = SetOp | CellOp | OvrOp | RinsOp | RdelOp | InsOp | DelOp | OrdOp
+
+// ---------------------------------------------------------------------------
+// serializable state
+// ---------------------------------------------------------------------------
+
+interface PosEntry { p: string; o: string; r: Reg }
+
+export interface SyncStateJSON {
+ v: number
+ lamport: number
+ vv: Record<string, number>
+ /** NESTED by node, so a row's twelve cell registers name the row once. The
+ * flat `"<node> <key>"` map slides uses would repeat a 40-byte composite
+ * row-node id per cell — measurable in a file, not in a deck. */
+ regs: Record<string, Record<string, Reg>>
+ pos: Record<string, PosEntry>
+ births: Record<string, Reg>
+ tombs: Record<string, Reg>
+ /** inserted row node → its fractional order key. Baseline rows are absent
+ * and derive theirs from `base`, which is the whole scaling trick. */
+ rpos: Record<string, string>
+ /**
+ * inserted row node → the columns its insert actually carried.
+ *
+ * One entry per inserted ROW (a dozen short ids), not one per cell, which is
+ * what keeps this O(inserts). It is what makes "the insert supersedes older
+ * writes" precise: an insert minted before a column existed says nothing
+ * about that column, and must not out-stamp a value written into it.
+ */
+ rnamed: Record<string, string[]>
+ /** sheet id → the row sequence as ADOPTED (from the file, or from a sheet
+ * insert's payload). Gives baseline rows the anchor they never had an op
+ * for. Run-length encoded: 20 bytes for 4200 rows. */
+ base: Record<string, Rle>
+ stash: Record<string, Record<string, { v?: unknown; r: Reg }>>
+}
+
+export interface ApplyResult {
+ changed: boolean
+ /** rows/columns/sheets appeared or moved — the grid must relayout, not repaint */
+ structure: boolean
+}
+
+const clone = <T>(v: T): T => (v === undefined ? v : JSON.parse(JSON.stringify(v)) as T)
+
+// ---------------------------------------------------------------------------
+
+export class DashSync {
+ actor: string
+ lamport = 0
+ vv: Record<string, number> = {}
+ private seq = 0
+ regs: Record<string, Record<string, Reg>> = {}
+ pos: Record<string, PosEntry> = {}
+ births: Record<string, Reg> = {}
+ tombs: Record<string, Reg> = {}
+ rpos: Record<string, string> = {}
+ rnamed: Record<string, string[]> = {}
+ base: Record<string, Rle> = {}
+ stash: Record<string, Record<string, { v?: unknown; r: Reg }>> = {}
+ /** ops naming a node we have not seen yet, keyed by node id */
+ private pending: Record<string, Op[]> = {}
+ /** out-of-order ops per actor awaiting their gap to fill */
+ private gap: Record<string, Op[]> = {}
+ /**
+ * Per-sheet row order as of the last mutation we know about — the PRE-state
+ * a local delete needs (it has to read the cell values it displaces before
+ * the store removes them) and the list an insert's anchors are read off.
+ * Run-length encoded, so a 4200-row sheet is 20 bytes here too.
+ */
+ private rids: Record<string, Rle> = {}
+ /**
+ * Local structural changes waiting for the store to apply them.
+ *
+ * `local()` runs BEFORE the store mutates the document, so it cannot do the
+ * reclaiming that the remote paths do inline. The session calls settle()
+ * straight after the commit and these are replayed there.
+ */
+ private localRows: Array<{ sh: string; rid: number; birth: Reg; named: string[]; vals: Record<string, unknown> }> = []
+ private localCols: Array<{ sh: string; col: string; birth: Reg; enc?: 'raw' | 'dict'; rids: number[]; vals: unknown[] }> = []
+ /**
+ * A local patch this engine cannot express as ops (a future patch op, or one
+ * of the store's reserved `applySteps`/`refreshBinding`). The session ships a
+ * state snapshot instead of silently dropping the change — an edit the user
+ * believes landed is the one failure mode worth extra machinery.
+ */
+ unsynced = false
+
+ /** base-62-safe form of the actor id, appended to every minted order key */
+ private keySuffix: string
+
+ constructor(actor: string) {
+ this.actor = actor
+ this.keySuffix = actor.replace(/[^0-9A-Za-z]/g, '') || '1'
+ }
+
+ /** actors with buffered out-of-order ops → catch-up should be requested */
+ get gappedActors(): string[] {
+ return Object.keys(this.gap).filter((a) => this.gap[a].length)
+ }
+
+ /** dead iff the latest delete out-stamps the latest insert */
+ dead(node: string): boolean {
+ const t = this.tombs[node]
+ if (!t) return false
+ const b = this.births[node]
+ return !b || !regNewer(b, t)
+ }
+
+ /** did the insert that created this row carry a value for `col`? */
+ private rowNames(node: string, col: string): boolean {
+ const l = this.rnamed[node]
+ return !!l && l.includes(col)
+ }
+
+ private reg(node: string, key: string): Reg | undefined {
+ return this.regs[node]?.[key]
+ }
+ private setReg(node: string, key: string, r: Reg): void {
+ ;(this.regs[node] ??= {})[key] = r
+ }
+
+ toJSON(): SyncStateJSON {
+ return {
+ v: SYNC_V,
+ lamport: this.lamport,
+ vv: this.vv,
+ regs: this.regs,
+ pos: this.pos,
+ births: this.births,
+ tombs: this.tombs,
+ rpos: this.rpos,
+ rnamed: this.rnamed,
+ base: this.base,
+ stash: this.stash,
+ }
+ }
+
+ static fromJSON(actor: string, j: SyncStateJSON): DashSync {
+ const s = new DashSync(actor)
+ if (!j || j.v !== SYNC_V) return s // unreadable state: rejoin as a fresh adopt
+ s.lamport = j.lamport ?? 0
+ s.vv = j.vv ?? {}
+ s.seq = s.vv[actor] ?? 0
+ s.regs = j.regs ?? {}
+ s.pos = j.pos ?? {}
+ s.births = j.births ?? {}
+ s.tombs = j.tombs ?? {}
+ s.rpos = j.rpos ?? {}
+ s.rnamed = j.rnamed ?? {}
+ s.base = j.base ?? {}
+ s.stash = j.stash ?? {}
+ return s
+ }
+
+ // --- adoption ------------------------------------------------------------
+
+ /**
+ * Adopt a document that has never synced: deterministic pos keys from the
+ * current array order (two readers of one file derive the same keys) with
+ * the null register [0,''] that loses to every real op.
+ *
+ * ROWS GET NOTHING, and that is the whole scaling decision. Their order is
+ * the file's own `rids`, which every replica of that file already agrees on,
+ * so an untouched row costs zero bytes of sync state.
+ */
+ adopt(doc: DashDoc): void {
+ const ns = doc.sheets.length
+ doc.sheets.forEach((s, i) => {
+ const sn = shNode(s.id)
+ if (!this.pos[sn]) this.pos[sn] = { p: DOC_NODE, o: spreadKey(i, ns), r: [0, ''] }
+ if (s.kind !== 'table') return
+ // the baseline sequence: what every replica of THIS file agrees the row
+ // order was before anybody edited it
+ this.base[s.id] ??= clone(s.rids)
+ this.seedColumnPos(s)
+ })
+ this.snapRids(doc)
+ }
+
+ /**
+ * Give a table sheet's columns their deterministic order keys.
+ *
+ * Every replica must do this for every sheet it ever holds, however the
+ * sheet arrived — from the file, from a peer's insert, or from a snapshot.
+ * Miss one and the column order stops being a function of the keys: the
+ * replica that MINTED an addColumn keeps the store's array position while
+ * everyone else sorts by keys the payload's columns never got, and the two
+ * show the same columns in different orders.
+ */
+ private seedColumnPos(sheet: Sheet): void {
+ if (sheet.kind !== 'table') return
+ const sn = shNode(sheet.id)
+ const n = sheet.columns.length
+ sheet.columns.forEach((c, j) => {
+ const cn = colNode(sheet.id, c.id)
+ if (!this.pos[cn]) this.pos[cn] = { p: sn, o: spreadKey(j, n), r: [0, ''] }
+ })
+ }
+
+ /**
+ * Refresh the row-order shadow, and drop an override overlay that has been
+ * emptied.
+ *
+ * `cells: {}` is not a state the document should ever be in: an empty
+ * overlay is the absence of an overlay. It arises because `setOverrides`'s
+ * INVERSE only carries `dropEmpty` when the container did not exist before
+ * the patch, so undoing the removal of the last override leaves the empty
+ * object behind — on the undoing replica alone, since every peer receives
+ * the op through a path that always drops it. A twelve-byte difference in
+ * the saved file, and a diverged fingerprint. (The real fix is one flag in
+ * store.ts; see docs/dash-collab.md.)
+ */
+ private snapRids(doc: DashDoc): void {
+ const seen = new Set<string>()
+ for (const s of doc.sheets) {
+ if (s.kind !== 'table') continue
+ seen.add(s.id)
+ if (s.cells && !Object.keys(s.cells).length) delete s.cells
+ // The watermark joins here, on every settle point, because it is
+ // document data that a plain monotonic counter cannot converge — see
+ // settleWatermark.
+ settleWatermark(s, this.births)
+ this.rids[s.id] = clone(s.rids)
+ }
+ for (const id of Object.keys(this.rids)) if (!seen.has(id)) delete this.rids[id]
+ }
+
+ // --- local op minting ----------------------------------------------------
+
+ private stamp(): OpBase {
+ this.lamport++
+ this.seq++
+ this.vv[this.actor] = this.seq
+ return { a: this.actor, s: this.seq, l: this.lamport }
+ }
+
+ /**
+ * Mint ops for patches the store is ABOUT TO APPLY.
+ *
+ * Pre-apply, deliberately, and it is the one ordering subtlety in this file:
+ * a delete has to read what it displaces (the row's registered cell values
+ * park in the stash so a later resurrection can lose to them) and a delete's
+ * `prev` anchors have to be read before the rows go. Everything else is
+ * indifferent. The engine keeps its own run-length row shadow so it never
+ * needs to look at a post-state.
+ */
+ local(doc: DashDoc, patches: Patch[]): Op[] {
+ const ops: Op[] = []
+ for (const p of patches) this.localOne(doc, p, ops)
+ return ops
+ }
+
+ private localOne(doc: DashDoc, p: Patch, ops: Op[]): void {
+ const push = <T extends Op>(o: T): T => { ops.push(o); return o }
+ switch (p.op) {
+ case 'setCells': {
+ // dictLen is a local undo artefact (it truncates a dictionary this edit
+ // grew); shipping it would truncate the RECEIVER's dictionary, which
+ // has a different length. Values are the wire format, never indices.
+ //
+ // It also has to be DISARMED HERE, on the patch the store is about to
+ // apply, and that is not tidiness — it is a silent data loss.
+ //
+ // A dictionary column's `idx` array points into a dictionary SHARED by
+ // every cell in the column, and `applyPatch` honours `dictLen` with a
+ // blunt `data.dict.length = p.dictLen`. That is sound for one writer:
+ // the only entries above the watermark are the ones this patch interned,
+ // and undo unwinds edits in the order they were made, so the dictionary
+ // is always exactly the length the inverse expects. Under collaboration
+ // it is false. A remote `cell` op that lands BETWEEN a local commit and
+ // its undo interns its own strings into the same dictionary, above the
+ // watermark the inverse recorded — so the undo drops them, and every
+ // cell pointing at them reads back null. It is asymmetric by
+ // construction: only the undoing replica truncates, only the values it
+ // did not author are lost, and NOTHING in the sync state changes — no
+ // register moves, no birth, no tomb — so the two replicas end up with
+ // identical sync states and different workbooks. That is exactly the
+ // shape of rig seeds 124 (ACTORS=4, STEPS=250) and 307 (ACTORS=5,
+ // STEPS=300): a text column with two blanks where a peer's values were,
+ // and every other field in agreement.
+ //
+ // The neighbouring guess — that the loss was in the column dead-window
+ // path (resetColumnValues/parkColumn) — was wrong; the column in both
+ // seeds was never deleted at all. The undo that loses the values need
+ // not even name the affected rows.
+ //
+ // Disarming costs the orphaned strings (the dictionary no longer shrinks
+ // back), which store.ts already calls "semantically right and no longer
+ // byte-identical". A live session has given that up regardless: two
+ // replicas intern in the order their ops arrive, so their dictionaries
+ // never matched byte-for-byte — which is why the rig's fingerprint
+ // compares materialized values, not encodings.
+ delete p.dictLen
+ const o = push<CellOp>({ ...this.stamp(), op: 'cell', sh: p.sheet, col: p.col, rids: p.rids.slice(), v: clone(p.v) })
+ p.rids.forEach((rid) => this.setReg(rowNode(p.sheet, rid), vKey(p.col), [o.l, o.a]))
+ break
+ }
+ case 'setOverrides': {
+ const o = push<OvrOp>({
+ ...this.stamp(), op: 'ovr', sh: p.sheet, keys: p.keys.slice(),
+ v: p.keys.map((_, i) => (p.v[i] ?? null) as CellOverride | null),
+ })
+ p.keys.forEach((k) => {
+ const col = k.slice(0, k.indexOf(':'))
+ const rid = Number(k.slice(k.indexOf(':') + 1))
+ this.setReg(rowNode(p.sheet, rid), oKey(col), [o.l, o.a])
+ })
+ break
+ }
+ case 'insertRows': {
+ const before = this.rids[p.sheet] ?? []
+ // Simulate the store's own splice (store.ts insertRows: ascending by
+ // position, each `at` a position in the GROWING list) so the keys are
+ // minted between the right neighbours — including rows inserted
+ // earlier in this same patch, which is why the keys are assigned in
+ // the same ascending pass rather than up front.
+ const flat = rleExpand(before)
+ const order = p.rids.map((rid, i) => ({ rid, at: p.at?.[i] ?? flat.length + i, i }))
+ .sort((a, b) => a.at - b.at)
+ const ord: string[] = new Array(p.rids.length).fill('')
+ for (const { rid, at, i } of order) {
+ const pos = Math.min(at, flat.length)
+ const lo = pos > 0 ? this.rowKey(p.sheet, flat[pos - 1]) : ''
+ const hi = pos < flat.length ? this.rowKey(p.sheet, flat[pos]) : ''
+ // The actor suffix is not decoration. Two replicas inserting between
+ // the same neighbours compute the SAME midstring, and then the list
+ // each one materialises depends on which rows it happened to have —
+ // one replica's sequence stops being sorted by key and every later
+ // binary search lands somewhere else (rig seed 42). Suffixing makes
+ // every key unique, so the sequence is sorted by construction on
+ // every replica. Safe to append: keyBetween never returns a key that
+ // is a prefix of its upper bound, so extending it cannot overshoot.
+ const key = keyBetween(lo, hi) + this.keySuffix
+ ord[i] = key
+ this.rpos[rowNode(p.sheet, rid)] = key
+ flat.splice(pos, 0, rid)
+ }
+ const o = push<RinsOp>({
+ ...this.stamp(), op: 'rins', sh: p.sheet, rids: p.rids.slice(), ord,
+ ...(p.values ? { vals: clone(p.values) } : {}),
+ })
+ p.rids.forEach((rid) => {
+ const n = rowNode(p.sheet, rid)
+ dbg(n, `local rins@${o.l} vals=${JSON.stringify(Object.fromEntries(Object.entries(p.values ?? {}).map(([c, a]) => [c, a[p.rids.indexOf(rid)]])))}`)
+ this.births[n] = [o.l, o.a]
+ this.rnamed[n] = Object.keys(p.values ?? {})
+ // NOT `delete this.stash[n]`: values parked for columns this insert
+ // does not carry still belong to the row, and settle() is what puts
+ // them back. Dropping them here left the author of an undo showing a
+ // blank cell that every collaborator could see filled in.
+ const at = p.rids.indexOf(rid)
+ const vals: Record<string, unknown> = {}
+ for (const [col, arr] of Object.entries(p.values ?? {})) vals[col] = arr[at]
+ this.localRows.push({ sh: p.sheet, rid, birth: [o.l, o.a], named: this.rnamed[n], vals })
+ })
+ this.rids[p.sheet] = rleCompress(flat)
+ break
+ }
+ case 'deleteRows': {
+ const before = this.rids[p.sheet] ?? []
+ const sheet = tableOf(doc, p.sheet)
+ const o = push<RdelOp>({ ...this.stamp(), op: 'rdel', sh: p.sheet, rids: p.rids.slice() })
+ p.rids.forEach((rid) => {
+ const n = rowNode(p.sheet, rid)
+ dbg(n, `local rdel@${o.l}`)
+ if (sheet) this.stashRow(sheet, p.sheet, rid)
+ this.tombs[n] = [o.l, o.a]
+ })
+ const flat = rleExpand(before).filter((r) => !p.rids.includes(r))
+ this.rids[p.sheet] = rleCompress(flat)
+ break
+ }
+ case 'addColumn': {
+ const sheet = tableOf(doc, p.sheet)
+ const ids = sheet ? sheet.columns.map((c) => c.id) : []
+ const at = p.at ?? ids.length
+ ids.splice(at, 0, p.column.id)
+ const ord = this.keyAround(shNode(p.sheet), ids.map((id) => colNode(p.sheet, id)), at)
+ const n = colNode(p.sheet, p.column.id)
+ const o = push<InsOp>({
+ ...this.stamp(), op: 'ins', n, ord, node: clone(p.column),
+ // `pack` is an author-chosen archive encoding that cannot be written
+ // into (store.ts refuses); a synced column comes back writable.
+ ...(p.data ? { enc: p.data.enc === 'dict' ? 'dict' as const : 'raw' as const } : {}),
+ })
+ // The values follow as a cell op — see InsOp. Nulls are skipped: a
+ // blank needs no register, and a fresh column is blank everywhere.
+ const keep: number[] = []
+ const vals: unknown[] = []
+ if (p.data) {
+ const rids = rleExpand(this.rids[p.sheet] ?? [])
+ rids.forEach((rid, i) => {
+ const v = readCell(p.data!, i)
+ if (v === null || v === undefined) return
+ keep.push(rid)
+ vals.push(v)
+ })
+ if (keep.length) {
+ const c = push<CellOp>({ ...this.stamp(), op: 'cell', sh: p.sheet, col: p.column.id, rids: keep, v: clone(vals) })
+ keep.forEach((rid) => this.setReg(rowNode(p.sheet, rid), vKey(p.column.id), [c.l, c.a]))
+ }
+ }
+ this.births[n] = [o.l, o.a]
+ this.pos[n] = { p: shNode(p.sheet), o: ord, r: [o.l, o.a] }
+ delete this.stash[n]
+ this.localCols.push({
+ sh: p.sheet, col: p.column.id, birth: [o.l, o.a],
+ ...(p.data ? { enc: p.data.enc === 'dict' ? 'dict' as const : 'raw' as const } : {}),
+ rids: keep, vals: clone(vals),
+ })
+ break
+ }
+ case 'removeColumn': {
+ const n = colNode(p.sheet, p.col)
+ const sheet = tableOf(doc, p.sheet)
+ const col = sheet?.columns.find((c) => c.id === p.col)
+ const o = push<DelOp>({ ...this.stamp(), op: 'del', n })
+ if (sheet) this.parkColumn(sheet, p.col)
+ if (col) this.stashNode(col as unknown as Record<string, unknown>, n)
+ this.tombs[n] = [o.l, o.a]
+ break
+ }
+ case 'reorderColumns': {
+ this.diffOrder(p.order.map((id) => colNode(p.sheet, id)), shNode(p.sheet), push)
+ break
+ }
+ case 'setColumn': {
+ const n = colNode(p.sheet, p.col)
+ for (const [k, v] of Object.entries(p.patch)) {
+ const o = push<SetOp>({ ...this.stamp(), op: 'set', n, k, ...(v === undefined ? {} : { v: clone(v) }) })
+ this.setReg(n, k, [o.l, o.a])
+ }
+ break
+ }
+ case 'setSheetProps': {
+ const n = shNode(p.sheet)
+ for (const [k, v] of Object.entries(p.props)) {
+ const o = push<SetOp>({ ...this.stamp(), op: 'set', n, k, v: clone(v) })
+ this.setReg(n, k, [o.l, o.a])
+ }
+ for (const k of p.drop ?? []) {
+ const o = push<SetOp>({ ...this.stamp(), op: 'set', n, k })
+ this.setReg(n, k, [o.l, o.a])
+ }
+ break
+ }
+ case 'setMeasure': {
+ const k = `measures.${p.name}`
+ const o = push<SetOp>({ ...this.stamp(), op: 'set', k, ...(p.measure === undefined ? {} : { v: clone(p.measure) }) })
+ this.setReg(DOC_NODE, k, [o.l, o.a])
+ break
+ }
+ case 'setTitle': {
+ const o = push<SetOp>({ ...this.stamp(), op: 'set', k: 'title', v: p.title })
+ this.setReg(DOC_NODE, 'title', [o.l, o.a])
+ break
+ }
+ default:
+ // applySteps / refreshBinding (the store refuses both today), or a
+ // patch op a future build minted. Never silently dropped: the session
+ // ships a whole-state snapshot, which is slower and always correct.
+ this.unsynced = true
+ break
+ }
+ }
+
+ /** Sheets are added by `replaceDoc` today (there is no addSheet patch), so
+ * their ops are minted explicitly by the session's structural reconciler. */
+ sheetIns(doc: DashDoc, sheet: Sheet): InsOp {
+ const ids = doc.sheets.map((s) => shNode(s.id))
+ const at = doc.sheets.findIndex((s) => s.id === sheet.id)
+ const ord = this.keyAround(DOC_NODE, ids, at < 0 ? ids.length : at)
+ const n = shNode(sheet.id)
+ const o: InsOp = { ...this.stamp(), op: 'ins', n, ord, node: clone(sheet) }
+ this.births[n] = [o.l, o.a]
+ this.pos[n] = { p: DOC_NODE, o: ord, r: [o.l, o.a] }
+ delete this.stash[n]
+ if (sheet.kind === 'table') {
+ this.rids[sheet.id] = clone(sheet.rids)
+ this.base[sheet.id] ??= clone(sheet.rids)
+ this.seedColumnPos(sheet)
+ }
+ return o
+ }
+
+ sheetDel(sheetId: string): DelOp {
+ const n = shNode(sheetId)
+ const o: DelOp = { ...this.stamp(), op: 'del', n }
+ this.tombs[n] = [o.l, o.a]
+ delete this.rids[sheetId]
+ return o
+ }
+
+ /** ord key for position i within `nodes` under parent `p` */
+ private keyAround(p: string, nodes: string[], i: number): string {
+ const ordOf = (n: string | undefined) =>
+ n && this.pos[n] && this.pos[n].p === p ? this.pos[n].o : undefined
+ let lo = ''
+ for (let k = i - 1; k >= 0; k--) { const o = ordOf(nodes[k]); if (o) { lo = o; break } }
+ let hi = ''
+ for (let k = i + 1; k < nodes.length; k++) {
+ const o = ordOf(nodes[k])
+ if (o && (!lo || o > lo)) { hi = o; break }
+ }
+ return keyBetween(lo, hi)
+ }
+
+ /** Emit ord ops for nodes whose relative order changed: keep a longest
+ * increasing run (by current pos key) untouched, re-key the rest. */
+ private diffOrder(nodes: string[], parent: string, push: <T extends Op>(o: T) => T): void {
+ if (nodes.some((n) => !this.pos[n])) return // unknown — keyed elsewhere
+ const keys = nodes.map((n) => this.pos[n].o + ' ' + n)
+ const keep = new Set(longestIncreasing(keys))
+ for (let i = 0; i < nodes.length; i++) {
+ if (keep.has(i) && this.pos[nodes[i]].p === parent) continue
+ let lo = ''
+ for (let k = i - 1; k >= 0; k--) {
+ const e = this.pos[nodes[k]]
+ if (e && e.p === parent) { lo = e.o; break }
+ }
+ let hi = ''
+ for (let k = i + 1; k < nodes.length; k++) {
+ if (!keep.has(k)) continue
+ const e = this.pos[nodes[k]]
+ if (e && e.p === parent && e.o > lo) { hi = e.o; break }
+ }
+ const ord = keyBetween(lo, hi)
+ const o = push<OrdOp>({ ...this.stamp(), op: 'ord', n: nodes[i], ord })
+ this.pos[nodes[i]] = { p: parent, o: ord, r: [o.l, o.a] }
+ }
+ }
+
+ // --- applying remote ops -------------------------------------------------
+
+ apply(doc: DashDoc, ops: Op[]): ApplyResult {
+ const res: ApplyResult = { changed: false, structure: false }
+ for (const op of ops) this.applyOne(doc, op, res)
+ this.reconcileParked(doc)
+ if (res.structure) this.rematerialize(doc)
+ this.snapRids(doc)
+ return res
+ }
+
+ private applyOne(doc: DashDoc, op: Op, res: ApplyResult): void {
+ if (op.a === this.actor) return // our own ops are pre-applied at mint time
+ const seen = this.vv[op.a] ?? 0
+ if (op.s <= seen) return // duplicate
+ if (op.s > seen + 1) {
+ const g = (this.gap[op.a] ??= [])
+ if (!g.some((o) => o.s === op.s)) { g.push(op); g.sort((x, y) => x.s - y.s) }
+ return
+ }
+ this.vv[op.a] = op.s
+ this.lamport = Math.max(this.lamport, op.l)
+ this.applyEffect(doc, op, res)
+ const g = this.gap[op.a]
+ while (g && g.length && g[0].s === this.vv[op.a] + 1) {
+ const next = g.shift()!
+ this.vv[op.a] = next.s
+ this.lamport = Math.max(this.lamport, next.l)
+ this.applyEffect(doc, next, res)
+ }
+ }
+
+ private applyEffect(doc: DashDoc, op: Op, res: ApplyResult): void {
+ switch (op.op) {
+ case 'set': this.applySet(doc, op, res); break
+ case 'cell': this.applyCell(doc, op, res); break
+ case 'ovr': this.applyOvr(doc, op, res); break
+ case 'rins': this.applyRins(doc, op, res); break
+ case 'rdel': this.applyRdel(doc, op, res); break
+ case 'ins': this.applyIns(doc, op, res); break
+ case 'del': this.applyDel(doc, op, res); break
+ case 'ord': this.applyOrd(doc, op, res); break
+ }
+ }
+
+ private pend(node: string, op: Op): void {
+ dbg(node, `PEND ${op.op}@${op.l},${op.a}`)
+ ;(this.pending[node] ??= []).push(op)
+ }
+
+ /**
+ * Drain everything parked on a sheet's members.
+ *
+ * A row that arrives INSIDE a sheet payload has no insert op of its own, so
+ * nothing ever fires the per-row drain for it — an override that raced ahead
+ * of the sheet stayed parked forever on the replicas that received it early,
+ * and only the author kept it. Sheet-level events therefore have to sweep
+ * the whole namespace, not just their own node.
+ */
+ private drainSheet(doc: DashDoc, sheetId: string): void {
+ const rows = rowNode(sheetId, 0).slice(0, -1)
+ const cols = colNode(sheetId, '')
+ for (const node of Object.keys(this.pending)) {
+ if (node.startsWith(rows) || node.startsWith(cols)) this.drainPending(doc, node)
+ }
+ }
+
+ private drainPending(doc: DashDoc, node: string, res?: ApplyResult): void {
+ const ps = this.pending[node]
+ if (!ps) return
+ delete this.pending[node]
+ const r: ApplyResult = res ?? { changed: false, structure: false }
+ for (const p of ps) this.applyEffect(doc, p, r)
+ }
+
+ /**
+ * Retry every parked op after a LOCAL change has been applied.
+ *
+ * Remote ops park on nodes we have not seen; the drains that release them
+ * all hang off remote events. A row brought back by the user's own undo
+ * fires none of them, so an override or a cell edit waiting on that row
+ * stayed parked forever — on the peers that received it early, and only
+ * there (rig seed 57). The session calls this right after the store has
+ * applied a local commit; the queue is O(edits) and an op that still cannot
+ * land simply parks again.
+ */
+ settle(doc: DashDoc): ApplyResult {
+ const res: ApplyResult = { changed: false, structure: false }
+ // (snapRids at the foot of this method performs the watermark join)
+ for (const { sh, rid, birth, named, vals } of this.localRows.splice(0)) {
+ const sheet = tableOf(doc, sh)
+ if (!sheet || !rleHas(sheet.rids, rid)) continue
+ this.replayStashRow(doc, sheet, sh, rid, birth, new Set(named))
+ // The remote path's park, for the local one: a value the insert carried
+ // for a column that does not exist here has nowhere to go, and applyPatch
+ // simply drops it. Park it against the row's birth so the column's
+ // arrival can claim it — the author of an insert must end up with the
+ // same cells as everyone who received it.
+ for (const col of named) {
+ if (sheet.data[col]) continue
+ const st = (this.stash[rowNode(sh, rid)] ??= {})
+ // Same rule as the remote path: a parked write NEWER than this insert
+ // out-stamps the insert's claim on the column and must survive it.
+ const cur = st[vKey(col)]
+ if (cur && regNewer(cur.r, birth)) continue
+ st[vKey(col)] = { v: clone(vals[col] ?? null), r: clone(birth) }
+ }
+ }
+ for (const { sh, col, birth, enc, rids, vals } of this.localCols.splice(0)) {
+ const sheet = tableOf(doc, sh)
+ if (!sheet || !sheet.columns.some((c) => c.id === col)) continue
+ // The author of a column insert takes the SAME path as everyone who
+ // receives it: reset to the encoding, then apply the values the op
+ // carries. The store has already written `p.data` here, and if that
+ // snapshot was stale (undo of a delete, rows changed since) the author
+ // would otherwise be the only participant holding the stale version.
+ this.resetColumnValues(doc, sheet, col, birth, enc)
+ const live = rids.filter((rid) => rleHas(sheet.rids, rid))
+ if (live.length && sheet.data[col]) {
+ applyPatch(doc, {
+ op: 'setCells', sheet: sh, col, rids: live,
+ v: live.map((rid) => clone(vals[rids.indexOf(rid)])),
+ })
+ }
+ }
+ for (const node of Object.keys(this.pending)) this.drainPending(doc, node, res)
+ this.reconcileParked(doc)
+ if (res.structure) this.rematerialize(doc)
+ this.snapRids(doc)
+ return res
+ }
+
+ // --- property sets --------------------------------------------------------
+
+ private applySet(doc: DashDoc, op: SetOp, res: ApplyResult): void {
+ const node = op.n ?? DOC_NODE
+ if (older(op.l, op.a, this.reg(node, op.k))) return
+ if (node === DOC_NODE) {
+ this.setReg(node, op.k, [op.l, op.a])
+ writeDocKey(doc, op.k, op.v)
+ res.changed = true
+ return
+ }
+ // birth gate: an ins is a whole-node assignment, so sets older than the
+ // node's (re)birth are superseded everywhere (the register still advances)
+ const birth = this.births[node]
+ if (birth && !newer(op.l, op.a, birth)) { this.setReg(node, op.k, [op.l, op.a]); return }
+ if (this.dead(node)) {
+ this.setReg(node, op.k, [op.l, op.a])
+ ;(this.stash[node] ??= {})[op.k] =
+ op.v === undefined ? { r: [op.l, op.a] } : { v: clone(op.v), r: [op.l, op.a] }
+ return
+ }
+ const sheetId = nodeSheet(node)
+ if (this.dead(shNode(sheetId))) {
+ // The sheet is gone, so there is nothing to write — but the register
+ // must still advance, or the replica that applied this op BEFORE the
+ // sheet died would carry a register its peers never learn and the two
+ // states would disagree forever about a value neither can see.
+ this.setReg(node, op.k, [op.l, op.a])
+ ;(this.stash[node] ??= {})[op.k] =
+ op.v === undefined ? { r: [op.l, op.a] } : { v: clone(op.v), r: [op.l, op.a] }
+ return
+ }
+ const sheet = doc.sheets.find((s) => s.id === sheetId)
+ if (!sheet) { this.pend(shNode(sheetId), op); return }
+ let target: Record<string, unknown> | undefined
+ if (node[0] === 's') target = sheet as unknown as Record<string, unknown>
+ else {
+ if (sheet.kind !== 'table') return
+ target = sheet.columns.find((c) => c.id === nodeTail(node)) as unknown as Record<string, unknown> | undefined
+ if (!target) { this.pend(node, op); return }
+ }
+ this.setReg(node, op.k, [op.l, op.a])
+ writeKey(target, op.k, op.v)
+ res.changed = true
+ if (node[0] === 's') res.structure = true // sheet name/frozen/condfmt all relayout
+ }
+
+ // --- cells ----------------------------------------------------------------
+
+ private applyCell(doc: DashDoc, op: CellOp, res: ApplyResult): void {
+ const sheet = tableOf(doc, op.sh)
+ // A missing sheet is two different situations and they must not be
+ // conflated: DEAD means every replica will agree it is gone, so the op is
+ // book-kept and dropped; ABSENT means its insert is still in flight, so
+ // the op waits (applyDel/applyIns both drain this queue).
+ if (!sheet && !this.dead(shNode(op.sh))) { this.pend(shNode(op.sh), op); return }
+ // A formula column stores no values (model.ts: storing them would let a
+ // file carry a number that disagrees with the formula) — nothing to write,
+ // and applyPatch would throw. The register still advances so state converges.
+ // The COLUMN is the other half of a cell's identity, so it gates the op the
+ // same way the sheet does. Absent-and-not-dead means its insert is still in
+ // flight: pend WITHOUT advancing any register, or the drained op would find
+ // its own register already recorded and skip itself — the value would be
+ // dropped on this replica and kept on the sender's, which is how one
+ // workbook ends up with a number the other has never heard of.
+ if (sheet && !sheet.columns.some((c) => c.id === op.col)) {
+ if (!this.dead(colNode(op.sh, op.col))) { this.pend(colNode(op.sh, op.col), op); return }
+ }
+ // A column insert carries the whole column's values, so it is a whole-node
+ // assignment for every cell in it: writes older than the (re)birth lose,
+ // exactly as they do against a row's birth.
+ const colBirth = this.births[colNode(op.sh, op.col)]
+ const colDead = this.dead(colNode(op.sh, op.col))
+ // A column insert is a whole-column event: writes minted before it are
+ // superseded, exactly as a row insert supersedes writes to the row.
+ const superseded = colBirth !== undefined && !newer(op.l, op.a, colBirth)
+ const hasData = !!sheet?.data[op.col]
+ const live: number[] = []
+ const liveV: unknown[] = []
+ for (let i = 0; i < op.rids.length; i++) {
+ const rid = op.rids[i]
+ const node = rowNode(op.sh, rid)
+ const key = vKey(op.col)
+ if (older(op.l, op.a, this.reg(node, key))) continue
+ // The row's insert supersedes older writes ONLY into the columns it
+ // carried; a write into any other column is untouched by it.
+ const birth = this.births[node]
+ if (birth && !newer(op.l, op.a, birth) && this.rowNames(node, op.col)) {
+ this.setReg(node, key, [op.l, op.a])
+ continue
+ }
+ if (this.dead(node)) {
+ this.setReg(node, key, [op.l, op.a])
+ ;(this.stash[node] ??= {})[key] = { v: clone(op.v[i]), r: [op.l, op.a] }
+ continue
+ }
+ if (!sheet || superseded) { this.setReg(node, key, [op.l, op.a]); continue }
+ if (colDead) {
+ // Buried HERE — but an undo may already have revived it elsewhere, and
+ // this write may out-stamp that revival, in which case the replicas
+ // that got them the other way round keep it. So advance the register
+ // (states converge) and PARK the op on the column: if the column comes
+ // back the write replays, and if it does not the op simply never runs.
+ // Dropping it instead cost exactly one replica exactly one number.
+ this.setReg(node, key, [op.l, op.a])
+ this.pend(colNode(op.sh, op.col), { ...op, rids: [rid], v: [op.v[i]] })
+ continue
+ }
+ if (!rleHas(sheet!.rids, rid)) {
+ // the row's insert has not arrived yet (cross-actor delivery race)
+ this.pend(node, { ...op, rids: [rid], v: [op.v[i]] })
+ continue
+ }
+ this.setReg(node, key, [op.l, op.a])
+ live.push(rid)
+ liveV.push(op.v[i])
+ }
+ if (!live.length || !hasData) return
+ applyPatch(doc, { op: 'setCells', sheet: op.sh, col: op.col, rids: live, v: clone(liveV) })
+ res.changed = true
+ }
+
+ private applyOvr(doc: DashDoc, op: OvrOp, res: ApplyResult): void {
+ const sheet = tableOf(doc, op.sh)
+ if (!sheet && !this.dead(shNode(op.sh))) { this.pend(shNode(op.sh), op); return }
+ const cols = new Set(op.keys.map((k) => k.slice(0, k.indexOf(':'))))
+ for (const c of cols) {
+ if (sheet && !sheet.columns.some((x) => x.id === c) && !this.dead(colNode(op.sh, c))) {
+ this.pend(colNode(op.sh, c), op)
+ return
+ }
+ }
+ const keys: string[] = []
+ const vals: Array<CellOverride | null> = []
+ for (let i = 0; i < op.keys.length; i++) {
+ const k = op.keys[i]
+ const col = k.slice(0, k.indexOf(':'))
+ const rid = Number(k.slice(k.indexOf(':') + 1))
+ const node = rowNode(op.sh, rid)
+ const key = oKey(col)
+ if (older(op.l, op.a, this.reg(node, key))) continue
+ // Overrides are not carried by a row insert, but a row's DEATH takes
+ // them with it (killRowOverrides), so a rebirth does supersede an older
+ // one — no `rnamed` exception here, unlike cell values.
+ const birth = this.births[node]
+ if (birth && !newer(op.l, op.a, birth)) { this.setReg(node, key, [op.l, op.a]); continue }
+ if (this.dead(node)) {
+ this.setReg(node, key, [op.l, op.a])
+ ;(this.stash[node] ??= {})[key] = { v: clone(op.v[i]), r: [op.l, op.a] }
+ continue
+ }
+ if (!sheet) { this.setReg(node, key, [op.l, op.a]); continue } // the sheet is gone
+ const cb = this.births[colNode(op.sh, col)]
+ if (cb && !newer(op.l, op.a, cb)) { this.setReg(node, key, [op.l, op.a]); continue } // superseded
+ if (this.dead(colNode(op.sh, col))) { // buried here — park it, see applyCell
+ this.setReg(node, key, [op.l, op.a])
+ this.pend(colNode(op.sh, col), { ...op, keys: [k], v: [op.v[i]] })
+ continue
+ }
+ if (!rleHas(sheet.rids, rid)) { this.pend(node, { ...op, keys: [k], v: [op.v[i]] }); continue }
+ this.setReg(node, key, [op.l, op.a])
+ keys.push(k)
+ vals.push(op.v[i])
+ }
+ if (!keys.length) return
+ applyPatch(doc, { op: 'setOverrides', sheet: op.sh, keys, v: clone(vals), dropEmpty: true })
+ res.changed = true
+ }
+
+ // --- rows -----------------------------------------------------------------
+
+ /**
+ * A row's fractional order key.
+ *
+ * Explicit for inserted rows; DERIVED for the rows that came with the sheet,
+ * from their position in the adopted baseline. That derivation is the reason
+ * a million-row workbook costs nothing to sync until somebody edits it.
+ */
+ /** Exposed for the convergence rig's sortedness invariant — not an app
+ * surface. The rig asserts, after every apply, that a sheet's `rids` really
+ * is sorted by (key, rid); a binary search over a list that is not sorted
+ * lands anywhere, which is how row order diverges while every register
+ * agrees. */
+ rowOrderKey(sh: string, rid: number): string { return this.rowKey(sh, rid) }
+
+ private rowKey(sh: string, rid: number): string {
+ const explicit = this.rpos[rowNode(sh, rid)]
+ if (explicit !== undefined) return explicit
+ const b = this.base[sh]
+ if (b) {
+ const i = rleIndex(b, rid)
+ if (i >= 0) return spreadKey(i, rleCount(b))
+ }
+ // No baseline (state discarded, or a hand-built sheet): fall back to the
+ // rid itself so the order is at least stable and total. Padded so that 9
+ // sorts before 10 — an unpadded number sorts lexicographically and would
+ // put row 10 before row 9.
+ return `~${String(rid).padStart(12, '0')}`
+ }
+
+ /** where a key belongs in a sheet's live sequence (binary search: the list is
+ * always sorted by (key, rid), and rleAt walks runs, not rows) */
+ private rowIndexFor(sheet: TableSheet, sh: string, key: string, rid: number): number {
+ const after = (at: number): boolean => {
+ const other = rleAt(sheet.rids, at)
+ const k = this.rowKey(sh, other)
+ return k < key || (k === key && other < rid)
+ }
+ let lo = 0
+ let hi = rleCount(sheet.rids)
+ while (lo < hi) {
+ const mid = (lo + hi) >> 1
+ if (after(mid)) lo = mid + 1
+ else hi = mid
+ }
+ return lo
+ }
+
+ /**
+ * Move a row that is already in the sheet to where its (new) key says it
+ * belongs.
+ *
+ * Only a resurrection can change a live row's key, so this is rare — but it
+ * has to rebuild the column arrays, because a row's VALUES are addressed by
+ * position and moving the rid alone would hand every row below the move
+ * somebody else's numbers. `permuteRows` is the same routine the snapshot
+ * merge uses: one pass per column, dictionaries kept intact, `pack` columns
+ * left alone.
+ */
+ private relocateRow(sheet: TableSheet, sh: string, rid: number): void {
+ const flat = rleExpand(sheet.rids)
+ const at = flat.indexOf(rid)
+ if (at < 0) return
+ flat.splice(at, 1)
+ const key = this.rowKey(sh, rid)
+ let lo = 0
+ let hi = flat.length
+ while (lo < hi) {
+ const mid = (lo + hi) >> 1
+ const other = flat[mid]
+ const k = this.rowKey(sh, other)
+ if (k < key || (k === key && other < rid)) lo = mid + 1
+ else hi = mid
+ }
+ if (lo === at) return
+ flat.splice(lo, 0, rid)
+ permuteRows(sheet, flat)
+ }
+
+ private applyRins(doc: DashDoc, op: RinsOp, res: ApplyResult): void {
+ const sheet = tableOf(doc, op.sh)
+ const stamp: Reg = [op.l, op.a]
+ if (!sheet && !this.dead(shNode(op.sh))) { this.pend(shNode(op.sh), op); return }
+ for (let i = 0; i < op.rids.length; i++) {
+ const rid = op.rids[i]
+ const node = rowNode(op.sh, rid)
+ const birth = this.births[node]
+ if (birth && !newer(op.l, op.a, birth)) continue // an older create
+ const wasKey = this.rpos[node]
+ this.births[node] = stamp
+ this.rpos[node] = op.ord[i]
+ this.rnamed[node] = Object.keys(op.vals ?? {})
+ res.changed = true
+ res.structure = true
+ // A delete still out-stamps this insert. The key is recorded above
+ // regardless, so ops waiting on this row can resolve now.
+ if (!sheet || this.dead(node)) { this.drainPending(doc, node); continue }
+ if (rleHas(sheet.rids, rid)) {
+ // ALREADY HERE — and the winning insert has just given the row a NEW
+ // key, so the row has to MOVE to match it. Recording the key and
+ // leaving the row where it sat is what broke row order at six actors
+ // (rig seed 116).
+ //
+ // The asymmetry is exact and invisible in the sync state, because the
+ // key both replicas end up holding is the same one. A row deleted and
+ // then resurrected by TWO actors gets two competing `rins`, and the
+ // higher (lamport, actor) wins the key everywhere. But a replica that
+ // received the loser FIRST already has the row in the document, so the
+ // winner arrives down this branch and only updated `rpos`; a replica
+ // that received the winner first placed the row by binary search at the
+ // winning key and then discarded the loser at the "an older create"
+ // gate. Same `rpos`, same births, same tombs — two different sequences.
+ //
+ // Worse than one row in the wrong place: `rids` is now no longer sorted
+ // by (key, rid), and `rowIndexFor` is a BINARY SEARCH that assumes it
+ // is. Every later insert on that replica lands somewhere arbitrary, so
+ // one stale key spreads into a wholly different row order. That is why
+ // it took six actors to see — it needs two concurrent resurrections of
+ // one row plus a later insert to amplify.
+ if (wasKey !== op.ord[i]) this.relocateRow(sheet, op.sh, rid)
+ continue
+ }
+ const idx = this.rowIndexFor(sheet, op.sh, op.ord[i], rid)
+ const vals: Record<string, unknown[]> = {}
+ for (const [col, arr] of Object.entries(op.vals ?? {})) vals[col] = [clone(arr[i])]
+ const named = new Set(Object.keys(vals))
+ // Where a row insert and a column insert cross, the newer one owns the
+ // cell. The column's payload is empty by construction, so "the column
+ // wins" means the cell is left blank for its own cell op to fill.
+ for (const col of named) {
+ const cb = this.births[colNode(op.sh, col)]
+ if (cb && !regNewer(stamp, cb)) { delete vals[col]; named.delete(col) }
+ }
+ dbg(node, `rins@${op.l},${op.a} ord=${op.ord[i]} at=${idx} vals=${JSON.stringify(vals)}`)
+ applyPatch(doc, { op: 'insertRows', sheet: op.sh, rids: [rid], at: [idx], values: vals })
+ this.replayStashRow(doc, sheet, op.sh, rid, stamp, named)
+ // A value for a column whose insert has not arrived has nowhere to go —
+ // applyPatch writes only into columns that exist — so park it against
+ // this row's birth and let the column's arrival claim it. AFTER the
+ // replay, which clears the stash it just consumed. Nulls are parked too:
+ // the parked entry is also the RECORD that this row's insert claimed the
+ // column, which is what tells the arriving column to stand down.
+ for (const col of named) {
+ if (sheet.data[col]) continue
+ const st = (this.stash[node] ??= {})
+ // NEVER clobber a parked entry that is NEWER than this insert. The
+ // insert claims the column, but a write minted after it out-stamps the
+ // claim, and the parked copy may be the only one left: on the author of
+ // that write the value was applied straight to a live document and was
+ // never pended anywhere, so overwriting it here deleted it outright,
+ // while every replica that received the write while the column was
+ // buried still had it queued on the column node and replayed it when
+ // the column came back. Rig seed 163 (ACTORS=6, STEPS=250): five
+ // replicas holding a number and its own author holding a blank.
+ // parkColumn has always carried the equivalent rule.
+ const cur = st[vKey(col)]
+ if (cur && regNewer(cur.r, stamp)) continue
+ st[vKey(col)] = { v: clone(vals[col]?.[0] ?? null), r: clone(stamp) }
+ }
+ this.drainPending(doc, node)
+ }
+ }
+
+ private applyRdel(doc: DashDoc, op: RdelOp, res: ApplyResult): void {
+ const sheet = tableOf(doc, op.sh)
+ if (!sheet && !this.dead(shNode(op.sh))) { this.pend(shNode(op.sh), op); return }
+ const gone: number[] = []
+ for (let i = 0; i < op.rids.length; i++) {
+ const rid = op.rids[i]
+ const node = rowNode(op.sh, rid)
+ if (!this.tombs[node] || newer(op.l, op.a, this.tombs[node])) this.tombs[node] = [op.l, op.a]
+ if (!this.dead(node)) continue
+ if (sheet && rleHas(sheet.rids, rid)) {
+ this.stashRow(sheet, op.sh, rid)
+ gone.push(rid)
+ }
+ this.drainPending(doc, node)
+ }
+ if (gone.length) {
+ dropRowOverrides(doc, sheet!, gone)
+ applyPatch(doc, { op: 'deleteRows', sheet: op.sh, rids: gone })
+ }
+ res.changed = true
+ res.structure = true
+ }
+
+ /**
+ * Who currently owns a cell's value?
+ *
+ * A cell sits in the intersection of TWO whole-node assignments — the row's
+ * insert payload and the COLUMN's insert payload — so the authority is
+ * max(cell register, column birth, row birth). But an assignment only claims
+ * the cells it actually NAMES: a row insert minted before a column existed
+ * says nothing about that column, and must not blank it. `fromRow` is that
+ * distinction — the caller knows whether the row's payload carried this
+ * column, because it is holding the payload. Without this the answer depended on arrival order, both ways round:
+ * a replica that got the column insert after a row's resurrection wrote the
+ * row payload's blank over a number all its peers could see (seed 18), and a
+ * replica that got a row insert before the column existed dropped the value
+ * the row was carrying for it (seed 36). Neither is recoverable later, which
+ * is why both are parked rather than resolved on the spot.
+ */
+ private cellAuth(sh: string, rid: number, key: string, fromRow = true): Reg | undefined {
+ const r = this.reg(rowNode(sh, rid), key)
+ if (!isVKey(key) || !fromRow) return r
+ const b = this.births[rowNode(sh, rid)]
+ return r && (!b || regNewer(r, b)) ? r : b
+ }
+
+ /**
+ * Park a dying row's cell values so a later resurrection can lose to them.
+ *
+ * Registered cells (somebody typed in them) and cells owned by a column that
+ * was created after the row — everything whose authority might out-stamp the
+ * insert that brings the row back. Cells nobody has touched, in columns older
+ * than the row, have no authority to record and cost nothing here: that is
+ * what keeps the state O(edits) on a sheet with a million untouched rows.
+ */
+ private stashRow(sheet: TableSheet, sh: string, rid: number): void {
+ const node = rowNode(sh, rid)
+ const at = rleIndex(sheet.rids, rid)
+ if (at < 0) return
+ const keys = new Set(Object.keys(this.regs[node] ?? {}))
+ for (const c of this.rnamed[node] ?? []) keys.add(vKey(c))
+ if (!keys.size) return
+ const st = (this.stash[node] ??= {})
+ for (const k of keys) {
+ // `rnamed` again: the row's birth is only an authority over the columns
+ // its insert carried. Parking a value under the row's stamp when the row
+ // never claimed that column made the stamp unrecognisable at the next
+ // resurrection, and the value was quietly dropped on that replica alone.
+ const r = this.cellAuth(sh, rid, k, !isVKey(k) || this.rowNames(node, keyCol(k)))
+ if (!r) continue
+ const v = isVKey(k) ? readCell(sheet.data[keyCol(k)], at) : sheet.cells?.[`${keyCol(k)}:${rid}`]
+ if (!(k in st) || cmpReg(st[k].r, r) !== 0) {
+ st[k] = v === undefined ? { r: clone(r) } : { v: clone(v), r: clone(r) }
+ }
+ }
+ }
+
+ /**
+ * Replay parked values over a row that has just (re)appeared.
+ *
+ * `named` is the set of columns the insert's payload carried. For those, the
+ * row is a competing assignment and only a NEWER authority may overwrite it.
+ * For every other column the row makes no claim at all, so whatever the
+ * column last said still stands and is restored unconditionally — otherwise
+ * `applyPatch`'s blank for an uncarried column silently becomes the value.
+ */
+ private replayStashRow(doc: DashDoc, sheet: TableSheet, sh: string, rid: number, birth: Reg, named: Set<string>): void {
+ const node = rowNode(sh, rid)
+ const st = this.stash[node]
+ if (!st) return
+ const keep: Record<string, { v?: unknown; r: Reg }> = {}
+ for (const [k, ent] of Object.entries(st)) {
+ const col = keyCol(k)
+ // The column is not here — buried, or its insert has not landed yet.
+ // Either way the value STAYS PARKED rather than being written (it would
+ // go into a column that does not exist) or dropped (deadness is a
+ // transient view; an undo that revives the column is exactly the case
+ // where a peer still holds this value, and assignColumnData reclaims
+ // parked entries when the column comes back).
+ if (this.dead(colNode(sh, col)) || (isVKey(k) && !sheet.data[col])) { keep[k] = ent; continue }
+ const claims = !isVKey(k) || named.has(col)
+ const r = this.cellAuth(sh, rid, k, claims)
+ // The authority the value is being weighed under.
+ //
+ // When the row's payload CLAIMS this column the two are competing
+ // assignments and only a strictly newer one may survive the rebirth.
+ //
+ // When it does NOT claim it, the parked entry IS the last word for the
+ // cell, and asking `cellAuth(…, fromRow:false)` for a verdict was the
+ // seed-374/184 bug. `rnamed` records only the CURRENT birth's claim, so a
+ // row resurrected TWICE — the first insert naming the column, the second
+ // (from a peer who did not have the column yet) not naming it —
+ // overwrites the record that the first insert ever claimed anything.
+ // After that the parked entry's stamp is the older birth, `cellAuth`
+ // returns the bare cell register (or undefined, when the value only ever
+ // arrived in a row payload), the stale guard below sees two different
+ // stamps and drops the value — while the author of the second
+ // resurrection, which never held a parked copy because it never processed
+ // the first insert, keeps the number it already had in the document. The
+ // MINORITY replica was right: an insert that does not name a column makes
+ // no claim on it, so nothing has superseded the parked value and it must
+ // come back. Only something strictly NEWER than the parked stamp can
+ // displace it.
+ const auth = claims ? r : (r && regNewer(r, ent.r) ? r : ent.r)
+ if (!auth) continue
+ if (claims && !regNewer(auth, birth)) continue
+ // THE COLUMN'S OWN BIRTH IS THE OTHER ASSIGNMENT, and it has to be
+ // weighed here as well as in reconcileParked — this is where the two
+ // readers of the stash disagreed.
+ //
+ // A cell sits under two whole-node assignments (cellAuth says so), yet
+ // this replay only ever compared the parked authority against the ROW's
+ // rebirth. So a value parked during the COLUMN's dead window was written
+ // back the moment its row reappeared, no matter how much newer the
+ // column's resurrection was. The asymmetry that follows is exact: the
+ // replica that had the value in hand (parked at delete time, or stashed
+ // because the write arrived while the row was dead) restored it, while
+ // every replica that reached the column's rebirth through
+ // resetColumnValues — which DOES apply the rule, `!regNewer(auth, birth)`
+ // — correctly blanked it. Same registers, same births, same tombs on both
+ // sides; one number more on one workbook. Rig seed 307 (ACTORS=5,
+ // STEPS=300): a column removed and re-added by undo at lamport 23/24, a
+ // value written to it at lamport 2 and parked, and the row carrying that
+ // cell resurrected at lamport 8 by a peer's own undo. The [24] rebirth
+ // supersedes both, and only the replay thought otherwise.
+ //
+ // reconcileParked has carried this rule from the start ("The column's own
+ // birth beats anything parked before it"); it simply never got the chance
+ // to apply it, because replayStashRow runs inside applyRins and has
+ // already written the document by the time the batch reconciles.
+ const cb = this.births[colNode(sh, col)]
+ if (cb && !regNewer(auth, cb)) continue
+ // stale guard: the parked value must belong to the CURRENT authority — a
+ // newer write that landed elsewhere supersedes it
+ if (cmpReg(ent.r, auth) !== 0) continue
+ dbg(node, `stash-replay ${k} := ${JSON.stringify(ent.v)}`)
+ if (isVKey(k)) {
+ if (sheet.data[col]) applyPatch(doc, { op: 'setCells', sheet: sh, col, rids: [rid], v: [clone(ent.v ?? null)] })
+ } else {
+ applyPatch(doc, {
+ op: 'setOverrides', sheet: sh, keys: [`${col}:${rid}`],
+ v: ['v' in ent ? clone(ent.v) as CellOverride : null], dropEmpty: true,
+ })
+ }
+ }
+ if (Object.keys(keep).length) this.stash[node] = keep
+ else delete this.stash[node]
+ }
+
+ /**
+ * A column insert assigns the whole column: it blanks the values and keeps
+ * only the cells that out-stamp it — a `set` register, or the birth of a row
+ * created after the column and carrying it. The blanked cells are filled by
+ * the cell op that accompanies the insert.
+ *
+ * Runs on BOTH paths, including the one where the column is still present.
+ * A replica that received the resurrect before the delete never removes
+ * anything, and if the rebirth left its values alone it would keep numbers
+ * every replica that processed the delete has lost.
+ *
+ * O(edits) to find the survivors, O(rows) to rebuild the array — which is
+ * what the store's own addColumn costs anyway.
+ */
+ private resetColumnValues(doc: DashDoc, sheet: TableSheet, col: string, birth: Reg, enc: 'raw' | 'dict' | undefined): void {
+ const key = vKey(col)
+ const prefix = rowNode(sheet.id, 0).slice(0, -1) // `r␟<sheet>␟`
+ const keeps: Array<[number, unknown]> = []
+ for (const node of new Set([...Object.keys(this.births), ...Object.keys(this.regs).filter((n) => key in this.regs[n])])) {
+ if (!node.startsWith(prefix)) continue
+ const rid = Number(nodeTail(node))
+ const at = rleIndex(sheet.rids, rid)
+ if (at < 0) continue
+ const r = this.reg(node, key)
+ const b = this.rowNames(node, col) ? this.births[node] : undefined
+ const auth = r && (!b || regNewer(r, b)) ? r : b
+ if (!auth || !regNewer(auth, birth)) continue
+ // the document if the column is still here, otherwise what its death parked
+ const ent = this.stash[node]?.[key]
+ const v = sheet.data[col] ? readCell(sheet.data[col], at)
+ : (ent && cmpReg(ent.r, auth) === 0 ? (ent.v ?? null) : null)
+ if (ent) {
+ delete this.stash[node][key]
+ if (!Object.keys(this.stash[node]).length) delete this.stash[node]
+ }
+ keeps.push([rid, v])
+ }
+ const n = rleCount(sheet.rids)
+ if (enc === undefined) delete sheet.data[col] // a formula column stores nothing
+ else if (enc === 'dict') sheet.data[col] = { enc: 'dict', dict: [], idx: new Array(n).fill(null) }
+ else sheet.data[col] = { enc: 'raw', v: new Array(n).fill(null) }
+ if (!sheet.data[col]) return
+ for (const [rid, v] of keeps) {
+ if (v === null || v === undefined) continue
+ applyPatch(doc, { op: 'setCells', sheet: sheet.id, col, rids: [rid], v: [clone(v)] })
+ }
+ }
+
+ /**
+ * Park what a column removal destroys, so a resurrection can weigh it.
+ *
+ * Cell values live in the document, not here, so once the column is gone the
+ * only replicas that can still produce them are the ones that kept a copy. A
+ * replica that had the write PENDING (the column was already buried when it
+ * arrived) replays it after the rebirth; this is the same guarantee for the
+ * replica that had already applied it. With only one of the two halves, the
+ * same cell came back filled on one side and empty on the other.
+ */
+ private parkColumn(sheet: TableSheet, col: string): void {
+ const key = vKey(col)
+ const ok = oKey(col)
+ const prefix = rowNode(sheet.id, 0).slice(0, -1) // `r␟<sheet>␟`
+ const park = (node: string, k: string, v: unknown, r: Reg | undefined) => {
+ if (!r) return
+ const st = (this.stash[node] ??= {})
+ // Never clobber an entry that already holds this authority: it is the
+ // one with the value, and ours may be the blank it is waiting to fill.
+ if (!(k in st) || cmpReg(st[k].r, r) !== 0) st[k] = { v: clone(v), r: clone(r) }
+ }
+ for (const node of new Set([...Object.keys(this.births), ...Object.keys(this.regs).filter((n) => key in this.regs[n])])) {
+ if (!node.startsWith(prefix)) continue
+ const rid = Number(nodeTail(node))
+ const at = rleIndex(sheet.rids, rid)
+ if (at < 0) continue
+ park(node, key, readCell(sheet.data[col], at), this.cellAuth(sheet.id, rid, key, this.rowNames(node, col)))
+ }
+ for (const k of Object.keys(sheet.cells ?? {})) {
+ if (k.slice(0, k.indexOf(':')) !== col) continue
+ const rid = Number(k.slice(k.indexOf(':') + 1))
+ park(rowNode(sheet.id, rid), ok, sheet.cells![k], this.reg(rowNode(sheet.id, rid), ok))
+ }
+ }
+
+ private killColumn(doc: DashDoc, sheet: TableSheet, col: string): void {
+ dbg(colNode(sheet.id, col), `killColumn`)
+ this.parkColumn(sheet, col)
+ const keys = Object.keys(sheet.cells ?? {}).filter((k) => k.slice(0, k.indexOf(':')) === col)
+ if (keys.length) applyPatch(doc, { op: 'setOverrides', sheet: sheet.id, keys, v: keys.map(() => null), dropEmpty: true })
+ applyPatch(doc, { op: 'removeColumn', sheet: sheet.id, col })
+ }
+
+ // --- sheets and columns ---------------------------------------------------
+
+ private applyIns(doc: DashDoc, op: InsOp, res: ApplyResult): void {
+ const stamp: Reg = [op.l, op.a]
+ const node = op.n
+ const isSheet = node[0] === 's'
+ // Resolve the host sheet BEFORE stamping the birth. Stamping first and
+ // pending afterwards looks harmless and is not: the drained op then finds
+ // its own birth already recorded, fails the "an older create" gate, and
+ // returns — the column silently never appears.
+ let host: TableSheet | undefined
+ let sheetGone = false
+ if (!isSheet) {
+ const sheetId = nodeSheet(node)
+ sheetGone = this.dead(shNode(sheetId))
+ if (!sheetGone) {
+ host = tableOf(doc, sheetId)
+ if (!host) { this.pend(shNode(sheetId), op); return }
+ }
+ }
+ const birth = this.births[node]
+ if (birth && !newer(op.l, op.a, birth)) return // an older create
+ this.births[node] = stamp
+ if (!this.pos[node] || regNewer(stamp, this.pos[node].r)) {
+ this.pos[node] = { p: isSheet ? DOC_NODE : shNode(nodeSheet(node)), o: op.ord, r: stamp }
+ }
+ res.changed = true
+ res.structure = true
+ if (isSheet) {
+ // Derived from the payload, so every replica computes the same thing —
+ // and must, even when the sheet is already dead here. A replica that
+ // learned of the death first would otherwise be missing order keys its
+ // peers hold, and the two sync states would never match again.
+ const seed = op.node as Sheet
+ if (seed.kind === 'table') this.base[seed.id] ??= clone(seed.rids)
+ this.seedColumnPos(seed)
+ }
+ if (this.dead(node) || sheetGone) { this.drainPending(doc, node); return }
+ if (isSheet) {
+ const src = op.node as Sheet
+ const existing = doc.sheets.find((s) => s.id === src.id)
+ if (existing) {
+ this.assignNode(existing as unknown as Record<string, unknown>, src as unknown as Record<string, unknown>, node, stamp, SHEET_STRUCTURAL)
+ } else {
+ doc.sheets.push(clone(src))
+ this.replayStash(doc.sheets[doc.sheets.length - 1] as unknown as Record<string, unknown>, node, stamp)
+ }
+ const landed = doc.sheets.find((s) => s.id === src.id)
+ if (landed && landed.kind === 'table') {
+ // A payload can carry columns and rows that somebody else has already
+ // buried. Adopting them wholesale would resurrect the dead on whichever
+ // replica happened to receive the sheet last.
+ this.pruneDead(doc, landed)
+ this.rids[src.id] = clone(landed.rids)
+ }
+ this.drainSheet(doc, src.id)
+ } else {
+ const sheet = host!
+ const src = op.node as Column
+ const existing = sheet.columns.find((c) => c.id === src.id)
+ if (existing) {
+ this.assignNode(existing as unknown as Record<string, unknown>, src as unknown as Record<string, unknown>, node, stamp, ['id'])
+ } else {
+ applyPatch(doc, { op: 'addColumn', sheet: sheet.id, column: clone(src) })
+ this.replayStash(sheet.columns[sheet.columns.length - 1] as unknown as Record<string, unknown>, node, stamp)
+ }
+ // BOTH paths reset the values, including the one where the column is
+ // already here. A replica that received the resurrect before the delete
+ // never removes anything, and if the rebirth left its values alone it
+ // would keep numbers that every replica which processed the delete has
+ // lost. Same event, same effect, whatever order it arrives in.
+ this.resetColumnValues(doc, sheet, src.id, stamp, op.enc)
+ dbg(node, `cins@${op.l},${op.a} ${src.id}`)
+ }
+ this.drainPending(doc, node)
+ }
+
+ /** drop members of a freshly-adopted sheet that are dead under our liveness */
+ private pruneDead(doc: DashDoc, sheet: TableSheet): void {
+ for (let i = sheet.columns.length - 1; i >= 0; i--) {
+ if (!this.dead(colNode(sheet.id, sheet.columns[i].id))) continue
+ this.killColumn(doc, sheet, sheet.columns[i].id)
+ }
+ const dead = rleExpand(sheet.rids).filter((rid) => this.dead(rowNode(sheet.id, rid)))
+ if (dead.length) {
+ dropRowOverrides(doc, sheet, dead)
+ applyPatch(doc, { op: 'deleteRows', sheet: sheet.id, rids: dead })
+ }
+ }
+
+ private applyDel(doc: DashDoc, op: DelOp, res: ApplyResult): void {
+ const node = op.n
+ if (!this.tombs[node] || newer(op.l, op.a, this.tombs[node])) this.tombs[node] = [op.l, op.a]
+ if (this.dead(node)) {
+ if (node[0] === 's') {
+ const i = doc.sheets.findIndex((s) => s.id === nodeSheet(node))
+ if (i >= 0) {
+ this.stashNode(doc.sheets[i] as unknown as Record<string, unknown>, node)
+ doc.sheets.splice(i, 1)
+ delete this.rids[nodeSheet(node)]
+ }
+ this.drainSheet(doc, nodeSheet(node))
+ } else {
+ const sheetId = nodeSheet(node)
+ const sheet = tableOf(doc, sheetId)
+ const colId = nodeTail(node)
+ const col = sheet?.columns.find((c) => c.id === colId)
+ if (sheet && col) {
+ this.stashNode(col as unknown as Record<string, unknown>, node)
+ this.killColumn(doc, sheet, colId)
+ }
+ }
+ }
+ this.drainPending(doc, node)
+ res.changed = true
+ res.structure = true
+ }
+
+ private applyOrd(_doc: DashDoc, op: OrdOp, res: ApplyResult): void {
+ const cur = this.pos[op.n]
+ if (cur && !newer(op.l, op.a, cur.r)) return
+ const parent = op.n[0] === 's' ? DOC_NODE : shNode(nodeSheet(op.n))
+ this.pos[op.n] = { p: parent, o: op.ord, r: [op.l, op.a] }
+ // a move never resurrects, and rematerialize (run once per apply batch)
+ // is what turns the pos registers back into array order
+ if (this.dead(op.n)) return
+ res.changed = true
+ res.structure = true
+ }
+
+ /**
+ * Whole-node assignment from an insert payload: every property whose register
+ * is OLDER than the (re)birth takes the payload's value; properties with
+ * newer registers keep the set-winner. Runs identically on every replica —
+ * including ones where the node never died — which is what makes
+ * resurrection convergent.
+ */
+ private assignNode(node: Record<string, unknown>, payload: Record<string, unknown>, id: string, birth: Reg, skip: readonly string[]): void {
+ for (const k of new Set([...Object.keys(node), ...Object.keys(payload)])) {
+ if (skip.includes(k)) continue
+ const r = this.reg(id, k)
+ if (r && regNewer(r, birth)) continue // a newer set beats the assignment
+ writeKey(node, k, payload[k] === undefined ? undefined : clone(payload[k]))
+ }
+ this.replayStash(node, id, birth)
+ }
+
+ /** park a to-be-removed node's registered property values (see replayStash) */
+ private stashNode(node: Record<string, unknown>, id: string): void {
+ const keys = this.regs[id]
+ if (!keys) return
+ const st = (this.stash[id] ??= {})
+ for (const [k, r] of Object.entries(keys)) {
+ if (!(k in st) || cmpReg(st[k].r, r) !== 0) {
+ st[k] = node[k] === undefined ? { r: clone(r) } : { v: clone(node[k]), r: clone(r) }
+ }
+ }
+ }
+
+ /** replay dead-window property values that out-rank a resurrecting insert */
+ private replayStash(node: Record<string, unknown>, id: string, birth: Reg): void {
+ const st = this.stash[id]
+ if (!st) return
+ for (const [k, ent] of Object.entries(st)) {
+ const r = this.reg(id, k)
+ if (!r || !regNewer(r, birth)) continue
+ if (cmpReg(ent.r, r) !== 0) continue
+ writeKey(node, k, 'v' in ent ? clone(ent.v) : undefined)
+ }
+ delete this.stash[id]
+ }
+
+ /**
+ * Settle parked cell values whose row and column are both live again.
+ *
+ * The stash is written by four different events (a row dies, a column dies,
+ * a write lands on something dead, a column payload covers a row we lack)
+ * and read by four more, and making every pair agree on WHO reclaims WHAT
+ * was where the ordering bugs lived. This is the single rule instead: a
+ * parked value belongs to the document as soon as its row and its column are
+ * both there, provided it still holds the cell's authority. If it does not,
+ * something newer won and the parked copy is forgotten.
+ *
+ * Runs after every batch. Costs O(parked), which is O(edits) and shrinks as
+ * entries are consumed — never O(rows).
+ */
+ private reconcileParked(doc: DashDoc): void {
+ for (const node of Object.keys(this.stash)) {
+ if (node[0] !== 'r') continue // sheet/column property stashes settle on rebirth
+ const sh = nodeSheet(node)
+ const rid = Number(nodeTail(node))
+ const sheet = tableOf(doc, sh)
+ if (!sheet || this.dead(node) || !rleHas(sheet.rids, rid)) continue
+ const st = this.stash[node]
+ for (const k of Object.keys(st)) {
+ const col = keyCol(k)
+ if (this.dead(colNode(sh, col))) continue // may yet be dug up
+ const live = isVKey(k) ? !!sheet.data[col] : sheet.columns.some((c) => c.id === col)
+ if (!live) continue // the column's insert has not landed here yet
+ const claims = !isVKey(k) || this.rowNames(node, col)
+ const r = this.cellAuth(sh, rid, k, claims)
+ // Same rule replayStashRow applies, and it has to be the same rule or
+ // the two readers of the stash disagree again: when the row's current
+ // birth does not CLAIM this column, the parked entry is the cell's last
+ // word and only something strictly newer displaces it. Asking for a
+ // register that may never have existed (the value arrived in an earlier
+ // insert's payload, and `rnamed` has since been overwritten by a second
+ // resurrection) dropped the value here too — on every replica except
+ // the second resurrector. Seeds 374 and 184.
+ const auth = claims ? r : (r && regNewer(r, st[k].r) ? r : st[k].r)
+ // The column's own birth beats anything parked before it: a value a
+ // row was holding for a column that has since been (re)created belongs
+ // to the creation, not to the row.
+ const cb = this.births[colNode(sh, col)]
+ if (auth && cmpReg(st[k].r, auth) === 0 && !(cb && !regNewer(st[k].r, cb))) {
+ dbg(node, `settle parked ${k} := ${JSON.stringify(st[k].v)}`)
+ if (isVKey(k)) applyPatch(doc, { op: 'setCells', sheet: sh, col, rids: [rid], v: [clone(st[k].v ?? null)] })
+ else {
+ applyPatch(doc, {
+ op: 'setOverrides', sheet: sh, keys: [`${col}:${rid}`],
+ v: [st[k].v === undefined ? null : clone(st[k].v) as CellOverride], dropEmpty: true,
+ })
+ }
+ }
+ delete st[k] // consumed, or superseded by something newer
+ }
+ if (!Object.keys(st).length) delete this.stash[node]
+ }
+ }
+
+ /** rebuild sheet and column order from pos registers (rows are maintained
+ * incrementally by the RGA — a global row sort would be O(rows) per op) */
+ private rematerialize(doc: DashDoc): void {
+ const ord = (n: string) => (this.pos[n] ? this.pos[n].o : '')
+ const cmp = (x: string, y: string) => {
+ const a = ord(x)
+ const b = ord(y)
+ if (a !== b) return a < b ? -1 : 1
+ return x < y ? -1 : 1
+ }
+ doc.sheets.sort((s1, s2) => cmp(shNode(s1.id), shNode(s2.id)))
+ for (const s of doc.sheets) {
+ if (s.kind !== 'table') continue
+ s.columns.sort((c1, c2) => cmp(colNode(s.id, c1.id), colNode(s.id, c2.id)))
+ }
+ }
+
+ // --- state-based merge (file forks, late joiners, catch-up beyond the log) -
+
+ /**
+ * Merge a remote (doc, state) pair into ours. Register-wise LWW with value
+ * adoption from the winning side, liveness max, and a symmetric row-order
+ * interleave. merge(A←B) followed by merge(B←A) must leave both identical,
+ * which is why nothing here may consult "which side is local".
+ */
+ mergeSnapshot(doc: DashDoc, rdoc: DashDoc, rstate: SyncStateJSON): ApplyResult {
+ const res: ApplyResult = { changed: false, structure: false }
+ if (!rstate || rstate.v !== SYNC_V) return res
+ this.lamport = Math.max(this.lamport, rstate.lamport ?? 0)
+ for (const [a, s] of Object.entries(rstate.vv ?? {})) {
+ if ((this.vv[a] ?? 0) < s) {
+ this.vv[a] = s
+ if (a === this.actor) this.seq = s
+ this.gap[a] = (this.gap[a] ?? []).filter((o) => o.s > s)
+ res.changed = true
+ }
+ }
+ const rebirths: string[] = []
+ for (const [id, r] of Object.entries(rstate.births ?? {})) {
+ if (!this.births[id] || regNewer(r, this.births[id])) { this.births[id] = clone(r); rebirths.push(id) }
+ }
+ for (const [id, r] of Object.entries(rstate.tombs ?? {})) {
+ if (!this.tombs[id] || regNewer(r, this.tombs[id])) { this.tombs[id] = clone(r); res.changed = true }
+ }
+ // A row's key is minted once and never changes, so first-wins is exact.
+ for (const [id, k] of Object.entries(rstate.rpos ?? {})) {
+ if (!(id in this.rpos)) this.rpos[id] = k
+ }
+ // Baselines: identical for two copies of one file, but two copies adopted
+ // at DIFFERENT points in a file's history disagree about which rows were
+ // there to begin with. Union them symmetrically so both sides derive the
+ // same keys — the alternative is two forks that each think the other's
+ // rows belong somewhere else.
+ for (const [id, b] of Object.entries(rstate.base ?? {})) {
+ const mine = this.base[id]
+ if (!mine) { this.base[id] = clone(b); continue }
+ const merged = mergeOrder(rleExpand(mine), rleExpand(b), () => undefined)
+ if (merged.length !== rleCount(mine)) this.base[id] = rleCompress(merged)
+ }
+ for (const [id, rp] of Object.entries(rstate.pos ?? {})) {
+ const cur = this.pos[id]
+ if (!cur || regNewer(rp.r, cur.r)) { this.pos[id] = clone(rp); res.changed = true; res.structure = true }
+ }
+
+ // --- structure: sheets, then per-sheet rows and columns
+ for (let i = doc.sheets.length - 1; i >= 0; i--) {
+ const s = doc.sheets[i]
+ if (this.dead(shNode(s.id))) {
+ this.stashNode(s as unknown as Record<string, unknown>, shNode(s.id))
+ doc.sheets.splice(i, 1)
+ delete this.rids[s.id]
+ res.changed = res.structure = true
+ }
+ }
+ for (const rs of rdoc.sheets) {
+ if (this.dead(shNode(rs.id))) continue
+ if (doc.sheets.some((s) => s.id === rs.id)) continue
+ doc.sheets.push(clone(rs))
+ this.seedColumnPos(rs)
+ if (rs.kind === 'table') {
+ this.rids[rs.id] = clone(rs.rids)
+ this.base[rs.id] ??= clone(rs.rids)
+ }
+ res.changed = res.structure = true
+ }
+ const rById = new Map(rdoc.sheets.map((s) => [s.id, s]))
+ for (const s of doc.sheets) {
+ if (s.kind !== 'table') continue
+ const rsheet = rById.get(s.id)
+ const rt = rsheet && rsheet.kind === 'table' ? rsheet : undefined
+ this.mergeColumns(doc, s, rt, res)
+ this.mergeRows(doc, s, rt, res)
+ }
+
+ // --- whole-node assignments the remote saw and we did not
+ for (const id of rebirths) {
+ if (this.dead(id) || id[0] === 'r') continue // rows assign through mergeRows
+ const src = remoteNode(rdoc, id)
+ const dst = localNode(doc, id)
+ if (!src || !dst) continue
+ this.assignNode(dst, src, id, this.births[id], id[0] === 's' ? SHEET_STRUCTURAL : ['id'])
+ res.changed = true
+ if (id[0] === 's') res.structure = true
+ }
+
+ // --- property registers: the winning side's value lives in its document
+ for (const [node, keys] of Object.entries(rstate.regs ?? {})) {
+ for (const [key, rr] of Object.entries(keys)) {
+ if (!regNewer(rr, this.reg(node, key))) continue
+ this.setReg(node, key, clone(rr))
+ if (node !== DOC_NODE) {
+ const b = this.births[node]
+ if (b && !regNewer(rr, b)) continue // superseded by a whole-node assignment
+ }
+ if (node[0] === 'r') { this.mergeCellReg(doc, rdoc, rstate, node, key, rr); continue }
+ if (node !== DOC_NODE && this.dead(node)) {
+ const src = remoteNode(rdoc, node)
+ const rstash = rstate.stash?.[node]?.[key]
+ if (src && src[key] !== undefined) (this.stash[node] ??= {})[key] = { v: clone(src[key]), r: clone(rr) }
+ else if (rstash) (this.stash[node] ??= {})[key] = clone(rstash)
+ continue
+ }
+ const src = node === DOC_NODE ? (rdoc as unknown as Record<string, unknown>) : remoteNode(rdoc, node)
+ const dst = node === DOC_NODE ? (doc as unknown as Record<string, unknown>) : localNode(doc, node)
+ if (!src || !dst) continue
+ if (node === DOC_NODE) writeDocKey(doc, key, readDocKey(rdoc, key))
+ else writeKey(dst, key, src[key])
+ res.changed = true
+ if (node === DOC_NODE || node[0] === 's') res.structure = true
+ }
+ }
+ this.reconcileParked(doc)
+ if (res.structure) this.rematerialize(doc)
+ this.snapRids(doc)
+ return res
+ }
+
+ /** one cell register during a snapshot merge: read the winner's value out of
+ * the remote's columnar arrays and write it into ours by rid */
+ private mergeCellReg(doc: DashDoc, rdoc: DashDoc, rstate: SyncStateJSON, node: string, key: string, rr: Reg): void {
+ const sh = nodeSheet(node)
+ const rid = Number(nodeTail(node))
+ const col = keyCol(key)
+ const sheet = tableOf(doc, sh)
+ const rsheet = tableOf(rdoc, sh)
+ const rAt = rsheet ? rleIndex(rsheet.rids, rid) : -1
+ const value = isVKey(key)
+ ? (rAt >= 0 && rsheet ? readCell(rsheet.data[col], rAt) : rstate.stash?.[node]?.[key]?.v)
+ : (rsheet?.cells?.[`${col}:${rid}`] ?? rstate.stash?.[node]?.[key]?.v)
+ if (this.dead(node) || !sheet || !rleHas(sheet.rids, rid)) {
+ ;(this.stash[node] ??= {})[key] = { v: clone(value), r: clone(rr) }
+ return
+ }
+ if (isVKey(key)) {
+ if (sheet.data[col]) applyPatch(doc, { op: 'setCells', sheet: sh, col, rids: [rid], v: [clone(value ?? null)] })
+ } else {
+ applyPatch(doc, {
+ op: 'setOverrides', sheet: sh, keys: [`${col}:${rid}`],
+ v: [value === undefined ? null : clone(value) as CellOverride], dropEmpty: true,
+ })
+ }
+ }
+
+ private mergeColumns(doc: DashDoc, sheet: TableSheet, rsheet: TableSheet | undefined, res: ApplyResult): void {
+ for (let i = sheet.columns.length - 1; i >= 0; i--) {
+ const n = colNode(sheet.id, sheet.columns[i].id)
+ if (!this.dead(n)) continue
+ this.stashNode(sheet.columns[i] as unknown as Record<string, unknown>, n)
+ this.killColumn(doc, sheet, sheet.columns[i].id)
+ res.changed = res.structure = true
+ }
+ if (!rsheet) return
+ const myRids = rleExpand(sheet.rids)
+ for (const rc of rsheet.columns) {
+ if (this.dead(colNode(sheet.id, rc.id))) continue
+ if (sheet.columns.some((c) => c.id === rc.id)) continue
+ sheet.columns.push(clone(rc))
+ const rd = rsheet.data[rc.id]
+ if (rd) sheet.data[rc.id] = alignColumnData(rd, rleExpand(rsheet.rids), myRids)
+ res.changed = res.structure = true
+ }
+ }
+
+ /**
+ * Reconcile two row sequences.
+ *
+ * Rows only one side knows about are adopted with their values; rows dead
+ * under merged liveness leave. The ORDER is a symmetric interleave (see
+ * mergeOrder) rather than a winner-takes-all — which is the honest limit of
+ * merging two sequences from state alone, since neither side kept the op log
+ * that produced the other's order.
+ */
+ private mergeRows(doc: DashDoc, sheet: TableSheet, rsheet: TableSheet | undefined, res: ApplyResult): void {
+ const mine = rleExpand(sheet.rids)
+ const dropped = mine.filter((rid) => this.dead(rowNode(sheet.id, rid)))
+ if (dropped.length) {
+ for (const rid of dropped) this.stashRow(sheet, sheet.id, rid)
+ dropRowOverrides(doc, sheet, dropped)
+ applyPatch(doc, { op: 'deleteRows', sheet: sheet.id, rids: dropped })
+ res.changed = res.structure = true
+ }
+ if (!rsheet) return
+ const live = rleExpand(sheet.rids)
+ const theirs = rleExpand(rsheet.rids).filter((rid) => !this.dead(rowNode(sheet.id, rid)))
+ const order = mergeOrder(live, theirs, (rid) => this.births[rowNode(sheet.id, rid)])
+ // adopt rows only they have, in the merged order, one splice each
+ for (let i = 0; i < order.length; i++) {
+ const rid = order[i]
+ if (rleHas(sheet.rids, rid)) continue
+ const at = rleIndex(rsheet.rids, rid)
+ const vals: Record<string, unknown[]> = {}
+ for (const col of Object.keys(sheet.data)) {
+ const rd = rsheet.data[col]
+ vals[col] = [rd ? readCell(rd, at) : null]
+ }
+ applyPatch(doc, { op: 'insertRows', sheet: sheet.id, rids: [rid], at: [Math.min(i, rleCount(sheet.rids))], values: vals })
+ for (const [k, ov] of Object.entries(rsheet.cells ?? {})) {
+ if (Number(k.slice(k.indexOf(':') + 1)) !== rid) continue
+ applyPatch(doc, { op: 'setOverrides', sheet: sheet.id, keys: [k], v: [clone(ov)], dropEmpty: true })
+ }
+ res.changed = res.structure = true
+ }
+ // then settle the order itself
+ const now = rleExpand(sheet.rids)
+ if (now.length === order.length && now.every((r, i) => r === order[i])) return
+ permuteRows(sheet, order)
+ res.changed = res.structure = true
+ }
+
+ /** ops from our log this version vector is missing (peer catch-up) */
+ missingFor(log: Op[], vv: Record<string, number>): Op[] {
+ return log.filter((o) => o.s > (vv[o.a] ?? 0))
+ }
+}
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+/** sheet-node keys that the payload owns wholesale: structure moves through
+ * row/column ops, never through a property register. Mirrors store.ts's
+ * `STRUCTURAL` refusal set in rowcol.ts, deliberately. */
+const SHEET_STRUCTURAL = ['id', 'kind', 'columns', 'data', 'rids', 'cells'] as const
+
+const tableOf = (doc: DashDoc, id: string): TableSheet | undefined => {
+ const s = doc.sheets.find((x) => x.id === id)
+ return s && s.kind === 'table' ? s : undefined
+}
+
+/**
+ * Take a removed row's cell overrides with it.
+ *
+ * `rowcol.deleteRowsAt` does this in the app, in the same commit, because an
+ * override keyed to a rid nobody can reach is garbage that the next writer
+ * inherits. The CRDT has to do it too, and not merely as tidiness: a replica
+ * that wrote the override BEFORE the delete arrived would otherwise keep it
+ * while a replica that got the delete first never writes it at all, and two
+ * workbooks would differ by a note pinned to a row that no longer exists.
+ * Deterministic given liveness, and safe because a rid is never reused.
+ */
+/** the row-axis twin of DashSync.killColumn (see rowcol.deleteRowsAt) */
+function dropRowOverrides(doc: DashDoc, sheet: TableSheet, rids: number[]): void {
+ if (!sheet.cells) return
+ const doomed = new Set(rids)
+ const keys = Object.keys(sheet.cells).filter((k) => doomed.has(Number(k.slice(k.indexOf(':') + 1))))
+ if (!keys.length) return
+ applyPatch(doc, { op: 'setOverrides', sheet: sheet.id, keys, v: keys.map(() => null), dropEmpty: true })
+}
+
+function writeKey(target: Record<string, unknown>, k: string, v: unknown): void {
+ if (v === undefined) delete target[k]
+ else target[k] = v
+}
+
+/** doc-level keys support dotted per-entry registers for the map fields, so two
+ * people adding different measures (or assets) both keep theirs. */
+function writeDocKey(doc: DashDoc, k: string, v: unknown): void {
+ const dot = k.indexOf('.')
+ const field = dot > 0 ? k.slice(0, dot) : ''
+ if (field === 'measures' || field === 'assets' || field === 'blobs' || field === 'names') {
+ const map = ((doc as unknown as Record<string, Record<string, unknown>>)[field] ??= {})
+ const key = k.slice(dot + 1)
+ if (v === undefined) delete map[key]
+ else map[key] = clone(v)
+ return
+ }
+ writeKey(doc as unknown as Record<string, unknown>, k, v === undefined ? undefined : clone(v))
+}
+
+function readDocKey(doc: DashDoc, k: string): unknown {
+ const dot = k.indexOf('.')
+ const field = dot > 0 ? k.slice(0, dot) : ''
+ if (field === 'measures' || field === 'assets' || field === 'blobs' || field === 'names') {
+ return (doc as unknown as Record<string, Record<string, unknown> | undefined>)[field]?.[k.slice(dot + 1)]
+ }
+ return (doc as unknown as Record<string, unknown>)[k]
+}
+
+const remoteNode = (rdoc: DashDoc, node: string): Record<string, unknown> | undefined => {
+ if (node === DOC_NODE) return rdoc as unknown as Record<string, unknown>
+ const sheet = rdoc.sheets.find((s) => s.id === nodeSheet(node))
+ if (!sheet) return undefined
+ if (node[0] === 's') return sheet as unknown as Record<string, unknown>
+ if (sheet.kind !== 'table') return undefined
+ return sheet.columns.find((c) => c.id === nodeTail(node)) as unknown as Record<string, unknown> | undefined
+}
+const localNode = remoteNode
+
+/**
+ * Re-align a column's encoded values from the sender's row order to ours.
+ *
+ * A column travels with the rid list it was encoded against, because the two
+ * replicas' row orders need not match — and reading a column at the wrong
+ * offsets is the silent-wrong-number failure this whole app is built to
+ * refuse. Rows we do not have are dropped; rows the sender lacked come out null.
+ */
+export function alignColumnData(data: ColumnData, from: number[], to: number[]): ColumnData {
+ if (data.enc === 'pack') return data // opaque archive encoding — cannot re-index
+ const at = new Map<number, number>()
+ from.forEach((rid, i) => at.set(rid, i))
+ if (data.enc === 'dict') {
+ return { enc: 'dict', dict: data.dict.slice(), idx: to.map((rid) => { const i = at.get(rid); return i === undefined ? null : (data.idx[i] ?? null) }) }
+ }
+ return { enc: 'raw', v: to.map((rid) => { const i = at.get(rid); return i === undefined ? null : (data.v[i] ?? null) }) }
+}
+
+/**
+ * Permute a sheet's rows into `order`.
+ *
+ * Rebuilds each column's index array rather than writing values one at a time:
+ * a dict column keeps its dictionary (no re-interning, no dictionary growth)
+ * and a raw column is one map. `pack` columns are opaque and are left ALONE —
+ * store.ts refuses to write them for the same reason, and silently re-indexing
+ * an archive column would misalign every value in it.
+ */
+/**
+ * Settle a sheet's rid watermark to a value every replica agrees on.
+ *
+ * `nextRid` is DOCUMENT data (store.ts raises it on every insert and delete so
+ * a rid is never minted twice), and a plain monotonic counter does not
+ * converge: two replicas that each did a different number of structural edits
+ * hold different numbers, and the documents differ forever. Measured before
+ * this existed: seed 12 diverged on `nextRid` 4002 against 4001 and on nothing
+ * else.
+ *
+ * A monotonic counter's join is MAX, and this engine already knows every rid
+ * that has ever existed for a sheet — `births` keeps a register for each row
+ * node whether or not it is still alive. So the converged watermark is one past
+ * the largest of them, which both replicas compute identically once their
+ * states agree, and which can never go below a rid that existed.
+ */
+function settleWatermark(sheet: TableSheet, births: Record<string, Reg>): void {
+ const prefix = rowNode(sheet.id, 0).slice(0, -1)
+ let hi = 0
+ for (const [start, count] of sheet.rids) hi = Math.max(hi, start + count - 1)
+ for (const k of Object.keys(births)) {
+ if (!k.startsWith(prefix)) continue
+ const rid = Number(k.slice(prefix.length))
+ if (Number.isFinite(rid)) hi = Math.max(hi, rid)
+ }
+ sheet.nextRid = hi + 1
+}
+
+function permuteRows(sheet: TableSheet, order: number[]): void {
+ const from = rleExpand(sheet.rids)
+ const at = new Map<number, number>()
+ from.forEach((rid, i) => at.set(rid, i))
+ for (const [col, d] of Object.entries(sheet.data)) {
+ if (d.enc === 'raw') sheet.data[col] = { enc: 'raw', v: order.map((rid) => { const i = at.get(rid); return i === undefined ? null : (d.v[i] ?? null) }) }
+ else if (d.enc === 'dict') sheet.data[col] = { enc: 'dict', dict: d.dict, idx: order.map((rid) => { const i = at.get(rid); return i === undefined ? null : (d.idx[i] ?? null) }) }
+ }
+ sheet.rids = rleCompress(order)
+}
+
+/**
+ * Symmetric two-sequence interleave.
+ *
+ * The rule may never ask which side is "local" — merge(A,B) and merge(B,A)
+ * have to produce the same list, or two forks that exchange snapshots settle on
+ * different row orders and never converge. So at every step the choice is made
+ * from the elements themselves: an element the other list does not contain goes
+ * first, and a genuine tie breaks on (birth stamp, rid), which both sides agree
+ * on.
+ */
+export function mergeOrder(a: number[], b: number[], birthOf: (rid: number) => Reg | undefined): number[] {
+ const inB = new Set(b)
+ const inA = new Set(a)
+ const out: number[] = []
+ const taken = new Set<number>()
+ let i = 0
+ let j = 0
+ const rank = (rid: number): string => {
+ const r = birthOf(rid)
+ return r ? `1${String(r[0]).padStart(12, '0')}${r[1]}${rid}` : `0${String(rid).padStart(12, '0')}`
+ }
+ const take = (rid: number) => { if (!taken.has(rid)) { taken.add(rid); out.push(rid) } }
+ while (i < a.length || j < b.length) {
+ while (i < a.length && taken.has(a[i])) i++
+ while (j < b.length && taken.has(b[j])) j++
+ if (i >= a.length) { if (j < b.length) take(b[j++]) ; continue }
+ if (j >= b.length) { take(a[i++]); continue }
+ const x = a[i]
+ const y = b[j]
+ if (x === y) { take(x); i++; j++; continue }
+ const xShared = inB.has(x)
+ const yShared = inA.has(y)
+ if (xShared && !yShared) { take(y); j++; continue }
+ if (!xShared && yShared) { take(x); i++; continue }
+ // both exclusive, or both shared but out of order: decide from the rows
+ if (rank(x) <= rank(y)) { take(x); i++ } else { take(y); j++ }
+ }
+ return out
+}
+
+/** indices of a longest strictly-increasing subsequence */
+function longestIncreasing(keys: string[]): number[] {
+ const tails: number[] = []
+ const prev = new Array<number>(keys.length).fill(-1)
+ for (let i = 0; i < keys.length; i++) {
+ let lo = 0
+ let hi = tails.length
+ while (lo < hi) {
+ const mid = (lo + hi) >> 1
+ if (keys[tails[mid]] < keys[i]) lo = mid + 1
+ else hi = mid
+ }
+ if (lo > 0) prev[i] = tails[lo - 1]
+ tails[lo] = i
+ }
+ const out: number[] = []
+ let k = tails.length ? tails[tails.length - 1] : -1
+ while (k >= 0) { out.push(k); k = prev[k] }
+ return out.reverse()
+}
+
+/**
+ * Is this patch safe to commit into a LIVE session?
+ *
+ * The asymmetry this closes is easy to miss and impossible to see afterwards.
+ * A locally committed patch is applied by the store unconditionally — it has no
+ * idea what a peer deleted — while the very same change, arriving as an op, is
+ * gated by liveness on every other replica. So an edit naming a row or column
+ * that is gone lands HERE and nowhere else, and the workbooks differ by a value
+ * only one person can see. `applyPatch` makes it worse for cells specifically:
+ * a `setCells` naming an unknown rid is silently skipped rather than refused,
+ * so nothing surfaces at the call site either.
+ *
+ * The rule is the honest one: you cannot edit what is not there. Undo is where
+ * this actually bites (its inverses were built against a document state that a
+ * collaborator has since changed), which is why the session filters rather than
+ * throws — a refused inverse is a lost undo step, and a divergent workbook is
+ * worse.
+ */
+export function committable(doc: DashDoc, p: Patch): boolean {
+ const table = (id: string): TableSheet | undefined => tableOf(doc, id)
+ const ridOf = (k: string) => Number(k.slice(k.indexOf(':') + 1))
+ const colOf = (k: string) => k.slice(0, k.indexOf(':'))
+ switch (p.op) {
+ case 'setCells': {
+ const s = table(p.sheet)
+ return !!s && !!s.data[p.col] && p.rids.every((r) => rleHas(s.rids, r))
+ }
+ case 'setOverrides': {
+ const s = table(p.sheet)
+ return !!s && p.keys.every((k) =>
+ rleHas(s.rids, ridOf(k)) && s.columns.some((c) => c.id === colOf(k)))
+ }
+ case 'insertRows': {
+ const s = table(p.sheet)
+ if (!s || !p.rids.every((r) => !rleHas(s.rids, r))) return false
+ // Every position must be reachable AT THE MOMENT it is spliced.
+ // store.ts's insertRows splices `rids` and the column arrays at `at`
+ // (which Array.splice clamps) but then writes the value at the RAW
+ // index, so an `at` past the end leaves a hole and a column one entry
+ // longer than the sheet has rows — after which every cell below the gap
+ // reads the next row's number. It is reachable exactly here: undo of a
+ // row delete carries the positions the rows had, and a collaborator may
+ // have removed rows since. Refusing costs one undo step.
+ let n = rleCount(s.rids)
+ for (const at of (p.at ?? []).slice().sort((x, y) => x - y)) {
+ if (at > n) return false
+ n++
+ }
+ return true
+ }
+ case 'deleteRows': return !!table(p.sheet)
+ case 'addColumn': {
+ const s = table(p.sheet)
+ if (!s || s.columns.some((c) => c.id === p.column.id)) return false
+ // A column's values are addressed by POSITION, so an array that is not
+ // exactly as long as the sheet has rows shifts every cell below the gap
+ // — silently, and identically on every replica, which is worse than a
+ // crash. It happens for real: `removeColumn`'s inverse carries the data
+ // snapshot taken at removal, and rows may have come or gone since, so an
+ // undo can restore a column that no longer fits the sheet it is going
+ // back into. Refusing costs one undo step; accepting costs the numbers.
+ if (!p.data) return true
+ const len = p.data.enc === 'raw' ? p.data.v.length : p.data.enc === 'dict' ? p.data.idx.length : -1
+ return len < 0 || len === rleCount(s.rids)
+ }
+ case 'removeColumn':
+ case 'setColumn': return !!table(p.sheet)?.columns.some((c) => c.id === p.col)
+ case 'reorderColumns': {
+ const s = table(p.sheet)
+ return !!s && p.order.length === s.columns.length && p.order.every((id) => s.columns.some((c) => c.id === id))
+ }
+ case 'setSheetProps': return !!table(p.sheet)
+ default: return true
+ }
+}
+
+/** Exposed for the convergence rig, as store.ts does — not an app surface. */
+export const _internals = { rleExpand, rleCompress, rleIndex, rleAt, permuteRows, longestIncreasing }
diff --git a/dash/src/sync/online.ts b/dash/src/sync/online.ts
new file mode 100644
index 00000000..485d8e7b
--- /dev/null
+++ b/dash/src/sync/online.ts
@@ -0,0 +1,726 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento-sync online transport for dash — E2EE WebSocket to the blind relay
+// (server/sync-worker). Every frame is AES-GCM encrypted with the room key
+// from doc.collab.key; the relay sees ciphertext, fan-out routing, and nothing
+// else. Auth is possession-proof: ?tok= is a hash of the key.
+//
+// THIS IS A PORT of slides/src/sync/online.ts, deliberately close to the
+// original, and the differences are only the types it names (DashDoc, dash's
+// Store, dash's Op/SyncStateJSON). Everything load-bearing — the room-id
+// commitment, the owner→invite→member signature chain, the 25s keepalive, the
+// refusal handling, the replay bookmark being memory-only — is unchanged,
+// because every one of those lines was paid for by a bug in production and
+// none of them are slides-shaped.
+//
+// Why a port and not an import: slides' module reaches into slides' store,
+// model and update modules, so importing it would pull the whole slides app
+// into dash's bundle. PLATFORM §9 already names this — the collab engine and
+// relay are "shared but NOT yet in kernel/", and genericizing them is its own
+// project. When that project happens, this file and its slides twin are the
+// two callers to reconcile. The protocol they speak is IDENTICAL, which is the
+// property that matters: one relay, one wire format, two apps.
+//
+// Relay contract: docs/relay-design.md. Threat model: docs/collab-design.md.
+
+import type { Store } from '../store.ts'
+import type { DashDoc } from '../model.ts'
+import type { Op, SyncStateJSON } from './crdt.ts'
+import type { Frame, RefusalCode, SyncSession, Transport } from './session.ts'
+import { offlineEnabled } from '../../../kernel/src/update.ts'
+import { lsGet, lsSet } from '../../../kernel/src/storage.ts'
+
+export const DEFAULT_SYNC_HOST = 'wss://sync.bento.page'
+const SNAP_EVERY = 200 // ops between encrypted snapshot uploads
+
+const b64u = {
+ enc(bytes: Uint8Array): string {
+ let s = ''
+ for (const b of bytes) s += String.fromCharCode(b)
+ return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+ },
+ dec(s: string): Uint8Array {
+ const b = atob(s.replace(/-/g, '+').replace(/_/g, '/'))
+ const out = new Uint8Array(b.length)
+ for (let i = 0; i < b.length; i++) out[i] = b.charCodeAt(i)
+ return out
+ },
+}
+
+export function mintRoomKey(): string {
+ const bytes = new Uint8Array(32)
+ crypto.getRandomValues(bytes)
+ return b64u.enc(bytes)
+}
+
+const EC = { name: 'ECDSA', namedCurve: 'P-256' } as const
+const SIGN_ALG = { name: 'ECDSA', hash: 'SHA-256' } as const
+
+/** Import a signing private key (PKCS#8, base64url) for op frames. */
+export async function importSignKey(privB64: string): Promise<CryptoKey> {
+ return crypto.subtle.importKey('pkcs8', b64u.dec(privB64) as BufferSource, EC, false, ['sign'])
+}
+
+/** ECDSA-P256/SHA-256 signature over `${i}.${d}`, base64url. */
+export async function signFrame(key: CryptoKey, i: string, d: string): Promise<string> {
+ const sig = await crypto.subtle.sign(SIGN_ALG, key, new TextEncoder().encode(`${i}.${d}`))
+ return b64u.enc(new Uint8Array(sig))
+}
+
+/** Sign an arbitrary string with a b64url PKCS#8 private key (cert chains). */
+export async function signText(privB64: string, text: string): Promise<string> {
+ const key = await importSignKey(privB64)
+ const sig = await crypto.subtle.sign(SIGN_ALG, key, new TextEncoder().encode(text))
+ return b64u.enc(new Uint8Array(sig))
+}
+
+async function mintKeypair(): Promise<{ pub: string; priv: string }> {
+ const kp = (await crypto.subtle.generateKey(EC, true, ['sign', 'verify'])) as CryptoKeyPair
+ return {
+ pub: b64u.enc(new Uint8Array(await crypto.subtle.exportKey('raw', kp.publicKey))),
+ priv: b64u.enc(new Uint8Array(await crypto.subtle.exportKey('pkcs8', kp.privateKey))),
+ }
+}
+
+export type CollabInvite = { pub: string; priv: string; role: 'writer' | 'commenter'; exp?: number; sig: string }
+
+/**
+ * The `collab` block as this app writes it. dash's model.ts types the field as
+ * `unknown` on purpose (it is credentials, not document content), so the shape
+ * lives here — where the code that reads it lives.
+ */
+export interface CollabBlock {
+ room: string
+ key: string
+ on?: boolean
+ v?: number
+ owner?: string
+ ownerPriv?: string
+ invite?: CollabInvite
+ /** legacy 1.0.2-era shared writer key */
+ writerPub?: string
+ writerPriv?: string
+ role?: 'writer' | 'reader'
+ sync?: SyncStateJSON
+}
+
+export const collabOf = (doc: DashDoc): CollabBlock | undefined =>
+ (doc.collab as CollabBlock | undefined) ?? undefined
+
+/** Owner-signed invite: a delegation keypair whose private half rides in the
+ * shared copy. Chain: owner signs `inv.${pub}.${role}.${exp||0}`; a joining
+ * device later signs its own pubkey with the invite key (`dlg.${memberPub}`).
+ * The relay verifies both signatures and never sees private material — so a
+ * blind relay still cannot certify its own key. */
+export async function mintInvite(ownerPrivB64: string, role: 'writer' | 'commenter' = 'writer', exp = 0): Promise<CollabInvite> {
+ const kp = await mintKeypair()
+ const sig = await signText(ownerPrivB64, `inv.${kp.pub}.${role}.${exp}`)
+ return { pub: kp.pub, priv: kp.priv, role, ...(exp ? { exp } : {}), sig }
+}
+
+/** This device's member identity for a doc — minted once, kept in localStorage,
+ * NEVER in the file (the file travels; a device key must not). */
+export async function deviceIdentity(docId: string): Promise<{ pub: string; priv: string }> {
+ const k = `bento-member-${docId}`
+ try {
+ const saved = lsGet(k)
+ if (saved) return JSON.parse(saved) as { pub: string; priv: string }
+ } catch { /* storage unavailable → ephemeral identity */ }
+ const id = await mintKeypair()
+ lsSet(k, JSON.stringify(id))
+ return id
+}
+
+/** Auth material for the relay connection. Exactly one shape applies:
+ * direct (owner or legacy shared-writer key) or chain (member via invite). */
+export type AuthSpec =
+ | { kind: 'direct'; pub: string; priv?: string }
+ | { kind: 'chain'; owner: string; invite: CollabInvite; docId: string }
+
+export type CollabCreds = {
+ room: string
+ key: string
+ on: boolean
+ v: number
+ owner: string
+ ownerPriv: string
+ role: 'writer'
+}
+
+/**
+ * Fresh collaboration credentials, minted at DOCUMENT CREATION and live by
+ * default: the moment identity and keys exist, any copy of the file joins the
+ * same room. Dormancy is enforced elsewhere (SyncSession.shareEligible) so a
+ * workbook nobody has saved or shared never phones home.
+ *
+ * The room id COMMITS to the owner's public key — `w` + b64url(SHA-256(pub)) —
+ * so the relay pins the writer key trustlessly: a viewer holds the room id but
+ * cannot substitute a key of their own. `key` is the separate symmetric READ
+ * capability. Async because keypair generation is.
+ */
+export async function mintCollab(): Promise<CollabCreds> {
+ const kp = await mintKeypair()
+ const commit = new Uint8Array(await crypto.subtle.digest('SHA-256', b64u.dec(kp.pub) as BufferSource))
+ return {
+ room: `${syncHost()}/d/w${b64u.enc(commit)}`,
+ key: mintRoomKey(),
+ on: true,
+ v: 2,
+ owner: kp.pub,
+ ownerPriv: kp.priv,
+ role: 'writer',
+ }
+}
+
+/** dev override for the relay host (e.g. ws://localhost:8787) */
+export function syncHost(): string {
+ try {
+ return lsGet('bento-sync-url') || DEFAULT_SYNC_HOST
+ } catch {
+ return DEFAULT_SYNC_HOST
+ }
+}
+
+export type OnlineStatus = 'connecting' | 'open' | 'closed'
+
+/** A frame written to (or parked for) the relay. `ops` is set for persisted op
+ * batches — the only frames the relay acks, and the only ones whose refusal
+ * has to reach the session (an unsendable op must leave the resend log). */
+type Outbound = { id: string; text: string; ops: Op[] | null; bytes: number; tries: number }
+
+let frameSeq = 0
+/** Short opaque per-frame id, emitted FIRST in the envelope so the relay can
+ * recover it with a bounded regex from an OVERSIZE frame — one it refuses
+ * before parsing, since parsing an attacker-sized string is a CPU abuse
+ * vector. */
+const nextFrameId = (): string => `f${(++frameSeq).toString(36)}${Math.random().toString(36).slice(2, 6)}`
+
+type RefusedEnv = {
+ code?: string
+ /** our frame id, echoed back — authoritative when present */
+ k?: string
+ max?: number
+ got?: number
+ bytes?: number
+ retryInMs?: number
+}
+
+export class OnlineTransport implements Transport {
+ readonly kind = 'online'
+ status: OnlineStatus = 'connecting'
+ onStatus: ((s: OnlineStatus) => void) | null = null
+ private ws: WebSocket | null = null
+ private key: CryptoKey | null = null
+ /** writer signing key — null for readers (they decrypt but cannot author) */
+ private signKey: CryptoKey | null = null
+ private queue: Outbound[] = []
+ private awaitingAck: Outbound[] = []
+ private paused = false
+ private pauseTimer: ReturnType<typeof setTimeout> | null = null
+ private lastLimitNotice = 0
+ private static readonly ACK_WINDOW = 64
+ private static readonly MAX_RETRIES = 4
+ private closed = false
+ private backoff = 800
+ private url = ''
+ // Heartbeat: ping the relay (which auto-responds "pong" without waking the
+ // Durable Object) so idle connections stay alive; if a pong does not come
+ // back before the next tick the socket is treated as dead and reconnected,
+ // rather than waiting out a TCP timeout that can take minutes.
+ private pingTimer: ReturnType<typeof setInterval> | null = null
+ private awaitingPong = false
+ private static readonly PING_MS = 25_000
+ /** the key THIS socket signs with — used to recognise our own revocation */
+ myPub: string | null = null
+ /**
+ * Replay bookmark — MEMORY ONLY, deliberately: it is valid only alongside
+ * the in-memory CRDT state it was earned with. A fresh join replays from the
+ * room's snapshot (or 0); reconnects of THIS session resume from here.
+ */
+ private seq = 0
+ private docId = ''
+ private inReplay = true
+ private snapInFlight = false
+ private replaySeen = new Set<string>()
+ private onFrame: (f: Frame) => void
+ private hooks: {
+ onSnap: (doc: DashDoc, state: SyncStateJSON) => void
+ getSnapshot: () => { doc: DashDoc; state: SyncStateJSON }
+ onOpen: () => void
+ onReady: (seen: Set<string>, seq: number) => boolean
+ onRefused?: (code: RefusalCode, ops: Op[] | null) => void
+ }
+ private auth?: AuthSpec
+ private keyB64: string
+
+ // NB: fields are declared and assigned explicitly rather than through
+ // constructor parameter properties — the node type-stripping loader that
+ // runs scripts/test-dash-sync.ts rejects that syntax outright.
+ constructor(
+ room: string,
+ keyB64: string,
+ docId: string,
+ onFrame: (f: Frame) => void,
+ hooks: OnlineTransport['hooks'],
+ auth?: AuthSpec,
+ ) {
+ this.keyB64 = keyB64
+ this.docId = docId
+ this.onFrame = onFrame
+ this.hooks = hooks
+ this.auth = auth
+ void this.init(room)
+ }
+
+ /** Credentials a blob layer would need: the relay origin, room name, the
+ * possession-proof token, and the raw room key. dash does not offload
+ * assets yet; the accessor exists so that layer needs no transport change. */
+ blobCreds(): { base: string; room: string; tok: string; rawKey: Uint8Array } | null {
+ if (!this.roomName || !this.tokValue) return null
+ return { base: this.originValue, room: this.roomName, tok: this.tokValue, rawKey: b64u.dec(this.keyB64) }
+ }
+ private roomName = ''
+ private tokValue = ''
+ private originValue = ''
+
+ private async init(room: string) {
+ const raw = b64u.dec(this.keyB64)
+ this.key = await crypto.subtle.importKey('raw', raw as BufferSource, 'AES-GCM', false, ['encrypt', 'decrypt'])
+ const tokDigest = new Uint8Array(await crypto.subtle.digest('SHA-256', raw as BufferSource))
+ const tok = b64u.enc(tokDigest.slice(0, 18))
+ try {
+ const u = new URL(room.replace(/^ws/, 'http'))
+ this.originValue = u.origin
+ this.roomName = u.pathname.replace(/^\/d\//, '')
+ this.tokValue = tok
+ } catch { /* malformed room url — blobs simply stay unavailable */ }
+ // Writers sign op frames; readers omit auth and the relay drops their
+ // writes. Two writer shapes: DIRECT (the presented key hash-matches the
+ // room commitment — the owner, or a legacy shared-writer copy) and CHAIN
+ // (a member: this device's key, plus the owner-signed invite and the
+ // invite-signed delegation of the device key — verified by the relay).
+ const a = this.auth
+ if (a?.kind === 'direct') {
+ if (a.priv) { try { this.signKey = await importSignKey(a.priv) } catch { this.signKey = null } }
+ this.myPub = a.pub
+ this.url = `${room}?tok=${tok}&w=${a.pub}`
+ } else if (a?.kind === 'chain') {
+ const id = await deviceIdentity(this.docId)
+ try { this.signKey = await importSignKey(id.priv) } catch { this.signKey = null }
+ this.myPub = id.pub
+ const iv = a.invite
+ const dg = await signText(iv.priv, `dlg.${id.pub}`)
+ this.url = `${room}?tok=${tok}&w=${id.pub}&o=${a.owner}` +
+ `&ivp=${iv.pub}&ivr=${iv.role}&ive=${iv.exp ?? 0}&ivs=${iv.sig}&dg=${dg}`
+ } else {
+ this.url = `${room}?tok=${tok}`
+ }
+ this.connect()
+ }
+
+ private setStatus(s: OnlineStatus) {
+ this.status = s
+ this.onStatus?.(s)
+ }
+
+ private connect() {
+ if (this.closed) return
+ this.setStatus('connecting')
+ let ws: WebSocket
+ try {
+ ws = new WebSocket(`${this.url}&since=${this.seq}`)
+ } catch {
+ this.retry()
+ return
+ }
+ this.ws = ws
+ ws.onopen = () => {
+ this.backoff = 800
+ this.inReplay = true
+ this.replaySeen = new Set()
+ // Acks do not survive the socket: whatever was un-acked is unknowable
+ // now, and a stale entry would mis-name a later refusal. Delivery of
+ // those ops is the log's job anyway (session.onRelayReady re-sends).
+ this.awaitingAck = []
+ this.setStatus('open')
+ for (const out of this.queue.splice(0)) this.write(out)
+ this.startHeartbeat(ws)
+ this.hooks.onOpen()
+ }
+ ws.onmessage = (ev) => {
+ const data = String(ev.data)
+ if (data === 'pong') { this.awaitingPong = false; return }
+ void this.onEnvelope(data).catch(() => {})
+ }
+ const drop = () => {
+ if (this.ws !== ws) return
+ this.stopHeartbeat()
+ this.ws = null
+ this.setStatus('closed')
+ this.retry()
+ }
+ ws.onclose = drop
+ ws.onerror = drop
+ }
+
+ private startHeartbeat(ws: WebSocket) {
+ this.stopHeartbeat()
+ this.awaitingPong = false
+ this.pingTimer = setInterval(() => {
+ if (this.ws !== ws || ws.readyState !== WebSocket.OPEN) return
+ if (this.awaitingPong) {
+ // no pong since the last ping → the socket is half-open; force a close
+ // so onclose fires and we reconnect, rather than hanging silently
+ try { ws.close() } catch { /* already gone */ }
+ return
+ }
+ this.awaitingPong = true
+ try { ws.send('ping') } catch { /* send failed → onclose handles it */ }
+ }, OnlineTransport.PING_MS)
+ }
+
+ private stopHeartbeat() {
+ if (this.pingTimer) { clearInterval(this.pingTimer); this.pingTimer = null }
+ this.awaitingPong = false
+ }
+
+ private retry() {
+ if (this.closed) return
+ setTimeout(() => this.connect(), this.backoff)
+ this.backoff = Math.min(this.backoff * 1.8, 30000)
+ }
+
+ /**
+ * The relay refused a frame. Handling this is not optional politeness: when
+ * the relay dropped oversize/over-quota frames SILENTLY, the sender got no
+ * ack, the peer stayed behind, its catch-up asked for the very same op, and
+ * the sender re-sent the identical doomed frame forever.
+ */
+ private handleRefusal(env: RefusedEnv) {
+ if (env.code === 'rate-limited') {
+ this.throttle(typeof env.retryInMs === 'number' ? env.retryInMs : 10_000)
+ return
+ }
+ if (env.code !== 'too-large' && env.code !== 'storage-failed' && env.code !== 'room-full') {
+ // a code from a newer relay: no recovery we can invent is better than
+ // leaving the op in the log, where the next catch-up retries it honestly
+ console.warn('[bento-sync] relay refused a frame:', env.code)
+ return
+ }
+ const culprit = this.matchRefused(env)
+ if (culprit) this.awaitingAck = this.awaitingAck.filter((o) => o !== culprit)
+ console.warn(`[bento-sync] relay refused a frame (${env.code})`, env)
+ this.hooks.onRefused?.(env.code, culprit?.ops ?? null)
+ }
+
+ /**
+ * Which frame does this refusal name? Exact when the relay echoed our id;
+ * otherwise the head of the ack queue CONFIRMED against the size it
+ * reported. Ambiguity → null → the ops stay in the log, because a wrong drop
+ * is silent permanent divergence.
+ */
+ private matchRefused(env: RefusedEnv): Outbound | null {
+ if (env.k) return this.awaitingAck.find((o) => o.id === env.k) ?? null
+ const byText = typeof env.got === 'number'
+ const want = byText ? env.got! : typeof env.bytes === 'number' ? env.bytes : null
+ const size = (o: Outbound) => (byText ? o.text.length : o.bytes)
+ const head = this.awaitingAck[0] ?? null
+ if (want === null) return head // room-full carries no size — order is all we have
+ if (head && size(head) === want) return head
+ return this.awaitingAck.find((o) => size(o) === want) ?? null
+ }
+
+ /** Rate limited: hold everything for the window, then replay what we sent
+ * into it. Re-sending is safe (the CRDT dedups by actor:seq); losing them
+ * silently is not. */
+ private throttle(ms: number) {
+ const wait = Math.min(Math.max(ms, 1000), 60_000)
+ const retryable = this.awaitingAck.filter((o) => ++o.tries <= OnlineTransport.MAX_RETRIES)
+ this.awaitingAck = []
+ this.queue = [...retryable, ...this.queue]
+ if (this.pauseTimer) clearTimeout(this.pauseTimer)
+ this.paused = true
+ this.pauseTimer = setTimeout(() => {
+ this.pauseTimer = null
+ this.paused = false
+ for (const out of this.queue.splice(0)) this.write(out)
+ }, wait)
+ const now = Date.now()
+ if (now - this.lastLimitNotice > 60_000) {
+ this.lastLimitNotice = now
+ this.hooks.onRefused?.('rate-limited', null)
+ }
+ }
+
+ /** write now, or park it (disconnected, or inside a rate-limit backoff) */
+ private write(out: Outbound) {
+ if (!this.paused && this.ws && this.ws.readyState === WebSocket.OPEN) {
+ try {
+ this.ws.send(out.text)
+ } catch {
+ this.park(out) // send threw → onclose will reconnect and flush
+ return
+ }
+ if (out.ops) {
+ this.awaitingAck.push(out)
+ if (this.awaitingAck.length > OnlineTransport.ACK_WINDOW) this.awaitingAck.shift()
+ }
+ return
+ }
+ this.park(out)
+ }
+
+ private park(out: Outbound) {
+ this.queue.push(out)
+ if (this.queue.length > 500) this.queue.shift()
+ }
+
+ private async onEnvelope(text: string) {
+ let env: { i?: string; d?: string; q?: number; snap?: number; ctl?: string; p?: string } & RefusedEnv
+ try {
+ env = JSON.parse(text)
+ } catch {
+ return
+ }
+ // the owner revoked a key; if it is OURS, stand down for good (the relay
+ // refuses our reconnects anyway — don't retry into a wall of 403s)
+ if (env.ctl === 'revoked') {
+ if (env.p && env.p === this.myPub) {
+ console.info('[bento-sync] this copy’s access was revoked by the owner')
+ this.close()
+ }
+ return
+ }
+ if (env.ctl === 'refused') {
+ this.handleRefusal(env)
+ return
+ }
+ if (env.ctl === 'ack' || env.ctl === 'ready') {
+ if (env.ctl === 'ack') this.awaitingAck.shift()
+ if (typeof env.q === 'number') {
+ if (env.q > this.seq) this.seq = env.q
+ this.maybeSnapshot(env.q)
+ }
+ if (env.ctl === 'ready') {
+ this.inReplay = false
+ const wantSnap = this.hooks.onReady(this.replaySeen, env.q ?? 0)
+ this.replaySeen = new Set()
+ // fresh rooms and just-merged forks get a snapshot immediately so late
+ // joiners converge without needing the full op log
+ if (wantSnap || env.q === 0) void this.uploadSnapshot(env.q ?? 0)
+ }
+ return
+ }
+ if (!env.i || !env.d || !this.key) return
+ let payload: unknown
+ try {
+ const pt = await crypto.subtle.decrypt(
+ { name: 'AES-GCM', iv: b64u.dec(env.i) as BufferSource },
+ this.key,
+ b64u.dec(env.d) as BufferSource,
+ )
+ payload = JSON.parse(new TextDecoder().decode(pt))
+ } catch {
+ return // wrong key / corrupted — ignore
+ }
+ if (typeof env.q === 'number' && env.q > this.seq) this.seq = env.q
+ if (env.snap === 1) {
+ const s = payload as { doc: DashDoc; state: SyncStateJSON }
+ if (s && s.doc && s.state) this.hooks.onSnap(s.doc, s.state)
+ return
+ }
+ const frame = payload as Frame
+ if (this.inReplay && frame.t === 'ops') {
+ for (const op of frame.ops) this.replaySeen.add(`${op.a}:${op.s}`)
+ }
+ this.onFrame(frame)
+ }
+
+ /** every SNAP_EVERY persisted ops, upload a fresh encrypted snapshot */
+ private maybeSnapshot(q: number) {
+ if (q === 0 || q % SNAP_EVERY !== 0) return
+ void this.uploadSnapshot(q)
+ }
+
+ /** encrypt + store the current (doc, state) as the room's snapshot */
+ async uploadSnapshot(q: number) {
+ if (this.snapInFlight) return
+ this.snapInFlight = true
+ try {
+ const snap = this.hooks.getSnapshot()
+ const text = await this.encrypt(JSON.stringify(snap))
+ if (text && this.ws && this.ws.readyState === WebSocket.OPEN) {
+ const env: Record<string, unknown> = { snap: 1, q, i: text.i, d: text.d }
+ if (this.signKey) env.g = await signFrame(this.signKey, text.i, text.d)
+ this.ws.send(JSON.stringify(env))
+ }
+ } finally {
+ this.snapInFlight = false
+ }
+ }
+
+ private async encrypt(plain: string): Promise<{ i: string; d: string } | null> {
+ if (!this.key) return null
+ const iv = new Uint8Array(12)
+ crypto.getRandomValues(iv)
+ const ct = await crypto.subtle.encrypt(
+ { name: 'AES-GCM', iv: iv as BufferSource },
+ this.key,
+ new TextEncoder().encode(plain),
+ )
+ return { i: b64u.enc(iv), d: b64u.enc(new Uint8Array(ct)) }
+ }
+
+ send(frame: Frame) {
+ void (async () => {
+ const enc = await this.encrypt(JSON.stringify(frame))
+ if (!enc) return
+ let env: Record<string, unknown> = enc
+ let ops: Op[] | null = null
+ const id = nextFrameId()
+ if (frame.t === 'ops') {
+ env = { k: id, p: 1, ...enc }
+ // sign the CIPHERTEXT so the relay verifies authorship while blind
+ if (this.signKey) env.g = await signFrame(this.signKey, enc.i, enc.d)
+ ops = frame.ops
+ }
+ this.write({ id, text: JSON.stringify(env), ops, bytes: enc.i.length + enc.d.length, tries: 0 })
+ })()
+ }
+
+ close() {
+ this.closed = true
+ if (this.pauseTimer) { clearTimeout(this.pauseTimer); this.pauseTimer = null }
+ this.stopHeartbeat()
+ this.ws?.close()
+ this.ws = null
+ this.setStatus('closed')
+ }
+
+ /** OWNER action: revoke one member key (or an invite key — cutting off every
+ * copy descended from that invite). Signed `rev.${pub}`; the relay stores
+ * it, drops that key's future writes/joins, and fans out a `revoked` note. */
+ async revokeKey(pub: string, ownerPub: string, ownerPriv: string): Promise<boolean> {
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false
+ const g = await signText(ownerPriv, `rev.${pub}`)
+ this.ws.send(JSON.stringify({ ctl: 'revoke', p: pub, o: ownerPub, g }))
+ return true
+ }
+}
+
+// --- share/join glue --------------------------------------------------------
+
+let active: OnlineTransport | null = null
+
+export function onlineTransport(): OnlineTransport | null {
+ return active
+}
+
+/** inert stand-in when a re-keyed document has no collab config */
+class NullTransport implements Transport {
+ readonly kind = 'off'
+ send() {}
+ close() {}
+}
+
+/** does this document want its relay connected? (absent `on` = true) */
+export function sharingOn(store: Store): boolean {
+ const c = collabOf(store.doc)
+ return !!c?.room && !!c.key && c.on !== false
+}
+
+/** connect the session to the relay in doc.collab (no-op unless sharing is on) */
+export function joinFromDoc(session: SyncSession, store: Store): OnlineTransport | null {
+ if (offlineEnabled()) return null // the hard no-network switch wins over everything
+ if (active) return active
+ if (!sharingOn(store)) return null
+ session.addTransport((docId, onFrame) => {
+ // re-invoked whenever the session re-keys (doc replaced): consult the
+ // CURRENT document — its collab config may differ or be off
+ const collab = collabOf(store.doc)
+ if (!collab?.room || !collab.key || collab.on === false || store.doc.docId !== docId) {
+ active = null
+ return new NullTransport()
+ }
+ active?.close()
+ let auth: AuthSpec | undefined
+ if (collab.role !== 'reader') {
+ if (collab.v === 2 && collab.owner && collab.ownerPriv) {
+ auth = { kind: 'direct', pub: collab.owner, priv: collab.ownerPriv }
+ } else if (collab.v === 2 && collab.owner && collab.invite) {
+ auth = { kind: 'chain', owner: collab.owner, invite: collab.invite, docId }
+ } else if (collab.writerPub) {
+ auth = { kind: 'direct', pub: collab.writerPub, priv: collab.writerPriv }
+ }
+ }
+ active = new OnlineTransport(collab.room, collab.key, docId, onFrame, {
+ onSnap: (doc, state) => session.applySnapshot(doc, state),
+ getSnapshot: () => session.snapshot(),
+ onOpen: () => session.hello(),
+ onReady: (seen) => session.onRelayReady(seen),
+ onRefused: (code, ops) => session.refused(code, ops),
+ }, auth)
+ return active
+ })
+ return active
+}
+
+/** flip sharing on and connect — the "Start live session" action. Credentials
+ * already exist (minted at creation); this only arms them. */
+export async function startSharing(session: SyncSession, store: Store): Promise<OnlineTransport | null> {
+ if (offlineEnabled()) return null
+ if (active) return active
+ const doc = store.doc as DashDoc & { collab?: CollabBlock }
+ if (!doc.collab) doc.collab = await mintCollab()
+ doc.collab.on = true
+ session.enableSharing()
+ return joinFromDoc(session, store)
+}
+
+/**
+ * Offline-mode disconnect: drop the relay WITHOUT touching doc.collab.on — the
+ * document's sharing intent is unchanged; this viewer just will not network.
+ */
+export function disconnectOnline(session: SyncSession) {
+ if (active) {
+ session.removeTransport(active)
+ active = null
+ }
+}
+
+/** flip sharing off and disconnect. Credentials stay — copies saved during the
+ * session can rejoin if sharing is turned back on. */
+export function stopSharing(session: SyncSession, store: Store) {
+ if (active) {
+ session.removeTransport(active)
+ active = null
+ }
+ const c = collabOf(store.doc)
+ if (c && c.on !== false) c.on = false
+}
+
+/** revocation: mint a fresh room + key. Every previously sent copy loses
+ * access; only copies saved AFTER this can join future sessions. */
+export async function rotateKeys(session: SyncSession, store: Store) {
+ stopSharing(session, store)
+ const fresh = await mintCollab()
+ const doc = store.doc as DashDoc & { collab?: CollabBlock }
+ const sync = doc.collab?.sync
+ doc.collab = sync ? { ...fresh, sync } : fresh
+}
+
+/** Save-a-copy helpers: what to strip for each tier. A reader copy keeps the
+ * READ key and loses every private half, so the relay drops its writes. */
+export function readerCopy(collab: CollabBlock): CollabBlock {
+ const { ownerPriv: _o, writerPriv: _w, invite: _i, ...rest } = collab
+ return { ...rest, role: 'reader' }
+}
+
+/** An invite copy: the owner's private half stays home, an owner-signed invite
+ * travels. Each device that opens it mints its own member key. */
+export async function inviteCopy(collab: CollabBlock): Promise<CollabBlock> {
+ if (!collab.ownerPriv) return collab // not the owner's copy — nothing to delegate
+ const invite = await mintInvite(collab.ownerPriv)
+ const { ownerPriv: _o, ...rest } = collab
+ return { ...rest, invite, role: 'writer' }
+}
diff --git a/dash/src/sync/people.ts b/dash/src/sync/people.ts
new file mode 100644
index 00000000..6df0beca
--- /dev/null
+++ b/dash/src/sync/people.ts
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// The People panel: who is in this workbook, and (for the owner) who may stay.
+//
+// Presence names are CLAIMS, not proofs — anyone can type any name — but the
+// KEY beside them is a proof, because the relay verified the owner→invite→
+// member signature chain before letting that socket write. So the panel is
+// keyed by pubkey and shows the name as a label, which is the honest way round
+// and the one that makes Remove meaningful: removing a name would remove
+// nothing, removing a key ends that device's write access in seconds.
+//
+// Deliberately a mount function rather than a topbar button: main.ts is not
+// this task's to edit. `mountPeople(host, session, store)` is one line at the
+// call site — see docs/dash-collab.md, "What this needs from main.ts".
+
+import '../sync.css'
+import type { Store } from '../store.ts'
+import type { SyncSession, Peer } from './session.ts'
+import { collabOf, onlineTransport, startSharing, stopSharing, sharingOn } from './online.ts'
+
+const esc = (s: string): string =>
+ s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+
+/** short, stable, human-checkable form of a public key */
+const fingerprint = (pub: string): string => `${pub.slice(0, 4)}…${pub.slice(-4)}`
+
+const ROLE_LABEL: Record<string, string> = {
+ owner: 'owner', editor: 'editor', viewer: 'view only',
+}
+
+/**
+ * Mount the live/people panel into `host`. Returns a teardown.
+ *
+ * Renders on every presence change, which is at most one repaint per peer
+ * heartbeat (5s) — the list is a handful of rows and nothing else on the page
+ * depends on it.
+ */
+export function mountPeople(host: HTMLElement, session: SyncSession, store: Store): () => void {
+ host.classList.add('dx-people')
+
+ const render = () => {
+ const c = collabOf(store.doc)
+ const live = sharingOn(store) && session.transportKinds.includes('online')
+ const iAmOwner = !!c?.ownerPriv
+ const peers = session.peers()
+ host.innerHTML =
+ `<div class="dx-people-head">` +
+ `<span class="dx-people-dot${live ? ' on' : ''}"></span>` +
+ `<span class="dx-people-title">${live ? 'Live' : 'Not sharing'}</span>` +
+ `<button class="dx-btn dx-people-toggle">${live ? 'Stop sharing' : 'Start live session'}</button>` +
+ `</div>` +
+ `<ul class="dx-people-list">` +
+ `<li class="dx-people-me"><span class="dx-people-chip" style="background:${esc(selfColor(session))}"></span>` +
+ `<span class="dx-people-name">You</span></li>` +
+ peers.map((p) => row(p, iAmOwner)).join('') +
+ `</ul>` +
+ (peers.length ? '' : `<p class="dx-people-empty">Nobody else is in this workbook.</p>`)
+
+ host.querySelector('.dx-people-toggle')?.addEventListener('click', () => {
+ if (live) stopSharing(session, store)
+ else void startSharing(session, store)
+ render()
+ })
+ host.querySelectorAll<HTMLElement>('[data-remove]').forEach((b) => {
+ b.addEventListener('click', () => {
+ const pub = b.dataset.remove!
+ // Revocation is an OWNER-SIGNED statement the relay stores and
+ // enforces; it is not a UI state. If the socket is not open there is
+ // nobody to tell, so say so rather than pretending it worked.
+ const tr = onlineTransport()
+ if (!tr || !c?.owner || !c.ownerPriv) return
+ void tr.revokeKey(pub, c.owner, c.ownerPriv).then((ok) => {
+ if (!ok) console.warn('[bento-sync] not connected — nothing was revoked')
+ })
+ })
+ })
+ }
+
+ const row = (p: Peer, iAmOwner: boolean): string => {
+ const role = p.role ? ROLE_LABEL[p.role] ?? p.role : ''
+ // Only a KEY can be removed, so a peer without one (an older build, or a
+ // member whose device key has not reached us yet) gets no button rather
+ // than a button that would quietly do nothing.
+ const canRemove = iAmOwner && !!p.pub && p.role !== 'owner'
+ return `<li>` +
+ `<span class="dx-people-chip" style="background:${esc(p.color)}"></span>` +
+ `<span class="dx-people-name">${esc(p.name)}</span>` +
+ (role ? `<span class="dx-people-role">${esc(role)}</span>` : '') +
+ (p.pub ? `<span class="dx-people-key" title="${esc(p.pub)}">${esc(fingerprint(p.pub))}</span>` : '') +
+ (canRemove ? `<button class="dx-people-x" data-remove="${esc(p.pub!)}" title="Remove this device">✕</button>` : '') +
+ `</li>`
+ }
+
+ const off = session.onPeers(render)
+ render()
+ return () => {
+ off()
+ host.innerHTML = ''
+ host.classList.remove('dx-people')
+ }
+}
+
+/** the colour this session shows to others, so "You" matches their chip */
+function selfColor(session: SyncSession): string {
+ const COLORS = ['#FF9E8A', '#8FA3BF', '#7FC8A9', '#E8C468', '#C792EA', '#6AB7D6', '#E88AB0', '#A9C77F']
+ let h = 0
+ for (let i = 0; i < session.actor.length; i++) h = (h * 31 + session.actor.charCodeAt(i)) >>> 0
+ return COLORS[h % COLORS.length]
+}
diff --git a/dash/src/sync/session.ts b/dash/src/sync/session.ts
new file mode 100644
index 00000000..e7f28476
--- /dev/null
+++ b/dash/src/sync/session.ts
@@ -0,0 +1,564 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento-sync session for dash — the bridge between the CRDT engine (crdt.ts)
+// and the running workbook. Owns: the patch tap on the store, transports
+// (same-machine BroadcastChannel always; an online relay can be added),
+// presence, and peer catch-up. Design: docs/dash-collab.md.
+//
+// Wire protocol (one JSON frame per message; E2EE happens inside the online
+// transport — this layer never knows), IDENTICAL to slides':
+// {t:'hello', a, vv, p} join/announce — receivers reply hello + missing ops
+// {t:'ops', a, ops} op batch
+// {t:'need', a, vv} gap catch-up request
+// {t:'p', a, p} presence heartbeat {t:'bye', a} leave
+// {t:'snap', a, doc, state} state-based fork merge
+//
+// WHERE THIS DIFFERS FROM SLIDES, and why. Slides diffs two whole-document
+// snapshots on every commit. A dash workbook is 10-25 MB, `JSON.stringify` on
+// it costs ~10 ms, and the shadow copy doubles resident memory — so there is
+// no shadow here. Ops are minted from the store's own `Patch` objects, which
+// already describe every mutation exactly, and they are minted BEFORE the
+// store applies them (crdt.ts `local()` explains why it has to be that way).
+
+import type { Store, Patch } from '../store.ts'
+import type { DashDoc } from '../model.ts'
+import { DashSync, SYNC_V, committable, type Op, type SyncStateJSON } from './crdt.ts'
+import { collabOf, mintCollab, type CollabBlock } from './online.ts'
+import { lsGet, lsJson } from '../../../kernel/src/storage.ts'
+
+export interface PresenceInfo {
+ name: string
+ color: string
+ /** the sheet this person is looking at */
+ sheet: string
+ /** v2 fine-grained: the key this copy signs with — key-bound identity */
+ pub?: string
+ /** capability of this copy, derived locally from its collab material */
+ role?: 'owner' | 'editor' | 'viewer'
+}
+
+export interface Peer extends PresenceInfo {
+ actor: string
+ at: number
+}
+
+interface HelloFrame { t: 'hello'; a: string; vv: Record<string, number>; p: PresenceInfo }
+interface OpsFrame { t: 'ops'; a: string; ops: Op[] }
+interface NeedFrame { t: 'need'; a: string; vv: Record<string, number> }
+interface PresFrame { t: 'p'; a: string; p: PresenceInfo }
+interface ByeFrame { t: 'bye'; a: string }
+interface SnapFrame { t: 'snap'; a: string; doc: DashDoc; state: SyncStateJSON }
+
+/** Every frame is stamped with the sync protocol version (`pv`); frames
+ * without the current one are dropped, because their keys do not interoperate. */
+export type Frame = (HelloFrame | OpsFrame | NeedFrame | PresFrame | ByeFrame | SnapFrame) & { pv?: number }
+
+export interface Transport {
+ readonly kind: string
+ send(frame: Frame): void
+ close(): void
+}
+
+/** Why the relay refused a frame. Everything but 'rate-limited' is PERMANENT
+ * for the frame that drew it: retrying can only reproduce the refusal. */
+export type RefusalCode = 'too-large' | 'storage-failed' | 'room-full' | 'rate-limited'
+
+export interface SyncNotice {
+ code: RefusalCode | 'patch-refused'
+ /** true = the change will never reach collaborators; false = retrying */
+ permanent: boolean
+ /** how many ops (or patches) were abandoned */
+ ops: number
+}
+
+/** Same-machine transport: every open tab/window of this document. */
+class BroadcastTransport implements Transport {
+ readonly kind = 'local'
+ private ch: BroadcastChannel
+ constructor(docId: string, onFrame: (f: Frame) => void) {
+ this.ch = new BroadcastChannel(`bento-sync-${docId}`)
+ this.ch.onmessage = (ev) => onFrame(ev.data as Frame)
+ }
+ send(frame: Frame) {
+ this.ch.postMessage(frame)
+ }
+ close() {
+ this.ch.close()
+ }
+}
+
+const PEER_COLORS = ['#FF9E8A', '#8FA3BF', '#7FC8A9', '#E8C468', '#C792EA', '#6AB7D6', '#E88AB0', '#A9C77F']
+
+const actorColor = (actor: string): string => {
+ let h = 0
+ for (let i = 0; i < actor.length; i++) h = (h * 31 + actor.charCodeAt(i)) >>> 0
+ return PEER_COLORS[h % PEER_COLORS.length]
+}
+
+/**
+ * Actor id: fresh per SESSION INSTANCE, deliberately — a reloaded tab is a new
+ * replica with empty CRDT state, and the engine skips "own" ops on apply, so
+ * reusing an id would make relay replay of the previous incarnation's ops a
+ * no-op. Random ids sidestep the whole class.
+ */
+const tabActor = (): string => Math.random().toString(36).slice(2, 10)
+
+const HEARTBEAT_MS = 5000
+const PEER_TTL_MS = 13000
+
+export class SyncSession {
+ readonly actor: string
+ state!: DashSync
+ private store: Store
+ private docId = ''
+ private log: Op[] = []
+ private transports: Transport[] = []
+ private peersMap = new Map<string, Peer>()
+ private applying = false
+ private heartbeat: number | null = null
+ private peerListeners = new Set<() => void>()
+ private noticeListeners = new Set<(n: SyncNotice) => void>()
+ private makeExtraTransports: Array<(docId: string, onFrame: (f: Frame) => void) => Transport> = []
+ private forkPending = false
+ private bornWithCollab = false
+ private explicitShare = false
+ /** the current sheet, for presence — view state, never in the document */
+ sheet = ''
+
+ constructor(store: Store) {
+ this.store = store
+ this.actor = tabActor()
+ this.attach()
+ this.tapStore()
+ if (typeof window !== 'undefined') {
+ window.addEventListener('beforeunload', () => this.broadcast({ t: 'bye', a: this.actor }))
+ }
+ }
+
+ // --- lifecycle -----------------------------------------------------------
+
+ /**
+ * Should this workbook auto-connect on open? Only if it ARRIVED carrying
+ * collab credentials (somebody saved or shared it) or the user opted in this
+ * session. A freshly created workbook mints credentials but stays dormant —
+ * the starter document must never phone home (PLATFORM §5).
+ */
+ shareEligible(): boolean {
+ return this.bornWithCollab || this.explicitShare
+ }
+
+ enableSharing() {
+ this.explicitShare = true
+ }
+
+ private attach() {
+ this.docId = this.store.doc.docId
+ const doc = this.store.doc
+ this.bornWithCollab = !!doc.collab
+ this.explicitShare = false
+ if (!doc.collab) void this.ensureCollab()
+ const saved = collabOf(doc)?.sync
+ if (saved && saved.v === SYNC_V) {
+ // saved during/after a shared session: restore the CRDT state so our
+ // offline edits carry real registers, relay replay dedups by version
+ // vector, and a snapshot exchange can merge the fork BOTH ways
+ this.state = DashSync.fromJSON(this.actor, JSON.parse(JSON.stringify(saved)) as SyncStateJSON)
+ this.forkPending = true
+ } else {
+ this.state = new DashSync(this.actor)
+ }
+ this.state.adopt(doc)
+ this.log = []
+ this.peersMap.clear()
+ this.emitPeers()
+ for (const tr of this.transports) tr.close()
+ this.transports = [new BroadcastTransport(this.docId, (f) => this.onFrame(f))]
+ for (const mk of this.makeExtraTransports) this.transports.push(mk(this.docId, (f) => this.onFrame(f)))
+ this.hello()
+ if (this.heartbeat) clearInterval(this.heartbeat)
+ this.heartbeat = (globalThis as { setInterval: typeof setInterval }).setInterval(() => {
+ this.pushPresence()
+ this.sweepPeers()
+ }, HEARTBEAT_MS) as unknown as number
+ }
+
+ private async ensureCollab() {
+ if (this.store.doc.collab) return
+ const creds = await mintCollab()
+ if (!this.store.doc.collab) this.store.doc.collab = creds
+ }
+
+ // --- the patch tap --------------------------------------------------------
+
+ /**
+ * Intercept the store's write verbs.
+ *
+ * `store.beforePatch` is the real hook: called from `commit`, `runEdit` AND
+ * `invert` with the patches about to be applied, and able to replace the
+ * list. `afterPatch` is its other half — the CRDT mints ops from the
+ * PRE-state (a delete has to be read before it displaces anything) and
+ * settles once the document has moved.
+ *
+ * INVERT IS WHY IT EXISTS. Wrapping the two public verbs on the instance
+ * covers every edit the UI makes and cannot see undo or redo, which apply
+ * their inverses through a private path — so undo used to fall back to
+ * broadcasting a whole state snapshot: correct, and enormously heavier than
+ * the two ops it stood in for. The wrapper below is kept for a store that
+ * predates the hook.
+ */
+ private tapStore() {
+ const store = this.store as Store & {
+ beforePatch?: (fn: (patches: Patch[]) => Patch[] | void) => () => void
+ afterPatch?: (fn: () => void) => () => void
+ }
+ if (typeof store.beforePatch === 'function' && typeof store.afterPatch === 'function') {
+ store.beforePatch((patches) => this.localPatches(patches))
+ store.afterPatch(() => this.afterLocal())
+ return
+ }
+ const commit = store.commit.bind(store)
+ const runEdit = store.runEdit.bind(store)
+ const undo = store.undo.bind(store)
+ const redo = store.redo.bind(store)
+ const replaceDoc = store.replaceDoc.bind(store)
+ store.commit = (patches: Patch | Patch[]) => {
+ const list = this.localPatches(Array.isArray(patches) ? patches : [patches])
+ if (list.length) commit(list)
+ this.afterLocal()
+ }
+ store.runEdit = (cellKey: string, patch: Patch | Patch[]) => {
+ const list = this.localPatches(Array.isArray(patch) ? patch : [patch])
+ if (list.length) runEdit(cellKey, list)
+ this.afterLocal()
+ }
+ store.undo = () => {
+ const ok = undo()
+ if (ok) this.shipSnapshot()
+ return ok
+ }
+ store.redo = () => {
+ const ok = redo()
+ if (ok) this.shipSnapshot()
+ return ok
+ }
+ store.replaceDoc = (next: DashDoc) => {
+ replaceDoc(next)
+ // a wholesale replacement re-keys everything; re-adopt and tell the room
+ this.attach()
+ this.shipSnapshot()
+ }
+ }
+
+ /**
+ * Mint ops for patches the store is about to apply, and drop the ones that
+ * cannot be committed into a live session (see crdt.committable — an edit
+ * naming a row or column a collaborator has deleted lands here and nowhere
+ * else). Returns the patches that survived.
+ */
+ private localPatches(patches: Patch[]): Patch[] {
+ if (this.applying) return patches // remote application, not a local edit
+ const doc = this.store.doc
+ const list = patches.filter((p) => committable(doc, p))
+ if (list.length !== patches.length) {
+ this.emitNotice({ code: 'patch-refused', permanent: true, ops: patches.length - list.length })
+ }
+ if (!list.length) return list
+ const ops = this.state.local(doc, list)
+ if (ops.length) {
+ this.log.push(...ops)
+ this.broadcast({ t: 'ops', a: this.actor, ops })
+ }
+ return list
+ }
+
+ /** after the store has applied a local commit: let parked remote ops land */
+ private afterLocal() {
+ this.state.settle(this.store.doc)
+ if (this.state.unsynced) {
+ // a patch this engine cannot express as ops — ship the whole state
+ // rather than let an edit the user believes landed reach nobody
+ this.state.unsynced = false
+ this.shipSnapshot()
+ }
+ }
+
+ private shipSnapshot() {
+ const s = this.snapshot()
+ this.broadcast({ t: 'snap', a: this.actor, doc: s.doc, state: s.state })
+ }
+
+ /** register a factory for an additional transport (the online relay) */
+ addTransport(mk: (docId: string, onFrame: (f: Frame) => void) => Transport): Transport {
+ this.makeExtraTransports.push(mk)
+ const tr = mk(this.docId, (f) => this.onFrame(f))
+ this.transports.push(tr)
+ this.broadcast({ t: 'hello', a: this.actor, vv: this.state.vv, p: this.presence() })
+ return tr
+ }
+
+ removeTransport(tr: Transport) {
+ tr.close()
+ this.transports = this.transports.filter((x) => x !== tr)
+ this.makeExtraTransports = []
+ }
+
+ get transportKinds(): string[] {
+ return this.transports.map((t) => t.kind)
+ }
+
+ // --- remote frames --------------------------------------------------------
+
+ private onFrame(f: Frame) {
+ if (f.pv !== SYNC_V) return // old-protocol frame — ignore
+ if (f.a === this.actor) return
+ switch (f.t) {
+ case 'hello': {
+ this.touchPeer(f.a, f.p)
+ // answer so the newcomer learns us, catch them up from our log, AND
+ // tell them our vv so ops they minted before connecting flow back
+ this.send({ t: 'p', a: this.actor, p: this.presence() })
+ this.send({ t: 'need', a: this.actor, vv: this.state.vv })
+ const missing = this.state.missingFor(this.log, f.vv)
+ if (missing.length) this.send({ t: 'ops', a: this.actor, ops: missing })
+ break
+ }
+ case 'ops':
+ this.applyRemote(f.ops)
+ break
+ case 'need': {
+ const missing = this.state.missingFor(this.log, f.vv)
+ if (missing.length) this.send({ t: 'ops', a: this.actor, ops: missing })
+ break
+ }
+ case 'p':
+ this.touchPeer(f.a, f.p)
+ break
+ case 'snap':
+ this.applySnapshot(f.doc, f.state)
+ break
+ case 'bye':
+ this.peersMap.delete(f.a)
+ this.emitPeers()
+ break
+ }
+ }
+
+ applyRemote(ops: Op[]) {
+ for (const op of ops) if (!this.log.some((o) => o.a === op.a && o.s === op.s)) this.log.push(op)
+ this.applying = true
+ try {
+ const res = this.state.apply(this.store.doc, ops)
+ if (res.changed) this.afterRemoteChange()
+ } finally {
+ this.applying = false
+ }
+ if (this.state.gappedActors.length) {
+ this.send({ t: 'need', a: this.actor, vv: this.state.vv })
+ }
+ }
+
+ /**
+ * Remote ops are applied SURGICALLY and then the store's own events are
+ * re-emitted, so the grid repaints through the path it already has. They are
+ * deliberately NOT routed through `store.commit`: a collaborator's edit is
+ * not an entry in your undo history.
+ */
+ private afterRemoteChange() {
+ // `store.changedRemotely()` is the public verb for exactly this: stamp
+ // modified, invalidate everything, emit what an edit emits — without
+ // touching the undo stack, because a collaborator's change is not an entry
+ // in your history. This used to reach through `unknown` for the PRIVATE
+ // `emit`, which works right up until the event names change.
+ const store = this.store as Store & { changedRemotely?: (t?: unknown) => void }
+ if (typeof store.changedRemotely === 'function') { store.changedRemotely(); return }
+ const legacy = this.store as unknown as {
+ doc: DashDoc; lastTouched: unknown; emit?: (ev: string) => void
+ }
+ legacy.doc.modified = new Date().toISOString()
+ legacy.lastTouched = { all: true }
+ legacy.emit?.('doc')
+ legacy.emit?.('view')
+ }
+
+ // --- presence -------------------------------------------------------------
+
+ private presence(): PresenceInfo {
+ let name = 'Guest'
+ try {
+ name = lsGet('bento-author') || 'Guest'
+ } catch { /* storage unavailable */ }
+ // key-bound identity (v2): which key this copy signs with + its capability
+ const c = collabOf(this.store.doc)
+ let pub: string | undefined
+ let role: 'owner' | 'editor' | 'viewer' | undefined
+ if (c) {
+ if (c.role === 'reader') role = 'viewer'
+ else if (c.v === 2 && c.ownerPriv) { role = 'owner'; pub = c.owner }
+ else if (c.v === 2 && c.invite) {
+ role = 'editor'
+ pub = lsJson<{ pub?: string } | null>(`bento-member-${this.store.doc.docId}`, null)?.pub
+ } else if (c.writerPriv) { role = 'editor'; pub = c.writerPub }
+ }
+ return {
+ name,
+ color: actorColor(this.actor),
+ sheet: this.sheet,
+ ...(pub ? { pub } : {}),
+ ...(role ? { role } : {}),
+ }
+ }
+
+ /** the grid calls this when the visible sheet changes */
+ setSheet(id: string) {
+ if (this.sheet === id) return
+ this.sheet = id
+ this.pushPresence()
+ }
+
+ private pushPresence() {
+ this.send({ t: 'p', a: this.actor, p: this.presence() })
+ }
+
+ private touchPeer(actor: string, p: PresenceInfo) {
+ this.peersMap.set(actor, { ...p, actor, at: Date.now() })
+ this.emitPeers()
+ }
+
+ private sweepPeers() {
+ const cut = Date.now() - PEER_TTL_MS
+ let changed = false
+ for (const [a, p] of this.peersMap) {
+ if (p.at < cut) {
+ this.peersMap.delete(a)
+ changed = true
+ }
+ }
+ if (changed) this.emitPeers()
+ }
+
+ peers(): Peer[] {
+ return [...this.peersMap.values()].sort((a, b) => (a.actor < b.actor ? -1 : 1))
+ }
+
+ onPeers(fn: () => void): () => void {
+ this.peerListeners.add(fn)
+ return () => this.peerListeners.delete(fn)
+ }
+
+ private emitPeers() {
+ this.peerListeners.forEach((fn) => fn())
+ }
+
+ // --- relay refusals -------------------------------------------------------
+
+ onNotice(fn: (n: SyncNotice) => void): () => void {
+ this.noticeListeners.add(fn)
+ return () => this.noticeListeners.delete(fn)
+ }
+
+ private emitNotice(n: SyncNotice) {
+ this.noticeListeners.forEach((fn) => fn(n))
+ }
+
+ /**
+ * The relay refused a frame. For the PERMANENT codes those ops can never be
+ * delivered, so they leave the resend log — otherwise every peer `need`
+ * re-offers them, they are re-sent and re-refused forever. The price is real
+ * and cannot be undone: this document keeps the change, remote replicas
+ * never see it. So only the exact ops of the named frame are dropped, never
+ * a range, and never anything when the frame could not be identified.
+ */
+ refused(code: RefusalCode, ops: Op[] | null) {
+ const doomed = ops ?? []
+ if (doomed.length) {
+ const keys = new Set(doomed.map((o) => `${o.a}:${o.s}`))
+ this.log = this.log.filter((o) => !keys.has(`${o.a}:${o.s}`))
+ }
+ this.emitNotice({ code, permanent: code !== 'rate-limited', ops: doomed.length })
+ }
+
+ // --- snapshots (online catch-up + file-fork merge) ------------------------
+
+ snapshot(): { doc: DashDoc; state: SyncStateJSON } {
+ return {
+ doc: JSON.parse(JSON.stringify(this.store.doc)) as DashDoc,
+ state: JSON.parse(JSON.stringify(this.state.toJSON())) as SyncStateJSON,
+ }
+ }
+
+ applySnapshot(rdoc: DashDoc, rstate: SyncStateJSON) {
+ if (!rstate || rstate.v !== SYNC_V) return // pre-v1 / foreign room snapshot
+ this.applying = true
+ try {
+ const res = this.state.mergeSnapshot(this.store.doc, rdoc, rstate)
+ if (res.changed) this.afterRemoteChange()
+ } finally {
+ this.applying = false
+ }
+ }
+
+ /** re-announce (an online transport connected or reconnected) */
+ hello() {
+ this.broadcast({ t: 'hello', a: this.actor, vv: this.state.vv, p: this.presence() })
+ if (this.forkPending) {
+ // a rejoining offline fork: its contributions live in document values +
+ // restored registers, not in ops — a state snapshot is how they travel
+ this.shipSnapshot()
+ }
+ }
+
+ /**
+ * Relay replay finished. `seen` holds the (actor,seq) pairs the room already
+ * has; anything in our log it lacks gets (re)sent for persistence — covering
+ * ops minted before the transport connected. Returns whether a fresh server
+ * snapshot should be uploaded (a fork just merged).
+ */
+ onRelayReady(seen: Set<string>): boolean {
+ const missing = this.log.filter((o) => !seen.has(`${o.a}:${o.s}`))
+ if (missing.length) this.send({ t: 'ops', a: this.actor, ops: missing })
+ const fork = this.forkPending
+ this.forkPending = false
+ return fork
+ }
+
+ /**
+ * Stamp the CRDT state into doc.collab.sync so the SAVED file can rejoin as
+ * a true fork later. Called by the save path; only shared documents carry it.
+ *
+ * The state is O(edits), but a long session with a big paste can still make
+ * it large, and it rides inside the FILE. Past the budget it is left out:
+ * the copy then rejoins as a fresh adopt, which loses two-way fork merge and
+ * loses nothing else. A workbook that will not open is a worse outcome than
+ * one that merges coarsely.
+ */
+ stampInto(doc: DashDoc, budget = SYNC_STAMP_BUDGET) {
+ const c = doc.collab as CollabBlock | undefined
+ if (!c || c.on === false) return
+ const state = JSON.parse(JSON.stringify(this.state.toJSON())) as SyncStateJSON
+ const bytes = JSON.stringify(state).length
+ if (bytes > budget) {
+ delete c.sync
+ console.warn(`[bento-sync] sync state is ${(bytes / 1024 / 1024).toFixed(1)} MB — not stamped into the file`)
+ return
+ }
+ c.sync = state
+ }
+
+ // --- plumbing -------------------------------------------------------------
+
+ private send(frame: Frame) {
+ const stamped = { ...frame, pv: SYNC_V }
+ for (const tr of this.transports) tr.send(stamped)
+ }
+
+ private broadcast(frame: Frame) {
+ this.send(frame)
+ }
+}
+
+/**
+ * How much sync state may ride inside the file. The whole columnar encoding
+ * exists to keep a workbook small (4.8 bytes/cell); a sync blob that dwarfs it
+ * would make the format pay for a feature the file does not need to open.
+ */
+export const SYNC_STAMP_BUDGET = 2 * 1024 * 1024
diff --git a/dash/src/viz3d.ts b/dash/src/viz3d.ts
new file mode 100644
index 00000000..115d362f
--- /dev/null
+++ b/dash/src/viz3d.ts
@@ -0,0 +1,1560 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// 3D data visualisation — scatter, surface, bars, globe — on the WebGL2 layer.
+//
+// WHAT WAS ASKED FOR IS THE LOOK, NOT THE LIBRARY. three.js is 600 KB+ against
+// a 43 KB shell, and this project already deleted ECharts at 630 KB and refused
+// DuckDB-WASM at 9.4 MB. But the expensive part of three.js is GENERALITY — a
+// scene graph, a material system, loaders for a dozen formats, a raycaster, a
+// shadow pipeline — and none of it is visible to a reader looking at a scatter
+// plot. FOUR fixed chart types need one camera (gl.ts has it), four geometry
+// builders, and two shaders. That is what is here.
+//
+// buildScene IS PURE, and that is the whole testing strategy. Every bug in 3D
+// geometry renders SOMETHING, plausibly, and no one looking at the screen can
+// tell that a surface is inside out or that a normal is 1.4 long. Geometry is
+// arithmetic, arithmetic runs in node, so all of it lives above the GL line and
+// the rig checks the numbers. Below `mountViz3d` nothing is testable, so that
+// half is kept as boring as it can be.
+//
+// EVERYTHING IS NORMALISED INTO A UNIT CUBE, PER AXIS INDEPENDENTLY. Two
+// reasons, both load-bearing. (1) Attributes are f32: a timestamp in ms or
+// revenue in pence has more significant digits than 24 bits of mantissa, and
+// the plot visibly quantises into rows. (2) Revenue in millions against margin
+// in [0,1] shares one cube only if each axis carries its OWN scale — otherwise
+// the margin axis collapses to a line, which is not a plot of the data, it is a
+// plot of the units. The real numbers live on in `Scene.axes` and the legend.
+//
+// LIGHTING EXISTS ONCE. `shade()` below is the model, and the GLSL in this file
+// is a literal transliteration of it. The 2D fallback shades on the CPU with
+// the same function, so a machine without WebGL2 gets the same picture rather
+// than a different one — two lighting models is a bug that only ever shows up
+// on someone else's laptop. Flat unlit geometry is what makes hand-rolled 3D
+// look amateur; a directional key light plus a hemisphere fill is most of what
+// separates it from three.js, and it costs four lines in a vertex shader.
+//
+// THERE IS NO TRANSPARENCY, DELIBERATELY. Correct alpha needs the geometry
+// sorted back-to-front from the CURRENT camera, which is a sort per orbit frame
+// (100k points, every mouse move) and is STILL wrong for interpenetrating
+// triangles and for anything with a cyclic overlap — the surface passing
+// through its own bar chart is exactly that case. The depth buffer is exact,
+// order-independent and free. So every mesh is opaque, and scatter points are
+// discs cut out with `discard` rather than blended: a marginally harder edge in
+// exchange for depth that is right at any point count.
+//
+// NULLS ARE DROPPED, NEVER ZEROED, and the count is reported. chart.ts's rule
+// (`nulls are gaps, not zeroes`) matters more in 3D, because a missing value
+// coerced to 0 is not an obvious gap in a surface — it is a crater, and craters
+// look like findings.
+//
+// THE FALLBACK IS A PICTURE. `supportsWebGL2()` is false on old iPads, in
+// locked-down enterprise browsers, over remote desktop, and in the shell's own
+// scriptless preview. A workbook that opens to an empty rectangle there is
+// worse than one that never offered 3D at all, so the same Scene is projected
+// with the same camera and the same lighting into an SVG.
+
+import {
+ GLView, Orbit, supportsWebGL2, project,
+ normalize as vnorm, dot as vdot,
+ type Mat4, type Vec3,
+} from './gl.ts'
+import type { TableSheet } from './model.ts'
+import { readCell } from './store.ts'
+import { isErr } from './formula.ts'
+
+// --- colour -----------------------------------------------------------------
+
+/** Channels in 0..1, because that is what a shader wants and what mixing needs. */
+export type RGB = [number, number, number]
+
+const clamp01 = (v: number): number => (v < 0 ? 0 : v > 1 ? 1 : v)
+const clamp = (v: number, lo: number, hi: number): number => (v < lo ? lo : v > hi ? hi : v)
+
+/** An unparseable colour is GREY, not black — black reads as "lit from behind". */
+export function hexToRgb(hex: string): RGB {
+ const s = String(hex).trim().replace(/^#/, '')
+ const full = s.length === 3 ? s[0] + s[0] + s[1] + s[1] + s[2] + s[2] : s.slice(0, 6)
+ const n = parseInt(full, 16)
+ if (full.length < 6 || !Number.isFinite(n)) return [0.5, 0.5, 0.5]
+ return [((n >> 16) & 255) / 255, ((n >> 8) & 255) / 255, (n & 255) / 255]
+}
+
+export const rgbToHex = (c: RGB): string =>
+ '#' + [c[0], c[1], c[2]]
+ .map((v) => Math.round(clamp01(v) * 255).toString(16).padStart(2, '0'))
+ .join('')
+
+/**
+ * Mix in LINEAR light, not in sRGB.
+ *
+ * sRGB is a transfer curve, so the naive midpoint of black and white is 0.5,
+ * which displays as about 21% of the light — every hand-rolled ramp has that
+ * mud in the middle, and on a surface it reads as a band of shadow that is not
+ * in the data. condfmt.mixColors reached the same conclusion for cell
+ * backgrounds; this one works in floats because a vertex colour is a float.
+ */
+export function mixRgb(a: RGB, b: RGB, t: number): RGB {
+ const u = clamp01(t)
+ const m = (x: number, y: number) => Math.sqrt(x * x * (1 - u) + y * y * u)
+ return [m(a[0], b[0]), m(a[1], b[1]), m(a[2], b[2])]
+}
+
+/**
+ * Sequential ramps, all monotonic in lightness. That is not decoration: a ramp
+ * that is not monotonic in lightness (the rainbow) invents ridges where the
+ * data is smooth, and is unreadable to the ~8% of readers with a red/green
+ * deficiency. `balance` is the exception and is diverging on purpose — for a
+ * signed measure, where the MIDDLE is the meaningful value.
+ */
+export const RAMPS: Record<string, string[]> = {
+ viridis: ['#3B1E54', '#3C558C', '#2E8B8B', '#63B36A', '#CFD84A'],
+ thermal: ['#12123A', '#5B2A86', '#C24B6E', '#F08A3C', '#F7E15F'],
+ ice: ['#0B1B33', '#1B4A73', '#3E86A8', '#84C1CD', '#DCEFF2'],
+ balance: ['#2166AC', '#7FB3D3', '#F2F2F0', '#EF9A7B', '#B2182B'],
+}
+
+/**
+ * dash's chart palette, repeated rather than imported: chart.ts keeps it as a
+ * default PARAMETER, so there is nothing to import — and a 3D view that
+ * disagreed with the 2D chart beside it about what colour "North" is would be
+ * its own bug report.
+ */
+export const CATEGORY_COLORS = ['#F7A600', '#5B8DEF', '#2FB47C', '#E1616C', '#8B6FD3', '#3FA9B8']
+
+/**
+ * Sample a ramp at `t` in [0, 1]. The ends are EXACT: `rampColor(0)` is the
+ * first stop and `rampColor(1)` is the last, with no interpolation error, so
+ * the legend's swatches and the extreme vertices are the same colours.
+ */
+export function rampColor(t: number, stops: RGB[]): RGB {
+ if (!stops.length) return [0.5, 0.5, 0.5]
+ if (stops.length === 1) return stops[0]
+ const u = clamp01(Number.isFinite(t) ? t : 0)
+ const x = u * (stops.length - 1)
+ const i = Math.min(stops.length - 2, Math.floor(x))
+ return mixRgb(stops[i], stops[i + 1], x - i)
+}
+
+// --- lighting ---------------------------------------------------------------
+
+/**
+ * The key light, in WORLD space: over the viewer's left shoulder and above.
+ * Fixed to the world, not to the camera, so orbiting a surface changes which
+ * slopes catch the light — a headlight rigidly attached to the eye flattens
+ * everything and is the single clearest tell of hand-rolled 3D.
+ */
+export const LIGHT: Vec3 = vnorm([-0.45, 0.82, 0.55])
+
+/** How much light reaches a surface facing away. Never 0: an unlit face that
+ * goes pure black reads as a hole in the mesh. */
+export const AMBIENT = 0.38
+
+/**
+ * The lighting model, and the ONLY copy of it. The GLSL below is a line-for-line
+ * transliteration, and the SVG fallback calls this directly.
+ *
+ * Lambert for the key, plus a hemisphere fill (`sky`) so the underside of a
+ * surface is dim rather than uniform — with flat ambient, everything facing away
+ * from the light is exactly one colour and the shape disappears into a silhouette.
+ *
+ * `light` is a parameter because the point-sprite path shades in VIEW space,
+ * where the light is the world light run through the view rotation. Same model,
+ * same numbers, different basis.
+ */
+export function shadeWith(n: Vec3, light: Vec3, ambient = AMBIENT): number {
+ const d = Math.max(0, vdot(n, light))
+ const sky = 0.55 + 0.45 * n[1]
+ return Math.min(1, ambient * sky + (1 - ambient) * d)
+}
+
+/** `shadeWith` against the world key light — what a mesh normal wants. */
+export const shade = (n: Vec3, ambient = AMBIENT): number => shadeWith(n, LIGHT, ambient)
+
+/**
+ * A DIRECTION through the view matrix — upper 3x3 only.
+ *
+ * `transformPoint` is wrong here: it adds the translation column, so the light
+ * direction would depend on where the camera IS rather than which way it faces,
+ * and the scene would appear to change its lighting when you pan. Needed
+ * because the point-sprite shader reconstructs its normal in VIEW space.
+ */
+export function dirToView(view: Mat4, d: Vec3): Vec3 {
+ return vnorm([
+ view[0] * d[0] + view[4] * d[1] + view[8] * d[2],
+ view[1] * d[0] + view[5] * d[1] + view[9] * d[2],
+ view[2] * d[0] + view[6] * d[1] + view[10] * d[2],
+ ])
+}
+
+// --- the scene --------------------------------------------------------------
+
+export type Viz3dKind = 'scatter' | 'surface' | 'bars' | 'globe'
+export type Agg = 'sum' | 'avg' | 'count' | 'min' | 'max'
+
+/**
+ * What to draw, from which columns.
+ *
+ * The binding speaks the CHART's language and the scene speaks GL's. For a
+ * surface and for bars that means `z = f(x, y)`: `x` and `y` are the two axes
+ * and `z` is the height — which lands on the scene's Y, because Y is up in GL
+ * and in gl.ts's Orbit. For a scatter there is no remapping; x/y/z are three
+ * spatial axes and map straight through.
+ */
+export interface Viz3dBinding {
+ kind: Viz3dKind
+ /** scatter: the three spatial axes. surface/bars: x and y are the grid axes,
+ * z is the measured value. */
+ x?: string
+ y?: string
+ z?: string
+ /** numeric → ramp; text → categorical palette. */
+ color?: string
+ /** numeric; scatter and globe only. Maps to point AREA, not radius. */
+ size?: string
+ lat?: string
+ lon?: string
+ /** how the value column collapses within one grid cell. Default 'sum'. */
+ agg?: Agg
+ /** target bin count for a numeric grid axis. Default 16. */
+ bins?: number
+ /** a RAMPS key, or explicit hex stops. */
+ ramp?: string | string[]
+}
+
+/**
+ * One draw call's worth of geometry. Typed arrays because that is what goes
+ * into a GPU buffer with no conversion, and because a 100k-point scatter as
+ * plain arrays of objects is 40 MB of garbage per rebuild.
+ */
+export interface Mesh {
+ mode: 'triangles' | 'lines' | 'points'
+ /** xyz per vertex */
+ positions: Float32Array
+ /** rgb per vertex, 0..1 */
+ colors: Float32Array
+ /** UNIT normals, xyz per vertex. Absent on `lines` (unlit) and on `points`
+ * (the sprite shader derives a sphere normal per FRAGMENT — one vertex per
+ * row instead of the ~80 a real sphere would cost). */
+ normals?: Float32Array
+ indices?: Uint32Array
+ /** per-point radius multiplier; `points` only. */
+ sizes?: Float32Array
+ lit: boolean
+ /** closed geometry, so the SVG fallback may cull back faces. False on an open
+ * surface, which must stay visible from below. */
+ cull?: boolean
+}
+
+export interface AxisMeta {
+ title: string
+ kind: 'value' | 'category'
+ min?: number
+ max?: number
+ labels?: string[]
+}
+
+export interface Legend {
+ title: string
+ kind: 'ramp' | 'categories'
+ ramp?: string[]
+ min?: number
+ max?: number
+ items?: Array<{ label: string; color: string }>
+}
+
+export interface Scene {
+ kind: Viz3dKind
+ meshes: Mesh[]
+ bounds: { min: Vec3; max: Vec3 }
+ center: Vec3
+ radius: number
+ axes: AxisMeta[]
+ legend?: Legend
+ /** rows the binding looked at */
+ rows: number
+ /** rows a bound column had no number for. Dropped, and SAID so — a viewer
+ * that quietly plots 4,000 of 5,000 rows is a wrong answer that looks right. */
+ dropped: number
+ /** set when there is nothing to draw, and it says WHY. `mountViz3d` and the
+ * SVG fallback both render this sentence instead of an empty rectangle. */
+ empty?: string
+}
+
+/** `radius` is 1, never 0: a zero-radius scene puts the camera AT the target,
+ * lookAt's forward vector is zero-length, and the matrix is NaN. */
+const emptyScene = (kind: Viz3dKind, why: string, rows = 0): Scene => ({
+ kind,
+ meshes: [],
+ bounds: { min: [0, 0, 0], max: [0, 0, 0] },
+ center: [0, 0, 0],
+ radius: 1,
+ axes: [],
+ rows,
+ dropped: 0,
+ empty: why,
+})
+
+// --- reading the sheet ------------------------------------------------------
+
+/** Never coerces: a blank, a formula error and "n/a" are all `null`, and null
+ * rows are dropped rather than plotted at the origin. */
+const num = (v: unknown): number | null => {
+ if (v == null || v === '' || isErr(v)) return null
+ const n = typeof v === 'number' ? v : Number(String(v).replace(/[,\s£$€¥%]/g, ''))
+ return Number.isFinite(n) ? n : null
+}
+
+const fmtNum = (v: number): string => {
+ if (!Number.isFinite(v)) return ''
+ const a = Math.abs(v)
+ if (a >= 1e6 || (a > 0 && a < 1e-3)) return v.toExponential(2)
+ return String(Math.round(v * 1000) / 1000)
+}
+
+/**
+ * Map finite values onto [-1, 1].
+ *
+ * A ZERO EXTENT MAPS TO 0, not to NaN. One constant column — and a filtered
+ * slice very often has one — would otherwise divide by zero, every position in
+ * the scene becomes NaN, GL draws absolutely nothing, and there is no error
+ * anywhere to explain it.
+ */
+function scaler(vals: Array<number | null>): { lo: number; hi: number; to: (v: number) => number } {
+ let lo = Infinity
+ let hi = -Infinity
+ for (const v of vals) {
+ if (v === null) continue
+ if (v < lo) lo = v
+ if (v > hi) hi = v
+ }
+ if (!Number.isFinite(lo)) { lo = 0; hi = 0 }
+ const span = hi - lo
+ return { lo, hi, to: (v) => (span > 0 ? ((v - lo) / span) * 2 - 1 : 0) }
+}
+
+/** 0..1 within the observed range; a zero range is 0.5 (the middle of the ramp,
+ * which is honest about "every value here is the same"). */
+const norm01 = (v: number, lo: number, hi: number): number =>
+ hi > lo ? clamp01((v - lo) / (hi - lo)) : 0.5
+
+// --- point sizes ------------------------------------------------------------
+
+const SIZE_MIN = 0.62
+const SIZE_MAX = 2.55
+
+/**
+ * Value → point RADIUS, with AREA proportional to the value.
+ *
+ * Mapping the value straight to the radius is the classic bubble-chart
+ * exaggeration: the reader compares the discs by area, so a 4x number drawn at
+ * 4x radius looks 16x. Interpolating in area and taking the root is one `sqrt`
+ * and the difference between a chart and a misrepresentation.
+ */
+const sizeFor = (t: number): number =>
+ Math.sqrt(SIZE_MIN * SIZE_MIN + clamp01(t) * (SIZE_MAX * SIZE_MAX - SIZE_MIN * SIZE_MIN))
+
+// --- grid axes --------------------------------------------------------------
+
+const DEFAULT_BINS = 16
+/** A surface with 200 categories on a side is 80,000 quads nobody can read. */
+const AXIS_MAX_SURFACE = 128
+/** Bars cost 24 vertices each, so their cap is tighter — 64x64 is 98k vertices. */
+const AXIS_MAX_BARS = 64
+
+interface Axis {
+ labels: string[]
+ /** row → bucket index; -1 means this row has no place on this axis. */
+ slot: number[]
+ numeric: boolean
+ min?: number
+ max?: number
+}
+
+/**
+ * Turn a column into an ordered set of buckets.
+ *
+ * ORDER IS THE DECISION HERE. A numeric axis is ASCENDING, because a surface
+ * interpolates between adjacent samples and interpolating between out-of-order
+ * bins draws a shape that is not in the data. A text axis is FIRST-SEEN, the
+ * same rule chart.ts uses, and for the same reason: sorting month names
+ * alphabetically gives Apr, Aug, Dec, and a surface over that is noise.
+ *
+ * Numeric columns with more distinct values than `bins` are binned to equal
+ * width; with fewer, each distinct value is its own slot. The mesh is ORDINAL
+ * (samples are evenly spaced regardless of value) — the labels carry the real
+ * numbers, and for the binned case the two agree exactly.
+ */
+function categorise(vals: unknown[], bins: number, cap: number): Axis {
+ const n = vals.length
+ const nums: Array<number | null> = new Array(n)
+ let numericCount = 0
+ let presentCount = 0
+ for (let i = 0; i < n; i++) {
+ const v = vals[i]
+ const blank = v == null || v === ''
+ if (!blank) presentCount++
+ const x = blank ? null : num(v)
+ nums[i] = x
+ if (x !== null) numericCount++
+ }
+
+ const slot = new Array<number>(n).fill(-1)
+
+ if (presentCount > 0 && numericCount === presentCount) {
+ const uniq = [...new Set(nums.filter((v): v is number => v !== null))].sort((a, b) => a - b)
+ if (uniq.length <= Math.max(2, bins)) {
+ const at = new Map(uniq.map((v, i) => [v, i]))
+ for (let i = 0; i < n; i++) if (nums[i] !== null) slot[i] = at.get(nums[i]!)!
+ return {
+ labels: uniq.map(fmtNum), slot, numeric: true,
+ min: uniq[0], max: uniq[uniq.length - 1],
+ }
+ }
+ const lo = uniq[0]
+ const hi = uniq[uniq.length - 1]
+ const k = Math.min(bins, cap)
+ const w = (hi - lo) / k
+ for (let i = 0; i < n; i++) {
+ const v = nums[i]
+ if (v === null) continue
+ // the top edge belongs to the LAST bin, not to a k+1'th one
+ slot[i] = w > 0 ? Math.min(k - 1, Math.floor((v - lo) / w)) : 0
+ }
+ const labels = Array.from({ length: k }, (_, i) => fmtNum(lo + w * (i + 0.5)))
+ return { labels, slot, numeric: true, min: lo, max: hi }
+ }
+
+ const labels: string[] = []
+ const at = new Map<string, number>()
+ for (let i = 0; i < n; i++) {
+ const v = vals[i]
+ if (v == null || v === '') continue
+ const s = String(v)
+ let k = at.get(s)
+ if (k === undefined) {
+ // past the cap the row is dropped rather than folded into an "other"
+ // bucket: an "other" column on a 3D chart is a bar whose height is an
+ // artefact of the cap, and readers total it.
+ if (labels.length >= cap) continue
+ k = labels.length
+ at.set(s, k)
+ labels.push(s)
+ }
+ slot[i] = k
+ }
+ return { labels, slot, numeric: false }
+}
+
+/** Collapse rows into (nx x ny) cells. `present` is what stops a missing cell
+ * becoming a crater at zero. */
+function aggregateGrid(
+ nx: number, ny: number,
+ sx: number[], sy: number[],
+ zs: Array<number | null> | null,
+ agg: Agg,
+): { v: Float64Array; present: Uint8Array; used: number } {
+ const cells = nx * ny
+ const v = new Float64Array(cells)
+ const count = new Float64Array(cells)
+ const present = new Uint8Array(cells)
+ let used = 0
+ for (let i = 0; i < sx.length; i++) {
+ const a = sx[i]
+ const b = sy[i]
+ if (a < 0 || b < 0) continue
+ const z = zs ? zs[i] : 1
+ if (agg !== 'count' && z === null) continue
+ const c = b * nx + a
+ used++
+ const first = present[c] === 0
+ present[c] = 1
+ count[c]++
+ if (agg === 'count') { v[c] = count[c]; continue }
+ const x = z as number
+ if (first) { v[c] = x; continue }
+ if (agg === 'sum' || agg === 'avg') v[c] += x
+ else if (agg === 'min') v[c] = Math.min(v[c], x)
+ else v[c] = Math.max(v[c], x)
+ }
+ if (agg === 'avg') for (let c = 0; c < cells; c++) if (present[c]) v[c] /= count[c]
+ return { v, present, used }
+}
+
+// --- geometry primitives ----------------------------------------------------
+
+/**
+ * Per-vertex normals by AREA-WEIGHTED accumulation of face normals.
+ *
+ * Area weighting is not a nicety: an un-weighted average lets a sliver triangle
+ * — which a binned grid produces at its edges — pull the normal as hard as the
+ * big quad beside it, and the surface gains a bright seam that is not in the
+ * data. The un-normalised cross product IS twice the area, so the weighting is
+ * free: accumulate it before normalising.
+ *
+ * A vertex with no usable contribution (an isolated point, a degenerate fan)
+ * gets +Y rather than zero. A zero normal shades to pure black, which reads as
+ * a hole in the mesh rather than as the missing information it is.
+ */
+export function computeNormals(positions: Float32Array, indices: Uint32Array): Float32Array {
+ const out = new Float32Array(positions.length)
+ for (let t = 0; t + 2 < indices.length; t += 3) {
+ const ia = indices[t] * 3, ib = indices[t + 1] * 3, ic = indices[t + 2] * 3
+ const ax = positions[ib] - positions[ia]
+ const ay = positions[ib + 1] - positions[ia + 1]
+ const az = positions[ib + 2] - positions[ia + 2]
+ const bx = positions[ic] - positions[ia]
+ const by = positions[ic + 1] - positions[ia + 1]
+ const bz = positions[ic + 2] - positions[ia + 2]
+ const nx = ay * bz - az * by
+ const ny = az * bx - ax * bz
+ const nz = ax * by - ay * bx
+ for (const i of [ia, ib, ic]) {
+ out[i] += nx; out[i + 1] += ny; out[i + 2] += nz
+ }
+ }
+ for (let i = 0; i < out.length; i += 3) {
+ const l = Math.hypot(out[i], out[i + 1], out[i + 2])
+ if (l > 1e-12) { out[i] /= l; out[i + 1] /= l; out[i + 2] /= l }
+ else { out[i] = 0; out[i + 1] = 1; out[i + 2] = 0 }
+ }
+ return out
+}
+
+/** lat/long in DEGREES → a point on a sphere. lon 0 faces +Z and lat +90 is +Y,
+ * matching gl.ts's Orbit (azimuth 0 looks down +Z), so "the camera starts over
+ * the prime meridian" is true rather than approximately true. */
+export function latLonToXyz(lat: number, lon: number, r = 1): Vec3 {
+ const p = (lat * Math.PI) / 180
+ const l = (lon * Math.PI) / 180
+ const c = Math.cos(p)
+ return [r * c * Math.sin(l), r * Math.sin(p), r * c * Math.cos(l)]
+}
+
+/**
+ * A UV sphere. Normals are the normalised POSITIONS — exact by construction,
+ * where computeNormals would only approximate them, and the poles (where a
+ * triangle fan's normals are least reliable) are the part of a globe people
+ * look at first.
+ *
+ * The seam column is duplicated so the grid is rectangular; the degenerate
+ * triangles at each pole are skipped rather than emitted zero-area, because a
+ * zero-area triangle contributes nothing but still costs a vertex fetch.
+ */
+function sphereMesh(r: number, segU: number, segV: number): {
+ positions: Float32Array; normals: Float32Array; indices: Uint32Array
+} {
+ const cols = segU + 1
+ const rows = segV + 1
+ const positions = new Float32Array(cols * rows * 3)
+ const normals = new Float32Array(cols * rows * 3)
+ for (let j = 0; j < rows; j++) {
+ const lat = 90 - (180 * j) / segV
+ for (let i = 0; i < cols; i++) {
+ const lon = -180 + (360 * i) / segU
+ const p = latLonToXyz(lat, lon, r)
+ const k = (j * cols + i) * 3
+ positions[k] = p[0]; positions[k + 1] = p[1]; positions[k + 2] = p[2]
+ normals[k] = p[0] / r; normals[k + 1] = p[1] / r; normals[k + 2] = p[2] / r
+ }
+ }
+ const idx: number[] = []
+ for (let j = 0; j < segV; j++) {
+ for (let i = 0; i < segU; i++) {
+ const a = j * cols + i, b = a + 1, c = a + cols, d = c + 1
+ if (j !== 0) idx.push(a, c, b)
+ if (j !== segV - 1) idx.push(b, c, d)
+ }
+ }
+ return { positions, normals, indices: new Uint32Array(idx) }
+}
+
+/** The six faces of an axis-aligned box, wound counter-clockwise from OUTSIDE
+ * and carrying their own normals. Flat shading is CORRECT for a box, so these
+ * are NOT run through computeNormals — smoothed box corners look like melted
+ * wax, which is a different failure from an unlit one but just as visible. */
+const BOX_FACES: Array<{ n: Vec3; c: Array<[number, number, number]> }> = [
+ { n: [1, 0, 0], c: [[1, 0, 1], [1, 0, 0], [1, 1, 0], [1, 1, 1]] },
+ { n: [-1, 0, 0], c: [[0, 0, 0], [0, 0, 1], [0, 1, 1], [0, 1, 0]] },
+ { n: [0, 0, 1], c: [[0, 0, 1], [1, 0, 1], [1, 1, 1], [0, 1, 1]] },
+ { n: [0, 0, -1], c: [[1, 0, 0], [0, 0, 0], [0, 1, 0], [1, 1, 0]] },
+ { n: [0, 1, 0], c: [[0, 1, 1], [1, 1, 1], [1, 1, 0], [0, 1, 0]] },
+ { n: [0, -1, 0], c: [[0, 0, 0], [1, 0, 0], [1, 0, 1], [0, 0, 1]] },
+]
+
+const FRAME_RGB: RGB = [0.42, 0.47, 0.56]
+const FRAME_GRID = 4
+
+/**
+ * The bounding box and floor grid.
+ *
+ * Not decoration: a perspective projection of unlabelled points has no scale
+ * cue at all, and readers systematically misjudge depth without a reference
+ * plane. Fifty vertices buys the whole depth read.
+ */
+function frameMesh(min: Vec3, max: Vec3): Mesh {
+ const pos: number[] = []
+ const col: number[] = []
+ const seg = (a: Vec3, b: Vec3, k: number) => {
+ pos.push(a[0], a[1], a[2], b[0], b[1], b[2])
+ for (let i = 0; i < 2; i++) col.push(FRAME_RGB[0] * k, FRAME_RGB[1] * k, FRAME_RGB[2] * k)
+ }
+ const [x0, y0, z0] = min
+ const [x1, y1, z1] = max
+ const corners: Vec3[] = [
+ [x0, y0, z0], [x1, y0, z0], [x1, y0, z1], [x0, y0, z1],
+ [x0, y1, z0], [x1, y1, z0], [x1, y1, z1], [x0, y1, z1],
+ ]
+ const edges = [[0, 1], [1, 2], [2, 3], [3, 0], [4, 5], [5, 6], [6, 7], [7, 4], [0, 4], [1, 5], [2, 6], [3, 7]]
+ for (const [a, b] of edges) seg(corners[a], corners[b], 1)
+ for (let i = 1; i < FRAME_GRID; i++) {
+ const t = i / FRAME_GRID
+ seg([x0 + (x1 - x0) * t, y0, z0], [x0 + (x1 - x0) * t, y0, z1], 0.5)
+ seg([x0, y0, z0 + (z1 - z0) * t], [x1, y0, z0 + (z1 - z0) * t], 0.5)
+ }
+ return {
+ mode: 'lines',
+ positions: new Float32Array(pos),
+ colors: new Float32Array(col),
+ lit: false,
+ }
+}
+
+function boundsOf(meshes: Mesh[]): { min: Vec3; max: Vec3 } {
+ const min: Vec3 = [Infinity, Infinity, Infinity]
+ const max: Vec3 = [-Infinity, -Infinity, -Infinity]
+ for (const m of meshes) {
+ const p = m.positions
+ for (let i = 0; i + 2 < p.length; i += 3) {
+ for (let k = 0; k < 3; k++) {
+ const v = p[i + k]
+ if (!Number.isFinite(v)) continue
+ if (v < min[k]) min[k] = v
+ if (v > max[k]) max[k] = v
+ }
+ }
+ }
+ for (let k = 0; k < 3; k++) {
+ if (!Number.isFinite(min[k])) { min[k] = 0; max[k] = 0 }
+ }
+ return { min, max }
+}
+
+function finish(kind: Viz3dKind, data: Mesh[], extra: Mesh[], rest: {
+ axes: AxisMeta[]; legend?: Legend; rows: number; dropped: number
+}): Scene {
+ const bounds = boundsOf(data)
+ const center: Vec3 = [
+ (bounds.min[0] + bounds.max[0]) / 2,
+ (bounds.min[1] + bounds.max[1]) / 2,
+ (bounds.min[2] + bounds.max[2]) / 2,
+ ]
+ const radius = Math.max(
+ 0.5,
+ 0.5 * Math.hypot(bounds.max[0] - bounds.min[0], bounds.max[1] - bounds.min[1], bounds.max[2] - bounds.min[2]),
+ )
+ return { kind, meshes: [...data, ...extra], bounds, center, radius, ...rest }
+}
+
+// --- buildScene -------------------------------------------------------------
+
+const rampOf = (b: Viz3dBinding): { hex: string[]; rgb: RGB[] } => {
+ const hex = (Array.isArray(b.ramp) ? b.ramp : RAMPS[b.ramp ?? 'viridis']) ?? RAMPS.viridis
+ return { hex, rgb: hex.map(hexToRgb) }
+}
+
+/**
+ * Columns → geometry. PURE: no canvas, no document, no GL — which is what lets
+ * the rig check the vertex counts, the winding and the normals in node.
+ *
+ * `computed` is chart.ts's contract, unchanged: the grid hands in what it just
+ * recalculated so a formula column plots the numbers the reader is looking at
+ * rather than the raw column underneath them.
+ */
+export function buildScene(
+ sheet: TableSheet,
+ binding: Viz3dBinding,
+ computed?: Map<string, unknown[]>,
+): Scene {
+ const rows = sheet.rids.reduce((a, [, c]) => a + c, 0)
+ if (rows === 0) return emptyScene(binding.kind, 'this sheet has no rows yet')
+
+ const nameOf = (id?: string): string =>
+ id ? (sheet.columns.find((c) => c.id === id)?.name ?? id) : ''
+ const col = (id?: string): unknown[] | null => {
+ if (!id) return null
+ const c = computed?.get(id)
+ if (c) return c
+ const d = sheet.data[id]
+ if (!d) return null
+ return Array.from({ length: rows }, (_, i) => readCell(d, i))
+ }
+
+ switch (binding.kind) {
+ case 'globe': return buildGlobe(binding, rows, col, nameOf)
+ case 'surface': return buildGrid(binding, rows, col, nameOf, true)
+ case 'bars': return buildGrid(binding, rows, col, nameOf, false)
+ default: return buildScatter(binding, rows, col, nameOf)
+ }
+}
+
+type ColFn = (id?: string) => unknown[] | null
+type NameFn = (id?: string) => string
+
+function buildScatter(b: Viz3dBinding, rows: number, col: ColFn, nameOf: NameFn): Scene {
+ const cx = col(b.x), cy = col(b.y), cz = col(b.z)
+ if (!cx || !cy || !cz) {
+ return emptyScene('scatter', 'a 3D scatter needs three numeric columns — pick X, Y and Z', rows)
+ }
+ const xs = cx.map(num), ys = cy.map(num), zs = cz.map(num)
+
+ const cc = col(b.color)
+ const cNums = cc ? cc.map(num) : null
+ // A colour column is NUMERIC only if every value present in it is a number;
+ // one stray "n/a" must not silently turn a category axis into a ramp of NaN.
+ const colourNumeric = !!cNums && cc!.some((v, i) => v != null && v !== '' && cNums[i] !== null)
+ && cc!.every((v, i) => v == null || v === '' || cNums![i] !== null)
+ const sc = col(b.size)
+ const sNums = sc ? sc.map(num) : null
+
+ const keep: number[] = []
+ for (let i = 0; i < rows; i++) if (xs[i] !== null && ys[i] !== null && zs[i] !== null) keep.push(i)
+ if (!keep.length) {
+ return emptyScene('scatter', 'no row has a number in all three of X, Y and Z', rows)
+ }
+
+ const sx = scaler(xs), sy = scaler(ys), sz = scaler(zs)
+ const ramp = rampOf(b)
+
+ // Categorical colour: first-seen order, so the 3D view and the 2D chart agree
+ // about which category is which colour.
+ const catAt = new Map<string, number>()
+ const catLabels: string[] = []
+ if (cc && !colourNumeric) {
+ for (const i of keep) {
+ const v = cc[i]
+ if (v == null || v === '') continue
+ const s = String(v)
+ if (!catAt.has(s)) { catAt.set(s, catAt.size); catLabels.push(s) }
+ }
+ }
+ const cScale = colourNumeric ? scaler(cNums!) : null
+ const sScale = sNums ? scaler(sNums) : null
+
+ const positions = new Float32Array(keep.length * 3)
+ const colors = new Float32Array(keep.length * 3)
+ const sizes = new Float32Array(keep.length)
+ keep.forEach((row, k) => {
+ positions[k * 3] = sx.to(xs[row]!)
+ positions[k * 3 + 1] = sy.to(ys[row]!)
+ positions[k * 3 + 2] = sz.to(zs[row]!)
+ let rgb: RGB
+ if (cScale) rgb = rampColor(norm01(cNums![row] ?? cScale.lo, cScale.lo, cScale.hi), ramp.rgb)
+ else if (cc) {
+ const s = cc[row] == null ? '' : String(cc[row])
+ const j = catAt.get(s)
+ rgb = hexToRgb(j === undefined ? '#8A93A5' : CATEGORY_COLORS[j % CATEGORY_COLORS.length])
+ } else {
+ // No colour column: ramp over Z anyway. A monochrome cloud in perspective
+ // has no depth cue at all beyond point size, and the ramp is free.
+ rgb = rampColor(norm01(zs[row]!, sz.lo, sz.hi), ramp.rgb)
+ }
+ colors[k * 3] = rgb[0]; colors[k * 3 + 1] = rgb[1]; colors[k * 3 + 2] = rgb[2]
+ const sv = sScale && sNums![row] !== null ? norm01(sNums![row]!, sScale.lo, sScale.hi) : 0.42
+ sizes[k] = sizeFor(sv)
+ })
+
+ const data: Mesh[] = [{ mode: 'points', positions, colors, sizes, lit: true }]
+ const legend: Legend = cScale
+ ? { title: nameOf(b.color), kind: 'ramp', ramp: ramp.hex, min: cScale.lo, max: cScale.hi }
+ : cc
+ ? {
+ title: nameOf(b.color), kind: 'categories',
+ items: catLabels.slice(0, 8).map((l, i) => ({ label: l, color: CATEGORY_COLORS[i % CATEGORY_COLORS.length] })),
+ }
+ : { title: nameOf(b.z), kind: 'ramp', ramp: ramp.hex, min: sz.lo, max: sz.hi }
+
+ const bounds = boundsOf(data)
+ return finish('scatter', data, [frameMesh(bounds.min, bounds.max)], {
+ axes: [
+ { title: nameOf(b.x), kind: 'value', min: sx.lo, max: sx.hi },
+ { title: nameOf(b.y), kind: 'value', min: sy.lo, max: sy.hi },
+ { title: nameOf(b.z), kind: 'value', min: sz.lo, max: sz.hi },
+ ],
+ legend,
+ rows,
+ dropped: rows - keep.length,
+ })
+}
+
+function buildGrid(b: Viz3dBinding, rows: number, col: ColFn, nameOf: NameFn, surface: boolean): Scene {
+ const kind: Viz3dKind = surface ? 'surface' : 'bars'
+ const cx = col(b.x), cy = col(b.y)
+ /**
+ * A SURFACE DEFAULTS TO AVERAGE AND BARS TO SUM, and that is not a taste.
+ *
+ * A surface is a FIELD — `z = f(x, y)` sampled at points — so a cell holding
+ * two samples must report what the field is worth there, not their total.
+ * Summing makes the height depend on SAMPLING DENSITY: bin 40 evenly-spaced x
+ * values into 24 bins and some bins take two samples and some one, so a
+ * perfectly smooth field renders as a comb of spikes with a period set by the
+ * binning. Caught by looking at a `sin(r)/r` surface, which should be smooth
+ * and was not.
+ *
+ * A bar is a TOTAL — revenue by region and quarter — and summing is what
+ * anyone reading it means. The two defaults are opposite because the two
+ * charts are answering opposite questions.
+ */
+ const agg = b.agg ?? (surface ? 'avg' : 'sum')
+ const cz = col(b.z)
+ if (!cx || !cy || (!cz && agg !== 'count')) {
+ return emptyScene(kind, `${surface ? 'a surface' : '3D bars'} needs two axis columns and a value column`, rows)
+ }
+ const cap = surface ? AXIS_MAX_SURFACE : AXIS_MAX_BARS
+ const bins = Math.max(2, Math.min(cap, b.bins ?? DEFAULT_BINS))
+ const ax = categorise(cx, bins, cap)
+ const ay = categorise(cy, bins, cap)
+ const nx = ax.labels.length
+ const ny = ay.labels.length
+ if (nx < 1 || ny < 1) return emptyScene(kind, 'the axis columns are empty', rows)
+ if (surface && (nx < 2 || ny < 2)) {
+ // One row or one column of samples is a line, not a surface, and the quad
+ // loop would emit nothing at all — say so rather than draw an empty box.
+ return emptyScene(kind, 'a surface needs at least two distinct values on each axis', rows)
+ }
+
+ const zs = cz ? cz.map(num) : null
+ const g = aggregateGrid(nx, ny, ax.slot, ay.slot, zs, agg)
+ if (!g.used) return emptyScene(kind, 'no row falls on both axes with a value', rows)
+
+ const present: Array<number | null> = []
+ for (let c = 0; c < nx * ny; c++) present.push(g.present[c] ? g.v[c] : null)
+ const vs = scaler(present)
+ const ramp = rampOf(b)
+ const at = (i: number, n: number) => (n > 1 ? (i / (n - 1)) * 2 - 1 : 0)
+
+ const data: Mesh[] = []
+ if (surface) {
+ const positions = new Float32Array(nx * ny * 3)
+ const colors = new Float32Array(nx * ny * 3)
+ for (let j = 0; j < ny; j++) {
+ for (let i = 0; i < nx; i++) {
+ const c = j * nx + i
+ const k = c * 3
+ const v = g.present[c] ? g.v[c] : vs.lo
+ positions[k] = at(i, nx)
+ positions[k + 1] = vs.to(v)
+ positions[k + 2] = at(j, ny)
+ const rgb = rampColor(norm01(v, vs.lo, vs.hi), ramp.rgb)
+ colors[k] = rgb[0]; colors[k + 1] = rgb[1]; colors[k + 2] = rgb[2]
+ }
+ }
+ // A quad is emitted only when all FOUR corners were measured. Interpolating
+ // across a gap invents a value, and on a surface an invented value is
+ // indistinguishable from a measured one.
+ const idx: number[] = []
+ for (let j = 0; j + 1 < ny; j++) {
+ for (let i = 0; i + 1 < nx; i++) {
+ const a = j * nx + i, bb = a + 1, c = a + nx, d = c + 1
+ if (!(g.present[a] && g.present[bb] && g.present[c] && g.present[d])) continue
+ // wound so the face normal is +Y (see the note on BOX_FACES)
+ idx.push(a, c, bb, bb, c, d)
+ }
+ }
+ const indices = new Uint32Array(idx)
+ data.push({
+ mode: 'triangles', positions, colors, indices,
+ normals: computeNormals(positions, indices), lit: true, cull: false,
+ })
+ } else {
+ // Bars start at ZERO. A bar's LENGTH is the value, so a truncated axis is a
+ // lie rather than a zoom — the one chart where that is unambiguous.
+ const span = Math.max(Math.abs(vs.lo), Math.abs(vs.hi))
+ const yk = span > 0 ? 1 / span : 0
+ const cells: number[] = []
+ for (let c = 0; c < nx * ny; c++) if (g.present[c]) cells.push(c)
+ const positions = new Float32Array(cells.length * 24 * 3)
+ const normals = new Float32Array(cells.length * 24 * 3)
+ const colors = new Float32Array(cells.length * 24 * 3)
+ const indices = new Uint32Array(cells.length * 36)
+ const wx = (nx > 1 ? 2 / (nx - 1) : 1) * 0.36
+ const wz = (ny > 1 ? 2 / (ny - 1) : 1) * 0.36
+ cells.forEach((c, bi) => {
+ const i = c % nx, j = (c / nx) | 0
+ const v = g.v[c] * yk
+ const x0 = at(i, nx) - wx, x1 = at(i, nx) + wx
+ const z0 = at(j, ny) - wz, z1 = at(j, ny) + wz
+ const y0 = Math.min(0, v), y1 = Math.max(0, v)
+ const rgb = rampColor(norm01(g.v[c], vs.lo, vs.hi), ramp.rgb)
+ let vi = bi * 24
+ let ii = bi * 36
+ for (const face of BOX_FACES) {
+ const base = vi
+ for (const [fx, fy, fz] of face.c) {
+ const k = vi * 3
+ positions[k] = fx ? x1 : x0
+ positions[k + 1] = fy ? y1 : y0
+ positions[k + 2] = fz ? z1 : z0
+ normals[k] = face.n[0]; normals[k + 1] = face.n[1]; normals[k + 2] = face.n[2]
+ colors[k] = rgb[0]; colors[k + 1] = rgb[1]; colors[k + 2] = rgb[2]
+ vi++
+ }
+ indices[ii++] = base; indices[ii++] = base + 1; indices[ii++] = base + 2
+ indices[ii++] = base; indices[ii++] = base + 2; indices[ii++] = base + 3
+ }
+ })
+ data.push({ mode: 'triangles', positions, colors, normals, indices, lit: true, cull: true })
+ }
+
+ const bounds = boundsOf(data)
+ return finish(kind, data, [frameMesh(
+ [Math.min(-1, bounds.min[0]), bounds.min[1], Math.min(-1, bounds.min[2])],
+ [Math.max(1, bounds.max[0]), bounds.max[1], Math.max(1, bounds.max[2])],
+ )], {
+ axes: [
+ { title: nameOf(b.x), kind: ax.numeric ? 'value' : 'category', min: ax.min, max: ax.max, labels: ax.labels },
+ { title: nameOf(b.y), kind: ay.numeric ? 'value' : 'category', min: ay.min, max: ay.max, labels: ay.labels },
+ { title: agg === 'count' ? 'count' : `${agg} of ${nameOf(b.z)}`, kind: 'value', min: vs.lo, max: vs.hi },
+ ],
+ legend: { title: agg === 'count' ? 'count' : nameOf(b.z), kind: 'ramp', ramp: ramp.hex, min: vs.lo, max: vs.hi },
+ rows,
+ // rows that fell off an axis (blank, unparseable, or past the category cap)
+ dropped: rows - g.used,
+ })
+}
+
+const GLOBE_R = 1
+/** Points sit just off the surface. Exactly ON it z-fights: the depth buffer
+ * cannot separate two surfaces at the same depth and the dots flicker as the
+ * camera moves, which reads as a rendering fault rather than as data. */
+const GLOBE_LIFT = 1.012
+
+function buildGlobe(b: Viz3dBinding, rows: number, col: ColFn, nameOf: NameFn): Scene {
+ const clat = col(b.lat), clon = col(b.lon)
+ if (!clat || !clon) return emptyScene('globe', 'a globe needs a latitude and a longitude column', rows)
+ const lats = clat.map(num)
+ const lons = clon.map(num)
+
+ const keep: number[] = []
+ for (let i = 0; i < rows; i++) {
+ const la = lats[i], lo = lons[i]
+ // Out-of-range values are REFUSED, not wrapped. A column that is not really
+ // a latitude (a row number, a temperature) otherwise paints a confident
+ // band of dots across the equator and nothing says the binding is wrong.
+ if (la === null || lo === null) continue
+ if (la < -90 || la > 90 || lo < -180 || lo > 180) continue
+ keep.push(i)
+ }
+
+ const ramp = rampOf(b)
+ const cc = col(b.color)
+ const cNums = cc ? cc.map(num) : null
+ const colourNumeric = !!cNums && cc!.some((v, i) => v != null && v !== '' && cNums[i] !== null)
+ && cc!.every((v, i) => v == null || v === '' || cNums![i] !== null)
+ const cScale = colourNumeric ? scaler(cNums!) : null
+ const sc = col(b.size)
+ const sNums = sc ? sc.map(num) : null
+ const sScale = sNums ? scaler(sNums) : null
+ const catAt = new Map<string, number>()
+ const catLabels: string[] = []
+ if (cc && !colourNumeric) {
+ for (const i of keep) {
+ const s = cc[i] == null ? '' : String(cc[i])
+ if (s && !catAt.has(s)) { catAt.set(s, catAt.size); catLabels.push(s) }
+ }
+ }
+
+ const sphere = sphereMesh(GLOBE_R, 48, 24)
+ const ocean: RGB = [0.13, 0.22, 0.34]
+ const sphereColors = new Float32Array(sphere.positions.length)
+ for (let i = 0; i < sphereColors.length; i += 3) {
+ sphereColors[i] = ocean[0]; sphereColors[i + 1] = ocean[1]; sphereColors[i + 2] = ocean[2]
+ }
+ const meshes: Mesh[] = [{
+ mode: 'triangles',
+ positions: sphere.positions,
+ normals: sphere.normals,
+ colors: sphereColors,
+ indices: sphere.indices,
+ lit: true,
+ cull: true,
+ }, graticule()]
+
+ if (keep.length) {
+ const positions = new Float32Array(keep.length * 3)
+ const colors = new Float32Array(keep.length * 3)
+ const sizes = new Float32Array(keep.length)
+ keep.forEach((row, k) => {
+ const p = latLonToXyz(lats[row]!, lons[row]!, GLOBE_R * GLOBE_LIFT)
+ positions[k * 3] = p[0]; positions[k * 3 + 1] = p[1]; positions[k * 3 + 2] = p[2]
+ let rgb: RGB
+ if (cScale) rgb = rampColor(norm01(cNums![row] ?? cScale.lo, cScale.lo, cScale.hi), ramp.rgb)
+ else if (cc) {
+ const j = catAt.get(cc[row] == null ? '' : String(cc[row]))
+ rgb = hexToRgb(j === undefined ? '#F7A600' : CATEGORY_COLORS[j % CATEGORY_COLORS.length])
+ } else rgb = hexToRgb('#F7A600')
+ colors[k * 3] = rgb[0]; colors[k * 3 + 1] = rgb[1]; colors[k * 3 + 2] = rgb[2]
+ const sv = sScale && sNums![row] !== null ? norm01(sNums![row]!, sScale.lo, sScale.hi) : 0.35
+ sizes[k] = sizeFor(sv)
+ })
+ meshes.push({ mode: 'points', positions, colors, sizes, lit: true })
+ }
+
+ const legend: Legend | undefined = cScale
+ ? { title: nameOf(b.color), kind: 'ramp', ramp: ramp.hex, min: cScale.lo, max: cScale.hi }
+ : catLabels.length
+ ? {
+ title: nameOf(b.color), kind: 'categories',
+ items: catLabels.slice(0, 8).map((l, i) => ({ label: l, color: CATEGORY_COLORS[i % CATEGORY_COLORS.length] })),
+ }
+ : undefined
+
+ return finish('globe', meshes, [], {
+ axes: [
+ { title: nameOf(b.lat), kind: 'value', min: -90, max: 90 },
+ { title: nameOf(b.lon), kind: 'value', min: -180, max: 180 },
+ ],
+ legend,
+ rows,
+ dropped: rows - keep.length,
+ })
+}
+
+/** Meridians and parallels every 30°. The graticule is what makes a sphere read
+ * as a rotating globe rather than as a flat lit disc — a smooth shaded sphere
+ * has no features, so nothing on screen moves when the camera does. */
+function graticule(): Mesh {
+ const pos: number[] = []
+ const col: number[] = []
+ const c: RGB = [0.38, 0.52, 0.62]
+ const r = GLOBE_R * 1.003
+ const push = (a: Vec3, b: Vec3) => {
+ pos.push(a[0], a[1], a[2], b[0], b[1], b[2])
+ for (let i = 0; i < 2; i++) col.push(c[0], c[1], c[2])
+ }
+ for (let lon = -180; lon < 180; lon += 30) {
+ for (let lat = -90; lat < 90; lat += 10) {
+ push(latLonToXyz(lat, lon, r), latLonToXyz(lat + 10, lon, r))
+ }
+ }
+ for (const lat of [-60, -30, 0, 30, 60]) {
+ for (let lon = -180; lon < 180; lon += 10) {
+ push(latLonToXyz(lat, lon, r), latLonToXyz(lat, lon + 10, r))
+ }
+ }
+ return { mode: 'lines', positions: new Float32Array(pos), colors: new Float32Array(col), lit: false }
+}
+
+/**
+ * A binding that needs no configuration, so the first 3D view takes one click.
+ * Mirrors chart.ts's defaultBinding in spirit: prefer the view the columns are
+ * actually shaped for, and return null rather than force one that is wrong.
+ */
+export function defaultViz3d(sheet: TableSheet): Viz3dBinding | null {
+ const numeric = sheet.columns.filter((c) => c.type === 'number' || c.type === 'money' || c.type === 'percent')
+ const cat = sheet.columns.filter((c) => c.type === 'text' || c.type === 'enum' || c.type === 'date')
+ const find = (re: RegExp) => numeric.find((c) => re.test(c.name) || re.test(c.id))
+ // `\b` matters: without it "platform" is a latitude column.
+ const lat = find(/^lat(itude)?$/i) ?? find(/\blat/i)
+ const lon = find(/^(lon|lng|long(itude)?)$/i) ?? find(/\b(lon|lng)/i)
+ if (lat && lon && lat.id !== lon.id) {
+ return { kind: 'globe', lat: lat.id, lon: lon.id, color: numeric.find((c) => c.id !== lat.id && c.id !== lon.id)?.id }
+ }
+ if (numeric.length >= 3) {
+ return {
+ kind: 'scatter',
+ x: numeric[0].id, y: numeric[1].id, z: numeric[2].id,
+ color: numeric[3]?.id ?? cat[0]?.id,
+ size: numeric[4]?.id,
+ }
+ }
+ if (cat.length >= 2 && numeric.length >= 1) {
+ return { kind: 'bars', x: cat[0].id, y: cat[1].id, z: numeric[0].id, agg: 'sum' }
+ }
+ return null
+}
+
+// --- the 2D fallback --------------------------------------------------------
+
+/** Past this the SVG is slower to lay out than the data is worth, so triangle
+ * meshes degrade to their VERTICES as dots. A half-resolution mesh would be
+ * worse: striding triangles punches holes in the surface, and a surface with
+ * holes reads as missing data. */
+const SVG_MAX_TRIS = 9000
+const SVG_MAX_POINTS = 4000
+
+const esc = (s: string): string =>
+ String(s).replace(/[&<>"]/g, (c) => (c === '&' ? '&amp;' : c === '<' ? '&lt;' : c === '>' ? '&gt;' : '&quot;'))
+
+export interface FallbackOpts {
+ /** reuse a live camera, so dragging the fallback works exactly like dragging GL */
+ camera?: Orbit
+ azimuth?: number
+ elevation?: number
+ background?: string
+ ink?: string
+}
+
+/** Frame a scene: far enough back that the bounding sphere fits the vertical fov. */
+export function frameCamera(scene: Scene, opts: { azimuth?: number; elevation?: number } = {}): Orbit {
+ const o = new Orbit()
+ o.target = [...scene.center] as Vec3
+ o.fovY = Math.PI / 4
+ o.distance = Math.max(0.6, scene.radius / Math.sin(o.fovY / 2)) * 0.85
+ o.minDistance = scene.radius * 0.15
+ o.maxDistance = scene.radius * 40
+ o.azimuth = opts.azimuth ?? 0.72
+ o.elevation = opts.elevation ?? 0.46
+ o.near = Math.max(0.01, scene.radius / 200)
+ o.far = scene.radius * 80
+ return o
+}
+
+/**
+ * The same scene, the same camera and the same lighting, projected into SVG.
+ *
+ * PAINTER'S ALGORITHM: every primitive is emitted in one list sorted far-to-near
+ * by centroid depth. That is exact for convex closed geometry (the globe, a
+ * bar) and correct in practice for a heightfield; it is WRONG for two triangles
+ * that interpenetrate, which the depth buffer would resolve per-pixel. Accepted,
+ * because the alternative on this path is a software rasteriser.
+ *
+ * Returns a STRING so it is testable in node — the whole reason the fallback is
+ * checkable at all.
+ */
+export function fallbackSvg(scene: Scene, w = 640, h = 420, opts: FallbackOpts = {}): string {
+ const bg = opts.background ?? '#0E1420'
+ const ink = opts.ink ?? '#C7D0DE'
+ const head = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}" width="100%" height="100%" ` +
+ `role="img" aria-label="${esc(scene.empty ?? `3D ${scene.kind}`)}" style="display:block">` +
+ `<rect width="${w}" height="${h}" fill="${esc(bg)}"/>`
+ const tail = '</svg>'
+
+ if (scene.empty || !scene.meshes.length) {
+ // NOT a blank box: the sentence is the point. A reader on a machine without
+ // WebGL2 must learn that the view exists and why it is not showing data.
+ return head +
+ `<text x="${w / 2}" y="${h / 2}" fill="${esc(ink)}" font-family="system-ui,sans-serif" ` +
+ `font-size="14" text-anchor="middle" opacity="0.85">${esc(scene.empty ?? 'nothing to draw')}</text>` +
+ tail
+ }
+
+ const cam = opts.camera ?? frameCamera(scene, opts)
+ const vp = cam.matrix(w / Math.max(1, h))
+
+ let tris = 0
+ for (const m of scene.meshes) {
+ if (m.mode === 'triangles') tris += (m.indices ? m.indices.length : m.positions.length / 3) / 3
+ }
+ const dots = tris > SVG_MAX_TRIS
+
+ const prims: Array<{ z: number; s: string }> = []
+ const px = (i: number, p: Float32Array) => project(vp, [p[i], p[i + 1], p[i + 2]], w, h)
+ const hex = (r: number, g: number, b: number, k: number): string =>
+ rgbToHex([r * k, g * k, b * k])
+
+ for (const m of scene.meshes) {
+ const p = m.positions
+ const c = m.colors
+ if (m.mode === 'triangles' && !dots) {
+ const idx = m.indices ?? new Uint32Array(Array.from({ length: p.length / 3 }, (_, i) => i))
+ for (let t = 0; t + 2 < idx.length; t += 3) {
+ const a = idx[t] * 3, b = idx[t + 1] * 3, d = idx[t + 2] * 3
+ const pa = px(a, p), pb = px(b, p), pd = px(d, p)
+ if (!(Number.isFinite(pa.x) && Number.isFinite(pb.x) && Number.isFinite(pd.x))) continue
+ if (pa.z > 1 || pb.z > 1 || pd.z > 1) continue // behind the eye, or past the far plane
+ if (m.cull) {
+ // screen-space signed area; y is flipped, so a front face is negative
+ const area = (pb.x - pa.x) * (pd.y - pa.y) - (pd.x - pa.x) * (pb.y - pa.y)
+ if (area > 0) continue
+ }
+ // FACE normal, not the interpolated vertex normals: SVG cannot shade a
+ // gradient across a polygon, so flat-per-triangle is the honest choice
+ // and a fine enough mesh looks smooth anyway.
+ const nx0 = p[b] - p[a], ny0 = p[b + 1] - p[a + 1], nz0 = p[b + 2] - p[a + 2]
+ const nx1 = p[d] - p[a], ny1 = p[d + 1] - p[a + 1], nz1 = p[d + 2] - p[a + 2]
+ let n: Vec3 = vnorm([
+ ny0 * nz1 - nz0 * ny1,
+ nz0 * nx1 - nx0 * nz1,
+ nx0 * ny1 - ny0 * nx1,
+ ])
+ // A back-facing normal on an OPEN surface is the underside; light it as
+ // if it faced us rather than painting it black.
+ if (!m.cull && m.normals) {
+ const dotv = n[0] * m.normals[a] + n[1] * m.normals[a + 1] + n[2] * m.normals[a + 2]
+ if (dotv < 0) n = [-n[0], -n[1], -n[2]]
+ }
+ const k = m.lit ? shade(n) : 1
+ const fill = hex((c[a] + c[b] + c[d]) / 3, (c[a + 1] + c[b + 1] + c[d + 1]) / 3, (c[a + 2] + c[b + 2] + c[d + 2]) / 3, k)
+ prims.push({
+ z: (pa.z + pb.z + pd.z) / 3,
+ s: `<polygon points="${pa.x.toFixed(1)},${pa.y.toFixed(1)} ${pb.x.toFixed(1)},${pb.y.toFixed(1)} ${pd.x.toFixed(1)},${pd.y.toFixed(1)}" fill="${fill}"/>`,
+ })
+ }
+ continue
+ }
+ if (m.mode === 'lines') {
+ for (let i = 0; i + 5 < p.length; i += 6) {
+ const pa = px(i, p), pb = px(i + 3, p)
+ if (!Number.isFinite(pa.x) || !Number.isFinite(pb.x) || pa.z > 1 || pb.z > 1) continue
+ prims.push({
+ z: (pa.z + pb.z) / 2,
+ s: `<line x1="${pa.x.toFixed(1)}" y1="${pa.y.toFixed(1)}" x2="${pb.x.toFixed(1)}" y2="${pb.y.toFixed(1)}" stroke="${hex(c[i], c[i + 1], c[i + 2], 1)}" stroke-width="1" opacity="0.75"/>`,
+ })
+ }
+ continue
+ }
+ // points, and triangle meshes degraded to their vertices
+ const count = p.length / 3
+ const stride = Math.max(1, Math.ceil(count / SVG_MAX_POINTS))
+ // world radius → pixels, the same formula the point shader uses
+ const scale = ((0.5 * h) / Math.tan(cam.fovY / 2)) * (scene.radius * 0.022)
+ // A sprite always faces the camera, so its CENTRE normal is +Z in view
+ // space; SVG cannot vary shading across a circle, so one value per point is
+ // all there is. Hoisted: eye() and view() allocate, and this is per-mesh.
+ const k = m.lit ? shadeWith([0, 0, 1], dirToView(cam.view(), LIGHT)) : 1
+ const eye = cam.eye()
+ for (let v = 0; v < count; v += stride) {
+ const i = v * 3
+ const q = px(i, p)
+ if (!Number.isFinite(q.x) || q.z > 1) continue
+ const dist = Math.max(1e-3, Math.hypot(p[i] - eye[0], p[i + 1] - eye[1], p[i + 2] - eye[2]))
+ const rad = clamp(((m.sizes ? m.sizes[v] : 0.5) * scale) / dist, 0.7, 30)
+ prims.push({
+ z: q.z,
+ s: `<circle cx="${q.x.toFixed(1)}" cy="${q.y.toFixed(1)}" r="${rad.toFixed(2)}" fill="${hex(c[i], c[i + 1], c[i + 2], k)}"/>`,
+ })
+ }
+ }
+
+ // far first. `project` returns NDC depth, where +1 is the far plane.
+ prims.sort((a, b) => b.z - a.z)
+
+ return head + prims.map((x) => x.s).join('') + overlaySvg(scene, w, h, ink) + tail
+}
+
+/** Axis titles, the colour legend and the dropped-row count. Chrome, but the
+ * dropped count is not optional: it is the only place the fallback can say
+ * that some rows are not in the picture. */
+function overlaySvg(scene: Scene, w: number, h: number, ink: string): string {
+ const font = 'font-family="system-ui,-apple-system,sans-serif"'
+ let out = ''
+ const titles = scene.axes.map((a) => a.title).filter(Boolean).join(' · ')
+ if (titles) {
+ out += `<text x="12" y="${h - 12}" fill="${esc(ink)}" ${font} font-size="11" opacity="0.75">${esc(titles)}</text>`
+ }
+ if (scene.dropped > 0) {
+ out += `<text x="${w - 12}" y="${h - 12}" fill="${esc(ink)}" ${font} font-size="11" ` +
+ `text-anchor="end" opacity="0.6">${scene.dropped} of ${scene.rows} rows had no value</text>`
+ }
+ const lg = scene.legend
+ if (lg && lg.kind === 'ramp' && lg.ramp?.length) {
+ const id = 'v3lg'
+ const stops = lg.ramp.map((c, i) =>
+ `<stop offset="${((i / (lg.ramp!.length - 1)) * 100).toFixed(0)}%" stop-color="${esc(c)}"/>`).join('')
+ out += `<defs><linearGradient id="${id}" x1="0" y1="1" x2="0" y2="0">${stops}</linearGradient></defs>` +
+ `<rect x="${w - 26}" y="24" width="10" height="96" fill="url(#${id})" rx="2"/>` +
+ `<text x="${w - 32}" y="30" fill="${esc(ink)}" ${font} font-size="10" text-anchor="end" opacity="0.8">${esc(fmtNum(lg.max ?? 0))}</text>` +
+ `<text x="${w - 32}" y="122" fill="${esc(ink)}" ${font} font-size="10" text-anchor="end" opacity="0.8">${esc(fmtNum(lg.min ?? 0))}</text>` +
+ (lg.title ? `<text x="12" y="20" fill="${esc(ink)}" ${font} font-size="11" opacity="0.8">${esc(lg.title)}</text>` : '')
+ } else if (lg && lg.items?.length) {
+ lg.items.slice(0, 6).forEach((it, i) => {
+ const y = 24 + i * 16
+ out += `<rect x="${w - 26}" y="${y}" width="10" height="10" fill="${esc(it.color)}" rx="2"/>` +
+ `<text x="${w - 32}" y="${y + 9}" fill="${esc(ink)}" ${font} font-size="10" text-anchor="end" opacity="0.8">${esc(it.label)}</text>`
+ })
+ }
+ return out
+}
+
+// --- GL (browser only) ------------------------------------------------------
+
+// GLSL ES 3.00. `#version` MUST be the very first characters of the source, so
+// these template literals open on it with no leading newline.
+const MESH_VS = `#version 300 es
+precision highp float;
+in vec3 a_pos;
+in vec3 a_normal;
+in vec3 a_color;
+uniform mat4 u_vp;
+uniform vec3 u_light;
+uniform float u_ambient;
+uniform float u_lit;
+out vec3 v_color;
+void main() {
+ // transliterated from shade() — the two must not disagree
+ float d = max(0.0, dot(a_normal, u_light));
+ float sky = 0.55 + 0.45 * a_normal.y;
+ float s = min(1.0, u_ambient * sky + (1.0 - u_ambient) * d);
+ v_color = mix(a_color, a_color * s, u_lit);
+ gl_Position = u_vp * vec4(a_pos, 1.0);
+}`
+
+const MESH_FS = `#version 300 es
+precision highp float;
+in vec3 v_color;
+out vec4 fragColor;
+void main() { fragColor = vec4(v_color, 1.0); }`
+
+// One vertex per row. A real sphere per point would be ~80 vertices each, so a
+// 100k-row scatter is 8M vertices instead of 100k — the impostor is what makes
+// the scatter the size of its data rather than eighty times it.
+const POINT_VS = `#version 300 es
+precision highp float;
+in vec3 a_pos;
+in vec3 a_color;
+in float a_size;
+uniform mat4 u_vp;
+uniform float u_pscale;
+out vec3 v_color;
+void main() {
+ v_color = a_color;
+ gl_Position = u_vp * vec4(a_pos, 1.0);
+ // gl_Position.w is the view-space distance for a perspective matrix, so this
+ // is the true projected diameter of a sphere of world radius a_size. Clamped
+ // because drivers cap gl_PointSize and SILENTLY DROP points that exceed it.
+ gl_PointSize = clamp(a_size * u_pscale / max(0.0001, gl_Position.w), 1.5, 96.0);
+}`
+
+const POINT_FS = `#version 300 es
+precision highp float;
+in vec3 v_color;
+uniform vec3 u_lightv;
+uniform float u_ambient;
+out vec4 fragColor;
+void main() {
+ vec2 pc = gl_PointCoord * 2.0 - 1.0;
+ float r2 = dot(pc, pc);
+ // A hard cut, not a blended edge: blending would need the points sorted
+ // back-to-front every frame and would still be wrong where they overlap.
+ if (r2 > 1.0) discard;
+ // gl_PointCoord counts DOWN, so y is negated to make +Y up.
+ vec3 n = vec3(pc.x, -pc.y, sqrt(max(0.0, 1.0 - r2)));
+ float d = max(0.0, dot(n, u_lightv));
+ float sky = 0.55 + 0.45 * n.y;
+ float s = min(1.0, u_ambient * sky + (1.0 - u_ambient) * d);
+ fragColor = vec4(v_color * s, 1.0);
+}`
+
+export interface Viz3dOpts {
+ background?: string
+ /** spin gently. Off by default: a dashboard of auto-rotating tiles is a
+ * laptop fan, and motion the reader did not ask for. */
+ autoRotate?: boolean
+ azimuth?: number
+ elevation?: number
+ /** point radius as a fraction of the scene radius */
+ pointScale?: number
+}
+
+/**
+ * Pointer control shared by BOTH paths, so the fallback drags exactly like GL
+ * does. One pointer rotates (shift or the right button pans); two pinch and
+ * pan, because `touch-action: none` is required for the first and disables the
+ * browser's own pinch along with it.
+ */
+function orbitControls(el: HTMLElement, orb: Orbit, changed: () => void): () => void {
+ const pts = new Map<number, { x: number; y: number }>()
+ let spread = 0
+
+ const centreOf = (): { x: number; y: number; d: number } => {
+ const l = [...pts.values()]
+ const x = l.reduce((a, p) => a + p.x, 0) / l.length
+ const y = l.reduce((a, p) => a + p.y, 0) / l.length
+ const d = l.length > 1 ? Math.hypot(l[0].x - l[1].x, l[0].y - l[1].y) : 0
+ return { x, y, d }
+ }
+
+ const down = (e: PointerEvent) => {
+ pts.set(e.pointerId, { x: e.clientX, y: e.clientY })
+ spread = centreOf().d
+ el.setPointerCapture?.(e.pointerId)
+ }
+ const move = (e: PointerEvent) => {
+ const was = pts.get(e.pointerId)
+ if (!was) return
+ const dx = e.clientX - was.x
+ const dy = e.clientY - was.y
+ pts.set(e.pointerId, { x: e.clientX, y: e.clientY })
+ if (pts.size >= 2) {
+ const now = centreOf()
+ if (spread > 0 && now.d > 0) orb.zoom(spread / now.d)
+ spread = now.d
+ orb.pan(dx / 2, dy / 2)
+ } else if (e.shiftKey || e.buttons === 2 || e.buttons === 4) {
+ orb.pan(dx, dy)
+ } else {
+ orb.rotate(dx, dy)
+ }
+ changed()
+ }
+ const up = (e: PointerEvent) => {
+ pts.delete(e.pointerId)
+ spread = pts.size > 1 ? centreOf().d : 0
+ el.releasePointerCapture?.(e.pointerId)
+ }
+ // preventDefault so the page behind a tile does not scroll away under the
+ // gesture. A 3D view that does not zoom on the wheel is the bigger surprise.
+ const wheel = (e: WheelEvent) => {
+ e.preventDefault()
+ orb.zoom(Math.exp(clamp(e.deltaY, -120, 120) * 0.0016))
+ changed()
+ }
+ const menu = (e: Event) => e.preventDefault()
+
+ el.addEventListener('pointerdown', down)
+ el.addEventListener('pointermove', move)
+ el.addEventListener('pointerup', up)
+ el.addEventListener('pointercancel', up)
+ el.addEventListener('wheel', wheel, { passive: false })
+ el.addEventListener('contextmenu', menu)
+ return () => {
+ el.removeEventListener('pointerdown', down)
+ el.removeEventListener('pointermove', move)
+ el.removeEventListener('pointerup', up)
+ el.removeEventListener('pointercancel', up)
+ el.removeEventListener('wheel', wheel)
+ el.removeEventListener('contextmenu', menu)
+ }
+}
+
+function mountFallback(host: HTMLElement, scene: Scene, opts: Viz3dOpts): () => void {
+ const box = document.createElement('div')
+ box.className = 'dash-viz3d dash-viz3d-2d'
+ box.style.cssText = 'width:100%;height:100%;touch-action:none;user-select:none'
+ host.appendChild(box)
+
+ const cam = frameCamera(scene, opts)
+ let raf = 0
+ const paint = () => {
+ raf = 0
+ cam.height = box.clientHeight || 420
+ box.innerHTML = fallbackSvg(scene, box.clientWidth || 640, box.clientHeight || 420, {
+ camera: cam, background: opts.background,
+ })
+ }
+ const schedule = () => {
+ if (!raf) raf = requestAnimationFrame(paint)
+ }
+ paint()
+
+ const detach = scene.empty ? () => {} : orbitControls(box, cam, schedule)
+ const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null
+ ro?.observe(box)
+ return () => {
+ if (raf) cancelAnimationFrame(raf)
+ detach()
+ ro?.disconnect()
+ box.remove()
+ }
+}
+
+/**
+ * Mount a scene into a host element. Returns a teardown.
+ *
+ * THE LOOP IDLES. A frame is scheduled only when something changed — a drag, a
+ * wheel, a resize, a context restore — and `draw` clears the flag rather than
+ * re-arming it. A permanent requestAnimationFrame loop is the default shape of
+ * every 3D example on the web and it is wrong here: a dashboard holds several
+ * tiles, none of them are moving, and between them they would keep the GPU and
+ * the compositor awake for as long as the file is open. `autoRotate` is the one
+ * case that re-arms, and it is opt-in.
+ */
+export function mountViz3d(host: HTMLElement, scene: Scene, opts: Viz3dOpts = {}): () => void {
+ host.textContent = ''
+ if (scene.empty || !supportsWebGL2()) return mountFallback(host, scene, opts)
+
+ const canvas = document.createElement('canvas')
+ // `touch-action:none` so a one-finger drag orbits instead of scrolling the
+ // page; `user-select:none` because an orbit drag that runs off the canvas
+ // otherwise selects the surrounding page text and leaves it highlighted.
+ canvas.style.cssText = 'display:block;width:100%;height:100%;touch-action:none;user-select:none'
+ host.appendChild(canvas)
+ const view = new GLView(canvas)
+ // supportsWebGL2() can be TRUE while this particular context fails: browsers
+ // cap live contexts at about 16, and a dashboard that swaps tiles reaches it.
+ // Falling back to the SVG is much better than a blank canvas.
+ if (!view.ok) {
+ view.dispose()
+ canvas.remove()
+ return mountFallback(host, scene, opts)
+ }
+
+ const meshProg = view.compile(MESH_VS, MESH_FS)
+ const pointProg = view.compile(POINT_VS, POINT_FS)
+ const bufs = scene.meshes.map((m) => ({
+ m,
+ pos: view.buffer(m.positions),
+ col: view.buffer(m.colors),
+ nrm: m.normals ? view.buffer(m.normals) : null,
+ siz: m.sizes ? view.buffer(m.sizes) : null,
+ idx: m.indices ? view.buffer(m.indices, { index: true }) : null,
+ }))
+
+ const cam = frameCamera(scene, opts)
+ const bg = hexToRgb(opts.background ?? '#0E1420')
+ const pointRadius = scene.radius * (opts.pointScale ?? 0.022)
+ let raf = 0
+
+ const draw = () => {
+ raf = 0
+ view.resize()
+ cam.height = canvas.clientHeight || 420
+ const vp = cam.matrix(view.aspect)
+ const lightView = dirToView(cam.view(), LIGHT)
+ const pscale = (2 * pointRadius * canvas.height * 0.5) / Math.tan(cam.fovY / 2)
+ view.clear(bg[0], bg[1], bg[2], 1)
+ for (const b of bufs) {
+ if (b.m.mode === 'points') {
+ view.draw({
+ program: pointProg,
+ attribs: {
+ a_pos: { buffer: b.pos, size: 3 },
+ a_color: { buffer: b.col, size: 3 },
+ ...(b.siz ? { a_size: { buffer: b.siz, size: 1 } } : {}),
+ },
+ uniforms: { u_vp: vp, u_pscale: pscale, u_lightv: lightView, u_ambient: AMBIENT },
+ count: b.m.positions.length / 3,
+ mode: 'points',
+ })
+ continue
+ }
+ view.draw({
+ program: meshProg,
+ attribs: {
+ a_pos: { buffer: b.pos, size: 3 },
+ a_color: { buffer: b.col, size: 3 },
+ ...(b.nrm ? { a_normal: { buffer: b.nrm, size: 3 } } : {}),
+ },
+ uniforms: { u_vp: vp, u_light: LIGHT, u_ambient: AMBIENT, u_lit: b.m.lit ? 1 : 0 },
+ count: b.idx ? b.m.indices!.length : b.m.positions.length / 3,
+ mode: b.m.mode,
+ ...(b.idx ? { index: b.idx } : {}),
+ })
+ }
+ if (opts.autoRotate) { cam.rotate(-0.4, 0); schedule() }
+ }
+ const schedule = () => {
+ if (!raf) raf = requestAnimationFrame(draw)
+ }
+
+ view.onRestore = schedule
+ view.onLost = () => { if (raf) { cancelAnimationFrame(raf); raf = 0 } }
+ const detach = orbitControls(canvas, cam, schedule)
+ const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(schedule) : null
+ ro?.observe(canvas)
+ schedule()
+
+ return () => {
+ if (raf) cancelAnimationFrame(raf)
+ detach()
+ ro?.disconnect()
+ view.dispose()
+ canvas.remove()
+ }
+}
+
+export const _internals = {
+ categorise, aggregateGrid, scaler, norm01, sizeFor, sphereMesh, frameMesh, boundsOf,
+ num, fmtNum, SIZE_MIN, SIZE_MAX, AXIS_MAX_SURFACE, AXIS_MAX_BARS, DEFAULT_BINS,
+ SVG_MAX_TRIS, SVG_MAX_POINTS, BOX_FACES, esc,
+}
diff --git a/dash/src/xlsx.ts b/dash/src/xlsx.ts
new file mode 100644
index 00000000..31bb41b2
--- /dev/null
+++ b/dash/src/xlsx.ts
@@ -0,0 +1,1568 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// .xlsx — SpreadsheetML in, SpreadsheetML out.
+//
+// THE REASON THIS EXISTS. Nobody adopts a spreadsheet they cannot get their
+// existing files into, or get their work out of. CSV is the interchange format
+// people already have and import.ts handles it; .xlsx is the format their work
+// is actually IN, and a tool that can only read a flattened, untyped, formula-
+// less copy of it is a tool people try once. This module is the other half of
+// the door, and the export half matters more than it looks: an importer with no
+// exporter is a roach motel, and people can tell.
+//
+// NO DEPENDENCY, ON PURPOSE. SheetJS is larger than this entire product and
+// JSZip roughly doubles it, so either one is paid for by every user who opens
+// any workbook, forever, to serve a format many of them never touch. What .xlsx
+// needs is a ZIP (zip.ts) and the fraction of SpreadsheetML that carries values,
+// types, number formats and formulas. That fraction is this file.
+//
+// THE THREE SILENT DISASTERS, in the order they cost, because every one of them
+// produces a file that OPENS, fills the grid, computes its totals, and is wrong:
+//
+// 1. THE DATE EPOCH. A workbook is on the 1900 serial system or the 1904 one,
+// and the difference is 1,462 days — four years and a day. Nothing on
+// screen says which; it is one attribute in workbook.xml, and a reader
+// that assumes 1900 shifts every date in every Mac-authored file by four
+// years without a word. Worse, the 1900 system has a deliberate BUG: it
+// believes 1900 was a leap year (Lotus did, and compatibility outlived the
+// reason), so serials 1–59 and 61+ need different epochs and serial 60 is
+// a day that never existed. All three cases are handled below and all
+// three are in the rig.
+// 2. PERCENT IS ALREADY A FRACTION. Excel stores 15% as 0.15 and dash stores
+// percent as a fraction too, so the value passes through UNCHANGED. The
+// instinct to multiply by 100 on the way in — because the cell *said* 15 —
+// is how a margin column becomes 1500%.
+// 3. THE CACHED VALUE IS THE TRUTH, THE FORMULA IS THE PROVENANCE. A formula
+// cell carries both. Importing only the formula means every cell dash
+// cannot evaluate reads `#NAME?` where a number used to be; importing only
+// the value throws away what the workbook was FOR. So both are taken, and
+// the formula is only made LIVE when dash can actually evaluate it — see
+// `liveFormula` for the three ways that can fail, one of which (a
+// cross-sheet reference) would otherwise resolve silently against the
+// wrong sheet.
+//
+// AND THE import.ts PRINCIPLE, which is the house style: where the file is
+// genuinely AMBIGUOUS, refuse and report rather than pick. `XlsxFinding` is
+// deliberately the same shape as `ImportFinding` so one banner renders both.
+//
+// WHAT IS DELIBERATELY NOT HERE, and why, so nobody thinks it was forgotten:
+// charts, images, pivot tables, conditional formatting, data validation,
+// comments, defined names, VBA. All of them survive as unread parts on import
+// (we drop them) and are not written on export. dash's own chart tiles are
+// derived from columns and would have to be REBUILT as DrawingML, which is a
+// larger module than this one for a feature whose data is exported anyway.
+
+import {
+ readZip, writeZip, ZipError, type ZipEntry,
+} from './zip.ts'
+import {
+ colToLetters, lettersToCol, parseRef, shiftRefsForInsert,
+} from './a1.ts'
+import { translateCellFormula } from './cellformula.ts'
+import { FUNCTIONS } from './formula.ts'
+import { readCell } from './store.ts'
+import type {
+ CellOverride, Column, ColumnData, ColumnType, DashDoc, TableSheet,
+} from './model.ts'
+
+// --- findings ---------------------------------------------------------------
+
+/**
+ * One thing the import or export decided on your behalf, in the same shape as
+ * `import.ts`'s `ImportFinding` — deliberately, so `showFindings` renders both
+ * without knowing which produced it. The `code` is for tests and future UI; the
+ * `message` is what a person reads.
+ */
+export interface XlsxFinding {
+ code:
+ | 'date-system' | 'date-1900-bug' | 'merged-cells' | 'mixed-types'
+ | 'coerce-failed' | 'no-header' | 'duplicate-header' | 'empty-header'
+ | 'formula-not-live' | 'hidden-sheet' | 'sheet-skipped' | 'time-of-day'
+ | 'leading-blanks' | 'formula-column' | 'chart-dropped' | 'renamed-sheet'
+ sheet?: string
+ column?: string
+ message: string
+}
+
+export interface XlsxImportResult {
+ sheets: TableSheet[]
+ findings: XlsxFinding[]
+ /** The workbook's own title, if `docProps/core.xml` carried one. */
+ title?: string
+}
+
+// --- a very small XML reader --------------------------------------------------
+//
+// DOMParser would be free in the browser and is the obvious choice — and it is
+// the wrong one twice over. It does not exist in node, so the rig could not
+// test a single line of the import path, which for a format this full of silent
+// failures is not a trade worth making; and it builds a full DOM for a
+// worksheet that can be a hundred megabytes of XML, when all we do is stream
+// through it once.
+//
+// SCANNING WITH REGEX IS SAFE HERE, and only here, for a reason worth writing
+// down: XML forbids a raw `<` in element content and in attribute values, so
+// `</c>` cannot appear inside a `<c>` element — a non-greedy match to the next
+// close tag cannot overshoot. That guarantee does NOT hold for HTML, and it
+// stops holding the moment an element can nest inside itself. None of the
+// elements read here can (`row` never contains `row`, `c` never contains `c`).
+
+type Attrs = Map<string, string>
+
+const ATTR_RE = /([\w:.-]+)\s*=\s*"([^"]*)"/g
+
+/** Attributes of one start tag. A Map, not an object: attribute names come out
+ * of the file, and `__proto__="…"` is legal XML. */
+function attrs(s: string): Attrs {
+ const out: Attrs = new Map()
+ ATTR_RE.lastIndex = 0
+ let m: RegExpExecArray | null
+ while ((m = ATTR_RE.exec(s))) out.set(m[1], unescapeXml(m[2]))
+ return out
+}
+
+/** `r:id`, `id`, `x:id` — producers differ on prefixes and we do not care. */
+function attr(a: Attrs, name: string): string | undefined {
+ const v = a.get(name)
+ if (v !== undefined) return v
+ for (const [k, val] of a) if (k === name || k.endsWith(`:${name}`)) return val
+ return undefined
+}
+
+const NS = '(?:[A-Za-z0-9_.-]+:)?'
+
+/** Every `<name …>…</name>` (and `<name …/>`) at any depth, in document order. */
+function* elements(xml: string, name: string): Generator<{ a: Attrs; body: string }> {
+ const re = new RegExp(`<${NS}${name}(\\s[^>]*?)?\\s*(/>|>([\\s\\S]*?)</${NS}${name}\\s*>)`, 'g')
+ let m: RegExpExecArray | null
+ while ((m = re.exec(xml))) yield { a: attrs(m[1] ?? ''), body: m[3] ?? '' }
+}
+
+/** The first such element, or undefined. */
+function element(xml: string, name: string): { a: Attrs; body: string } | undefined {
+ for (const e of elements(xml, name)) return e
+ return undefined
+}
+
+const NUM_ENT = /&#(x?)([0-9A-Fa-f]+);/g
+const NAMED_ENT: Record<string, string> = {
+ amp: '&', lt: '<', gt: '>', quot: '"', apos: "'",
+}
+
+/**
+ * XML text back to a string.
+ *
+ * `_xHHHH_` is Excel's own escape for characters XML cannot carry, and it is
+ * decoded ONLY for control characters (< 0x20). The escape is ambiguous with
+ * ordinary text — a product code literally called `_x0041_` exists — and Excel
+ * resolves that by escaping the underscore too (`_x005F_x0041_`), which we
+ * would have to unwind in the right order to get right. Limiting the decode to
+ * control characters keeps the case that actually occurs (`_x000D_`, a carriage
+ * return inside a shared string) and cannot corrupt a product code.
+ */
+export function unescapeXml(s: string): string {
+ if (!s) return s
+ let out = s
+ if (out.includes('&')) {
+ out = out.replace(NUM_ENT, (_, hex, digits) =>
+ String.fromCodePoint(parseInt(digits, hex ? 16 : 10)))
+ .replace(/&(amp|lt|gt|quot|apos);/g, (_, n: string) => NAMED_ENT[n])
+ }
+ if (out.includes('_x00')) {
+ out = out.replace(/_x00([01][0-9A-Fa-f])_/g, (_, h) => String.fromCharCode(parseInt(h, 16)))
+ }
+ return out
+}
+
+/**
+ * A string into XML text.
+ *
+ * Control characters are STRIPPED rather than escaped. XML 1.0 simply cannot
+ * carry most of them at any encoding, and Excel treats a file containing one as
+ * corrupt — the "we found a problem with some content" dialog, which is the
+ * exact outcome this whole exporter is judged on. Tab, newline and carriage
+ * return are legal and stay.
+ */
+export function escapeXml(s: string): string {
+ let out = ''
+ for (const ch of s) {
+ const c = ch.codePointAt(0)!
+ if (c < 0x20 && c !== 9 && c !== 10 && c !== 13) continue
+ if (c === 0xfffe || c === 0xffff) continue
+ out += ch === '&' ? '&amp;' : ch === '<' ? '&lt;' : ch === '>' ? '&gt;'
+ : ch === '"' ? '&quot;' : ch
+ }
+ return out
+}
+
+// --- dates --------------------------------------------------------------------
+
+/** ms per day, spelled out because a bare 86400000 in date maths is unreadable. */
+const DAY = 86_400_000
+
+/**
+ * A serial number to an ISO date (or date-time).
+ *
+ * THE 1900 LEAP BUG, in full, because getting it approximately right is worse
+ * than getting it wrong loudly. Excel's 1900 system believes 1900 was a leap
+ * year, so its day numbering runs:
+ *
+ * 1 → 1900-01-01 (epoch 1899-12-31)
+ * 59 → 1900-02-28
+ * 60 → "1900-02-29" a day that does not exist
+ * 61 → 1900-03-01 (epoch 1899-12-30, and from here on)
+ *
+ * A single epoch therefore cannot be right for the whole range. Almost every
+ * implementation uses 1899-12-30 throughout, which is correct for every date
+ * after February 1900 and off by one for every date before it — invisible,
+ * unless your data is a century old, in which case it is invisible AND wrong.
+ *
+ * The 1904 system (Mac Excel's default until 2011, and still what a converted
+ * file carries) has no such bug: serial 0 is 1904-01-01.
+ */
+export function serialToIso(serial: number, epoch1904: boolean, wantTime = false): string | null {
+ if (!Number.isFinite(serial)) return null
+ const whole = Math.floor(serial)
+ const frac = serial - whole
+ let ms: number
+ if (epoch1904) {
+ ms = Date.UTC(1904, 0, 1) + whole * DAY
+ } else {
+ if (whole === 60) {
+ // The impossible day. Reported as a finding by the caller; rendered as
+ // Excel renders it, because pretending it is 1900-02-28 or 1900-03-01
+ // silently moves someone's data by a day.
+ return wantTime ? `1900-02-29T${clock(frac)}` : '1900-02-29'
+ }
+ ms = (whole < 60 ? Date.UTC(1899, 11, 31) : Date.UTC(1899, 11, 30)) + whole * DAY
+ }
+ const d = new Date(ms)
+ if (!Number.isFinite(d.getTime())) return null
+ const iso = `${String(d.getUTCFullYear()).padStart(4, '0')}-${
+ String(d.getUTCMonth() + 1).padStart(2, '0')}-${String(d.getUTCDate()).padStart(2, '0')}`
+ return wantTime ? `${iso}T${clock(frac)}` : iso
+}
+
+/** The fraction of a day as `HH:MM:SS`. */
+function clock(frac: number): string {
+ // Round to the nearest second FIRST: 0.5 of a day held as a float is
+ // 11:59:59.999… often enough to matter, and truncating gives 11:59:59.
+ let secs = Math.round(frac * 86400)
+ if (secs >= 86400) secs = 86399
+ const h = Math.floor(secs / 3600)
+ const m = Math.floor((secs % 3600) / 60)
+ return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(secs % 60).padStart(2, '0')}`
+}
+
+const ISO_RE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?/
+
+/**
+ * An ISO date string to a 1900-system serial — the inverse of the above, and it
+ * has to carry the same leap bug or a round trip moves early-1900 dates by a
+ * day. Exports always use the 1900 system, so there is no epoch to choose.
+ */
+export function isoToSerial(iso: string): number | null {
+ const m = ISO_RE.exec(iso.trim())
+ if (!m) return null
+ const days = (Date.UTC(+m[1], +m[2] - 1, +m[3]) - Date.UTC(1899, 11, 30)) / DAY
+ if (!Number.isFinite(days)) return null
+ const time = (Number(m[4] ?? 0) * 3600 + Number(m[5] ?? 0) * 60 + Number(m[6] ?? 0)) / 86400
+ // Below serial 61 Excel's numbering is one AHEAD of a sane epoch, because of
+ // the phantom 29 February.
+ return (days < 61 ? days - 1 : days) + time
+}
+
+// --- number formats ------------------------------------------------------------
+
+/**
+ * The built-in format ids every consumer is required to know. Only the ones
+ * that CHANGE A TYPE are listed: 14–22 are dates and times, 9/10 are percent,
+ * 5–8 and 37–44 are currency/accounting. Everything else is a number, and 49
+ * (`@`) is text.
+ *
+ * The CJK block (27–36, 50–58) is date formats in the Japanese, Chinese and
+ * Korean locales. They are omitted deliberately: they are locale-dependent, a
+ * file carrying them will normally also carry an explicit custom format, and
+ * claiming a range we have not tested is how a number column becomes a column
+ * of 1970s dates.
+ */
+const BUILTIN: Record<number, 'date' | 'time' | 'percent' | 'money' | 'text'> = {
+ 5: 'money', 6: 'money', 7: 'money', 8: 'money',
+ 9: 'percent', 10: 'percent',
+ 14: 'date', 15: 'date', 16: 'date', 17: 'date', 18: 'time', 19: 'time',
+ 20: 'time', 21: 'time', 22: 'date',
+ 37: 'money', 38: 'money', 39: 'money', 40: 'money',
+ 41: 'money', 42: 'money', 43: 'money', 44: 'money',
+ 45: 'time', 46: 'time', 47: 'time',
+ 49: 'text',
+}
+
+const CURRENCY = /[$£€¥₹₩]|\[\$|"[A-Z]{3}"/
+
+/**
+ * What a custom format code MEANS, for the purpose of choosing a column type.
+ *
+ * The parsing that matters is what to IGNORE. A format code is full of
+ * characters that look like date tokens and are not:
+ *
+ * "GBP" a quoted literal — `m` inside "Amount" is not a month
+ * \- \( an escaped character — the `\d` in `#,##0\d` is a literal d
+ * _0 a width-skip whose argument is the NEXT character
+ * [Red] a colour or a condition — but `[h]` is elapsed hours, a TIME
+ * ; section separator (positive;negative;zero;text)
+ *
+ * Stripping those first is the whole job; what remains can be tested for date
+ * letters. Not stripping them was the first implementation, and `#,##0;\(#,##0\)`
+ * — an ordinary accounting number — came out as a DATE, because of the `\(`.
+ */
+export function classifyFormat(code: string): 'date' | 'time' | 'percent' | 'money' | 'text' | 'number' {
+ if (!code || code === 'General') return 'number'
+ const money = CURRENCY.test(code)
+ let s = ''
+ let elapsed = false
+ for (let i = 0; i < code.length; i++) {
+ const c = code[i]
+ if (c === '"') { const j = code.indexOf('"', i + 1); i = j < 0 ? code.length : j; continue }
+ if (c === '\\' || c === '_' || c === '*') { i++; continue }
+ if (c === '[') {
+ const j = code.indexOf(']', i)
+ const inner = code.slice(i + 1, j < 0 ? code.length : j)
+ // [h] [hh] [m] [mm] [s] are ELAPSED time, not a colour or a condition.
+ if (/^\[?[hms]+\]?$/i.test(inner)) elapsed = true
+ i = j < 0 ? code.length : j
+ continue
+ }
+ s += c
+ }
+ // `@` is the text placeholder, and it beats everything: a column formatted
+ // `@` holds text even when every value in it looks like a number, which is
+ // exactly what a column of ZIP codes or part numbers with leading zeros is.
+ if (s.includes('@')) return 'text'
+ if (s.includes('%')) return 'percent'
+ const hasDate = /[yd]/i.test(s) || /\bmmm/i.test(s)
+ const hasClock = elapsed || /h/i.test(s) || /s/i.test(s)
+ // `m` alone is genuinely ambiguous — month or minute — and is resolved by
+ // what it sits next to, exactly as Excel resolves it: after `h` or before
+ // `s` it is minutes, otherwise it is a month.
+ const bareM = /m/i.test(s) && !hasDate && !hasClock
+ if (hasDate || bareM) return hasClock ? 'date' : 'date'
+ if (hasClock) return 'time'
+ if (money) return 'money'
+ return 'number'
+}
+
+/** Does a date format also carry a time? Used to decide whether to keep one. */
+const formatHasTime = (code: string): boolean => /h|\[h\]/i.test(code.replace(/"[^"]*"/g, ''))
+
+// --- reading a workbook --------------------------------------------------------
+
+interface Styles {
+ /** cellXfs index → format code ('' = General). */
+ xf: string[]
+}
+
+function readStyles(xml: string): Styles {
+ const codes = new Map<number, string>()
+ for (const nf of elements(xml, 'numFmt')) {
+ const id = Number(attr(nf.a, 'numFmtId'))
+ const code = attr(nf.a, 'formatCode') ?? ''
+ if (Number.isFinite(id)) codes.set(id, code)
+ }
+ // ONLY the cellXfs block. `cellStyleXfs` has an identical `<xf>` shape and
+ // comes FIRST in the file, so a scan for every `<xf>` in the document indexes
+ // a cell's `s="12"` into the wrong table — the bug produces plausible formats
+ // for the first few columns and nonsense after, which reads as random.
+ const block = element(xml, 'cellXfs')
+ const xf: string[] = []
+ if (block) {
+ for (const e of elements(block.body, 'xf')) {
+ const id = Number(attr(e.a, 'numFmtId') ?? 0)
+ xf.push(codes.get(id) ?? BUILTIN_CODE[id] ?? '')
+ }
+ }
+ return { xf }
+}
+
+/** A stand-in code for the built-ins we classify by id. Only the letters
+ * matter — `classifyFormat` reads these, nothing displays them. */
+const BUILTIN_CODE: Record<number, string> = (() => {
+ const out: Record<number, string> = {}
+ for (const [id, kind] of Object.entries(BUILTIN)) {
+ out[Number(id)] = kind === 'date' ? 'yyyy-mm-dd' : kind === 'time' ? 'hh:mm:ss'
+ : kind === 'percent' ? '0%' : kind === 'money' ? '$#,##0.00' : '@'
+ }
+ return out
+})()
+
+function readSharedStrings(xml: string): string[] {
+ const out: string[] = []
+ for (const si of elements(xml, 'si')) {
+ // A rich-text string is a run of `<r><t>…</t></r>`; a plain one is a single
+ // `<t>`. Concatenating every `<t>` handles both, and drops the formatting,
+ // which dash has nowhere to put.
+ let s = ''
+ for (const t of elements(si.body, 't')) s += unescapeXml(t.body)
+ out.push(s)
+ }
+ return out
+}
+
+/** Resolve a relationship id against a `.rels` part. */
+function relTargets(xml: string): Map<string, { target: string; type: string }> {
+ const out = new Map<string, { target: string; type: string }>()
+ for (const r of elements(xml, 'Relationship')) {
+ const id = attr(r.a, 'Id')
+ const target = attr(r.a, 'Target')
+ if (id && target) out.set(id, { target, type: attr(r.a, 'Type') ?? '' })
+ }
+ return out
+}
+
+/** Join an OPC part path with a relationship target (which may be relative). */
+function resolvePart(base: string, target: string): string {
+ if (target.startsWith('/')) return target.slice(1)
+ const dir = base.includes('/') ? base.slice(0, base.lastIndexOf('/') + 1) : ''
+ const parts = (dir + target).split('/')
+ const out: string[] = []
+ for (const p of parts) {
+ if (p === '.' || p === '') continue
+ if (p === '..') out.pop()
+ else out.push(p)
+ }
+ return out.join('/')
+}
+
+// --- one worksheet's cells -------------------------------------------------------
+
+interface RawCell {
+ /** 0-based */
+ row: number
+ col: number
+ /** the raw `t` attribute: s | str | b | e | inlineStr | d | (absent = number) */
+ t: string
+ /** style index into cellXfs */
+ s: number
+ /** the `<v>` text, already unescaped */
+ v: string
+ /** inline or shared string text, when the value is a string */
+ text?: string
+ /** formula source WITHOUT a leading `=` */
+ f?: string
+}
+
+/**
+ * Pull every cell out of a worksheet part.
+ *
+ * SHARED FORMULAS are expanded here, and they are why `translateCellFormula` is
+ * imported rather than reimplemented. Excel writes a group of identical
+ * formulas once — `<f t="shared" si="0" ref="B2:B99">A2*2</f>` on the master
+ * and `<f t="shared" si="0"/>` on the other 97 — and a reader that ignores the
+ * followers imports one formula and 97 bare numbers. The translation from the
+ * master to each follower is exactly a fill-down, which cellformula.ts already
+ * does correctly (including leaving `$`-pinned references alone).
+ */
+function readSheetCells(xml: string, shared: string[]): {
+ cells: RawCell[]; merges: string[]; maxCol: number; widths: Map<number, number>
+} {
+ const cells: RawCell[] = []
+ const merges: string[] = []
+ const widths = new Map<number, number>()
+ let maxCol = -1
+
+ const masters = new Map<string, { f: string; row: number; col: number }>()
+
+ const data = element(xml, 'sheetData')
+ for (const row of elements(data ? data.body : xml, 'row')) {
+ const rAttr = Number(attr(row.a, 'r') ?? NaN)
+ let cursor = -1
+ for (const c of elements(row.body, 'c')) {
+ const ref = attr(c.a, 'r')
+ const pos = ref ? parseRef(ref) : null
+ // A `<c>` may legally omit `r`, in which case it is the next column along.
+ const col = pos ? pos.col : cursor + 1
+ const rowIdx = pos ? pos.row : (Number.isFinite(rAttr) ? rAttr - 1 : 0)
+ cursor = col
+ if (col > maxCol) maxCol = col
+
+ const t = attr(c.a, 't') ?? ''
+ const s = Number(attr(c.a, 's') ?? 0) || 0
+ const vEl = element(c.body, 'v')
+ let v = vEl ? unescapeXml(vEl.body) : ''
+ let text: string | undefined
+
+ if (t === 's') {
+ const i = Number(v)
+ text = shared[i] ?? ''
+ v = ''
+ } else if (t === 'inlineStr') {
+ let str = ''
+ const is = element(c.body, 'is')
+ for (const tEl of elements(is ? is.body : c.body, 't')) str += unescapeXml(tEl.body)
+ text = str
+ } else if (t === 'str' || t === 'e') {
+ text = v
+ }
+
+ let f: string | undefined
+ const fEl = element(c.body, 'f')
+ if (fEl) {
+ const kind = attr(fEl.a, 't') ?? ''
+ const si = attr(fEl.a, 'si')
+ const body = unescapeXml(fEl.body)
+ if (kind === 'shared' && si !== undefined) {
+ if (body) {
+ masters.set(si, { f: body, row: rowIdx, col })
+ f = body
+ } else {
+ const m = masters.get(si)
+ // A follower whose master we have not seen is unrecoverable — the
+ // file is out of order or damaged. Dropping the formula (and
+ // keeping the cached value) loses less than inventing one.
+ if (m) f = translateCellFormula(`=${m.f}`, rowIdx - m.row, col - m.col).slice(1)
+ }
+ } else if (kind !== 'dataTable' && body) {
+ f = body
+ }
+ }
+
+ // A cell with neither a value nor a formula is styling only.
+ if (v === '' && text === undefined && f === undefined) continue
+ cells.push({ row: rowIdx, col, t, s, v, text, f })
+ }
+ }
+
+ for (const m of elements(xml, 'mergeCell')) {
+ const ref = attr(m.a, 'ref')
+ if (ref) merges.push(ref)
+ }
+ for (const c of elements(xml, 'col')) {
+ const min = Number(attr(c.a, 'min') ?? NaN)
+ const max = Number(attr(c.a, 'max') ?? NaN)
+ const w = Number(attr(c.a, 'width') ?? NaN)
+ if (!Number.isFinite(min) || !Number.isFinite(w)) continue
+ // Excel's width is in "characters of the default font"; dash's is pixels.
+ // 7px per character + 5px of padding is the conversion Excel documents.
+ const px = Math.round(w * 7 + 5)
+ for (let i = min; i <= (Number.isFinite(max) ? max : min); i++) widths.set(i - 1, px)
+ }
+ return { cells, merges, maxCol, widths }
+}
+
+// --- typing a column ---------------------------------------------------------
+
+type Kind = 'blank' | 'text' | 'number' | 'money' | 'percent' | 'date' | 'time' | 'bool' | 'error'
+
+/** What ONE cell is, given the workbook's styles. The only place a cell's type
+ * is decided; everything downstream aggregates these. */
+function kindOf(c: RawCell, styles: Styles): Kind {
+ if (c.t === 'e') return 'error'
+ if (c.t === 'b') return 'bool'
+ if (c.t === 's' || c.t === 'str' || c.t === 'inlineStr') return c.text ? 'text' : 'blank'
+ if (c.t === 'd') return 'date' // ISO-in-the-file, an ECMA-376 2nd-edition thing
+ if (c.v === '') return 'blank'
+ const code = styles.xf[c.s] ?? ''
+ const f = classifyFormat(code)
+ return f === 'text' ? 'text' : f === 'number' ? 'number' : f
+}
+
+/** The four families that are genuinely different KINDS OF DATA, as opposed to
+ * different ways of displaying a number. money/percent/number differ only in
+ * presentation; date and text differ in what the value IS. */
+const familyOf = (k: Kind): 'numeric' | 'date' | 'bool' | 'text' | 'blank' =>
+ k === 'blank' ? 'blank'
+ : k === 'date' ? 'date'
+ : k === 'bool' ? 'bool'
+ : k === 'number' || k === 'money' || k === 'percent' ? 'numeric'
+ : 'text'
+
+/** import.ts's threshold, and the same reasoning: a column that is 90% one
+ * thing has 10% mess in it, which is reported; a column that is 60% one thing
+ * is not one thing. */
+const CONSENSUS = 0.9
+
+interface ColumnPlan {
+ type: ColumnType
+ /** cells that will not survive the chosen type, and become blank */
+ failed: number
+ /** no family reached consensus: imported as text, and SAID SO */
+ ambiguous?: string
+ /** the format code the majority of cells carried, kept as `Column.format` */
+ format?: string
+ /** date cells carried a time of day */
+ hasTime?: boolean
+}
+
+function planColumn(cells: Array<RawCell | undefined>, styles: Styles): ColumnPlan {
+ const present = cells.filter((c): c is RawCell => !!c && kindOf(c, styles) !== 'blank')
+ if (!present.length) return { type: 'text', failed: 0 }
+
+ const kinds = present.map((c) => kindOf(c, styles))
+ const fam = new Map<string, number>()
+ for (const k of kinds) fam.set(familyOf(k), (fam.get(familyOf(k)) ?? 0) + 1)
+
+ let bestFam = 'text'
+ let bestN = 0
+ for (const [f, n] of fam) if (n > bestN) { bestFam = f; bestN = n }
+
+ if (bestN / present.length < CONSENSUS) {
+ return {
+ type: 'text',
+ failed: 0,
+ ambiguous: `${[...fam].map(([f, n]) => `${n} ${f}`).join(', ')} — no single type covers the column`,
+ }
+ }
+
+ // The format code the winning family mostly carries, so `Column.format` keeps
+ // the author's chosen presentation instead of dash inventing one.
+ const codes = new Map<string, number>()
+ present.forEach((c, i) => {
+ if (familyOf(kinds[i]) !== bestFam) return
+ const code = styles.xf[c.s] ?? ''
+ if (code && code !== 'General') codes.set(code, (codes.get(code) ?? 0) + 1)
+ })
+ let format: string | undefined
+ let topN = 0
+ for (const [code, n] of codes) if (n > topN) { topN = n; format = code }
+
+ const failed = present.length - bestN
+ if (bestFam === 'date') {
+ return { type: 'date', failed, format, hasTime: !!format && formatHasTime(format) }
+ }
+ if (bestFam === 'bool') return { type: 'bool', failed }
+ if (bestFam === 'text') return { type: 'text', failed: 0 }
+
+ // numeric: money vs percent vs number is a DISPLAY choice over the same
+ // stored value, so the majority wins and nothing can be lost by getting it
+ // wrong beyond a currency sign.
+ const sub = new Map<Kind, number>()
+ present.forEach((_, i) => {
+ if (familyOf(kinds[i]) !== 'numeric') return
+ sub.set(kinds[i], (sub.get(kinds[i]) ?? 0) + 1)
+ })
+ let type: ColumnType = 'number'
+ let n = 0
+ for (const [k, count] of sub) if (count > n) { n = count; type = k as ColumnType }
+ return { type, failed, format }
+}
+
+/** Coerce one cell into the column's chosen type. `null` means it would not go. */
+function coerceCell(
+ c: RawCell | undefined, plan: ColumnPlan, styles: Styles, epoch1904: boolean,
+): { v: unknown; lost: boolean; leap1900: boolean } {
+ if (!c) return { v: null, lost: false, leap1900: false }
+ const k = kindOf(c, styles)
+ if (k === 'blank') return { v: null, lost: false, leap1900: false }
+ const num = () => (c.v === '' ? NaN : Number(c.v))
+
+ switch (plan.type) {
+ case 'date': {
+ if (k === 'date' && c.t === 'd') return { v: c.text ?? c.v, lost: false, leap1900: false }
+ if (k !== 'date') return { v: null, lost: true, leap1900: false }
+ const n = num()
+ const iso = serialToIso(n, epoch1904, !!plan.hasTime && n % 1 !== 0)
+ return { v: iso, lost: iso === null, leap1900: !epoch1904 && Math.floor(n) === 60 }
+ }
+ case 'bool': {
+ if (k === 'bool') return { v: c.v === '1' || c.v.toLowerCase() === 'true', lost: false, leap1900: false }
+ const n = num()
+ if (n === 0 || n === 1) return { v: n === 1, lost: false, leap1900: false }
+ return { v: null, lost: true, leap1900: false }
+ }
+ case 'text':
+ // Everything has a string form, so nothing is ever lost to a text column.
+ // An error cell keeps its code (`#DIV/0!`) — that IS what the cell says.
+ if (k === 'text' || k === 'error') return { v: c.text ?? c.v, lost: false, leap1900: false }
+ if (k === 'bool') return { v: c.v === '1' ? 'TRUE' : 'FALSE', lost: false, leap1900: false }
+ if (k === 'date') {
+ const iso = serialToIso(num(), epoch1904)
+ return { v: iso ?? c.v, lost: false, leap1900: false }
+ }
+ if (k === 'time') return { v: clock(num() % 1), lost: false, leap1900: false }
+ return { v: c.v, lost: false, leap1900: false }
+ default: {
+ // number / money / percent — all stored as the plain number Excel holds.
+ // PERCENT IS NOT MULTIPLIED: Excel stores 15% as 0.15 and so does dash.
+ if (familyOf(k) !== 'numeric') return { v: null, lost: true, leap1900: false }
+ const n = num()
+ return { v: Number.isFinite(n) ? n : null, lost: !Number.isFinite(n), leap1900: false }
+ }
+ }
+}
+
+// --- formulas ------------------------------------------------------------------
+
+const FN_SET = new Set(FUNCTIONS.map((f) => f.toUpperCase()))
+const CALL_RE = /([A-Za-z][A-Za-z0-9_.]*)\s*\(/g
+
+/**
+ * Can dash make this formula LIVE, or must it stay a number with the source
+ * recorded beside it?
+ *
+ * Three ways it cannot, and the first is the dangerous one:
+ *
+ * 1. A SHEET QUALIFIER (`Sheet2!A1`, `'Q1 data'!B7`). a1.ts deliberately
+ * leaves the name before `!` alone — but the `A1` AFTER it is then read as
+ * a reference on THIS sheet, so `Sheet2!A1` would silently resolve against
+ * the wrong sheet's column A. That is a wrong number wearing a right
+ * number's clothes, which is the one outcome this codebase refuses.
+ * 2. AN EXTERNAL OR STRUCTURED REFERENCE (`[1]Sheet!A1`, `Table1[Amount]`).
+ * The data it names is not in the file.
+ * 3. A FUNCTION dash does not implement. VLOOKUP, INDEX/MATCH, XLOOKUP and
+ * the rest would evaluate to `#NAME?` — visible, not silent, but a grid
+ * full of `#NAME?` where numbers used to be is not an import, it is a
+ * demolition.
+ *
+ * In all three cases the cached VALUE is kept (so the sheet still reads
+ * correctly) and the formula text is preserved on the override under `xlsxF`,
+ * which is an additive field: nothing in dash reads it yet, the format promises
+ * it survives (PLATFORM §3), and the export half below writes it back out. That
+ * is what makes xlsx → dash → xlsx not lose someone's model.
+ */
+export function liveFormula(src: string): { ok: true } | { ok: false; why: string; fn?: string } {
+ // A quoted literal can contain anything; strip it before looking for `!`.
+ const bare = src.replace(/"[^"]*"/g, '""')
+ if (/'[^']*'\s*!/.test(bare) || /[A-Za-z0-9_.$]\s*!/.test(bare.replace(/#REF!/g, ''))) {
+ return { ok: false, why: 'it points at another sheet' }
+ }
+ if (/\[/.test(bare)) return { ok: false, why: 'it uses an external or table reference' }
+ CALL_RE.lastIndex = 0
+ let m: RegExpExecArray | null
+ while ((m = CALL_RE.exec(bare))) {
+ const fn = m[1].toUpperCase()
+ if (!FN_SET.has(fn)) return { ok: false, why: `dash has no ${fn}() yet`, fn }
+ }
+ return { ok: true }
+}
+
+// --- import --------------------------------------------------------------------
+
+export interface XlsxImportOpts {
+ /** Provenance, written into `steps[0]`. */
+ source?: string
+ at?: string
+ /** Sheet id prefix; ids are `${prefix}-1`, `${prefix}-2`, … */
+ idPrefix?: string
+ /** Override the header-row decision instead of letting it be inferred. */
+ header?: boolean
+}
+
+const blank = (s: string): boolean => s.trim() === ''
+
+const slug = (s: string, i: number): string =>
+ (s.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '') || `col-${i + 1}`).slice(0, 40)
+
+/**
+ * Read a .xlsx into dash sheets.
+ *
+ * Throws only for a container we cannot open at all (`ZipError`, or a package
+ * with no workbook part). Everything else is a FINDING: a workbook that is
+ * partly readable should open, with the parts we could not read named, rather
+ * than refusing wholesale — the person has the file and needs what is in it.
+ */
+export async function importXlsx(
+ bytes: Uint8Array, opts: XlsxImportOpts = {},
+): Promise<XlsxImportResult> {
+ const parts = await readZip(bytes)
+ const dec = new TextDecoder()
+ const text = (name: string): string | undefined => {
+ const b = parts.get(name)
+ return b ? dec.decode(b) : undefined
+ }
+
+ // The workbook part is found through the package relationships, never
+ // assumed to be `xl/workbook.xml`. It usually is; Numbers and a few
+ // generators put it elsewhere, and the cost of doing this properly is four
+ // lines.
+ const rootRels = text('_rels/.rels')
+ let wbPath = 'xl/workbook.xml'
+ if (rootRels) {
+ for (const r of relTargets(rootRels).values()) {
+ if (r.type.endsWith('/officeDocument')) { wbPath = resolvePart('', r.target); break }
+ }
+ }
+ const wbXml = text(wbPath)
+ if (!wbXml) throw new ZipError('this .xlsx has no workbook part — it is not a spreadsheet package')
+
+ const wbRels = text(resolvePart(wbPath, `_rels/${wbPath.split('/').pop()}.rels`))
+ const rels = wbRels ? relTargets(wbRels) : new Map()
+
+ let sharedPath = ''
+ let stylesPath = ''
+ for (const r of rels.values()) {
+ if (r.type.endsWith('/sharedStrings')) sharedPath = resolvePart(wbPath, r.target)
+ else if (r.type.endsWith('/styles')) stylesPath = resolvePart(wbPath, r.target)
+ }
+ const shared = readSharedStrings(text(sharedPath) ?? '')
+ const styles = readStyles(text(stylesPath) ?? '')
+
+ // THE FOUR-YEAR BUG. `date1904` is one attribute and there is no other clue
+ // in the file; assuming 1900 shifts every date in a Mac-authored workbook by
+ // 1,462 days, silently, and the numbers still look like dates.
+ const pr = element(wbXml, 'workbookPr')
+ const d1904 = pr ? (attr(pr.a, 'date1904') ?? '') : ''
+ const epoch1904 = d1904 === '1' || d1904.toLowerCase() === 'true'
+
+ const findings: XlsxFinding[] = []
+ if (epoch1904) {
+ findings.push({
+ code: 'date-system',
+ message: 'This workbook uses the 1904 date system (Mac Excel). Dates were converted from that epoch — read on the 1900 system they would all be four years and a day early.',
+ })
+ }
+
+ const sheets: TableSheet[] = []
+ const prefix = opts.idPrefix ?? `xl-${Math.floor(Date.now() % 1e8).toString(36)}`
+ const usedIds = new Set<string>()
+ let n = 0
+
+ for (const s of elements(wbXml, 'sheet')) {
+ const name = attr(s.a, 'name') ?? `Sheet ${n + 1}`
+ const rid = attr(s.a, 'id') ?? ''
+ const state = attr(s.a, 'state') ?? ''
+ const rel = rels.get(rid)
+ if (!rel) {
+ findings.push({ code: 'sheet-skipped', sheet: name, message: `"${name}" could not be located in the package and was not imported.` })
+ continue
+ }
+ const partPath = resolvePart(wbPath, rel.target)
+ const xml = text(partPath)
+ if (xml === undefined) {
+ findings.push({ code: 'sheet-skipped', sheet: name, message: `"${name}" is listed in the workbook but its data is missing from the file.` })
+ continue
+ }
+ // A chartsheet has no `sheetData` at all.
+ if (rel.type.endsWith('/chartsheet') || !/<(?:[A-Za-z0-9_.-]+:)?sheetData[\s>]/.test(xml)) {
+ findings.push({ code: 'chart-dropped', sheet: name, message: `"${name}" is a chart sheet, which has no data of its own; it was not imported.` })
+ continue
+ }
+ if (state === 'hidden' || state === 'veryHidden') {
+ findings.push({
+ code: 'hidden-sheet', sheet: name,
+ message: `"${name}" was hidden in Excel. It was imported anyway — hiding a sheet is not deleting it, and dropping data silently is the worse mistake.`,
+ })
+ }
+ n++
+ const id = `${prefix}-${n}`
+ usedIds.add(id)
+ sheets.push(readOneSheet(xml, name, id, shared, styles, epoch1904, findings, opts))
+ }
+
+ if (!sheets.length && !findings.some((f) => f.code === 'sheet-skipped')) {
+ throw new ZipError('this workbook contains no worksheets')
+ }
+
+ const core = text('docProps/core.xml')
+ const title = core ? element(core, 'title')?.body : undefined
+ return { sheets, findings: condense(findings), title: title ? unescapeXml(title) : undefined }
+}
+
+/** How many of one KIND of finding, on one sheet, are worth listing before the
+ * rest become a count. */
+const FINDING_RUN = 3
+
+/**
+ * Collapse repetition, without dropping the fact that it happened.
+ *
+ * A real financial model — measured on a 4-sheet cost model with 34 columns of
+ * mixed-type data — produces over EIGHTY findings, one per column, and the
+ * banner that was supposed to say "here is what opening this file decided on
+ * your behalf" becomes a wall nobody reads. That is a worse outcome than a
+ * shorter list: an unread warning and an absent warning are the same warning.
+ *
+ * So the first few of each (code, sheet) pair are listed in full and the rest
+ * become one line with the count. Nothing is hidden — the number is there, and
+ * the columns are still flagged on the columns themselves via `failed`.
+ */
+function condense(findings: XlsxFinding[]): XlsxFinding[] {
+ const seen = new Map<string, number>()
+ const out: XlsxFinding[] = []
+ const extra = new Map<string, { n: number; f: XlsxFinding }>()
+ for (const f of findings) {
+ const key = `${f.code}${f.sheet ?? ''}`
+ const n = (seen.get(key) ?? 0) + 1
+ seen.set(key, n)
+ if (n <= FINDING_RUN) out.push(f)
+ else extra.set(key, { n: n - FINDING_RUN, f })
+ }
+ for (const [, { n, f }] of extra) {
+ out.push({
+ code: f.code, sheet: f.sheet,
+ message: `…and ${n} more column${n === 1 ? '' : 's'}${f.sheet ? ` in "${f.sheet}"` : ''} with the same finding.`,
+ })
+ }
+ return out
+}
+
+function readOneSheet(
+ xml: string, name: string, id: string, shared: string[], styles: Styles,
+ epoch1904: boolean, findings: XlsxFinding[], opts: XlsxImportOpts,
+): TableSheet {
+ const { cells, merges, maxCol, widths } = readSheetCells(xml, shared)
+
+ if (merges.length) {
+ findings.push({
+ code: 'merged-cells', sheet: name,
+ message: `"${name}" has ${merges.length} merged range${merges.length === 1 ? '' : 's'} (${merges.slice(0, 3).join(', ')}${merges.length > 3 ? ', …' : ''}). A merged range holds ONE value, in its top-left cell, and that is where it stayed — filling every cell of the range would turn one spanning heading into a row of repeated values and one total into several.`,
+ })
+ }
+
+ // The used range. Rows are taken from the first row that has anything in it:
+ // a report with four blank rows of letterhead above the table is common, and
+ // importing them as empty rows makes every column read as ambiguous.
+ const rowsUsed = [...new Set(cells.map((c) => c.row))].sort((a, b) => a - b)
+ const firstRow = rowsUsed.length ? rowsUsed[0] : 0
+ const lastRow = rowsUsed.length ? rowsUsed[rowsUsed.length - 1] : -1
+ const width = maxCol + 1
+
+ // COLUMNS KEEP THEIR POSITION, always from column A. A table starting at C2
+ // could have its two empty leading columns trimmed — and then every A1
+ // formula in the sheet would point two columns off. Position is what a
+ // formula means; an empty column is cosmetic. So the empties stay, and are
+ // reported so nobody thinks dash invented them.
+ const grid: Array<Array<RawCell | undefined>> = []
+ for (const c of cells) {
+ const r = c.row - firstRow
+ ;(grid[r] ??= [])[c.col] = c
+ }
+
+ const headerRow = grid[0] ?? []
+ const head = decideHeader(headerRow, grid, styles, opts.header)
+ const bodyStart = head.start
+ if (bodyStart === 0 && opts.header === undefined) {
+ findings.push({
+ code: 'no-header', sheet: name,
+ message: `"${name}" does not appear to start with a header row (its first row holds values, not labels), so the columns are named by position. Rename them, or re-import telling dash there is a header.`,
+ })
+ } else if (!head.sure && opts.header === undefined) {
+ // The undecidable case, and it costs a ROW OF DATA if we are wrong. Every
+ // column of an all-text sheet looks exactly like its own heading, so there
+ // is no evidence in the file and the honest thing is to say which way it
+ // was resolved rather than to resolve it quietly.
+ findings.push({
+ code: 'no-header', sheet: name,
+ message: `Every column in "${name}" is text, so its first row is indistinguishable from its data. It was taken as a header (which is what it usually is) — if those were values, re-import without one, because a wrong guess here costs a row.`,
+ })
+ }
+
+ let leadingBlank = 0
+ while (leadingBlank < width && !cells.some((c) => c.col === leadingBlank)) leadingBlank++
+ if (leadingBlank > 0 && leadingBlank < width) {
+ findings.push({
+ code: 'leading-blanks', sheet: name,
+ message: `"${name}" starts at column ${colToLetters(leadingBlank)}. The ${leadingBlank} empty column${leadingBlank === 1 ? '' : 's'} before it ${leadingBlank === 1 ? 'was' : 'were'} kept, because every A1 formula in the sheet is written against those positions.`,
+ })
+ }
+
+ const dataRows = grid.slice(bodyStart)
+ const rowCount = Math.max(0, lastRow - firstRow + 1 - bodyStart)
+
+ const columns: Column[] = []
+ const data: Record<string, ColumnData> = {}
+ const overrides: Record<string, CellOverride> = {}
+ const ids = new Set<string>()
+ let leapSeen = false
+ let timeSeen = false
+ let notLive = 0
+ let liveCount = 0
+ const missingFns = new Set<string>()
+
+ for (let ci = 0; ci < width; ci++) {
+ const rawName = bodyStart > 0 ? cellText(headerRow[ci], shared, styles, epoch1904) : ''
+ let colId = slug(rawName, ci)
+ if (ids.has(colId)) {
+ let k = 2
+ while (ids.has(`${colId}-${k}`)) k++
+ findings.push({
+ code: 'duplicate-header', sheet: name, column: rawName,
+ message: `"${name}" has two columns called "${rawName}"; the second is kept separately.`,
+ })
+ colId = `${colId}-${k}`
+ }
+ ids.add(colId)
+ if (bodyStart > 0 && blank(rawName)) {
+ findings.push({
+ code: 'empty-header', sheet: name, column: colId,
+ message: `Column ${colToLetters(ci)} of "${name}" has no name in the header row.`,
+ })
+ }
+
+ const column = Array.from({ length: rowCount }, (_, r) => dataRows[r]?.[ci])
+ const plan = planColumn(column, styles)
+ if (plan.ambiguous) {
+ findings.push({
+ code: 'mixed-types', sheet: name, column: rawName || colId,
+ message: `"${rawName || colId}" mixes kinds of value (${plan.ambiguous}). Imported as text so nothing is lost — set the column type once you have decided what it is.`,
+ })
+ }
+
+ const values: unknown[] = []
+ let lostHere = 0
+ for (let r = 0; r < rowCount; r++) {
+ const cell = column[r]
+ const out = coerceCell(cell, plan, styles, epoch1904)
+ if (out.lost) lostHere++
+ if (out.leap1900) leapSeen = true
+ // A TIME OF DAY, not "any string with a T in it" — which is what this
+ // was, and `Financials` set the flag on a sheet with no dates at all.
+ if (plan.type === 'date' && typeof out.v === 'string' && out.v.includes('T')) timeSeen = true
+ values.push(out.v)
+
+ if (cell?.f !== undefined) {
+ // LIVENESS IS DECIDED ON THE ORIGINAL TEXT, BEFORE ANY SHIFT, and the
+ // order is not cosmetic. Shifting first ran `Sheet2!A1*3` through
+ // a1.ts, which leaves `Sheet2` alone and then dutifully moves the `A1`
+ // after it — off the top of the sheet, into `Sheet2!#REF!*3`. So the
+ // very formula we were refusing to trust got corrupted on its way into
+ // the field that exists to preserve it verbatim.
+ const rid = r + 1
+ const key = `${colId}:${rid}`
+ const live = liveFormula(cell.f)
+ if (live.ok) {
+ // Row references shift by exactly the rows we did not import: the
+ // blank rows above the table plus the header.
+ // `shiftRefsForInsert(..., 0, -k)` is the same call the grid makes
+ // when someone deletes k rows at the top, which is precisely what
+ // happened to this formula's world.
+ const drop = firstRow + bodyStart
+ const moved = drop > 0 ? shiftRefsForInsert(cell.f, 'row', 0, -drop) : cell.f
+ overrides[key] = { ...(overrides[key] ?? {}), f: `=${moved}` }
+ liveCount++
+ } else {
+ // The value stays (it is in `values` already); the source is kept
+ // beside it, EXACTLY as the workbook wrote it, so nothing the author
+ // wrote is lost and a re-export puts it back where it came from.
+ overrides[key] = { ...(overrides[key] ?? {}), xlsxF: `=${cell.f}` }
+ notLive++
+ if ('fn' in live && live.fn) missingFns.add(live.fn)
+ }
+ }
+ }
+
+ if (lostHere) {
+ findings.push({
+ code: 'coerce-failed', sheet: name, column: rawName || colId,
+ message: `${lostHere} value${lostHere === 1 ? '' : 's'} in "${rawName || colId}" could not be read as ${plan.type} and ${lostHere === 1 ? 'is' : 'are'} blank.`,
+ })
+ }
+
+ columns.push({
+ id: colId,
+ name: bodyStart > 0 && !blank(rawName) ? rawName.trim() : `Column ${ci + 1}`,
+ type: plan.type,
+ ...(plan.format ? { format: plan.format } : {}),
+ ...(plan.failed || lostHere ? { failed: lostHere } : {}),
+ ...(widths.has(ci) ? { w: widths.get(ci) } : {}),
+ })
+ data[colId] = { enc: 'raw', v: values as Array<number | string | boolean | null> }
+ }
+
+ if (leapSeen) {
+ findings.push({
+ code: 'date-1900-bug', sheet: name,
+ message: `"${name}" contains serial 60, which Excel displays as 29 February 1900 — a date that does not exist (the 1900 system inherited Lotus 1-2-3's leap-year bug). It was kept as written rather than quietly moved a day.`,
+ })
+ }
+ if (timeSeen) {
+ findings.push({
+ code: 'time-of-day', sheet: name,
+ message: `"${name}" has dates carrying a time of day; they were kept as full ISO date-times so the time is not thrown away.`,
+ })
+ }
+ if (notLive) {
+ const fns = [...missingFns].slice(0, 4).join(', ')
+ findings.push({
+ code: 'formula-not-live', sheet: name,
+ message: `${notLive} formula${notLive === 1 ? '' : 's'} in "${name}" could not be made live${fns ? ` (dash has no ${fns} yet)` : ' (they point at other sheets or external data)'}. The values Excel last calculated are shown, and the formula text is kept with each cell so nothing is lost — a live formula dash cannot evaluate would replace real numbers with #NAME?.`,
+ })
+ }
+
+ return {
+ id, name, kind: 'table',
+ rids: rowCount ? [[1, rowCount]] : [],
+ columns,
+ data,
+ ...(Object.keys(overrides).length ? { cells: overrides } : {}),
+ steps: [{
+ op: 'import',
+ from: opts.source ?? `${name}.xlsx`,
+ at: opts.at ?? '',
+ rows: rowCount,
+ note: liveCount ? `${liveCount} cell formula(s) imported live` : undefined,
+ }],
+ } as TableSheet
+}
+
+/** The displayed text of a cell, for header names. */
+function cellText(
+ c: RawCell | undefined, _shared: string[], styles: Styles, epoch1904: boolean,
+): string {
+ if (!c) return ''
+ if (c.text !== undefined) return c.text
+ const k = kindOf(c, styles)
+ if (k === 'date') return serialToIso(Number(c.v), epoch1904) ?? c.v
+ return c.v
+}
+
+/**
+ * Is the first row a header? Returns where the DATA starts (1 = yes, 0 = no).
+ *
+ * The test is not "row 1 is all strings" — a column of country names is all
+ * strings too. It is that row 1 is all strings AND the rows below it are not,
+ * i.e. row 1 looks different from its column. A sheet that is entirely text has
+ * no evidence either way, and there the header assumption is right far more
+ * often than not (it is what someone typed at the top), so it wins — but the
+ * caller reports the no-header decision when it goes the other way, which is
+ * the case where the reader loses a row of data to a header if we guess wrong.
+ */
+function decideHeader(
+ head: Array<RawCell | undefined>, grid: Array<Array<RawCell | undefined>>,
+ styles: Styles, forced?: boolean,
+): { start: number; sure: boolean } {
+ if (forced !== undefined) return { start: forced ? 1 : 0, sure: true }
+ const filled = head.filter(Boolean) as RawCell[]
+ if (!filled.length || grid.length < 2) return { start: filled.length ? 1 : 0, sure: true }
+ const allText = filled.every((c) => familyOf(kindOf(c, styles)) === 'text')
+ if (!allText) return { start: 0, sure: true }
+ // Any non-text below means row 1 is describing rather than being data, and
+ // that IS evidence.
+ for (let r = 1; r < Math.min(grid.length, 25); r++) {
+ for (const c of grid[r] ?? []) {
+ const f = c ? familyOf(kindOf(c, styles)) : 'blank'
+ if (f !== 'text' && f !== 'blank') return { start: 1, sure: true }
+ }
+ }
+ // Text above text. No evidence at all, and the caller says so.
+ return { start: 1, sure: false }
+}
+
+// --- export ---------------------------------------------------------------------
+
+export interface XlsxExportOpts {
+ /** Timestamp for the ZIP entries. Fixed by default so exports are diffable. */
+ at?: Date
+ /**
+ * sheetId → (columnId → computed values, in canonical row order).
+ *
+ * A FORMULA COLUMN HAS NO STORED VALUES — that is the point of it (model.ts:
+ * storing them would let a file carry a number that disagrees with the
+ * expression that produced it) — so an export that does not receive them
+ * writes blanks and says so. The editor hands `grid.computed` in, exactly as
+ * it does for charts.
+ */
+ computed?: Record<string, Map<string, unknown[]>>
+ /** Skip DEFLATE (rig only). */
+ store?: boolean
+}
+
+export interface XlsxExportResult {
+ bytes: Uint8Array
+ findings: XlsxFinding[]
+}
+
+const MAIN_NS = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'
+const REL_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+const CT = 'http://schemas.openxmlformats.org/package/2006/content-types'
+const DECL = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>'
+
+/**
+ * A sheet name Excel will accept.
+ *
+ * Excel does not warn about a bad sheet name — it refuses to open the file, or
+ * "repairs" it, which is the same thing with an extra dialog. The rules are:
+ * 1–31 characters, none of `[]:*?/\`, not starting or ending with an
+ * apostrophe, and unique within the workbook.
+ */
+function safeSheetName(name: string, taken: Set<string>): string {
+ let s = (name || 'Sheet').replace(/[[\]:*?/\\]/g, '-').replace(/^'+|'+$/g, '').trim()
+ if (!s) s = 'Sheet'
+ s = s.slice(0, 31)
+ if (taken.has(s.toLowerCase())) {
+ let k = 2
+ let t = `${s.slice(0, 28)} ${k}`
+ while (taken.has(t.toLowerCase())) { k++; t = `${s.slice(0, 28)} ${k}` }
+ s = t
+ }
+ taken.add(s.toLowerCase())
+ return s
+}
+
+/** The style table, built as we go: one xf per (format code, bold) pair. */
+class StyleBook {
+ codes: string[] = []
+ xfs: Array<{ fmt: number; bold: boolean }> = [{ fmt: 0, bold: false }]
+ private seen = new Map<string, number>()
+
+ constructor() { this.seen.set('|false', 0) }
+
+ /** The cellXfs index for a format code (`''` = General) and weight. */
+ at(code: string, bold = false): number {
+ const key = `${code}|${bold}`
+ const hit = this.seen.get(key)
+ if (hit !== undefined) return hit
+ let fmt = 0
+ if (code) {
+ const i = this.codes.indexOf(code)
+ fmt = 164 + (i >= 0 ? i : this.codes.push(code) - 1)
+ }
+ const at = this.xfs.push({ fmt, bold }) - 1
+ this.seen.set(key, at)
+ return at
+ }
+
+ xml(): string {
+ const numFmts = this.codes.length
+ ? `<numFmts count="${this.codes.length}">${this.codes.map((c, i) =>
+ `<numFmt numFmtId="${164 + i}" formatCode="${escapeXml(c)}"/>`).join('')}</numFmts>`
+ : ''
+ // The counts and the two fills are not decoration. Excel requires at least
+ // the `none` and `gray125` fills and a `cellStyleXfs` entry; a styles part
+ // missing either is the single most common cause of the repair dialog.
+ return `${DECL}<styleSheet xmlns="${MAIN_NS}">${numFmts}` +
+ '<fonts count="2"><font><sz val="11"/><name val="Calibri"/></font>' +
+ '<font><b/><sz val="11"/><name val="Calibri"/></font></fonts>' +
+ '<fills count="2"><fill><patternFill patternType="none"/></fill>' +
+ '<fill><patternFill patternType="gray125"/></fill></fills>' +
+ '<borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders>' +
+ '<cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs>' +
+ `<cellXfs count="${this.xfs.length}">${this.xfs.map((x) =>
+ `<xf numFmtId="${x.fmt}" fontId="${x.bold ? 1 : 0}" fillId="0" borderId="0" xfId="0"` +
+ `${x.fmt ? ' applyNumberFormat="1"' : ''}${x.bold ? ' applyFont="1"' : ''}/>`).join('')}</cellXfs>` +
+ '<cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles>' +
+ '<dxfs count="0"/></styleSheet>'
+ }
+}
+
+/** The number format a column should carry in Excel. The author's own
+ * `Column.format` wins — model.ts says it is an Excel-style pattern and it is
+ * DOCUMENT data, so passing it through is both correct and free. */
+function formatFor(col: Column): string {
+ if (typeof col.format === 'string' && col.format) return col.format
+ switch (col.type) {
+ // ISO, deliberately: `mm/dd/yyyy` renders as 4 March in half the world and
+ // 3 April in the other half, and the export is what someone else opens.
+ case 'date': return 'yyyy-mm-dd'
+ case 'percent': return '0.0%'
+ case 'money': return moneyFormat(col.unit)
+ default: return ''
+ }
+}
+
+const SYMBOL: Record<string, string> = { USD: '$', GBP: '£', EUR: '€', JPY: '¥', INR: '₹' }
+
+const moneyFormat = (unit: unknown): string => {
+ const u = typeof unit === 'string' ? unit.toUpperCase() : ''
+ const sym = SYMBOL[u]
+ if (sym) return `"${sym}"#,##0.00`
+ return u ? `#,##0.00" ${u}"` : '#,##0.00'
+}
+
+/** Shared-string table, built while the sheets are written. */
+class Strings {
+ list: string[] = []
+ private at = new Map<string, number>()
+ total = 0
+
+ id(s: string): number {
+ this.total++
+ const hit = this.at.get(s)
+ if (hit !== undefined) return hit
+ const i = this.list.push(s) - 1
+ this.at.set(s, i)
+ return i
+ }
+
+ xml(): string {
+ return `${DECL}<sst xmlns="${MAIN_NS}" count="${this.total}" uniqueCount="${this.list.length}">` +
+ this.list.map((s) => `<si><t xml:space="preserve">${escapeXml(s)}</t></si>`).join('') +
+ '</sst>'
+ }
+}
+
+const AGG_FN: Record<string, string> = {
+ sum: 'SUM', avg: 'AVERAGE', count: 'COUNT', min: 'MIN', max: 'MAX',
+}
+
+/**
+ * Write a dash workbook as .xlsx.
+ *
+ * WHAT IS EXPORTED AS A FORMULA AND WHAT IS EXPORTED AS A NUMBER, which is the
+ * one judgement call in here:
+ *
+ * PER-CELL formulas (`CellOverride.f`) go out as formulas. They are already
+ * A1 expressions in Excel's own syntax; the only change they need is a
+ * one-row shift, because dash's row 0 is the first DATA row and Excel's row 1
+ * is the header.
+ *
+ * COLUMN formulas go out as VALUES. A dash column expression names columns by
+ * IDENTITY and evaluates over vectors — `Value / SUM(Value)` is one
+ * expression over a whole column — and Excel has no such thing. Translating
+ * it per row is possible for simple arithmetic and stops being possible the
+ * moment the expression uses anything whose Excel counterpart differs even
+ * slightly. A translation that is right 95% of the time produces a workbook
+ * that is wrong 5% of the time and says nothing, which is the failure mode
+ * this whole codebase is organised against. So the numbers go out, and a
+ * finding says the expression did not.
+ */
+export async function exportXlsx(
+ doc: DashDoc, opts: XlsxExportOpts = {},
+): Promise<XlsxExportResult> {
+ const findings: XlsxFinding[] = []
+ const styles = new StyleBook()
+ const strings = new Strings()
+ const taken = new Set<string>()
+
+ const tables = doc.sheets.filter((s): s is TableSheet => s.kind === 'table')
+ if (!tables.length) {
+ findings.push({ code: 'sheet-skipped', message: 'This workbook has no table sheets to export.' })
+ }
+
+ const sheetXml: string[] = []
+ const names: string[] = []
+
+ for (const sheet of tables) {
+ const name = safeSheetName(sheet.name, taken)
+ if (name !== sheet.name) {
+ findings.push({
+ code: 'renamed-sheet', sheet: sheet.name,
+ message: `"${sheet.name}" was renamed to "${name}": Excel rejects a sheet name over 31 characters or containing []:*?/\\, and refuses to open the file rather than warning.`,
+ })
+ }
+ names.push(name)
+ sheetXml.push(writeSheet(sheet, styles, strings, opts, findings))
+ }
+
+ const parts: ZipEntry[] = []
+ const enc = new TextEncoder()
+ const add = (n: string, s: string) => parts.push({ name: n, data: enc.encode(s) })
+
+ // [Content_Types].xml FIRST — a consumer streaming the package cannot type
+ // any part until it has read this one, and it is the one ordering rule OPC
+ // actually states.
+ add('[Content_Types].xml', `${DECL}<Types xmlns="${CT}">` +
+ '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>' +
+ '<Default Extension="xml" ContentType="application/xml"/>' +
+ '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>' +
+ sheetXml.map((_, i) => `<Override PartName="/xl/worksheets/sheet${i + 1}.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>`).join('') +
+ '<Override PartName="/xl/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml"/>' +
+ '<Override PartName="/xl/sharedStrings.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml"/>' +
+ '<Override PartName="/docProps/core.xml" ContentType="application/vnd.openxmlformats-package.core-properties+xml"/>' +
+ '</Types>')
+
+ add('_rels/.rels', `${DECL}<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+ `<Relationship Id="rId1" Type="${REL_NS}/officeDocument" Target="xl/workbook.xml"/>` +
+ '<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties" Target="docProps/core.xml"/>' +
+ '</Relationships>')
+
+ add('docProps/core.xml',
+ `${DECL}<cp:coreProperties xmlns:cp="http://schemas.openxmlformats.org/package/2006/metadata/core-properties"` +
+ ' xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:dcterms="http://purl.org/dc/terms/"' +
+ ' xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">' +
+ `<dc:title>${escapeXml(doc.title ?? '')}</dc:title>` +
+ `<dc:creator>${escapeXml(String(doc.meta?.author ?? 'bento/dash'))}</dc:creator>` +
+ '</cp:coreProperties>')
+
+ // `fullCalcOnLoad` is why no formula cell needs a cached `<v>`: every
+ // consumer recalculates on open. A cached value we did not compute would be
+ // a number that disagrees with the formula beside it — the exact thing
+ // model.ts refuses to store for formula columns.
+ add('xl/workbook.xml', `${DECL}<workbook xmlns="${MAIN_NS}" xmlns:r="${REL_NS}">` +
+ `<sheets>${names.map((nm, i) =>
+ `<sheet name="${escapeXml(nm)}" sheetId="${i + 1}" r:id="rId${i + 1}"/>`).join('')}</sheets>` +
+ '<calcPr calcId="0" fullCalcOnLoad="1"/></workbook>')
+
+ add('xl/_rels/workbook.xml.rels',
+ `${DECL}<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+ names.map((_, i) => `<Relationship Id="rId${i + 1}" Type="${REL_NS}/worksheet" Target="worksheets/sheet${i + 1}.xml"/>`).join('') +
+ `<Relationship Id="rId${names.length + 1}" Type="${REL_NS}/styles" Target="styles.xml"/>` +
+ `<Relationship Id="rId${names.length + 2}" Type="${REL_NS}/sharedStrings" Target="sharedStrings.xml"/>` +
+ '</Relationships>')
+
+ sheetXml.forEach((x, i) => add(`xl/worksheets/sheet${i + 1}.xml`, x))
+ // styles LAST of the pair, because writing the sheets is what filled it in
+ add('xl/styles.xml', styles.xml())
+ add('xl/sharedStrings.xml', strings.xml())
+
+ return { bytes: await writeZip(parts, { at: opts.at, store: opts.store }), findings }
+}
+
+/** Rows of one sheet. */
+function writeSheet(
+ sheet: TableSheet, styles: StyleBook, strings: Strings,
+ opts: XlsxExportOpts, findings: XlsxFinding[],
+): string {
+ const cols = sheet.columns.filter((c) => !c.hidden)
+ const rows = sheet.rids.reduce((n, [, c]) => n + c, 0)
+ const computed = opts.computed?.[sheet.id]
+ const overrides = sheet.cells ?? {}
+ const rids: number[] = []
+ for (const [start, count] of sheet.rids) for (let i = 0; i < count; i++) rids.push(start + i)
+
+ const headStyle = styles.at('', true)
+ const colStyle = cols.map((c) => styles.at(formatFor(c)))
+
+ const out: string[] = []
+ out.push(`<row r="1">${cols.map((c, i) =>
+ `<c r="${colToLetters(i)}1" s="${headStyle}" t="s"><v>${strings.id(c.name)}</v></c>`).join('')}</row>`)
+
+ for (let r = 0; r < rows; r++) {
+ const cells: string[] = []
+ for (let i = 0; i < cols.length; i++) {
+ const col = cols[i]
+ const rid = rids[r]
+ const over = overrides[`${col.id}:${rid}`]
+ const ref = `${colToLetters(i)}${r + 2}`
+
+ // A per-cell formula: dash's `f`, or the source an import could not make
+ // live (`xlsxF`) — writing the latter back out is what closes the
+ // xlsx → dash → xlsx loop without losing someone's model.
+ const live = typeof over?.f === 'string' ? over.f : undefined
+ const src = live ?? (typeof over?.xlsxF === 'string' ? over.xlsxF : undefined)
+ if (src) {
+ // Down one row — but ONLY for a live formula. `f` is written in dash
+ // coordinates, where row 0 is the first DATA row, so it moves to
+ // Excel's row 2. `xlsxF` is the source text an import could not make
+ // live, kept verbatim in the ORIGINAL workbook's coordinates; shifting
+ // it would run a cross-sheet reference through a1.ts, which cannot see
+ // past the `!` and would silently renumber the other sheet's row.
+ const body = live
+ ? shiftRefsForInsert(src.replace(/^=/, ''), 'row', 0, 1)
+ : src.replace(/^=/, '')
+ // A cached value if dash happens to hold one. It is NOT authoritative —
+ // dash computes a formula cell live and never writes the result back,
+ // so what is stored underneath may be stale — but `fullCalcOnLoad`
+ // means the first thing every consumer does is replace it. Emitting it
+ // is what lets an xlsx → dash round trip keep a formula column's TYPE
+ // instead of reading a column of empty cells as text.
+ const cached = over && 'v' in over ? over.v : readCell(sheet.data[col.id], r)
+ const cachedXml = cached === null || cached === undefined || cached === ''
+ ? '' : cachedValue(cached, col.type)
+ cells.push(`<c r="${ref}" s="${colStyle[i]}"><f>${escapeXml(body)}</f>${cachedXml}</c>`)
+ continue
+ }
+
+ const v = over && 'v' in over ? over.v
+ : computed?.has(col.id) ? computed.get(col.id)![r]
+ : col.formula ? undefined
+ : readCell(sheet.data[col.id], r)
+ const cell = valueCell(ref, colStyle[i], v, col.type, strings)
+ if (cell) cells.push(cell)
+ }
+ if (cells.length) out.push(`<row r="${r + 2}">${cells.join('')}</row>`)
+ }
+
+ for (const col of cols) {
+ if (col.formula && !computed?.has(col.id)) {
+ findings.push({
+ code: 'formula-column', sheet: sheet.name, column: col.name,
+ message: `"${col.name}" is a computed column (${col.formula}) and its values were not available to the export, so it is empty. Excel has no equivalent of a whole-column expression, so the numbers are what travels — export from the editor, where they have been calculated.`,
+ })
+ } else if (col.formula) {
+ findings.push({
+ code: 'formula-column', sheet: sheet.name, column: col.name,
+ message: `"${col.name}" is a computed column (${col.formula}). Excel has no whole-column expression, so its VALUES were exported rather than a per-row translation — a translation that is right most of the time is worse than numbers that are right all of it.`,
+ })
+ }
+ }
+
+ // The totals row. Written as real SUM/AVERAGE formulas over the data range
+ // AND with the value we computed, so it reads correctly before a recalc.
+ let totalsXml = ''
+ if (sheet.totals && Object.keys(sheet.totals).length && rows) {
+ const cells: string[] = []
+ cols.forEach((col, i) => {
+ const spec = sheet.totals![col.id]
+ if (!spec) return
+ const ref = `${colToLetters(i)}${rows + 2}`
+ const range = `${colToLetters(i)}2:${colToLetters(i)}${rows + 1}`
+ if (typeof spec === 'object' && typeof spec.f === 'string') {
+ cells.push(`<c r="${ref}" s="${colStyle[i]}"><f>${escapeXml(spec.f.replace(/^=/, ''))}</f></c>`)
+ return
+ }
+ const fn = AGG_FN[spec as string]
+ if (!fn) return
+ const nums: number[] = []
+ for (let r = 0; r < rows; r++) {
+ const raw = computed?.has(col.id) ? computed.get(col.id)![r] : readCell(sheet.data[col.id], r)
+ const n = typeof raw === 'number' ? raw : Number(raw)
+ if (Number.isFinite(n) && raw !== null && raw !== '') nums.push(n)
+ }
+ const value = fn === 'SUM' ? nums.reduce((a, b) => a + b, 0)
+ : fn === 'AVERAGE' ? (nums.length ? nums.reduce((a, b) => a + b, 0) / nums.length : 0)
+ : fn === 'COUNT' ? nums.length
+ : fn === 'MIN' ? Math.min(...nums) : Math.max(...nums)
+ const shown = Number.isFinite(value) ? value : 0
+ cells.push(`<c r="${ref}" s="${colStyle[i]}"><f>${fn}(${range})</f><v>${shown}</v></c>`)
+ })
+ if (cells.length) totalsXml = `<row r="${rows + 2}">${cells.join('')}</row>`
+ }
+
+ const widths = cols.map((c, i) => typeof c.w === 'number' && c.w > 0
+ ? `<col min="${i + 1}" max="${i + 1}" width="${Math.max(2, (c.w - 5) / 7).toFixed(2)}" customWidth="1"/>`
+ : '').join('')
+
+ const lastRow = rows + (totalsXml ? 2 : 1)
+ return `${DECL}<worksheet xmlns="${MAIN_NS}">` +
+ `<dimension ref="A1:${colToLetters(Math.max(0, cols.length - 1))}${Math.max(1, lastRow)}"/>` +
+ '<sheetViews><sheetView workbookViewId="0"><pane ySplit="1" topLeftCell="A2" activePane="bottomLeft" state="frozen"/></sheetView></sheetViews>' +
+ '<sheetFormatPr defaultRowHeight="15"/>' +
+ (widths ? `<cols>${widths}</cols>` : '') +
+ `<sheetData>${out.join('')}${totalsXml}</sheetData></worksheet>`
+}
+
+/**
+ * The `<v>` to sit beside an `<f>`, for NUMERIC results only.
+ *
+ * A text or boolean result would need its own `t` attribute on the enclosing
+ * `<c>`, which is written before we know the value; and a formula whose result
+ * is text is rare enough that carrying no cached value (and letting
+ * `fullCalcOnLoad` fill it in) costs nothing. Numbers are the case that matters,
+ * because they are what a re-import types the column from.
+ */
+function cachedValue(v: unknown, type: ColumnType): string {
+ if (type === 'date') {
+ const s = typeof v === 'number' ? v : isoToSerial(String(v))
+ return s === null ? '' : `<v>${s}</v>`
+ }
+ const n = typeof v === 'number' ? v : NaN
+ return Number.isFinite(n) ? `<v>${n}</v>` : ''
+}
+
+/** One value cell, or '' for a blank (a blank cell is simply absent in xlsx —
+ * writing `<c r="B7"/>` for every empty cell doubles a sparse sheet). */
+function valueCell(
+ ref: string, style: number, v: unknown, type: ColumnType, strings: Strings,
+): string {
+ if (v === null || v === undefined || v === '') return ''
+ if (typeof v === 'boolean') return `<c r="${ref}" s="${style}" t="b"><v>${v ? 1 : 0}</v></c>`
+ if (type === 'date') {
+ const serial = typeof v === 'number' ? v : isoToSerial(String(v))
+ // A date column with something in it that is not a date keeps the text
+ // rather than becoming a wrong day.
+ if (serial === null) return `<c r="${ref}" s="${style}" t="s"><v>${strings.id(String(v))}</v></c>`
+ return `<c r="${ref}" s="${style}"><v>${serial}</v></c>`
+ }
+ if (typeof v === 'number') {
+ // NaN and Infinity have no XSD double spelling; Excel calls the file
+ // corrupt rather than showing an error, so they go out as error cells.
+ if (!Number.isFinite(v)) return `<c r="${ref}" s="${style}" t="e"><v>#NUM!</v></c>`
+ return `<c r="${ref}" s="${style}"><v>${v}</v></c>`
+ }
+ const s = String(v)
+ // A dash cell can hold a formula ERROR value; it round-trips as an error cell
+ // rather than as the literal text "#DIV/0!".
+ if (/^#(DIV\/0!|VALUE!|REF!|NAME\?|NUM!|N\/A|NULL!|CYCLE!)$/.test(s)) {
+ return `<c r="${ref}" s="${style}" t="e"><v>${escapeXml(s === '#CYCLE!' ? '#REF!' : s)}</v></c>`
+ }
+ return `<c r="${ref}" s="${style}" t="s"><v>${strings.id(s)}</v></c>`
+}
+
+/** A filename for the download. `.xlsx`, never `.xls` — the extension is what
+ * every consumer sniffs first. */
+export const xlsxFileName = (title: string): string =>
+ `${(title || 'Workbook').replace(/[/\\:*?"<>|]/g, '-').slice(0, 80)}.xlsx`
+
+export const _internals = {
+ attrs, attr, elements, element, planColumn, decideHeader, readStyles,
+ readSharedStrings, readSheetCells, resolvePart, safeSheetName, valueCell,
+ clock, lettersToCol,
+}
diff --git a/dash/src/zip.ts b/dash/src/zip.ts
new file mode 100644
index 00000000..cedfa33d
--- /dev/null
+++ b/dash/src/zip.ts
@@ -0,0 +1,346 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// A minimal ZIP reader and writer — the container .xlsx is made of.
+//
+// WHY THIS EXISTS RATHER THAN A DEPENDENCY. The shell ships as one
+// self-contained HTML file and the whole app is ~98 KB compressed. JSZip is
+// ~100 KB and SheetJS is larger than the entire product, so either one doubles
+// the file every user downloads in order to open a format most of them will
+// never touch. What .xlsx actually needs from ZIP is a fraction of the spec: a
+// few dozen small parts, DEFLATE or stored, no encryption, no spanning, no
+// streaming producer. That fraction is this file, and the browser already
+// carries the expensive half — `DecompressionStream`/`CompressionStream`
+// ('deflate-raw') are the same primitives the compressed-shell loader boots on,
+// so the baseline is established and costs us nothing.
+//
+// THE READER TRUSTS THE CENTRAL DIRECTORY, NOT THE LOCAL HEADERS, and that is
+// the single decision that makes a hand-written reader survive real files.
+// A writer that does not know a part's size in advance (every streaming
+// producer — which is most server-side xlsx generators) sets general-purpose
+// bit 3, writes zeroes for crc/sizes in the local header, and appends a data
+// DESCRIPTOR after the compressed bytes. Reading sizes from the local header
+// then yields zero, and the naive fix — scanning forward for the next signature
+// — collides with compressed data that happens to contain those four bytes.
+// The central directory always has the true sizes. The local header is read for
+// exactly one thing: its name and extra-field lengths, which give the offset
+// where the data begins, and which may legitimately DIFFER from the central
+// copy's (Excel itself writes a Zip64 extra field in one and not the other).
+//
+// WHAT IS DELIBERATELY NOT HERE: encryption (an encrypted xlsx must be refused,
+// loudly, not half-read), multi-disk archives (a floppy-era feature), ZIP64
+// WRITING (we would have to be emitting >4 GB from a browser tab, which the
+// document budget rules out long before), and CP437 filename decoding — every
+// part name inside an OPC package is ASCII by specification, so UTF-8 decodes
+// it correctly whether or not the flag bit is set.
+
+/** Thrown for a container that is not a ZIP, or is one we refuse to guess at. */
+export class ZipError extends Error {
+ constructor(message: string) { super(message); this.name = 'ZipError' }
+}
+
+const SIG_LOCAL = 0x04034b50
+const SIG_CD = 0x02014b50
+const SIG_EOCD = 0x06054b50
+const SIG_EOCD64 = 0x06064b50
+const SIG_EOCD64_LOC = 0x07064b50
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+
+// --- CRC-32 -----------------------------------------------------------------
+// Built once, on first use. A ZIP whose CRCs are wrong is a ZIP that `unzip -t`
+// rejects and Excel calls corrupt, and there is no way to notice by eye — which
+// is exactly why the reader verifies them too (see `readZip`).
+
+let CRC_TABLE: Uint32Array | null = null
+
+function crcTable(): Uint32Array {
+ if (CRC_TABLE) return CRC_TABLE
+ const t = new Uint32Array(256)
+ for (let n = 0; n < 256; n++) {
+ let c = n
+ for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1
+ t[n] = c >>> 0
+ }
+ CRC_TABLE = t
+ return t
+}
+
+/** The ZIP/PNG CRC-32 of a byte range. Exported because the rig checks it
+ * against a known vector — a self-consistent wrong CRC would be invisible. */
+export function crc32(b: Uint8Array): number {
+ const t = crcTable()
+ let c = 0xffffffff
+ for (let i = 0; i < b.length; i++) c = t[(c ^ b[i]) & 0xff] ^ (c >>> 8)
+ return (c ^ 0xffffffff) >>> 0
+}
+
+// --- DEFLATE, through the platform -------------------------------------------
+
+const hasCompression = (): boolean => typeof CompressionStream !== 'undefined'
+
+async function through(b: Uint8Array, s: ReadableWritablePair<Uint8Array, Uint8Array>): Promise<Uint8Array> {
+ // A Blob is the shortest route from bytes to a ReadableStream that works
+ // identically in a browser and in node's rigs; `Response.arrayBuffer` is the
+ // shortest route back. Neither allocates more than one extra copy.
+ const out = new Blob([b as BlobPart]).stream().pipeThrough(s as ReadableWritablePair<BufferSource, BufferSource>)
+ return new Uint8Array(await new Response(out as BodyInit).arrayBuffer())
+}
+
+const inflateRaw = (b: Uint8Array): Promise<Uint8Array> =>
+ through(b, new DecompressionStream('deflate-raw') as unknown as ReadableWritablePair<Uint8Array, Uint8Array>)
+
+const deflateRaw = (b: Uint8Array): Promise<Uint8Array> =>
+ through(b, new CompressionStream('deflate-raw') as unknown as ReadableWritablePair<Uint8Array, Uint8Array>)
+
+// --- Reading -----------------------------------------------------------------
+
+export interface ZipEntry {
+ name: string
+ data: Uint8Array
+}
+
+/**
+ * Every part of a ZIP archive, by name.
+ *
+ * A Map rather than an object because part names are attacker-adjacent data:
+ * `__proto__` is a perfectly legal ZIP entry name, and an object keyed by it is
+ * a prototype-pollution hole in a file format people will open from email.
+ */
+export type ZipParts = Map<string, Uint8Array>
+
+const u16 = (v: DataView, at: number): number => v.getUint16(at, true)
+const u32 = (v: DataView, at: number): number => v.getUint32(at, true)
+/** 64-bit little-endian as a JS number. Exact below 2^53, which every real
+ * archive is; beyond it we would already have failed on allocation. */
+const u64 = (v: DataView, at: number): number =>
+ v.getUint32(at, true) + v.getUint32(at + 4, true) * 0x100000000
+
+/** Locate the end-of-central-directory record, searching back over the
+ * (almost always empty) archive comment. */
+function findEocd(v: DataView, len: number): number {
+ const min = Math.max(0, len - 22 - 0xffff)
+ for (let i = len - 22; i >= min; i--) if (u32(v, i) === SIG_EOCD) return i
+ throw new ZipError('this file does not end in a ZIP central directory — it is not an .xlsx')
+}
+
+/**
+ * Read an archive into its parts.
+ *
+ * CRCs ARE VERIFIED. It costs one extra pass over data we have just inflated
+ * anyway, and it converts the entire class of "the file was truncated by a mail
+ * gateway / a partial download / a bad USB stick" from *silently short data*
+ * into a refusal. Silently short data in a spreadsheet importer means a column
+ * that stops early and a total that is wrong by exactly the missing rows, and
+ * nothing on screen says so.
+ */
+export async function readZip(bytes: Uint8Array): Promise<ZipParts> {
+ if (bytes.length < 22) throw new ZipError('this file is too small to be a ZIP archive')
+ const v = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+ const eocd = findEocd(v, bytes.length)
+
+ let count = u16(v, eocd + 10)
+ let cdOffset = u32(v, eocd + 16)
+
+ // ZIP64 — reading only. Both markers must be honoured: an archive with more
+ // than 65535 parts saturates the count, one over 4 GB saturates the offset,
+ // and Excel writes ZIP64 for either. Missing this reads the central directory
+ // from offset 0xFFFFFFFF, i.e. off the end, and the file "is not a ZIP".
+ if (count === 0xffff || cdOffset === 0xffffffff) {
+ const loc = eocd - 20
+ if (loc < 0 || u32(v, loc) !== SIG_EOCD64_LOC) {
+ throw new ZipError('this archive claims ZIP64 sizes but carries no ZIP64 locator')
+ }
+ const at = u64(v, loc + 8)
+ if (u32(v, at) !== SIG_EOCD64) throw new ZipError('the ZIP64 central directory record is missing')
+ count = u64(v, at + 32)
+ cdOffset = u64(v, at + 48)
+ }
+
+ const parts: ZipParts = new Map()
+ let p = cdOffset
+ for (let i = 0; i < count; i++) {
+ if (u32(v, p) !== SIG_CD) throw new ZipError('the ZIP central directory is damaged')
+ const flags = u16(v, p + 8)
+ const method = u16(v, p + 10)
+ const crc = u32(v, p + 16)
+ let csize = u32(v, p + 20)
+ let usize = u32(v, p + 24)
+ const nameLen = u16(v, p + 28)
+ const extraLen = u16(v, p + 30)
+ const commentLen = u16(v, p + 32)
+ let local = u32(v, p + 42)
+ const name = dec.decode(bytes.subarray(p + 46, p + 46 + nameLen))
+
+ // Bit 0 is the 1989 password scheme; bit 6 is AES. Either way the bytes are
+ // not the bytes, and half-reading them would produce garbage that looks
+ // like a parse failure rather than a locked file.
+ if (flags & 1) throw new ZipError(`"${name}" is encrypted — dash cannot open a password-protected workbook`)
+
+ // The ZIP64 extra field replaces exactly the fields that saturated, in a
+ // fixed order, and ONLY those. Reading it positionally without checking
+ // which ones saturated is the classic way to shift every value by 8 bytes.
+ if (usize === 0xffffffff || csize === 0xffffffff || local === 0xffffffff) {
+ let e = p + 46 + nameLen
+ const end = e + extraLen
+ while (e + 4 <= end) {
+ const id = u16(v, e)
+ const size = u16(v, e + 2)
+ if (id === 0x0001) {
+ let q = e + 4
+ if (usize === 0xffffffff) { usize = u64(v, q); q += 8 }
+ if (csize === 0xffffffff) { csize = u64(v, q); q += 8 }
+ if (local === 0xffffffff) { local = u64(v, q) }
+ break
+ }
+ e += 4 + size
+ }
+ }
+
+ if (u32(v, local) !== SIG_LOCAL) throw new ZipError(`"${name}" does not start with a ZIP local header`)
+ // The LOCAL header's own name/extra lengths, never the central copy's:
+ // Excel writes a ZIP64 extra field into one and not the other, and using
+ // the wrong pair starts the data a few bytes early. The symptom is an
+ // inflate error on a file every other tool opens.
+ const dataAt = local + 30 + u16(v, local + 26) + u16(v, local + 28)
+ const raw = bytes.subarray(dataAt, dataAt + csize)
+
+ let data: Uint8Array
+ if (method === 0) data = raw
+ else if (method === 8) {
+ // DecompressionStream rejects with a bare TypeError whose message is
+ // often EMPTY, which is how a damaged file first showed up here: the
+ // caller saw an unnamed exception from somewhere inside a stream and had
+ // nothing to tell the user. Every failure this file can produce has to
+ // arrive as a ZipError naming the part, or the refusal is not a refusal.
+ try {
+ data = await inflateRaw(raw)
+ } catch {
+ throw new ZipError(`"${name}" could not be decompressed — the file is damaged or truncated`)
+ }
+ } else throw new ZipError(`"${name}" uses compression method ${method}, which dash does not implement`)
+
+ if (data.length !== usize) {
+ throw new ZipError(`"${name}" unpacked to ${data.length} bytes but the directory says ${usize} — the file is truncated or damaged`)
+ }
+ if (crc32(data) !== crc) {
+ throw new ZipError(`"${name}" failed its checksum — the file is damaged, and reading it anyway would give you data that is wrong without looking wrong`)
+ }
+ parts.set(name, data)
+ p += 46 + nameLen + extraLen + commentLen
+ }
+ return parts
+}
+
+// --- Writing ------------------------------------------------------------------
+
+export interface WriteOpts {
+ /** Timestamp stamped into every entry. Fixed by default, so two exports of
+ * one workbook are byte-identical and a diff means a real change. */
+ at?: Date
+ /** Skip DEFLATE. Only for the rig and for a browser without CompressionStream. */
+ store?: boolean
+}
+
+/** DOS date/time. 1980-01-01 is the epoch of the field and the safe default —
+ * an all-zero date is out of range and makes some tools print a warning. */
+function dosStamp(d: Date | undefined): { time: number; date: number } {
+ if (!d) return { time: 0, date: 33 } // 1980-01-01 00:00
+ const y = Math.max(1980, d.getFullYear())
+ return {
+ time: (d.getHours() << 11) | (d.getMinutes() << 5) | (d.getSeconds() >> 1),
+ date: ((y - 1980) << 9) | ((d.getMonth() + 1) << 5) | d.getDate(),
+ }
+}
+
+/**
+ * Build a ZIP archive.
+ *
+ * Entries are written in the order given, which for OPC matters more than it
+ * looks: `[Content_Types].xml` must be the FIRST part, because a consumer is
+ * entitled to stream the package and it cannot type any part until it has read
+ * it. Excel tolerates it elsewhere; other readers have not always.
+ *
+ * DEFLATE is skipped when it does not pay (tiny parts, and anything that grew),
+ * and the whole archive falls back to STORED where `CompressionStream` is
+ * missing. A stored ZIP is a completely valid ZIP — just bigger — so an old
+ * browser exports a working file instead of an error.
+ */
+export async function writeZip(entries: ZipEntry[], opts: WriteOpts = {}): Promise<Uint8Array> {
+ const { time, date } = dosStamp(opts.at)
+ const store = opts.store || !hasCompression()
+ const locals: Uint8Array[] = []
+ const central: Uint8Array[] = []
+ let offset = 0
+ let cdSize = 0
+
+ for (const e of entries) {
+ const name = enc.encode(e.name)
+ const usize = e.data.length
+ const crc = crc32(e.data)
+ let method = 0
+ let body = e.data
+ if (!store && usize > 64) {
+ const z = await deflateRaw(e.data)
+ // A part that got BIGGER (already-compressed media, tiny XML) is stored.
+ if (z.length < usize) { method = 8; body = z }
+ }
+
+ const lh = new Uint8Array(30 + name.length)
+ const lv = new DataView(lh.buffer)
+ lv.setUint32(0, SIG_LOCAL, true)
+ lv.setUint16(4, 20, true) // version needed: 2.0 = DEFLATE
+ lv.setUint16(6, 0x800, true) // bit 11: the name is UTF-8
+ lv.setUint16(8, method, true)
+ lv.setUint16(10, time, true)
+ lv.setUint16(12, date, true)
+ lv.setUint32(14, crc, true)
+ lv.setUint32(18, body.length, true)
+ lv.setUint32(22, usize, true)
+ lv.setUint16(26, name.length, true)
+ lv.setUint16(28, 0, true)
+ lh.set(name, 30)
+
+ const ch = new Uint8Array(46 + name.length)
+ const cv = new DataView(ch.buffer)
+ cv.setUint32(0, SIG_CD, true)
+ cv.setUint16(4, 20, true) // version made by
+ cv.setUint16(6, 20, true)
+ cv.setUint16(8, 0x800, true)
+ cv.setUint16(10, method, true)
+ cv.setUint16(12, time, true)
+ cv.setUint16(14, date, true)
+ cv.setUint32(16, crc, true)
+ cv.setUint32(20, body.length, true)
+ cv.setUint32(24, usize, true)
+ cv.setUint16(28, name.length, true)
+ cv.setUint32(42, offset, true)
+ ch.set(name, 46)
+
+ locals.push(lh, body)
+ central.push(ch)
+ offset += lh.length + body.length
+ cdSize += ch.length
+ }
+
+ const eocd = new Uint8Array(22)
+ const ev = new DataView(eocd.buffer)
+ ev.setUint32(0, SIG_EOCD, true)
+ ev.setUint16(8, entries.length, true)
+ ev.setUint16(10, entries.length, true)
+ ev.setUint32(12, cdSize, true)
+ ev.setUint32(16, offset, true)
+
+ return concat([...locals, ...central, eocd])
+}
+
+export function concat(chunks: Uint8Array[]): Uint8Array {
+ let n = 0
+ for (const c of chunks) n += c.length
+ const out = new Uint8Array(n)
+ let at = 0
+ for (const c of chunks) { out.set(c, at); at += c.length }
+ return out
+}
+
+export const _internals = { findEocd, dosStamp, inflateRaw, deflateRaw }
diff --git a/docs/dash-collab.md b/docs/dash-collab.md
new file mode 100644
index 00000000..f0fe06f6
--- /dev/null
+++ b/docs/dash-collab.md
@@ -0,0 +1,531 @@
+# bento/dash collaboration — design, and what it loses
+
+*Design document, August 2026. Status: **engine and rig implemented, and the
+rig is green** (`dash/src/sync/crdt.ts`, `scripts/test-dash-sync.ts` — no open
+convergence failure, §7); session, transport and People panel implemented but
+**not yet mounted by the app** (see "What this
+needs from the rest of dash"). Companion to `docs/collab-design.md`, which is
+the authoritative spec for the wire protocol, the relay and the key chain —
+dash speaks that protocol unchanged. This document covers only what is
+different, which is everything below the wire.*
+
+---
+
+## 1. Why slides' engine does not transfer
+
+`slides/src/sync/crdt.ts` is a good CRDT for a deck: a slide has tens of
+elements, each element is a small flat object with a globally-ish unique id,
+and the whole document fits comfortably in memory twice over. Two of its load-
+bearing assumptions are false for a workbook.
+
+**It diffs whole-document snapshots.** Every commit re-serializes the document
+and compares it to a shadow copy. `store.ts` already measured what that costs
+here — 10 ms per snapshot on a 12.2 MB workbook, most of a frame, paid in the
+frame the user starts typing, and 1.19 GB of live strings for a full undo
+stack. That is why dash's history is typed inverses rather than snapshots, and
+it is why sync cannot be a differ either.
+
+**It keys state per node, and a workbook has a million of them.** Slides
+assigns every element a fractional order key and a birth stamp at adopt time.
+A 1M-row sheet doing the same would carry ~1M order keys and ~1M stamps — in
+memory, and in the FILE, since `collab.sync` is stamped into the saved
+document. The entire columnar-plus-dictionary encoding exists to get a cell
+down to 4.8 bytes; a sync layer costing 40 bytes a row would undo it.
+
+So dash's engine is built on two rules that slides does not need:
+
+> **Ops are minted from patches, never from a diff.**
+> **State is O(edits), never O(rows).** A row nobody has touched costs zero
+> bytes. A cell nobody has written costs zero bytes.
+
+The first rule was free, because `store.ts` already predicted it: *"The same
+Patch objects are the undo entries, the future CRDT ops and the agent API."*
+A `Patch` is a complete, position-independent description of one mutation, and
+`setCells` is already keyed by **rid**, not by row position. That is the single
+luckiest fact in this design.
+
+---
+
+## 2. Node identity
+
+| node | id | why |
+|---|---|---|
+| the document | `@doc` | title, meta, theme, measures, names, views |
+| a sheet | `s␟<sheetId>` | |
+| a column | `c␟<sheetId>␟<colId>` | column ids are **sheet-scoped** (`model.ts` is explicit: two sheets may both call a column `c1`), so a bare id is not identity |
+| a row | `r␟<sheetId>␟<rid>` | rids are minted at insert and **never reused** (`rowcol.ts` is emphatic), which is exactly what makes them usable as identity |
+
+`␟` is U+001F. It cannot occur in a sheet or column id: import mints column ids
+by slugging headers, and `parseDoc` repairs anything it cannot claim.
+
+This is slides' composite-key lesson applied before it could bite. Slides
+shipped v1 keyed by bare element id, discovered that the same id on many slides
+is the *core morph idiom*, and had to version the wire format to fix it. dash
+composites from commit one.
+
+**A cell is not a node.** A cell is a PROPERTY of its row, keyed by column id:
+the register `r␟s1␟7 ⟹ v␟price` is the cell at row 7, column `price`. That
+gives per-cell last-writer-wins out of exactly the same (lamport, actor)
+register machinery slides uses for `x` and `fill`, with no new algebra and no
+per-cell state until somebody writes a cell. Cell *overrides* (the `cells`
+overlay) are a second key space on the same node, `o␟price`.
+
+---
+
+## 3. Patches → ops
+
+| store patch | op | granularity |
+|---|---|---|
+| `setCells` | `cell` (many rids, one column) | **per cell**, LWW by (lamport, actor) |
+| `setOverrides` | `ovr` | **per cell**, whole-override-object LWW |
+| `insertRows` | `rins` (rids + fractional keys + values) | per row |
+| `deleteRows` | `rdel` | per row, tombstone |
+| `addColumn` | `ins` (metadata) **+** `cell` (its values) | per column |
+| `removeColumn` | `del` | tombstone |
+| `reorderColumns` | `ord` per moved column | fractional key |
+| `setColumn` | `set` per key | **per property** |
+| `setSheetProps` | `set` per key (a `drop` becomes `v` absent) | **per property** |
+| `setMeasure` | `set` on `measures.<name>` | **per measure** |
+| `setTitle` | `set` on `title` | whole value |
+| `applySteps`, `refreshBinding` | — | not expressible; the session ships a state snapshot instead of dropping the edit |
+
+Two details in that table are load-bearing.
+
+`setCells` carries `dictLen`, which truncates a dictionary the edit grew. It is
+**stripped** when minting: it is a local undo artefact, and applying it to a
+peer would truncate a dictionary of a different length. Values are the wire
+format; dictionary indices never travel.
+
+A **column insert carries no values**. Its values follow as an ordinary `cell`
+op in the same commit. While a column payload assigned cells, every cell had
+two possible owners — the column's payload and the row's — and the rig kept
+finding deliveries where two replicas disagreed about a number. One writer per
+cell, decided by one register, is worth its cost. That cost is real and stated
+in §6.
+
+---
+
+## 4. Row order: a fractional index over rids
+
+Row order is data ("in a spreadsheet, order is data" — `store.ts`), so it needs
+a real sequence CRDT, and the cheap ones do not fit. Three designs were tried;
+the rig killed two.
+
+1. **`rids` as a whole-value LWW register.** Simple, converges, and silently
+ drops one side's rows whenever two people edit structure at once. Rejected:
+ this is precisely the class of loss the app exists to refuse.
+2. **An RGA whose inserts name an ANCHOR RID**, with deleted anchors resolved
+ by walking back to the anchor's own anchor. Position-preserving and cheap —
+ and wrong: the walk lands a row ahead of rows that used to sit between the
+ anchor and its predecessor, so two replicas that applied the deletes in
+ different orders disagreed. Found on seed 16 of a 20-seed run.
+3. **A fractional index** (shipped). Every row has an order key; order is
+ `sort by (key, rid)`, a pure function of converged state. A neighbour may
+ die without moving anything, because the key already sits between the
+ survivors — no tombstones, no chains.
+
+The trick that makes it affordable: **most rows never get a key.** A row that
+came with the file takes its key from its position in the adopted baseline
+sequence (`base`, one run-length list per sheet — 20 bytes for 4200 rows).
+Only an INSERTED row stores an explicit key. Cost: O(inserts) + O(sheets).
+
+Minted keys are suffixed with the author's actor id. Two replicas inserting
+between the same neighbours compute the same midstring, and with equal keys the
+sequence each replica materialises depends on which rows it happened to hold —
+it stops being sorted, and every later binary search lands somewhere else (seed
+42). The suffix makes every key unique, so the sequence is sorted by
+construction everywhere.
+
+---
+
+## 5. Concurrent structural edits
+
+**Two people insert rows at the same place.** Both rows survive, ordered by
+(key, rid). Deterministic, and the same on every replica.
+
+**Insert vs delete of the neighbour.** The insert keeps its place; the deleted
+row leaves. The fractional key does not care that its neighbour died.
+
+**Delete vs edit of the same row.** Delete wins (standard, predictable, and the
+same rule slides ships). The edit's register still advances, so states converge.
+
+**Undo of a row delete** is a fresh insert carrying the row's values, which
+resurrects the row by out-stamping its tombstone. Values written by others
+during the row's dead window are parked and replay if they out-stamp the
+resurrection.
+
+**Two people undo the same row delete.** The higher (lamport, actor) wins, and
+its insert decides two separate things: where the row sits (its order key) and
+what the row's payload says about each column it NAMES. Both are absolute —
+a replica that had already put the row back at the loser's key MOVES it, and
+a replica that had already applied the loser's payload takes the winner's.
+
+A column the winning insert does **not** name is untouched by it. The two
+undoers' documents need not hold the same columns (one may not have heard of a
+column the other has), so an insert can only ever claim what it carried; for
+everything else the cell's last writer still stands. Both halves of that rule
+were bugs before they were rules — see §7.
+
+**Two people add columns.** Both survive; order by fractional key.
+
+**Column delete vs edits inside it.** Delete wins. See §6.
+
+**Sheet delete vs anything inside it.** Delete wins, coarsely. See §6.
+
+---
+
+## 6. What loses data
+
+This is the section to read twice. Everything here is a **documented
+limitation**, not a bug: each one is deterministic (every replica loses the
+same thing) and each one is a deliberate trade against a cost named beside it.
+
+### 6.1 A cell override is a whole-object register
+
+`{note, bg, bold, align, color, why, by}` is ONE register. Two people
+annotating the same cell — one sets a note, the other a colour — and one of
+the two edits is lost silently. Cell VALUES do not have this problem; only the
+override overlay does. Fixable later by making the override per-key like
+`measures.<name>`, at the cost of more registers per annotated cell.
+
+### 6.2 Deleting a column loses concurrent edits to it
+
+A column's death is final for its values. Writes to it during the delete's
+flight are dropped (their registers still advance, so replicas agree); undoing
+the delete restores the values **the undoer had**, and nobody else's.
+
+Re-adding the column is a whole-column assignment, so it also out-stamps every
+write older than itself, wherever that write is being held — in the document, in
+a parked stash entry, or in an op still waiting on the buried column. All three
+readers apply the same rule (`resetColumnValues`, `reconcileParked` and
+`replayStashRow`); the last of those did not, and that was the seed-307 bug.
+
+The converse is equally load-bearing and cost two more bugs (§7): a write NEWER
+than the assignment survives it, and the parked copy is the only record of it
+that its own AUTHOR has — every other replica still holds the op itself, queued
+on the buried column. So nothing may overwrite a parked entry that outranks it.
+
+This is the one place dash refuses to be clever, deliberately. Cell values live
+in the document, not in the sync layer, so a resurrected column could only come
+back full if each replica restored what IT happened to hold — and no two
+replicas hold the same thing, so they came back different. Every attempt to
+reconcile those private copies grew another ordering rule and another rig
+failure. Delete-wins is convergent and explicable; "everyone keeps their own
+version" is neither.
+
+### 6.3 Deleting a sheet beats everything inside it
+
+Ops for a dead sheet's rows and columns are book-kept (registers, births and
+tombstones advance so the states converge) and otherwise discarded. Undoing a
+sheet delete restores the sheet **as the deleter saw it**; concurrent edits
+made elsewhere in that window are gone.
+
+The alternative is a cascade tombstone per row, which is O(rows) in the op, in
+memory and in the file — the exact cost this design exists to avoid.
+
+### 6.4 Undo under collaboration
+
+Two prices, both inherited and both real.
+
+*It can revert a collaborator's edit.* Undo replays the inverse patch built
+when you made the change, and that inverse restores the value it displaced —
+which may since have been overwritten by someone else. Same compromise slides
+documents.
+
+*It no longer shrinks a dictionary back.* `setCells`'s inverse carries
+`dictLen`, and `applyPatch` honours it by truncating the column's dictionary to
+the length the edit found. That is exact for one writer and unsound for two: a
+peer's write interns ITS strings into the same dictionary above that watermark,
+so the truncation strands them and every cell pointing at one reads back null —
+on the undoing replica alone, with no register moving, which is a divergence
+rather than a lost undo. `local()` therefore deletes `dictLen` from the patch
+before the store sees it. The cost is the orphaned strings, which store.ts
+already calls "semantically right and no longer byte-identical"; a live session
+had given up byte-identical dictionaries anyway, since two replicas intern in
+the order their ops arrive. This was the seed-124 bug.
+
+*It can be refused outright.* An inverse names rows and columns that may no
+longer exist, and `committable()` (crdt.ts) refuses patches that name what is
+not there. Without that refusal the local store applies the patch anyway — it
+has no idea what a peer deleted — while every peer's engine gates it, so the
+edit lands on exactly one replica. A refused inverse costs one undo step; the
+alternative costs the numbers.
+
+### 6.5 Row ORDER after an offline fork merge
+
+Two copies edited offline and merged by snapshot exchange (rather than by op
+log) reconcile their row order by a symmetric interleave — an element only one
+side has goes first, and a genuine conflict breaks on (birth stamp, rid). Both
+sides land on the same order; it is not necessarily the order either side
+intended. Op-based sessions are unaffected: they order by key.
+
+Two copies adopted at *different points* in a file's history disagree about
+which rows were baseline. Their baselines are merged (symmetrically) so both
+derive the same keys, but a third replica that never merged may order those
+rows differently until it exchanges a snapshot too.
+
+### 6.6 Bulk column adds cost one register per cell
+
+Because a column insert carries no values (§3), adding a fully-populated column
+mints one cell register per value — a 100k-row column costs ~100k register
+entries in the sync state, and in `collab.sync` if the file is saved during the
+session. Bulk data arrives through IMPORT in practice, and import creates a
+whole SHEET, whose insert carries its rows wholesale for one op.
+
+The session refuses to stamp a sync state larger than `SYNC_STAMP_BUDGET`
+(2 MB) into the file. Such a copy rejoins as a fresh adopt: it loses two-way
+fork merge and loses nothing else.
+
+### 6.7 Ops too large for the relay
+
+A sheet insert carries the whole sheet. Past the relay's frame ceiling it is
+refused, the session drops those exact ops from the resend log (or they loop
+forever), and the user is told. The local document keeps the change; peers
+never see it. Sharing a workbook whose import exceeds the frame budget means
+sending the file, not the ops.
+
+### 6.8 Packed columns do not participate
+
+`enc:'pack'` is an author-chosen archive encoding that `store.ts` refuses to
+write into. Row inserts and deletes do not maintain it, so a sheet holding a
+packed column should not be edited structurally under collab. Pre-existing in
+the store; named here because collab makes it easier to hit.
+
+### 6.9 Canvas sheets sync only wholesale
+
+`CanvasSheet.cells` has no patch op in `store.ts`, so nothing can express a
+canvas edit as an op. Canvas sheets travel in sheet inserts and snapshots only.
+The register scheme is reserved (`cell.<A1>` keys on the sheet node) so this is
+additive when the patches exist.
+
+### 6.10 `steps` is a whole-array register
+
+`setSheetProps` refuses `steps` (it is structural), so the transform chain
+travels only in sheet payloads and snapshots. Two people appending different
+steps concurrently is not expressible today.
+
+---
+
+## 7. Convergence rig
+
+`node scripts/test-dash-sync.ts`, modelled on `scripts/test-sync.ts`.
+`SEEDS` (a COUNT, default 60) / `STEPS` (160) / `ACTORS` (3) / `SEED_ONLY` /
+`DBG_NODE` / `DIFF_WIDTH` / `TRACE_SHAPE` / `TRACE_ORDER`. Write the assignments
+INLINE — zsh does not word-split an unquoted `$cfg`, so `env $cfg node …` passes
+the whole string as one variable name and silently applies only the first. If two
+different configurations report the same check count, the variables are not
+reaching the rig.
+
+N simulated replicas mutate through the SAME patches the editor commits, ops
+travel over per-(from,to) FIFO queues in random interleavings, and at
+quiescence every replica's materialized workbook AND sync state must be
+identical. Plus targeted cases: per-cell LWW, dictionary interning, the row
+index (concurrent inserts at one place, insert beside a row someone deleted),
+delete-wins, undo resurrection with a dead-window edit, column add/remove/
+reorder, rid-aligned column data, sheet delete, gap buffering, log catch-up,
+two-way snapshot merge of offline forks, and the five hand-built cases named in
+the closed-seed accounts below (a column re-added by undo out-stamping a value
+parked in its dead window; undo not truncating a dictionary a collaborator grew;
+a row resurrected twice taking the winning insert's place; a second
+resurrection that does not name a column keeping its value; a row insert not
+clobbering a newer value parked for a buried column).
+
+It also asserts, after every single apply on every replica, that **every column
+array is exactly as long as the sheet has rows** — columnar storage addresses
+cells by position, so a column one entry short returns the next row's number
+for every row below the gap, silently. That check found a real store bug (§8).
+
+`TRACE_ORDER=1` adds the second structural invariant, after every apply: **a
+sheet's `rids` is sorted by (order key, rid)**. That is the fractional index's
+whole contract, and `rowIndexFor` is a binary search that assumes it. One row
+left at a stale key does not merely sit in the wrong place — it makes every
+later insert on that replica land arbitrarily, which is how a single missed
+move becomes a wholly different row order. It is off by default because it
+costs a scan per apply; run it whenever anything touches row placement.
+
+Status (all measured on the current engine):
+
+| configuration | result |
+|---|---|
+| `SEEDS=200 STEPS=200 ACTORS=3` | ALL PASS (23,660 checks) |
+| `SEEDS=300 STEPS=250 ACTORS=4` | ALL PASS (24,660 checks) |
+| `SEEDS=800 STEPS=300 ACTORS=4` | ALL PASS (27,660 checks) |
+| `SEEDS=400 STEPS=300 ACTORS=5` | ALL PASS (26,060 checks) |
+| `SEEDS=200 STEPS=250 ACTORS=6` | ALL PASS (24,860 checks) |
+| `SEEDS=600 STEPS=400 ACTORS=6` | ALL PASS (28,860 checks) |
+| `SEEDS=1000 STEPS=250 ACTORS=6` | ALL PASS (32,860 checks) |
+| `SEEDS=120 STEPS=300 ACTORS=7` | ALL PASS (24,300 checks) |
+| `TRACE_ORDER=1 SEEDS=100 STEPS=300 ACTORS=7` | ALL PASS (24,060 checks) |
+| `TRACE_ORDER=1 SEEDS=300 STEPS=400 ACTORS=8` | ALL PASS (27,060 checks) |
+
+**No open failure class.** Every seed named below is closed, and each has a
+hand-built deterministic case in the rig rather than a seed number, verified to
+fail when — and only when — its own fix is reverted.
+
+**Seeds 124 and 307.** They looked like one failure class and were two, both
+invisible in the sync state (registers, births, tombs, positions and version
+vectors all agreed on both sides; only the workbook differed by a cell).
+
+* **124 was not a dead-window bug at all** — the column in question was never
+ deleted. It was `dictLen`: an undo truncating a dictionary a collaborator had
+ grown, blanking cells the undoer never touched. See §6.4.
+* **307 was** the column dead window, in `replayStashRow`: a parked value was
+ weighed only against the ROW's rebirth, never against the COLUMN's, so the
+ replica whose row came back AFTER the column's undo restored a number that
+ every replica reaching the same rebirth through `resetColumnValues` had
+ correctly blanked. See §6.2.
+
+**Seed 116 — row ORDER diverged at six actors.** Three replicas materialised
+three different sequences while every register agreed. `applyRins`'s
+already-here branch recorded the winning insert's order key and left the row
+sitting where the LOSING insert had put it. Two actors resurrecting one row
+produce two inserts; a replica that received the loser first has the row in the
+document when the winner arrives and took that branch, while a replica that
+received the winner first placed the row by binary search at the winning key and
+discarded the loser at the "an older create" gate. Same `rpos` on both, two
+sequences — and then the first replica's `rids` was no longer sorted, so every
+later insert compounded it. The branch now MOVES the row (`relocateRow`,
+rebuilding the column arrays through `permuteRows`, since a row's values are
+addressed by position). Six actors were needed because it takes two concurrent
+resurrections of one row plus a later insert to become visible.
+
+**Seeds 374 and 184 — a value dropped by everyone except the second
+resurrector.** A row resurrected twice: the first insert's payload named a
+column, the second's (from an actor who had not yet heard of that column) did
+not. `rnamed` holds only the CURRENT birth's claim, so the winning insert erased
+the record that the first had ever claimed the column; the parked value's
+authority — the first birth — became unrecognisable, `cellAuth(…, fromRow:false)`
+returned the bare cell register (or nothing at all, when the value had only ever
+arrived in a row payload), the stale guard saw two different stamps and dropped
+it. The author of the second resurrection kept the number because it had never
+parked a copy. **The minority replica was right**: an insert makes no claim on a
+column it does not name, so nothing superseded the value. `replayStashRow` and
+`reconcileParked` now weigh a non-claiming rebirth against the PARKED stamp, and
+only something strictly newer displaces it.
+
+**Seed 163 — the same family, found while sweeping the two above.** A write is
+parked at its row's death; the row is then resurrected by an insert whose
+payload names that column while the column itself is buried, and the "park what
+the insert carried" loop overwrote the newer entry with the insert's own older
+value. Every replica but one recovers anyway, because the write reached them
+while the column was dead and is still queued on the column node — but its
+AUTHOR applied it straight into a live document and the parked copy was its only
+record, so the author alone lost it. Both park loops (`applyRins`'s and
+`settle`'s local twin) now refuse to clobber an entry that outranks the insert,
+the rule `parkColumn` has always carried.
+
+---
+
+## 8. What this needs from the rest of dash
+
+None of these are in this task's ownership. Each is small, and each closes a
+real hole rather than a stylistic one.
+
+### store.ts
+
+1. ~~**A patch hook.**~~ **DONE.** `store.beforePatch(fn)` is called from
+ `commit`, `runEdit` and `invert` with the patches about to be applied and
+ may replace the list; `store.afterPatch(fn)` is the other half, since the
+ CRDT mints from the PRE-state and settles once the document has moved.
+ `invert` passes `substitute: false` — a hook may refuse a patch it cannot
+ express, and dropping one there would apply half an inverse and leave the
+ undo stack describing a document that no longer exists.
+
+ Undo and redo therefore ship as OPS now rather than a whole state snapshot.
+ Measured in two tabs: an edit broadcasts one `ops` frame, the undo
+ broadcasts one `ops` frame, and the peer follows both.
+
+2. ~~**`insertRows` must clamp the write.**~~ **DONE.** `applyPatch` clamps the
+ write index to the splice position, so an `at` past the end no longer leaves
+ a hole and a column longer than the sheet has rows. It was reachable without
+ collab too — `window.bento.commit` is a public API.
+
+3. ~~**`deleteRows` should take the row's overrides with it**~~ **DONE.**, as
+ `rowcol.deleteRowsAt` does. The inverse of `insertRows` is a bare
+ `deleteRows`, so undoing an insert orphans any override added to the row in
+ the meantime — on the undoing replica only, since the engine strips them
+ everywhere else.
+4. ~~**`setOverrides`' inverse should carry `dropEmpty`.**~~ **DONE.** Undoing the removal of
+ the last override leaves `cells: {}` behind on the undoing replica while
+ every peer receives it through a path that drops the container. Twelve bytes
+ in the file, and a diverged document. The engine normalises it; the store
+ should not create it.
+5. ~~**A public "changed underneath you" event.**~~ **DONE** — `store.changedRemotely()`. Remote ops are applied
+ surgically and must not enter undo history, so the session cannot use
+ `commit`; it currently calls the private `emit`.
+
+### model.ts
+
+6. **Partitioning the rid space by actor.** Half of this has landed: `sheet.nextRid`
+ is a durable monotonic watermark now (`store.ts` raises it on every structural
+ edit, `rowcol.nextRidFloor` reads it, and `crdt.settleWatermark` joins the two
+ replicas' values with MAX at every settle point, since a plain counter does not
+ converge). What is still open is the concurrent case the watermark cannot
+ reach: two replicas inserting at the same time both mint the next rid, for
+ DIFFERENT rows, and rid is identity. **This must land before collab is
+ enabled**; it is the one item on this list that is a correctness precondition
+ rather than an improvement. The rig sidesteps it by giving each replica its
+ own rid range.
+
+### main.ts
+
+7. Construct the session, mount the panel, connect on eligibility, and stamp
+ the state on save — about six lines:
+ `const sync = new SyncSession(store)`, `mountPeople(el, sync, store)`,
+ `if (sync.shareEligible()) joinFromDoc(sync, store)`,
+ `sync.stampInto(store.doc)` before serializing, and `sync.setSheet(id)` when
+ the visible sheet changes.
+
+---
+
+## 9. What is reused, and what is a port
+
+`docs/collab-design.md` is the spec for all of it; dash speaks the same wire
+format, so ONE relay serves both apps.
+
+**Reused unchanged (protocol and semantics):** the room-id commitment to the
+owner pubkey (`w` + b64url(SHA-256(pub))), the owner→invite→member signature
+chain, per-socket verification, owner-signed revocation, the AES-GCM frame
+envelope, `?tok` possession proof, the 25-second keepalive ping and its
+fast-reconnect, refusal handling, the memory-only replay bookmark, the
+BroadcastChannel same-machine transport, the hello/need/ops/p/bye/snap frames,
+and dormant-until-shared eligibility.
+
+**Ported, not imported:** `online.ts`. Slides' module reaches into slides'
+store, model and update modules, so importing it would pull the whole slides
+app into dash's bundle. PLATFORM §9 already names this: the collab engine and
+relay are "shared but NOT yet in kernel/", and genericizing them is its own
+project. When that project happens, these two files are the callers to
+reconcile.
+
+**Written for dash:** the engine (`crdt.ts`), the patch tap and snapshot policy
+(`session.ts`), and the People panel (`people.ts`).
+
+---
+
+## 10. Public surface
+
+```ts
+// dash/src/sync/crdt.ts
+class DashSync {
+ constructor(actor: string)
+ adopt(doc: DashDoc): void // a document that has never synced
+ local(doc: DashDoc, patches: Patch[]): Op[] // BEFORE the store applies them
+ settle(doc: DashDoc): ApplyResult // AFTER the store applies them
+ apply(doc: DashDoc, ops: Op[]): ApplyResult // remote ops, applied surgically
+ mergeSnapshot(doc, rdoc, rstate): ApplyResult // offline fork / late joiner
+ missingFor(log: Op[], vv): Op[] // peer catch-up
+ toJSON(): SyncStateJSON
+ static fromJSON(actor, j): DashSync
+ get gappedActors(): string[]
+ dead(node: string): boolean
+ unsynced: boolean // a patch it could not express
+}
+function committable(doc: DashDoc, p: Patch): boolean // refuse before minting
+```
+
+The ordering contract is the only sharp edge: `local()` runs **before** the
+store applies the patches (it has to read what a delete displaces, and its
+`prev`/anchor bookkeeping only makes sense against the pre-state), and
+`settle()` runs **after** (parked remote ops may have been waiting for exactly
+what the user just did). `apply()` handles both halves itself.
diff --git a/scripts/postbuild-compress.mjs b/scripts/postbuild-compress.mjs
index abce1f8e..cb748909 100644
--- a/scripts/postbuild-compress.mjs
+++ b/scripts/postbuild-compress.mjs
@@ -53,10 +53,18 @@ const modRe = /<script type="module"[^>]*>([\s\S]*?)<\/script>/
const mod = html.match(modRe)
if (!mod) throw new Error('module script not found')
-// the FIRST big <style> is the app css; the splash <style> lives in body
-const styleRe = /<style[^>]*>([\s\S]*?)<\/style>/
+// The app css. Vite emits it as `<style rel="stylesheet" crossorigin>`, and we
+// match THAT rather than "the first <style> in head" — the module script is
+// inlined into the head too, so any app whose source builds a `<style>` string
+// (dash's thumbnail preview does) had its own string matched first. The whole
+// runtime stylesheet was then left uncompressed and unregistered, and the app
+// booted with no CSS at all. esbuild constant-folds `\`<${'style'}>\`` straight
+// back to a literal, so this cannot be worked around in the app source.
const headPart = html.slice(0, html.indexOf('</head>'))
-const styleM = headPart.match(styleRe)
+const linkedRe = /<style[^>]*\brel="stylesheet"[^>]*>([\s\S]*?)<\/style>/
+const styleM = headPart.match(linkedRe)
+ // Fallback for a build that does not carry the attribute; unchanged behaviour.
+ ?? headPart.match(/<style[^>]*>([\s\S]*?)<\/style>/)
if (!styleM) throw new Error('app stylesheet not found in head')
const js = mod[1]
diff --git a/scripts/test-dash-a1.ts b/scripts/test-dash-a1.ts
new file mode 100644
index 00000000..c3ca6435
--- /dev/null
+++ b/scripts/test-dash-a1.ts
@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash A1 addressing rig.
+//
+// node scripts/test-dash-a1.ts
+//
+// WHAT THIS PROVES. dash's COLUMN formulas cannot produce `#REF!`: they name a
+// column by identity, so structural edits move nothing. A1 references
+// reintroduce the whole class, and every failure in it is a plausible number
+// rather than a crash:
+//
+// 1. A REFERENCE THAT DOES NOT MOVE. Insert a row above `A5` and it must be
+// `A6`. If it stays `A5` it now reads the inserted blank row — a total
+// that is short by one row and looks entirely normal.
+// 2. A DEAD REFERENCE THAT STAYS ALIVE. Delete row 5 and `A5` must become
+// `#REF!`, NOT keep pointing at whatever slid up into that position. This
+// is the headline check: the wrong answer here is another customer's
+// number in your invoice.
+// 3. `$` MISREAD. `$A$1` must NOT move under fill and MUST move under insert.
+// Both halves are asserted, because implementations get exactly one of
+// them right.
+// 4. A LABEL TREATED AS AN ADDRESS. `="A1 is "&A1` shifted a row is
+// `="A1 is "&A2`. Text inside quotes is not a reference, and neither is
+// `LOG10(`, `Sheet1!` or `[REV2024]`.
+// 5. THE 27th COLUMN. Plain base-26 puts `BA` where `AA` belongs, and nobody
+// notices until a workbook is 27 columns wide.
+
+import {
+ colToLetters, lettersToCol, parseRef, formatRef, parseRange, formatRange,
+ expandRange, translateRef, rewriteFormulaRefs, shiftRefsForInsert,
+ REF_ERR, RANGE_CELL_MAX, type CellRef,
+} from '../dash/src/a1.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+// ------------------------------------------------------- column letters
+ok(colToLetters(0) === 'A' && colToLetters(25) === 'Z', '0 is A, 25 is Z')
+ok(colToLetters(26) === 'AA', '26 is AA — bijective base-26, the 27th column')
+ok(colToLetters(26) !== 'BA', 'and NOT BA, which plain base-26 would give')
+ok(colToLetters(701) === 'ZZ' && colToLetters(702) === 'AAA', '701 is ZZ, 702 is AAA')
+ok(lettersToCol('A') === 0 && lettersToCol('Z') === 25, 'letters back to 0 and 25')
+ok(lettersToCol('AA') === 26, 'AA is 26, not 27 — there is no zero digit')
+ok(lettersToCol('ZZ') === 701 && lettersToCol('AAA') === 702, 'ZZ and AAA')
+ok(lettersToCol('aa') === 26, 'letters are case-insensitive')
+
+{
+ // the whole point of a bijective encoding: it round-trips at EVERY index,
+ // including the ones either side of each carry (25/26, 701/702)
+ let bad = -1
+ for (let i = 0; i <= 1000; i++) {
+ if (lettersToCol(colToLetters(i)) !== i) { bad = i; break }
+ }
+ ok(bad < 0, 'colToLetters → lettersToCol round-trips for every index 0..1000')
+
+ // and no two indices share a spelling — the failure a non-bijective scheme
+ // actually produces
+ const seen = new Set<string>()
+ for (let i = 0; i <= 1000; i++) seen.add(colToLetters(i))
+ ok(seen.size === 1001, 'and all 1001 spellings are distinct')
+}
+
+ok(colToLetters(-1) === '' && colToLetters(1.5) === '', 'a non-index has no letters')
+ok(lettersToCol('') === -1 && lettersToCol('A1') === -1 && lettersToCol('$A') === -1,
+ 'anything that is not letters is -1, not NaN — NaN would compute a plausible ref')
+
+// -------------------------------------------------------------- parseRef
+{
+ const a1 = parseRef('A1')!
+ ok(a1.col === 0 && a1.row === 0, 'A1 is {col:0,row:0} — rows are 0-BASED here')
+ ok(!(a1.row === 1), 'the 1 in A1 is display, and is not stored')
+ ok(!a1.absCol && !a1.absRow, 'A1 is relative in both axes')
+}
+{
+ const r = parseRef('$A$1')!
+ ok(r.absCol && r.absRow && r.col === 0 && r.row === 0, '$A$1 is absolute in both')
+ ok(parseRef('A$1')!.absRow && !parseRef('A$1')!.absCol, 'A$1 pins the row only')
+ ok(parseRef('$A1')!.absCol && !parseRef('$A1')!.absRow, '$A1 pins the column only')
+}
+{
+ const r = parseRef('bc12')!
+ ok(r.col === lettersToCol('BC') && r.row === 11, 'lowercase parses')
+ ok(parseRef('$b$2')!.absCol && parseRef('$b$2')!.absRow, 'and so does lowercase with $')
+}
+ok(parseRef('A0') === null, 'A0 is not a cell — rows start at 1 on the page')
+ok(parseRef('A') === null && parseRef('1') === null && parseRef('') === null,
+ 'half an address is not an address')
+ok(parseRef('A1:B2') === null, 'a range is not a single reference')
+ok(parseRef('REVENUE2024') === null,
+ 'over 3 letters is a NAME, not a cell — dash columns live in the same expression')
+ok(parseRef('A12345678') === null, 'over 7 digits is past any sheet, so not a cell')
+ok(parseRef('REV2024') !== null,
+ 'but REV2024 IS cell-shaped and resolves as a cell, as it does in every spreadsheet')
+ok(parseRef(' A1 ') !== null, 'surrounding space is tolerated')
+
+// ------------------------------------------------------------- formatRef
+ok(formatRef({ col: 0, row: 0, absCol: false, absRow: false }) === 'A1', 'formatRef is the inverse')
+ok(formatRef(parseRef('$A$1')!) === '$A$1', '$A$1 round-trips')
+ok(formatRef(parseRef('a$1')!) === 'A$1', 'and canonicalises the case')
+ok(formatRef(parseRef('$B$27')!) === '$B$27', 'a two-digit row round-trips')
+{
+ let bad = ''
+ for (const s of ['A1', '$A$1', 'A$1', '$A1', 'ZZ100', 'AAA1', 'B12']) {
+ if (formatRef(parseRef(s)!) !== s) { bad = s; break }
+ }
+ ok(!bad, `parseRef → formatRef round-trips every $ shape (${bad || 'all'})`)
+}
+ok(formatRef({ col: -1, row: 0, absCol: false, absRow: false }) === REF_ERR,
+ 'a column off the left edge formats as #REF!')
+ok(formatRef({ col: 0, row: -1, absCol: false, absRow: false }) === REF_ERR,
+ 'and a row off the top — never A0, which would parse back as nothing')
+
+// ---------------------------------------------------------------- ranges
+{
+ const r = parseRange('A1:B10')!
+ ok(r.from.col === 0 && r.from.row === 0 && r.to.col === 1 && r.to.row === 9, 'A1:B10 parses')
+ ok(formatRange(r) === 'A1:B10', 'and formats back')
+ ok(parseRange('$A$1:$B$10') !== null, 'absolute ranges parse')
+ ok(parseRange('A1') === null, 'a lone reference is not a range')
+ ok(parseRange('A1:') === null && parseRange('A1:nope!') === null,
+ 'half a range is not a range')
+}
+{
+ const cells = expandRange(parseRange('A1:B10')!)!
+ ok(cells.length === 20, 'A1:B10 expands to 20 cells')
+ ok(formatRef(cells[0]) === 'A1' && formatRef(cells[1]) === 'B1',
+ 'in reading order — row-major, so the second cell is B1 not A2')
+ ok(formatRef(cells[19]) === 'B10', 'and ends at the far corner')
+ ok(!cells.some((c) => c.col > 1 || c.row > 9), 'and nothing outside the rectangle')
+ ok(!cells.some((c: CellRef) => c.absCol || c.absRow),
+ 'expanded cells are ADDRESSES — $ describes a written reference, not a cell')
+ ok(expandRange(parseRange('$A$1:$B$2')!)!.length === 4, '$ does not change what a range covers')
+}
+{
+ const back = expandRange(parseRange('B10:A1')!)!
+ ok(back.length === 20 && formatRef(back[0]) === 'A1',
+ 'the corners normalise — B10:A1 is the same area as A1:B10')
+}
+{
+ const atCap = expandRange({
+ from: { col: 0, row: 0, absCol: false, absRow: false },
+ to: { col: 999, row: 999, absCol: false, absRow: false },
+ })
+ ok(atCap !== null && atCap.length === RANGE_CELL_MAX, `exactly ${RANGE_CELL_MAX} cells still expands`)
+ const over = expandRange({
+ from: { col: 0, row: 0, absCol: false, absRow: false },
+ to: { col: 999, row: 1000, absCol: false, absRow: false },
+ })
+ ok(over === null, 'one cell past the cap returns null rather than allocating')
+ // the one a person actually types
+ ok(expandRange(parseRange('A1:A1048576')!) === null,
+ 'a whole-column range is refused, not expanded into a dead tab')
+}
+
+// ------------------------------------------------- translateRef (fill)
+ok(translateRef('A1', 1, 0) === 'A2', 'fill down moves the row')
+ok(translateRef('A1', 0, 1) === 'B1', 'fill right moves the column')
+ok(translateRef('B2', 2, 3) === 'E4', 'both at once')
+ok(translateRef('$A$1', 1, 0) === '$A$1', '$A$1 does NOT move under fill')
+ok(!(translateRef('$A$1', 1, 0) === '$A$2'), 'specifically: it does not become $A$2')
+ok(translateRef('A$1', 5, 2) === 'C$1', 'A$1 moves sideways only')
+ok(translateRef('$A1', 5, 2) === '$A6', '$A1 moves down only')
+ok(translateRef('a1', 1, 0) === 'A2', 'case is canonicalised on the way out')
+ok(translateRef('A1', -1, 0) === REF_ERR, 'filling A1 upward is #REF!, not A1')
+ok(translateRef('A1', 0, -1) === REF_ERR, 'and off the left edge is #REF!')
+ok(translateRef('B2', -1, -1) === 'A1', 'but a legal negative offset is fine')
+ok(translateRef('SUM', 1, 0) === 'SUM', 'a non-address comes back untouched')
+ok(translateRef('A1', 0, 0) === 'A1', 'a zero offset is identity')
+
+// -------------------------------------------------- rewriteFormulaRefs
+ok(rewriteFormulaRefs('=A1+B1', 1, 0) === '=A2+B2', 'every reference in the expression moves')
+ok(rewriteFormulaRefs('=SUM(A1:A10)', 1, 0) === '=SUM(A2:A11)', 'both ends of a range move')
+ok(rewriteFormulaRefs('=$A$1*B2', 3, 2) === '=$A$1*D5', '$ survives beside a relative ref')
+ok(rewriteFormulaRefs('=A$1+$A1', 2, 2) === '=C$1+$A3', 'mixed anchoring, one row and one column')
+ok(rewriteFormulaRefs('=A1+B1', 0, 0) === '=A1+B1', 'a zero offset changes nothing')
+
+// the string-literal case, spelled out in the task
+ok(rewriteFormulaRefs('="A1 is "&A1', 1, 0) === '="A1 is "&A2',
+ '="A1 is "&A1 shifted a row is ="A1 is "&A2 — quoted text is a LABEL')
+ok(!rewriteFormulaRefs('="A1 is "&A1', 1, 0).includes('A2 is'),
+ 'and the label is definitely not rewritten')
+ok(rewriteFormulaRefs('="a""A1""b"', 1, 0) === '="a""A1""b"',
+ 'an escaped quote does not end the literal early')
+
+ok(rewriteFormulaRefs('=LOG10(A1)', 1, 0) === '=LOG10(A2)',
+ 'LOG10 is a function name, not cell LOG10 — it must not become LOG11')
+ok(rewriteFormulaRefs('=Sheet1!A1', 1, 0) === '=Sheet1!A2',
+ 'Sheet1 qualifies, A1 moves — the sheet name is cell-shaped and must survive')
+ok(rewriteFormulaRefs('=[REV2024]*A1', 1, 0) === '=[REV2024]*A2',
+ 'a [bracketed] name is the escape hatch for a column named like a cell')
+ok(rewriteFormulaRefs('=REV2024*2', 1, 0) === '=REV2025*2',
+ 'unbracketed, REV2024 IS a cell — documented, and why the escape hatch exists')
+ok(rewriteFormulaRefs('=REVENUE2024*A1', 1, 0) === '=REVENUE2024*A2',
+ 'a name over 3 letters is never a cell, so ordinary dash columns are safe')
+ok(rewriteFormulaRefs('=Price*Qty', 1, 0) === '=Price*Qty',
+ 'a column formula passes through untouched — the two systems coexist')
+ok(rewriteFormulaRefs('=A1+#REF!', 1, 0) === '=A2+#REF!',
+ 'an existing #REF! stays #REF! and does not become a reference')
+ok(rewriteFormulaRefs('=A1:B2', -1, 0) === `=${REF_ERR}`,
+ 'a range with a corner off the sheet is #REF! whole, not #REF!:B1')
+ok(!rewriteFormulaRefs('=A1:B2', -1, 0).includes(':'),
+ 'specifically: no half-range survives')
+ok(rewriteFormulaRefs('=IF(A1>0,"A1","B1")', 1, 0) === '=IF(A2>0,"A1","B1")',
+ 'inside a call: the argument moves, the two labels do not')
+
+// -------------------------------------------- shiftRefsForInsert (rows)
+ok(shiftRefsForInsert('=A5', 'row', 0, 1) === '=A6', 'inserting a row above pushes the ref down')
+ok(shiftRefsForInsert('=A5', 'row', 9, 1) === '=A5', 'inserting BELOW it changes nothing')
+ok(shiftRefsForInsert('=A5', 'row', 4, 1) === '=A6',
+ 'inserting AT the referenced row pushes it down — the cell moved')
+ok(shiftRefsForInsert('=A5', 'row', 0, 3) === '=A8', 'three rows move it three')
+
+// $ under structure: the half everyone gets wrong
+ok(shiftRefsForInsert('=$A$5', 'row', 0, 1) === '=$A$6',
+ '$A$5 DOES move when a row is inserted above it — $ pins against fill, not structure')
+ok(!(shiftRefsForInsert('=$A$5', 'row', 0, 1) === '=$A$5'),
+ 'specifically: $ does not freeze it in place while the cell moves')
+ok(shiftRefsForInsert('=A$5', 'row', 0, 1) === '=A$6', 'and the same for a pinned row alone')
+
+// deletion — the headline
+{
+ const after = shiftRefsForInsert('=A5+A10', 'row', 4, -1)
+ ok(after === '=#REF!+A9',
+ 'deleting row 5: the reference INTO it is #REF!, and the live one moves up')
+ ok(!after.includes('=A5'),
+ 'and A5 does NOT survive pointing at whatever slid into that position')
+ ok(after !== '=A5+A9', 'specifically: not the silent re-point, which is the wrong number')
+}
+ok(shiftRefsForInsert('=A1', 'row', 4, -1) === '=A1', 'a reference above the deletion is untouched')
+ok(shiftRefsForInsert('=A5+A6+A7', 'row', 4, -3) === '=#REF!+#REF!+#REF!',
+ 'every reference inside a multi-row deletion dies')
+ok(shiftRefsForInsert('=A8', 'row', 4, -3) === '=A5', 'and the row below it moves up by three')
+ok(shiftRefsForInsert('=B7', 'row', 3, -1) === '=B6',
+ 'a row edit never touches the column letter')
+ok(!(shiftRefsForInsert('=B7', 'row', 3, -1) === '=A6'), 'specifically: B does not become A')
+ok(shiftRefsForInsert('=A5', 'row', 0, 0) === '=A5', 'a zero-count edit is identity')
+
+// ranges across a structural edit
+ok(shiftRefsForInsert('=SUM(A1:A10)', 'row', 2, -3) === '=SUM(A1:A7)',
+ 'deleting three rows from inside a range SHRINKS it — the other numbers are still there')
+ok(shiftRefsForInsert('=SUM(A3:A5)', 'row', 2, -3) === '=SUM(#REF!)',
+ 'but a range whose every row was deleted is #REF!, not an empty range summing to 0')
+ok(shiftRefsForInsert('=SUM(A1:A4)', 'row', 2, -4) === '=SUM(A1:A2)',
+ 'a range whose BOTTOM fell into the hole ends at the last surviving row')
+ok(!(shiftRefsForInsert('=SUM(A1:A4)', 'row', 2, -4) === '=SUM(A1:A3)'),
+ 'specifically: it does not stretch over the row that moved up into the gap')
+ok(shiftRefsForInsert('=SUM(A3:A10)', 'row', 2, -3) === '=SUM(A3:A7)',
+ 'and a range whose TOP fell in starts at the first surviving row')
+ok(shiftRefsForInsert('=SUM(A1:A10)', 'row', 5, 2) === '=SUM(A1:A12)',
+ 'inserting inside a range EXTENDS it')
+ok(shiftRefsForInsert('=SUM(A1:A10)', 'row', 10, 1) === '=SUM(A1:A10)',
+ 'inserting directly below a range does not extend it — the classic append trap')
+
+// ----------------------------------------- shiftRefsForInsert (columns)
+ok(shiftRefsForInsert('=B7', 'col', 0, 1) === '=C7', 'inserting a column moves the letter')
+ok(shiftRefsForInsert('=B7', 'col', 0, 1) !== '=B8', 'and does NOT touch the row')
+ok(shiftRefsForInsert('=B1', 'col', 1, -1) === '=#REF!', 'deleting column B kills a ref into it')
+ok(shiftRefsForInsert('=C1', 'col', 1, -1) === '=B1', 'and C slides into B')
+ok(shiftRefsForInsert('=Z1', 'col', 0, 1) === '=AA1',
+ 'a column insert that crosses the Z/AA carry')
+ok(shiftRefsForInsert('=$B$7', 'col', 0, 1) === '=$C$7', '$ moves under a column insert too')
+ok(shiftRefsForInsert('=SUM(B1:D1)', 'col', 2, -1) === '=SUM(B1:C1)',
+ 'a horizontal range shrinks the same way')
+
+// what must survive a structural edit untouched
+ok(shiftRefsForInsert('=IF(A5="A5","x","y")', 'row', 4, -1) === '=IF(#REF!="A5","x","y")',
+ 'the reference dies, the identical text in quotes does not')
+ok(shiftRefsForInsert('=LOG10(A5)', 'row', 4, -1) === '=LOG10(#REF!)',
+ 'and a cell-shaped function name is not a casualty')
+ok(shiftRefsForInsert('=Price*Qty', 'row', 0, 1) === '=Price*Qty',
+ 'a column formula is immune to structural edits — which is the whole point of dash')
+ok(shiftRefsForInsert('=#REF!+A9', 'row', 0, 1) === '=#REF!+A10',
+ 'an already-dead reference stays dead while the live one moves')
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-about.ts b/scripts/test-dash-about.ts
new file mode 100644
index 00000000..9524b7a5
--- /dev/null
+++ b/scripts/test-dash-about.ts
@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash About-surface rig — the decisions, not the dialog.
+//
+// node scripts/test-dash-about.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. Three of About's buttons hand a WHOLE NEW WORKBOOK to the
+// running app — replace-from-JSON, restore-a-version, duplicate — and each has
+// a failure that looks like nothing at all until much later:
+//
+// 1. A SWAP THAT TAKES THE APP DOWN. `Grid.sheet` throws when the sheet id it
+// holds is missing, and it reads it from a `doc` listener registered
+// before all the others. So a workbook arriving with different sheet ids
+// throws mid-emit and the chart, the 3D panel and THE DIRTY FLAG never
+// run: the app looks fine, and the next tab-close is silent data loss.
+// 2. A DUPLICATE THAT IS NOT A DUPLICATE. Share the docId and the copy
+// inherits the original's version timeline and overwrites its recovery
+// snapshot — two files restoring each other's work. Share the mutable
+// objects and editing the copy edits the original in memory, so the fork
+// that was supposed to be independent saves the original's changes.
+// 3. A COPY THAT PHONES HOME. The file IS the capability (PLATFORM §5): a
+// fork keeping `collab` joins the room it forked away from.
+//
+// Only the pure half is exercised here. The dialog itself is DOM wiring, and
+// the two document-level handlers it has to survive (main.ts's bare-key grid
+// typing and its CSV paste sniffer) need a real browser to prove.
+
+import { registerHooks } from 'node:module'
+
+// about.ts imports its own stylesheet — Vite's job, and a file extension Node
+// refuses outright. Stub it here rather than splitting the module: the logic
+// under test is what the dialog is FOR, and it belongs beside it.
+registerHooks({
+ load(url, context, next) {
+ if (url.endsWith('.css')) return { format: 'module', source: 'export {}', shortCircuit: true }
+ return next(url, context)
+ },
+})
+
+const { planReplace, duplicateWorkbook, workbookStats } =
+ await import('../dash/src/about.ts')
+const { parseDoc } = await import('../dash/src/model.ts')
+type DashDoc = import('../dash/src/model.ts').DashDoc
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+// --------------------------------------------------------------- fixtures
+
+const workbook = (sheetIds: string[], extra: Record<string, unknown> = {}): DashDoc => {
+ const r = parseDoc(JSON.stringify({
+ format: 'bento/dash', version: 1, policy: 'bento-dash-1',
+ docId: 'doc-original', title: 'test',
+ sheets: sheetIds.map((id) => ({
+ id, name: id, kind: 'table',
+ rids: [[1, 3]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'number' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, 0] },
+ amount: { enc: 'raw', v: [10, 20, 30] },
+ },
+ steps: [],
+ })),
+ theme: { background: '#FFFFFF', color: '#1E2A3A', accent: '#F7A600', fontFamily: 'sans-serif' },
+ ...extra,
+ }))
+ if (!r.ok) throw new Error('fixture does not parse')
+ return r.doc
+}
+
+// ========================================================= planReplace
+
+{
+ const next = workbook(['sh1', 'sh2'])
+ const plan = planReplace(next, 'sh2')
+ ok(plan !== null && plan.show === 'sh2' && !plan.carry,
+ 'a workbook that still has the sheet on screen swaps in one step and stays put')
+}
+{
+ // the round trip an agent makes: same ids, different values
+ const plan = planReplace(workbook(['sh1']), 'sh1')
+ ok(plan !== null && !plan.carry,
+ 'an edited copy of the SAME workbook never needs the carry — the reader is not moved')
+}
+{
+ const plan = planReplace(workbook(['other']), 'sh1')
+ ok(plan !== null && plan.show === 'other' && plan.carry,
+ 'a workbook with different sheet ids carries the outgoing sheet through, or the grid throws mid-emit')
+}
+{
+ const plan = planReplace(workbook(['a', 'b', 'c']), 'gone')
+ ok(plan !== null && plan.show === 'a',
+ 'the first table sheet is where a moved reader lands')
+}
+{
+ const canvasOnly = workbook([])
+ canvasOnly.sheets = [{ id: 'cv', name: 'Canvas', kind: 'canvas', cells: {} } as never]
+ ok(planReplace(canvasOnly, 'sh1') === null,
+ 'a workbook with no TABLE sheet is refused — the grid has nothing to show, and a blank screen reads as data loss')
+}
+{
+ ok(planReplace(workbook([]), 'sh1') === null,
+ 'a workbook with no sheets at all is refused rather than swapped in')
+}
+
+// ========================================================= duplicateWorkbook
+
+{
+ const src = workbook(['sh1'], { collab: { room: 'w-abc', key: 'secret' }, template: true })
+ const copy = duplicateWorkbook(src)
+ ok(copy.docId !== src.docId && copy.docId.length > 8,
+ 'a duplicate mints a fresh docId — sharing it would make the copy overwrite the original’s recovery snapshot')
+ ok(copy.collab === undefined,
+ 'a duplicate drops collab: the file is the capability, so a copy carrying it writes into the room it forked from')
+ ok(copy.template === undefined,
+ 'a duplicate drops template — a duplicate is a document, not a thing that spawns fresh documents')
+ ok(src.docId === 'doc-original' && (src as { collab?: unknown }).collab !== undefined,
+ 'the original is not touched by being duplicated')
+}
+{
+ const src = workbook(['sh1'])
+ const copy = duplicateWorkbook(src)
+ ok(copy.sheets[0] !== src.sheets[0] && copy.theme !== src.theme,
+ 'the clone is DEEP — a shared sheet object means editing the fork edits the original in memory')
+ const sheet = copy.sheets[0] as { data: Record<string, { enc: string; v?: unknown[] }> }
+ ;(sheet.data.amount.v as number[])[0] = 999
+ const orig = src.sheets[0] as { data: Record<string, { v: number[] }> }
+ ok(orig.data.amount.v[0] === 10,
+ 'writing a cell in the fork leaves the original’s column alone')
+}
+{
+ ok(duplicateWorkbook(workbook(['sh1']), 'fixed-id').docId === 'fixed-id',
+ 'the docId can be supplied, so a caller that has to mint it elsewhere still round-trips')
+}
+
+// ========================================================= workbookStats
+
+{
+ const doc = workbook(['sh1', 'sh2'])
+ const s = workbookStats(doc)
+ ok(s.sheets === 2 && s.tables === 2 && s.rows === 6 && s.columns === 4,
+ 'the counts read the run-length encoded row ids, not a flattened copy of them')
+ ok(s.bytes === JSON.stringify(doc).length,
+ 'size is the JSON length, because #bento-doc is plaintext forever — file size IS document size')
+}
+{
+ const mixed = workbook(['sh1'])
+ mixed.sheets.push({ id: 'cv', name: 'Canvas', kind: 'canvas', cells: {} } as never)
+ const s = workbookStats(mixed)
+ ok(s.sheets === 2 && s.tables === 1 && s.rows === 3,
+ 'a canvas sheet counts as a sheet and contributes no rows or columns')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-cellformula.ts b/scripts/test-dash-cellformula.ts
new file mode 100644
index 00000000..6780ed8c
--- /dev/null
+++ b/scripts/test-dash-cellformula.ts
@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash per-cell formula rig.
+//
+// node scripts/test-dash-cellformula.ts
+//
+// WHAT THIS PROVES. A per-cell formula produces a number that a reader will
+// trust without being able to check it, which makes every failure here a
+// SILENT one. The three that matter:
+//
+// ORDER `=A1*2` computed before `A1` itself reads a stale value and
+// writes it into the document looking authoritative.
+// CYCLES a cycle resolved by "whatever we had last time" reports a
+// different answer on each recalculation and nothing says so.
+// ERRORS an error that becomes a zero is the same sin as a gap drawn as
+// a zero in a chart — an absence rendered as a fact.
+//
+// Every check below is a NEGATIVE control on one of those: it constructs the
+// case where a plausible-looking implementation gets it wrong.
+
+import {
+ bindRefs, cellDeps, cellKey, evalCell, isFormula, recalcCells, formulaBody,
+ translateCellFormula, shiftSheetFormulas, type CellSource,
+} from '../dash/src/cellformula.ts'
+import { isErr, type Cell, type Vec } from '../dash/src/formula.ts'
+import { parseRef } from '../dash/src/a1.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+/** A grid literal: `null` is empty, a leading `=` is a formula. */
+function grid(cells: (string | number | null)[][]): CellSource {
+ const rows = cells.length
+ const cols = Math.max(...cells.map((r) => r.length))
+ return {
+ rows,
+ cols,
+ formulaAt: (r, c) => {
+ const v = cells[r]?.[c]
+ return isFormula(v) ? v : undefined
+ },
+ valueAt: (r, c) => {
+ const v = cells[r]?.[c]
+ return isFormula(v) ? null : (v ?? null) as Cell
+ },
+ }
+}
+
+const val = (g: CellSource, ref: string): Cell => {
+ const r = parseRef(ref)!
+ return recalcCells(g).values.get(cellKey(r.row, r.col)) ?? null
+}
+const code = (v: Cell): string => (isErr(v) ? String(v) : `not an error (${JSON.stringify(v)})`)
+
+// ------------------------------------------------------------- binding
+{
+ const { expr, deps } = bindRefs('B4*1.2')
+ ok(expr === '_a1_0*1.2', 'a reference is rewritten to a bound name')
+ ok(deps.length === 1 && deps[0].cells.length === 1 && deps[0].cells[0].row === 3,
+ 'and the name carries the position it points at (B4 = row 3, 0-based)')
+}
+{
+ const { deps } = bindRefs('SUM(A1:A4)')
+ ok(deps[0].cells.length === 4, 'a range binds to every cell it covers')
+}
+{
+ // the whole reason the scanner is shared with a1.ts rather than re-written
+ const { expr } = bindRefs('"A1 is " & A1')
+ ok(expr.includes('"A1 is "') && expr.includes('_a1_0'),
+ 'a reference inside a string literal is TEXT, and only the real one is bound')
+ ok(bindRefs('LOG10(2)').deps.length === 0,
+ 'LOG10 is a call, not a reference to cell LOG10 — the name is followed by (')
+ ok(bindRefs('[A1] * 2').deps.length === 0,
+ 'and [A1] is the escape for a COLUMN named like a cell')
+}
+
+// --------------------------------------------------- evaluation, in isolation
+{
+ const read = (r: { row: number; col: number }): Cell =>
+ ([[10, 20], [30, 40]] as Cell[][])[r.row]?.[r.col] ?? null
+ ok(evalCell('=A1+B2', read) === 50, 'a formula reads the cells it names')
+ ok(evalCell('=SUM(A1:B2)', read) === 100, 'and a range aggregates without `:` being an operator')
+ ok(evalCell('A1+1', read) === 11, 'the leading = is optional at this level')
+}
+
+// --------------------------------------------------------------- ORDER
+{
+ // C1 depends on A1, which depends on B1. Any implementation that evaluates
+ // in document order gets C1 wrong, and gets it wrong QUIETLY.
+ const g = grid([['=B1*2', 5, '=A1+1']])
+ const r = recalcCells(g)
+ ok(val(g, 'A1') === 10, 'A1 = B1*2 = 10')
+ ok(val(g, 'C1') === 11,
+ 'C1 = A1+1 = 11 — computed AFTER A1 even though it comes first in no useful order')
+ ok(r.order.indexOf(cellKey(0, 0)) < r.order.indexOf(cellKey(0, 2)),
+ 'and the reported order says so')
+}
+{
+ // THE ORDERING TEST THAT BITES. Above, A1 happens to sit left of the cell
+ // that needs it, so plain document order gets the right answer by luck and
+ // the check proves nothing. Here the dependency chain runs BACKWARDS against
+ // the document: A1 needs C1, which needs B1. Anything that walks the grid in
+ // order computes A1 from an unsettled C1.
+ const g = grid([['=C1+1', 5, '=B1*2']])
+ ok(val(g, 'C1') === 10, 'C1 = B1*2 = 10')
+ ok(val(g, 'A1') === 11,
+ 'A1 = C1+1 = 11, with the chain running right-to-left against document order')
+}
+{
+ // and the same, downwards, since a row walk and a column walk fail differently
+ const g = grid([['=A3+1'], ['=A1*10'], [4]])
+ ok(val(g, 'A2') === 50, 'A2 = A1*10 = 50, where A1 itself waits on a row BELOW it')
+}
+{
+ // a chain long enough that a single pass cannot fake it
+ const row: (string | number)[] = [1]
+ for (let i = 1; i < 12; i++) row.push(`=${String.fromCharCode(65 + i - 1)}1+1`)
+ const g = grid([row])
+ ok(val(g, 'L1') === 12, 'a twelve-deep chain settles to the right number in one recalculation')
+}
+
+// --------------------------------------------------------------- CYCLES
+{
+ const g = grid([['=B1', '=A1']])
+ ok(code(val(g, 'A1')) === '#CYCLE!', 'a two-cell cycle is #CYCLE!')
+ ok(code(val(g, 'B1')) === '#CYCLE!', 'on BOTH cells, not just the one we noticed second')
+ ok(recalcCells(g).cycles.length === 2, 'and it is reported, not just rendered')
+}
+{
+ const g = grid([['=A1+1']])
+ ok(code(val(g, 'A1')) === '#CYCLE!',
+ 'a cell that reads ITSELF is a cycle of one — the case a plain edge count misses entirely')
+}
+{
+ const g = grid([['=B1', '=C1', '=A1', '=A1+100']])
+ ok(code(val(g, 'D1')) === '#CYCLE!',
+ 'a cell DOWNSTREAM of a cycle is an error too, never a number computed from a guess')
+}
+{
+ // the check that a cycle does not poison the whole sheet
+ const g = grid([['=B1', '=A1'], [7, '=A2*3']])
+ ok(val(g, 'B2') === 21, 'a cell unrelated to the cycle still computes')
+}
+
+// --------------------------------------------------------------- ERRORS
+{
+ const g = grid([[0, '=1/A1']])
+ ok(code(val(g, 'B1')) === '#DIV/0!', 'division by zero is an error')
+ const g2 = grid([[0, '=1/A1', '=B1+5']])
+ ok(code(val(g2, 'C1')) === '#DIV/0!',
+ 'and it PROPAGATES — a formula reading an error is an error, not 5')
+}
+{
+ const g = grid([[null, '=A1+1']])
+ ok(val(g, 'B1') === 1, 'an EMPTY cell reads as nothing and arithmetic treats it as 0')
+}
+{
+ const g = grid([[1, '=A50+1']])
+ ok(val(g, 'B1') === 1,
+ 'a reference past the end of the sheet is EMPTY, not #REF! — #REF! means "deleted", and spending it here would make the informative error indistinguishable from a typo')
+}
+{
+ const g = grid([['=#REF!+1']])
+ ok(code(val(g, 'A1')) === '#REF!',
+ 'a #REF! left by an earlier deletion stays #REF!, rather than degrading to a parse failure')
+}
+{
+ const g = grid([['=SUM(A1:XFD1048576)']])
+ ok(isErr(val(g, 'A1')), 'a range too large to expand is an error rather than an attempt')
+}
+{
+ const g = grid([['=NOSUCH(1)']])
+ ok(isErr(val(g, 'A1')), 'an unknown function is an error')
+}
+
+// ------------------------------------------------- text, booleans, and types
+{
+ const g = grid([['north', '=A1 & " region"']])
+ ok(val(g, 'B1') === 'north region', 'text concatenates')
+ const g2 = grid([[5, '=IF(A1>3,"big","small")']])
+ ok(val(g2, 'B1') === 'big', 'IF picks a branch on a cell value')
+}
+
+// ------------------------------------------------- column names still resolve
+{
+ const g = grid([[1], [2], [3]])
+ const cols = new Map<string, Vec>([['amount', [1, 2, 3]]])
+ ok(evalCell('=SUM(amount)', () => null, { cols }) === 6,
+ 'a cell formula can also name a COLUMN — the two systems share one evaluator')
+}
+
+// ------------------------------------------------------------ dependencies
+{
+ const d = cellDeps(formulaBody('=A1+SUM(B1:B3)'))
+ ok(d.length === 4, 'cellDeps reports every position read, ranges expanded')
+ ok(cellDeps('"B2" & 1').length === 0, 'and none from a string literal')
+}
+
+// -------------------------------------------------------------- the classic
+{
+ // quantity × price down a column, then a total — the thing a person actually
+ // types into a spreadsheet on the first day
+ const g = grid([
+ [2, 3.5, '=A1*B1'],
+ [4, 1.25, '=A2*B2'],
+ [1, 10, '=A3*B3'],
+ [null, null, '=SUM(C1:C3)'],
+ ])
+ ok(val(g, 'C1') === 7 && val(g, 'C2') === 5 && val(g, 'C3') === 10, 'line totals')
+ ok(val(g, 'C4') === 22,
+ 'and the total sums the COMPUTED line totals, which only works if the sum runs last')
+}
+
+// ------------------------------------- moving formulas, and moving the cells
+//
+// TWO RULES, and conflating them is the classic spreadsheet bug. Copying moves
+// the FORMULA and leaves the cells; inserting moves the CELLS and leaves the
+// formula. `$` is the tell: it pins against the first and not the second.
+{
+ ok(translateCellFormula('=A1*2', 1, 0) === '=A2*2',
+ 'copied one row down, a relative reference follows')
+ ok(translateCellFormula('=A1*2', 0, 1) === '=B1*2', 'and one column right')
+ ok(translateCellFormula('=$A$1*2', 5, 5) === '=$A$1*2',
+ '$ PINS against a copy — that is the whole meaning of $')
+ ok(translateCellFormula('=$A1*2', 1, 1) === '=$A2*2',
+ 'and it pins per-axis: $A holds the column, the row still moves')
+ ok(translateCellFormula('12', 3, 0) === '12', 'a plain value is not a formula and does not move')
+ ok(translateCellFormula('=A1', 0, 0) === '=A1', 'a zero offset is left exactly alone')
+}
+{
+ const shift = (f: string, axis: 'row' | 'col', at: number, n: number) =>
+ shiftSheetFormulas([['k', f]], axis, at, n)[0]?.[1] ?? f
+ ok(shift('=$A$5*2', 'row', 0, 1) === '=$A$6*2',
+ 'inserting a row above $A$5 moves it to $A$6 — $ does NOT pin here, because the cell itself moved')
+ ok(shift('=A5', 'row', 9, 1) === '=A5', 'a row inserted BELOW a reference leaves it alone')
+ ok(shift('=A5', 'row', 4, -1) === '=#REF!',
+ 'a reference INTO a deleted row is #REF! — never the row that slid up into the gap, which would be a wrong number wearing a right one\'s clothes')
+ ok(shift('=SUM(A1:A10)', 'row', 3, -3) === '=SUM(A1:A7)',
+ 'a RANGE spanning the hole shrinks: the numbers under the heading are still there, there are just fewer of them')
+ ok(shift('=B1', 'col', 0, 1) === '=C1', 'and the same on the column axis')
+}
+{
+ // the pair that proves they are different rules and not one rule twice
+ const copied = translateCellFormula('=$A$1+B2', 2, 0)
+ const shifted = shiftSheetFormulas([['k', '=$A$1+B2']], 'row', 0, 2)[0][1]
+ ok(copied === '=$A$1+B4', 'copying two rows down: $A$1 pinned, B2 followed')
+ ok(shifted === '=$A$3+B4', 'inserting two rows at the top: BOTH moved')
+ ok(copied !== shifted, 'so the two operations genuinely differ on the same input')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-condfmt.ts b/scripts/test-dash-condfmt.ts
new file mode 100644
index 00000000..34650ea9
--- /dev/null
+++ b/scripts/test-dash-condfmt.ts
@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash conditional-formatting rig.
+//
+// node scripts/test-dash-condfmt.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. Conditional formatting is the feature people reach for
+// straight after totals, and every one of its failures is SILENT — a colour is
+// never obviously wrong the way a number is, so nothing here can be caught by
+// looking at the grid:
+//
+// 1. DEGENERATE DATA. An empty column, an all-equal column, a column of text.
+// Each one is a 0/0 waiting to happen, and NaN reaches CSS as
+// `#NaNNaNNaN` — which paints nothing, on the day the data went flat.
+// 2. A MUDDY MIDPOINT. Averaging sRGB BYTES loses about half the luminance
+// in the middle of a ramp, so red→green peaks at a dark olive-brown
+// instead of yellow. It looks like a design choice rather than a bug,
+// which is why it survives in so many heatmaps.
+// 3. BARS ANCHORED AT THE LEFT EDGE. Map each value onto (v − min)/(max − min)
+// from the left and the most negative row draws a bar of length ZERO —
+// invisible, and it is the row that most needs to be seen.
+// 4. A RULE THAT SILENTLY DOES NOTHING. First-match-wins means a colour scale
+// and a "negatives in red" rule cannot coexist: one of them is discarded
+// and the author is never told which.
+//
+// So each of those is asserted BOTH ways: the right answer lands, and the
+// plausible wrong answer is refused by name.
+
+import {
+ colorScale, dataBarWidths, evaluateRules, mixColors,
+ type CellStyle, type CompareOp, type Rule,
+} from '../dash/src/condfmt.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+const near = (a: number, b: number, eps = 1e-9): boolean => Math.abs(a - b) < eps
+const isHex = (s: string): boolean => /^#[0-9a-f]{6}$/.test(s)
+const noNaN = (s: string): boolean => !/nan/i.test(s)
+
+// ------------------------------------------------------- the empty column
+// Every entry point takes the empty array, because a filtered-to-nothing view
+// is a normal state of the grid, not an error one.
+{
+ ok(colorScale([], ['#ff0000', '#00ff00']).length === 0,
+ 'an empty value set gives an empty colour list — no divide by zero')
+ ok(dataBarWidths([]).length === 0, 'and an empty bar list')
+ const rules: Rule[] = [
+ { kind: 'colorScale', colors: ['#ff0000', '#ffff00', '#00aa00'] },
+ { kind: 'dataBar', color: '#4488cc' },
+ { kind: 'cellValue', op: '>', value: 0, style: { bold: true } },
+ { kind: 'topN', n: 3, style: { bold: true } },
+ { kind: 'duplicates', style: { italic: true } },
+ { kind: 'formula', expr: 'value > 1', style: { color: '#fff' } },
+ ]
+ ok(evaluateRules(rules, []).length === 0,
+ 'every rule kind survives an empty column without throwing')
+}
+
+// ---------------------------------------------------- the all-equal column
+{
+ const c = colorScale([7, 7, 7], ['#ff0000', '#ffff00', '#00aa00'])
+ ok(c.every(noNaN), 'all-equal values produce no NaN in a colour scale')
+ ok(c.every((x) => x === c[0]) && isHex(c[0]), 'and one uniform, valid colour')
+ ok(c[0] === '#ffff00',
+ 'which is the MID colour: with no spread nothing is lowest and nothing is highest')
+
+ const b = dataBarWidths([5, 5, 5])
+ ok(b.every((w) => Number.isFinite(w.pct)), 'all-equal values produce no NaN percentages')
+ ok(b.every((w) => w.pct === 100),
+ 'and full bars — the domain includes zero, so 5 of a 0..5 range is the whole width')
+ ok(b.every((w) => w.axis === 0), 'zero sits at the left edge when nothing is negative')
+
+ const z = dataBarWidths([0, 0, 0])
+ ok(z.every((w) => w.pct === 0 && Number.isFinite(w.pct)),
+ 'an all-ZERO column draws nothing rather than dividing 0 by 0')
+}
+
+// -------------------------------------------------- a column with no numbers
+{
+ const c = colorScale(['north', 'south', null], ['#ff0000', '#00ff00'])
+ ok(c.every((x) => x === ''), 'text has no position on a numeric scale, so it gets NO colour')
+ ok(!c.includes('#ff0000'),
+ 'and specifically NOT the low colour, which would claim "this is the smallest value"')
+ const b = dataBarWidths(['x', null, 3])
+ ok(b[0].pct === 0 && b[1].pct === 0 && b[2].pct === 100, 'non-numeric rows draw no bar')
+}
+
+// ------------------------------------------------ gamma-correct interpolation
+{
+ const mid = mixColors('#ff0000', '#00ff00', 0.5)
+ ok(mid === '#bcbc00', `red→green at the midpoint is #bcbc00 (got ${mid})`)
+ ok(mid !== '#808000',
+ 'and NOT #808000 — the byte average, a dark olive-brown that is half the light')
+ ok(parseInt(mid.slice(1, 3), 16) > 128,
+ 'the linear-light midpoint is brighter than the naive one, which is the whole point')
+ ok(mixColors('#ff0000', '#00ff00', 0) === '#ff0000'
+ && mixColors('#ff0000', '#00ff00', 1) === '#00ff00',
+ 'the endpoints round-trip EXACTLY through the encode/decode — no drift at a stop')
+ ok(mixColors('#000000', '#ffffff', 0.5) === '#bcbcbc',
+ 'mid grey is #bcbc — 50% LIGHT, not 50% of the byte')
+ ok(mixColors('#ff0000', '#00ff00', -3) === '#ff0000'
+ && mixColors('#ff0000', '#00ff00', 9) === '#00ff00', 't outside [0,1] clamps')
+ ok(mixColors('#f00', '#0f0', 0.5) === mid, 'three-digit hex expands')
+ ok(mixColors('#FF0000', '#00FF00', 0.5) === mid, 'and uppercase normalises')
+ ok(mixColors('rgb(255, 0, 0)', 'rgb(0, 255, 0)', 0.5) === mid, 'rgb() parses too')
+ ok(mixColors('#ff000000', '#ff0000ff', 0.5) === 'rgba(255, 0, 0, 0.5)',
+ 'alpha interpolates LINEARLY — it is coverage, not light')
+ ok(mixColors('rebeccapurple', '#00ff00', 0.2) === 'rebeccapurple',
+ 'an unresolvable colour snaps to the nearest stop rather than inventing black')
+}
+
+// ------------------------------------------------------------- colour scales
+{
+ const stops: [string, string, string] = ['#ff0000', '#ffff00', '#00aa00']
+ const c = colorScale([0, 50, 100], stops)
+ ok(c[1] === '#ffff00', 'a scale over [0,50,100] gives the EXACT mid colour at 50')
+ ok(c[0] === '#ff0000' && c[2] === '#00aa00', 'and the exact end colours at the ends')
+ ok(c.every(isHex), 'every colour is a valid six-digit hex')
+
+ const two = colorScale([0, 50, 100], ['#ff0000', '#00ff00'])
+ ok(two[1] === '#bcbc00', 'a TWO-stop scale blends gamma-correctly at its middle value')
+ ok(two[1] !== '#808000', 'and does not fall back to the byte average')
+
+ // an off-centre mid: pinning neutral to zero on a −20..+300 column
+ const div = colorScale([-20, 0, 300], stops, { mid: 0 })
+ ok(div[1] === '#ffff00', 'an explicit mid VALUE puts the neutral colour on that value')
+ ok(div[0] === '#ff0000' && div[2] === '#00aa00', 'with both ramps still reaching their ends')
+ ok(colorScale([140], stops, { min: -20, max: 300 })[0] === '#ffff00'
+ && colorScale([0], stops, { min: -20, max: 300 })[0] !== '#ffff00',
+ 'and without it the neutral colour lands on 140, the midpoint of the range — not on zero')
+
+ const pinned = colorScale([5, 500], stops, { min: 0, max: 100 })
+ ok(pinned[1] === '#00aa00', 'a value above an explicit max clamps to the top colour')
+ ok(pinned.every(isHex), 'clamping keeps every channel in range — no #ff01ff overflow')
+ ok(colorScale([-999], stops, { min: 0, max: 100 })[0] === '#ff0000',
+ 'and below an explicit min clamps to the bottom colour')
+
+ const mixed = colorScale([1, 'n/a', 9], ['#ff0000', '#00ff00'])
+ ok(mixed[1] === '' && mixed[0] === '#ff0000' && mixed[2] === '#00ff00',
+ 'a text row is skipped and does not drag the extent')
+ ok(colorScale([1, 2], ['#ff0000', '#00ff00'])[1] === '#00ff00',
+ 'a NaN-free extent: the max of the numeric values sets the top, not the text')
+}
+
+// ---------------------------------------------------------------- data bars
+{
+ const sym = dataBarWidths([-100, 100])
+ ok(sym[0].axis === 50 && sym[1].axis === 50,
+ 'with symmetric negatives, ZERO sits in the MIDDLE of the cell')
+ ok(sym[0].axis !== 0,
+ 'and NOT at the left edge — the naive answer, which hides the sign entirely')
+ ok(sym[0].negative === true && sym[1].negative === false, 'the sign is reported per row')
+ ok(sym[0].pct === 50 && sym[1].pct === 50, 'both bars run 50% of the width from the axis')
+
+ const b = dataBarWidths([-50, 0, 100])
+ ok(near(b[0].axis, 100 / 3), 'an asymmetric column puts zero at |min|/(|min|+max) = 33.3%')
+ ok(b[0].pct > 0,
+ 'the MOST NEGATIVE value gets a visible bar — left-anchored scaling gives it zero length')
+ ok(near(b[0].pct, b[2].pct / 2),
+ 'one shared scale: a −50 bar is exactly half a +100 bar')
+ ok(!near(b[0].pct, b[2].pct),
+ 'and NOT the same length, which per-side normalisation would give')
+ ok(b[1].pct === 0 && b[1].negative === false, 'a zero value sits on the axis with no bar')
+ ok(b.every((w) => (w.negative ? w.pct <= w.axis + 1e-9 : w.axis + w.pct <= 100 + 1e-9)),
+ 'no bar overflows its side of the axis')
+ // The old check compared entries to each other, but `axis` is computed once
+ // outside the map and closed over — two entries cannot differ without a
+ // refactor, so it could not fail. Check the VALUE instead: an all-positive
+ // set puts the axis hard left, which is what "no negatives, no split bar"
+ // means, and a naive implementation that always centres it fails here.
+ const allPos = dataBarWidths([10, 20, 30])
+ ok(allPos.every((w) => w.axis === 0),
+ 'an all-positive set puts the zero axis at the LEFT edge — an implementation that always centres it fails here')
+ ok(allPos[2].pct === 100 && allPos[0].pct > 0,
+ 'and the largest fills the width while the smallest still shows')
+
+ const neg = dataBarWidths([-5, -1])
+ ok(neg[0].axis === 100, 'an all-negative column puts zero at the RIGHT edge')
+ ok(neg[0].pct === 100 && neg[1].pct === 20, 'and scales the bars leftwards from it')
+
+ const pos = dataBarWidths([10, 20])
+ ok(pos[0].pct === 50 && pos[1].pct === 100,
+ 'an all-positive column measures from ZERO, so 10 is half of 20')
+ ok(pos[0].pct !== 0,
+ 'not from the minimum — that would make the smallest value invisible')
+
+ const fixed = dataBarWidths([50, 500], { min: 0, max: 100 })
+ ok(fixed[0].pct === 50 && fixed[1].pct === 100, 'an explicit domain clamps rather than rescales')
+}
+
+// ---------------------------------------------------- composition, not shadow
+{
+ const scale: Rule = { kind: 'colorScale', colors: ['#ffffff', '#000000'] }
+ const negatives: Rule = { kind: 'cellValue', op: '<', value: 0, style: { color: '#cc0000', bold: true } }
+ const out = evaluateRules([scale, negatives], [-1, 1])
+ ok(out[0]?.bg === '#ffffff', 'the earlier rule KEEPS its background under a later match')
+ ok(out[0]?.color === '#cc0000' && out[0]?.bold === true, 'and the later rule adds its own properties')
+ ok(!(out[0]?.bg === undefined),
+ 'first-match-wins would have discarded the scale silently — refused')
+ ok(out[1]?.bg === '#000000' && out[1]?.color === undefined,
+ 'a row the later rule does not match keeps only the scale')
+
+ const a: Rule = { kind: 'cellValue', op: '>', value: 0, style: { bg: '#111111' } }
+ const b: Rule = { kind: 'cellValue', op: '>', value: 0, style: { bg: '#222222' } }
+ ok(evaluateRules([a, b], [1])[0]?.bg === '#222222', 'the LAST rule to set a property wins it')
+ ok(evaluateRules([b, a], [1])[0]?.bg === '#111111', 'so order is meaningful')
+
+ // the shape a UI produces after clearing a field
+ const cleared: Rule = { kind: 'cellValue', op: '>', value: 0, style: { bg: undefined, bold: true } as CellStyle }
+ const kept = evaluateRules([a, cleared], [1])[0]
+ ok(kept?.bg === '#111111',
+ 'an explicit `bg: undefined` in a later style does NOT erase an earlier background')
+ ok(kept?.bold === true, 'while its defined properties still apply')
+
+ ok(evaluateRules([negatives], [5])[0] === null, 'a row no rule matches is null, not an empty style')
+
+ const style = { bold: true }
+ const got = evaluateRules([{ kind: 'topN', n: 1, style }], [1])[0]!
+ got.bold = false
+ ok(style.bold === true, 'the returned style is a COPY — a caller cannot mutate the rule')
+
+ const unknown = { kind: 'sparkline', style: { bold: true } } as unknown as Rule
+ ok(evaluateRules([unknown, negatives], [-1])[0]?.color === '#cc0000',
+ 'a rule kind from a later build is ignored, and the rules around it still apply')
+
+ // Rules are DOCUMENT data: a hand-edited file can put anything in the list,
+ // and this runs in the grid's paint path, where a throw blanks the grid.
+ const junk = [
+ null, 'nonsense', { kind: 'colorScale' }, { kind: 'colorScale', colors: ['#ff0000'] },
+ { kind: 'cellValue', op: '>', value: 0 }, { kind: 'topN', n: 1 },
+ ] as unknown as Rule[]
+ ok(evaluateRules([...junk, negatives], [-1])[0]?.color === '#cc0000',
+ 'malformed rules are skipped rather than thrown on, and the valid ones still apply')
+ ok(colorScale([1, 2], ['#ff0000'] as unknown as [string, string]).every((x) => x === ''),
+ 'a ramp with fewer than two stops has nothing to interpolate, so it gives no colour')
+}
+
+// ------------------------------------------------------------ cell-value ops
+{
+ const style = { bold: true }
+ const hit = (op: CompareOp, value: unknown, vals: unknown[], to?: unknown) =>
+ JSON.stringify(evaluateRules([{ kind: 'cellValue', op, value, to, style }], vals)
+ .map((s) => s !== null))
+
+ ok(hit('>', 10, [9, 10, 11]) === '[false,false,true]', '>')
+ ok(hit('>=', 10, [9, 10, 11]) === '[false,true,true]', '>=')
+ ok(hit('<>', 10, [9, 10]) === '[true,false]', '<>')
+ ok(hit('between', 10, [9, 10, 15, 20, 21], 20) === '[false,true,true,true,false]',
+ 'between is inclusive at both ends')
+ ok(hit('between', 20, [15], 10) === '[true]',
+ 'and sorts its bounds — a reversed pair is a typo, not an empty set')
+ ok(hit('contains', 'ACME', ['acme ltd', 'other']) === '[true,false]', 'contains is case-insensitive')
+ ok(hit('contains', '', ['anything']) === '[false]',
+ 'an EMPTY needle matches nothing — a rule that would light up every cell is refused')
+ ok(hit('startsWith', 'a', ['abc', 'bac']) === '[true,false]', 'startsWith')
+ ok(hit('endsWith', 'c', ['abc', 'cba']) === '[true,false]', 'endsWith')
+ ok(hit('blank', undefined, [null, '', ' ', 0, 'x']) === '[true,true,true,false,false]',
+ 'blank counts null and whitespace, but NOT zero')
+ ok(hit('notBlank', undefined, [null, 0]) === '[false,true]', 'notBlank')
+ ok(hit('>', 9, ['10']) === '[true]',
+ 'numeric TEXT compares numerically — "10" > 9, not lexically less than "9"')
+ ok(hit('>', 'b', ['c', 'a']) === '[true,false]', 'and text against text compares lexically')
+}
+
+// --------------------------------------------------------------- top / bottom
+{
+ const style = { bold: true }
+ const top = (n: number, vals: unknown[], bottom?: boolean) =>
+ evaluateRules([{ kind: 'topN', n, ...(bottom ? { bottom } : {}), style }], vals)
+ .map((s) => s !== null)
+
+ ok(JSON.stringify(top(2, [5, 1, 9, 7])) === '[false,false,true,true]', 'top 2 is 9 and 7')
+ ok(JSON.stringify(top(2, [5, 1, 9, 7], true)) === '[true,true,false,false]',
+ 'bottom 2 is 1 and 5 — the same sort read from the other end')
+ ok(JSON.stringify(top(1, [10, 10, 9])) === '[true,true,false]',
+ 'a TIE for the last place is included — picking one of two identical numbers would')
+ ok(JSON.stringify(top(1, [10, 10, 9])) !== '[true,false,false]',
+ 'show a difference in the grid that does not exist in the data')
+ ok(JSON.stringify(top(9, [1, 2])) === '[true,true]', 'n larger than the column takes everything')
+ ok(JSON.stringify(top(0, [1, 2])) === '[false,false]', 'n of 0 takes nothing')
+ ok(JSON.stringify(top(-1, [1, 2])) === '[false,false]', 'and a negative n does not throw')
+ ok(JSON.stringify(top(1, ['a', 'b'])) === '[false,false]', 'a column with no numbers has no top')
+ ok(JSON.stringify(top(1, [3, 'zzz'])) === '[true,false]', 'text never outranks a number')
+}
+
+// ----------------------------------------------------------------- duplicates
+{
+ const style = { italic: true }
+ const dup = (vals: unknown[]) =>
+ evaluateRules([{ kind: 'duplicates', style }], vals).map((s) => s !== null)
+
+ ok(JSON.stringify(dup(['a', 'b', 'a'])) === '[true,false,true]', 'both copies are flagged')
+ ok(JSON.stringify(dup(['ACME', 'acme '])) === '[true,true]',
+ 'case and surrounding space do not make two values different to the eye')
+ ok(JSON.stringify(dup([null, '', null, 'x'])) === '[false,false,false,false]',
+ 'BLANKS are never duplicates — absence repeated is still absence')
+ ok(JSON.stringify(dup([1, 2, 3])) === '[false,false,false]', 'a unique column flags nothing')
+}
+
+// -------------------------------------------------------------- formula rules
+{
+ const style = { bold: true }
+ const f = (expr: string, vals: unknown[], cols?: Record<string, unknown[]>) =>
+ evaluateRules([{ kind: 'formula', expr, style }], vals, cols).map((s) => s !== null)
+
+ ok(JSON.stringify(f('value > 10', [9, 11])) === '[false,true]', 'the column is bound to `value`')
+ ok(JSON.stringify(f('VALUE > 10', [9, 11])) === '[false,true]', 'and the name is case-insensitive')
+ ok(JSON.stringify(f('value > AVERAGE(value)', [1, 2, 3])) === '[false,false,true]',
+ 'an aggregate mixes with the per-row value in ONE vectorised pass')
+ ok(JSON.stringify(f('MOD(value,2)=0', [1, 2, 3, 4])) === '[false,true,false,true]',
+ 'the whole function library is available')
+ ok(JSON.stringify(f('value > [Target]', [8, 12], { Target: [10, 10] })) === '[false,true]',
+ 'a cross-column rule compares against another column when the caller passes one')
+ ok(JSON.stringify(f('1/0', [1, 2])) === '[false,false]',
+ 'an ERROR never matches — a formatting rule must not paint on a wrong answer')
+ ok(JSON.stringify(f('Nope > 1', [1])) === '[false]', 'nor does an unknown column reference')
+ ok(JSON.stringify(f('UPPER(value)', ['a', 'b'])) === '[false,false]',
+ 'a non-empty STRING is not true — JS truthiness would light up the whole column')
+ ok(JSON.stringify(f('"true"', [1])) === '[true]', 'but the word "true" is')
+ ok(JSON.stringify(f('1=1', [1, 2])) === '[true,true]',
+ 'a scalar result broadcasts to every row')
+ ok(JSON.stringify(f(')(nonsense', [1])) === '[false]', 'and an unparseable expression matches nothing')
+}
+
+// ------------------------------------------------------------- the bar style
+{
+ const rule: Rule = { kind: 'dataBar', color: '#4488cc', negativeColor: '#cc4444' }
+ const out = evaluateRules([rule], [-50, 0, 100])
+ ok(out[0]?.bar?.color === '#cc4444' && out[2]?.bar?.color === '#4488cc',
+ 'negatives take the negative colour')
+ ok(out[0]?.bar?.negative === true && out[2]?.bar?.negative === undefined,
+ 'and carry the direction flag')
+ ok(near(out[0]?.bar?.axis ?? -1, 100 / 3),
+ 'the axis rides on the cell style — a renderer sees one row at a time and cannot recompute it')
+ ok(evaluateRules([{ kind: 'dataBar', color: '#4488cc' }], [-1])[0]?.bar?.color === '#4488cc',
+ 'without a negative colour, negatives use the one colour given')
+ ok(evaluateRules([rule], ['text'])[0] === null, 'a non-numeric row gets no bar style at all')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-dashboard.ts b/scripts/test-dash-dashboard.ts
new file mode 100644
index 00000000..d6a84f09
--- /dev/null
+++ b/scripts/test-dash-dashboard.ts
@@ -0,0 +1,683 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash dashboard + cross-filtering rig.
+//
+// node scripts/test-dash-dashboard.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. A dashboard is the one surface where every failure is
+// silent: the tiles still paint, the bars still have heights, and the number
+// on screen is a real number — of the wrong population. Six ways that happens,
+// and every one of them looks like a working dashboard:
+//
+// 1. A TILE THAT FILTERS ITSELF. Click "North" on a region chart and the
+// chart becomes one bar — so the reader cannot click "South", cannot
+// click "North" again, and the selection is not in the undo stack because
+// it is view state. A control that traps you is worse than no control.
+// 2. A SELECTION THAT DOES NOT COMPOSE. Two clicks on two tiles must mean
+// region = North AND stage = Won. The natural bug — a map keyed by column
+// that is assigned instead of merged — keeps the LAST click, and the tile
+// answers a wider question than it was asked, confidently.
+// 3. A BLANK THAT BELONGS TO EVERY CATEGORY, OR TO NONE. Both are wrong and
+// both are invisible: rows counted twice make totals that do not add up,
+// rows counted never make a dashboard whose categories quietly omit part
+// of the sheet. The check here is an EQUALITY — the categories of a
+// column partition the rows — because that is the statement that stops
+// being true when somebody "just" changes how nulls are stringified.
+// 4. AN EMPTY RESULT DRAWN AS ZERO. An axis with no bars reads as "we sold
+// nothing", and a KPI of £0 reads as a loss. Both are a lie in the shape
+// of a number, and both are what falling through to the renderer does.
+// 5. AN AVERAGE DIVIDED BY ROWS. Dividing by rows rather than by the values
+// PRESENT understates every average in proportion to how patchy the data
+// is — a number that is plausible, stable and wrong.
+// 6. A CACHED SERIES. The whole reason dash derives series at render is that
+// a stored one can disagree with the table beside it. A memo keyed by
+// tile id under a live selection is the same bug wearing a performance
+// argument.
+//
+// Every check below is then RE-RUN against a deliberately broken dependency,
+// and the run fails if the break does not trip it. A check that passes for a
+// broken implementation is not a check, and the only way to find out is to
+// break it on purpose.
+
+import { registerHooks } from 'node:module'
+
+// dashboard.ts imports its stylesheet — Vite's job, not Node's. Stub the
+// extension rather than moving the import, which is how every Bento app
+// co-locates a surface with its styles.
+registerHooks({
+ load(url, context, next) {
+ if (url.endsWith('.css')) {
+ return { format: 'module', source: 'export {}', shortCircuit: true }
+ }
+ return next(url, context)
+ },
+})
+
+const {
+ catOf, deriveTile, rowList, rowsForTile, selectionFilters, sheetGet,
+ toggleSelection, selectionChips, pickedOn, withView, viewsOf, defaultDashboard,
+ niceTicks, Dashboard, DEFAULT_COLS,
+} = await import('../dash/src/dashboard.ts')
+type DashTile = import('../dash/src/dashboard.ts').DashTile
+type DashView = import('../dash/src/dashboard.ts').DashView
+type CrossSelection = import('../dash/src/dashboard.ts').CrossSelection
+type SelectionEntry = import('../dash/src/dashboard.ts').SelectionEntry
+type TileData = import('../dash/src/dashboard.ts').TileData
+
+const { parseDoc } = await import('../dash/src/model.ts')
+type DashDoc = import('../dash/src/model.ts').DashDoc
+type TableSheet = import('../dash/src/model.ts').TableSheet
+
+const { Store } = await import('../dash/src/store.ts')
+const { starterDoc } = await import('../dash/src/starter.ts')
+type ColumnFilter = import('../dash/src/filter.ts').ColumnFilter
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string): void {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+/** Inside a check: a broken dependency has to make one of these throw. */
+class CheckFailed extends Error {}
+function must(cond: boolean, msg: string): void {
+ if (!cond) throw new CheckFailed(msg)
+}
+
+/**
+ * A NEGATIVE CONTROL. Run a check against a broken dependency and require it
+ * to trip. `ok` reports the mutation, not the check — so the transcript reads
+ * as "this break was caught", which is the only thing a negative control is
+ * evidence of.
+ */
+function mutated(name: string, run: () => void): void {
+ let thrown: unknown
+ try { run() } catch (e) { thrown = e }
+ ok(thrown instanceof CheckFailed,
+ `MUTANT — ${name} — is caught${thrown && !(thrown instanceof CheckFailed) ? ` (by a crash, not a check: ${(thrown as Error).message})` : ''}`)
+}
+
+// --------------------------------------------------------------- fixtures
+
+/**
+ * Seven rows, and every awkward case is deliberate:
+ * - row 4 has a BLANK region: the category that must exist, must be
+ * clickable, and must not be swept into North.
+ * - rows 3 and 5 have a blank VALUE: what `avg` must not divide by and what
+ * a bar must draw as a gap rather than as a zero.
+ * - row 5 (East) has no value at all: a category whose bar is absent and
+ * which still has to be selectable.
+ * - `zero` is all zeroes: the baseline that makes a percentage undefined.
+ */
+const FIXTURE = {
+ format: 'bento/dash',
+ version: 1,
+ policy: 'bento-dash-1',
+ docId: 'doc-fixture',
+ title: 'pipeline',
+ sheets: [{
+ id: 'sales',
+ name: 'Sales',
+ kind: 'table',
+ rids: [[1, 7]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'stage', name: 'Stage', type: 'text' },
+ { id: 'value', name: 'Value', type: 'money' },
+ { id: 'target', name: 'Target', type: 'money' },
+ { id: 'zero', name: 'Zero', type: 'number' },
+ ],
+ data: {
+ region: { enc: 'raw', v: ['North', 'North', 'South', 'South', null, 'East', 'North'] },
+ stage: { enc: 'raw', v: ['Won', 'Open', 'Won', 'Lost', 'Won', 'Open', 'Won'] },
+ value: { enc: 'raw', v: [100, 200, 300, null, 400, null, 50] },
+ target: { enc: 'raw', v: [120, 150, 200, 50, 100, null, 10] },
+ zero: { enc: 'raw', v: [0, 0, 0, 0, 0, 0, 0] },
+ },
+ steps: [{ op: 'import', from: 'fixture', at: '2026-08-05T00:00:00Z', rows: 7 }],
+ }],
+}
+
+const fresh = (): DashDoc => {
+ const r = parseDoc(JSON.stringify(FIXTURE))
+ if (!r.ok) throw new Error('fixture does not parse')
+ return r.doc
+}
+
+const sheetOf = (d: DashDoc): TableSheet => d.sheets[0] as TableSheet
+
+const CHART: DashTile = {
+ id: 'chart-region', kind: 'chart', x: 0, y: 0, w: 6, h: 3, chart: 'bar',
+ title: 'Value by region',
+ bind: { sheet: 'sales', x: 'region', series: ['value'], agg: 'sum' },
+}
+const KPI: DashTile = {
+ id: 'kpi-value', kind: 'kpi', x: 6, y: 0, w: 3, h: 1,
+ bind: { sheet: 'sales', col: 'value', agg: 'sum' },
+}
+const TABLE: DashTile = {
+ id: 'table-rows', kind: 'table', x: 0, y: 3, w: 12, h: 3,
+ bind: { sheet: 'sales', by: 'region' },
+}
+
+const pick = (from: string, col: string, v: string | null): SelectionEntry =>
+ ({ from, sheet: 'sales', col, v })
+
+/** The composition under test: filters → rows → derived tile. */
+type FilterFn = (sel: CrossSelection, tile: DashTile) => ColumnFilter[]
+
+function rowsOf(doc: DashDoc, tile: DashTile, sel: CrossSelection, filters: FilterFn): number[] {
+ const sheet = sheetOf(doc)
+ return rowList(sheet, rowsForTile(sheet, sheetGet(sheet), filters(sel, tile)))
+}
+
+function tileOf(
+ doc: DashDoc, tile: DashTile, sel: CrossSelection, filters: FilterFn,
+): TileData {
+ const sheet = sheetOf(doc)
+ return deriveTile(doc, tile, rowsForTile(sheet, sheetGet(sheet), filters(sel, tile)))
+}
+
+const asChart = (td: TileData): Extract<TileData, { kind: 'chart' }> => {
+ if (td.kind !== 'chart') throw new CheckFailed(`expected a chart, got ${td.kind}`)
+ return td
+}
+const asKpi = (td: TileData): Extract<TileData, { kind: 'kpi' }> => {
+ if (td.kind !== 'kpi') throw new CheckFailed(`expected a kpi, got ${td.kind}`)
+ return td
+}
+const same = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b)
+
+// ==================================================== the selection algebra
+
+console.log('\nthe selection is an algebra, and it composes')
+{
+ const a = pick('t1', 'region', 'North')
+ const sel0: CrossSelection = []
+ const sel1 = toggleSelection(sel0, a)
+ const sel2 = toggleSelection(sel1, { ...a })
+ ok(sel1.length === 1 && sel2.length === 0,
+ 'clicking a category selects it and clicking it again lets go — the toggle is the whole interaction')
+ ok(sel0.length === 0 && sel1.length === 1,
+ 'toggle is PURE: the array handed in is untouched, so the value assigned inside store.view() is a new one')
+
+ const two = toggleSelection(toggleSelection([], a), pick('t2', 'region', 'North'))
+ ok(two.length === 2,
+ 'the same category picked on two tiles is two entries — a selection remembers WHERE it came from, or a tile cannot skip its own')
+
+ const composed = toggleSelection(toggleSelection([], pick('t1', 'region', 'North')), pick('t2', 'stage', 'Won'))
+ const f = selectionFilters(composed, KPI)
+ ok(f.length === 2 && f.map((x) => x.col).join() === 'region,stage',
+ 'two columns become two filters — buildOrder ANDs them, which is what region=North AND stage=Won means')
+
+ const ored = toggleSelection(toggleSelection([], pick('t1', 'region', 'North')), pick('t2', 'region', 'South'))
+ const fo = selectionFilters(ored, KPI)
+ const set = fo[0].pred.op === 'isOneOf' ? [...fo[0].pred.set] : []
+ ok(fo.length === 1 && set.length === 2,
+ 'two categories of ONE column become one isOneOf of two values — inside a column values OR, or clicking a second bar would mean "no rows"')
+}
+
+console.log('\na tile never filters itself, and never reaches across sheets')
+{
+ const sel = [pick(CHART.id, 'region', 'North')]
+ ok(selectionFilters(sel, CHART).length === 0,
+ "a tile's own entries are not in its own filters")
+ ok(selectionFilters(sel, KPI).length === 1,
+ 'the same entry does filter every OTHER tile — that is the feature')
+
+ const foreign = [{ from: 't9', sheet: 'other-sheet', col: 'region', v: 'North' }]
+ ok(selectionFilters(foreign, KPI).length === 0,
+ 'a selection on another sheet does not reach this one — two sheets sharing a column NAME are not related, and a join is')
+}
+
+// ============================================== re-derivation under selection
+
+console.log('\ntiles re-derive against the selection')
+{
+ const doc = fresh()
+ const base = asChart(tileOf(doc, CHART, [], selectionFilters))
+ ok(same(base.cats, ['North', 'South', null, 'East']),
+ 'unfiltered, the region chart has four categories INCLUDING the blank one')
+ ok(same(base.series[0].data, [350, 300, 400, null]),
+ 'and the sums are the hand-computed ones — East has no values at all, which is a GAP (null), never a zero')
+
+ const won = [pick('other', 'stage', 'Won')]
+ const filtered = asChart(tileOf(doc, CHART, won, selectionFilters))
+ ok(same(filtered.cats, ['North', 'South', null]) && same(filtered.series[0].data, [150, 300, 400]),
+ 'selecting stage=Won on another tile re-derives this one: 150/300/400, and East disappears because it has no Won rows')
+
+ const kpi = asKpi(tileOf(doc, KPI, won, selectionFilters))
+ ok(kpi.value === 850 && kpi.rows === 4,
+ 'the KPI beside it re-derives to the same population — 850 over 4 rows')
+
+ const self = asChart(tileOf(doc, CHART, [pick(CHART.id, 'region', 'North')], selectionFilters))
+ ok(same(self.cats, base.cats) && same(self.series[0].data, base.series[0].data),
+ 'the SOURCE tile is unchanged by its own click — every other bar is still there to click')
+}
+
+console.log('\nnothing is cached: a tile re-derives from the document it is given')
+{
+ const doc = fresh()
+ const store = new Store(doc)
+ const before = asChart(deriveTile(store.doc, CHART, null))
+ store.commit({ op: 'setCells', sheet: 'sales', col: 'value', rids: [1], v: [999] })
+ const after = asChart(deriveTile(store.doc, CHART, null))
+ ok(before.series[0].data[0] === 350 && after.series[0].data[0] === 1249,
+ 'editing a cell moves the tile on the next derive — 350 becomes 1249, with no invalidation call anywhere')
+}
+
+// ================================================== the blank rule (§3)
+
+console.log('\nnull is a category, not an exemption')
+{
+ const doc = fresh()
+ const cats: Array<string | null> = ['North', 'South', null, 'East']
+ const got = cats.map((c) => rowsOf(doc, KPI, [pick('t', 'region', c)], selectionFilters))
+ ok(same(got[0], [0, 1, 6]), 'selecting North selects the North rows — and NOT the blank-region row')
+ ok(same(got[2], [4]), 'selecting the blank category selects exactly the blank-region row')
+ const union = got.flat().sort((a, b) => a - b)
+ ok(same(union, [0, 1, 2, 3, 4, 5, 6]),
+ 'the four categories PARTITION the sheet: every row is in exactly one, so no row is silently dropped and none is counted twice')
+
+ const b = parseDoc(JSON.stringify({
+ ...FIXTURE,
+ sheets: [{
+ ...FIXTURE.sheets[0], id: 'sales', rids: [[1, 4]],
+ data: {
+ region: { enc: 'raw', v: ['', ' ', null, 'North'] },
+ stage: { enc: 'raw', v: ['a', 'b', 'c', 'd'] },
+ value: { enc: 'raw', v: [1, 2, 4, 8] },
+ target: { enc: 'raw', v: [1, 1, 1, 1] },
+ zero: { enc: 'raw', v: [0, 0, 0, 0] },
+ },
+ }],
+ }))
+ if (!b.ok) throw new Error('blank fixture does not parse')
+ const bc = asChart(deriveTile(b.doc, CHART, null))
+ ok(same(bc.cats, [null, 'North']) && same(bc.series[0].data, [7, 8]),
+ '"", " " and null are ONE blank category, not three bars all labelled (blank) — the categories are the classes the filter can express')
+ const sheetB = b.doc.sheets[0] as TableSheet
+ const rowsB = rowList(sheetB, rowsForTile(sheetB, sheetGet(sheetB), selectionFilters([pick('t', 'region', null)], KPI)))
+ ok(same(rowsB, [0, 1, 2]),
+ 'and clicking that one bar selects all three spellings of blank — the bar and the filter agree by construction')
+}
+
+// ================================================== the empty case
+
+console.log('\nan empty result says so; it never draws a zero')
+{
+ const doc = fresh()
+ const impossible = [pick('a', 'region', 'East'), pick('b', 'stage', 'Won')]
+ const c = tileOf(doc, CHART, impossible, selectionFilters)
+ ok(c.kind === 'empty' && c.reason === 'no-rows',
+ 'a chart with no surviving rows is an EMPTY tile, not an axis with no bars — an empty bar chart reads as zero')
+ const k = tileOf(doc, KPI, impossible, selectionFilters)
+ ok(k.kind === 'empty' && k.reason === 'no-rows',
+ 'and so is the KPI — £0 for "we could not compute this" is the most expensive wrong number a dashboard prints')
+
+ const textKpi = deriveTile(doc, { ...KPI, bind: { sheet: 'sales', col: 'stage', agg: 'sum' } }, null)
+ ok(textKpi.kind === 'kpi' && textKpi.value === null,
+ 'summing a text column answers null, not 0 — filter.ts summarize refuses to invent a number and this passes that through')
+
+ const unknown = deriveTile(doc, { ...CHART, id: 'x', kind: 'sunburst' }, null)
+ ok(unknown.kind === 'empty' && unknown.reason === 'unknown-kind',
+ 'a tile kind this build cannot draw says so — an empty box reads as "no data", which is a different and wrong statement')
+
+ const noSheet = deriveTile(doc, { ...KPI, id: 'y', bind: { sheet: 'gone', col: 'value' } }, null)
+ ok(noSheet.kind === 'empty' && noSheet.reason === 'no-sheet',
+ 'a tile pointing at a sheet that is not here says THAT, rather than rendering a blank')
+}
+
+// ================================================== aggregation
+
+console.log('\naggregates divide by the values present')
+{
+ const doc = fresh()
+ const avg = asKpi(deriveTile(doc, { ...KPI, id: 'avg', bind: { sheet: 'sales', col: 'value', agg: 'avg' } }, null))
+ ok(avg.value === 210,
+ 'the average of 100/200/300/400/50 over seven rows is 210 — divided by the five values PRESENT, not by the rows')
+ const count = asKpi(deriveTile(doc, { ...KPI, id: 'n', bind: { sheet: 'sales', col: 'value', agg: 'count' } }, null))
+ ok(count.value === 5,
+ 'count counts values present, the same definition the status bar uses — a KPI that counted blanks would disagree with the footer')
+
+ const zero = asKpi(deriveTile(doc, { ...KPI, id: 'z', compare: { of: 'column', col: 'zero' } }, null))
+ ok(zero.baseline === 0 && zero.pct === null && zero.share === null && zero.delta === 1050,
+ 'a percentage against a zero baseline is null, not Infinity — the delta is still real and is still shown')
+
+ const won = [pick('other', 'stage', 'Won')]
+ const share = asKpi(tileOf(doc, { ...KPI, id: 's', compare: { of: 'all' } }, won, selectionFilters))
+ ok(share.value === 850 && share.baseline === 1050,
+ 'compare:"all" deliberately ignores the selection — that comparison is "how much of everything is this?"')
+ const plain = asKpi(deriveTile(doc, KPI, null))
+ ok(share.compare === 'all' && zero.compare === 'column' && plain.compare === null,
+ 'a KPI states WHICH comparison it made as a model word — the renderer branches on that and never on a translated label, which would take the wrong arm outside English')
+}
+
+// ================================================== the picking round trip
+
+console.log('\nwhat a click means is the same everywhere')
+{
+ const doc = fresh()
+ const sheet = sheetOf(doc)
+ const get = sheetGet(sheet)
+ const chart = asChart(deriveTile(doc, CHART, null))
+ // A ROW click and a BAR click have to produce the same entry, or a table and
+ // the chart above it toggle each other's selections instead of cancelling.
+ const rowCat = catOf(get('region', 4))
+ ok(rowCat === null && chart.cats[2] === null,
+ 'the blank row and the blank bar canonicalise to the same category, so a row click and a bar click cancel each other')
+ const numeric = catOf(10)
+ ok(numeric === '10',
+ 'a numeric category canonicalises to its digits — filter.ts isOneOf matches "10" back to the cell holding 10')
+
+ const on = pickedOn([pick(CHART.id, 'region', 'North'), pick('other', 'region', 'South')], CHART, 'region')
+ ok(on.size === 1 && on.has('North'),
+ 'a tile highlights only what was picked ON it — the highlight is the source, the filter is everyone else')
+
+ const chips = selectionChips([pick('t', 'region', null)], doc)
+ ok(chips[0].label === 'Region: (blank)',
+ 'the selection is legible: the chip names the column and the category, blank included')
+}
+
+// ================================================== view state, not document
+
+console.log('\nthe selection goes through store.view(): no checkpoint, no dirty flag, no op')
+{
+ const doc = fresh()
+ const store = new Store(doc)
+ const seen: string[] = []
+ store.on('doc', () => seen.push('doc'))
+ store.on('view', () => seen.push('view'))
+
+ // A minimal host: the class only ever touches classList/style/innerHTML plus
+ // the listeners, so a plain object is enough to run the real code path in
+ // node — which is the point, since a hand-rolled imitation of `pick` would
+ // prove nothing about `pick`.
+ const el = {
+ classList: { add(): void {} },
+ style: { setProperty(): void {} },
+ addEventListener(): void {},
+ removeEventListener(): void {},
+ innerHTML: '',
+ } as unknown as HTMLElement
+
+ const dash = new Dashboard({ el, store })
+ const before = JSON.stringify(store.doc)
+ dash.pick(pick('kpi-total', 'region', 'North'))
+
+ ok(JSON.stringify(store.doc) === before,
+ 'a click changes NOTHING in the document — not a field, not `modified`')
+ ok(store.canUndo === false,
+ 'and takes no undo checkpoint: exploring a dashboard must not fill the undo stack a reader would then have to walk back')
+ ok(seen.includes('view') && !seen.includes('doc'),
+ 'it emits `view` and never `doc` — the invalidation tier that does not dirty the file or mint a collab op')
+ ok(dash.selection.length === 1, 'and the selection landed')
+
+ dash.pick(pick('kpi-total', 'region', 'North'))
+ ok(dash.selection.length === 0, 'clicking the same category again clears it')
+
+ dash.pick(pick('kpi-total', 'region', 'East'))
+ dash.pick(pick('kpi-total', 'stage', 'Won'))
+ const html = String((el as unknown as { innerHTML: string }).innerHTML)
+ ok(html.includes('No rows match the current selection'),
+ 'and a selection that empties a tile paints the sentence, not an axis — the empty state reaches the DOM, not just the derivation')
+ ok(html.includes('Filtered by') && html.includes('Region: East'),
+ 'the chips say what the dashboard is filtered by, so a number is never quoted for a slice nobody can see')
+}
+
+// ================================================== the layout is document data
+
+console.log('\nthe layout travels in the file, additively')
+{
+ const view: DashView = {
+ id: 'v1', name: 'Overview', w: 12, h: 6,
+ tiles: [
+ { ...CHART },
+ { id: 'future', kind: 'sunburst', x: 6, y: 0, w: 6, h: 3, depth: 4 } as DashTile,
+ ],
+ legend: 'right',
+ }
+ const json = JSON.stringify({ ...FIXTURE, views: [view] })
+ const r = parseDoc(json)
+ ok(r.ok, 'a workbook carrying a dashboard parses')
+ if (r.ok) {
+ ok(JSON.stringify(r.doc) === json,
+ 'and round-trips BYTE-identical: an unknown tile kind, an unknown tile field and an unknown view field all survive (PLATFORM §3)')
+ const back = viewsOf(r.doc)
+ ok(back.length === 1 && back[0].tiles.length === 2 && back[0].tiles[1].depth === 4,
+ 'the reader sees them too — additivity is not just "the bytes survived", it is "nothing dropped them on the way in"')
+ }
+
+ const doc = fresh()
+ const one = withView(doc, view)
+ const two = withView(one, { ...view, name: 'Renamed' })
+ ok(viewsOf(doc).length === 0 && viewsOf(one).length === 1 && viewsOf(two).length === 1,
+ 'withView is pure and replaces by id — a second dashboard with the same id is an edit, not a duplicate')
+ ok(viewsOf(two)[0].name === 'Renamed', 'and the edit landed')
+}
+
+console.log('\na workbook with no dashboard gets a sensible one, and it is ephemeral')
+{
+ const doc = starterDoc()
+ const v = defaultDashboard(doc)
+ ok(!!v && v.tiles.length >= 4, 'the starter workbook mints a dashboard with KPIs, a chart and a table')
+ if (v) {
+ const ids = new Set(v.tiles.map((tile) => tile.id))
+ ok(ids.size === v.tiles.length, 'tile ids are unique — the selection is keyed by them')
+ ok(v.tiles.every((tile) => tile.x >= 0 && tile.x + tile.w <= (v.w || DEFAULT_COLS)),
+ 'and every tile fits inside the declared column count')
+ ok(v.tiles.every((tile) => !tile.bind || doc.sheets.some((s) => s.id === tile.bind!.sheet)),
+ 'every tile names a sheet that exists')
+ const kpi = deriveTile(doc, v.tiles[0], null)
+ ok(kpi.kind === 'kpi' && kpi.value === 97050,
+ 'and it derives: the starter pipeline totals £97,050')
+ }
+ ok(viewsOf(doc).length === 0,
+ 'minting it did NOT write it into the document — a dashboard nobody arranged must not dirty a file just for being looked at')
+}
+
+console.log('\nodds and ends')
+{
+ const doc = fresh()
+ const sheet = sheetOf(doc)
+ ok(rowsForTile(sheet, sheetGet(sheet), []) === null,
+ 'no filters is the null fast path — the identity vector is not allocated per tile per paint')
+ const slow = rowsForTile(sheet, sheetGet(sheet), [{ col: 'region', pred: { op: 'notBlank' } }])
+ ok(same(rowList(sheet, null), [0, 1, 2, 3, 4, 5, 6]) && same(slow, [0, 1, 2, 3, 5, 6]),
+ 'and the fast path agrees with the slow one on the population it stands for')
+
+ const table = deriveTile(doc, TABLE, [1, 2])
+ ok(table.kind === 'table' && table.rows.length === 2 && table.total === 7,
+ 'a table tile reports BOTH numbers — 2 of 7 — because "2 rows" under a filter is how a subtotal gets quoted as a total')
+
+ ok(same(niceTicks(0, 350), [0, 100, 200, 300, 400]), 'axis ticks are the ones a person would have chosen')
+ ok(same(niceTicks(5, 5), [5]), 'and a flat series does not divide by a zero range')
+
+ const overridden = fresh()
+ const s = sheetOf(overridden)
+ s.cells = { 'value:1': { v: 1000, why: 'corrected' } }
+ const k = asKpi(deriveTile(overridden, KPI, null))
+ ok(k.value === 1950,
+ 'a hand correction in sheet.cells is what the tile totals — the grid paints the override, so a tile that read past it would contradict the cell three inches away')
+ const c = asChart(deriveTile(overridden, CHART, null))
+ ok(c.series[0].data[0] === 1250,
+ 'and the CHART sees it too, because every bound column reaches optionFor through the same accessor')
+}
+
+// ==================================================== NEGATIVE CONTROLS
+//
+// Each mutation below is a plausible implementation of this feature, not a
+// strawman: they are the six failures in the header, plus the two boundary
+// bugs the fast path and the round trip invite. Every one is fed through the
+// REAL derivation wherever a dependency can carry the fault, so what is being
+// tested is the check, on the code path it guards.
+
+console.log('\nnegative controls: each break must trip a check')
+
+/** The check that the source tile keeps its other categories. */
+function checkSelfExemption(filters: FilterFn): void {
+ const doc = fresh()
+ const td = asChart(tileOf(doc, CHART, [pick(CHART.id, 'region', 'North')], filters))
+ must(td.cats.length === 4, `source tile lost its categories: ${JSON.stringify(td.cats)}`)
+ must(td.series[0].data[0] === 350, 'source tile re-derived against its own click')
+}
+
+/** The check that two clicks on two tiles AND together. */
+function checkCompose(filters: FilterFn): void {
+ const doc = fresh()
+ const sel = [pick('a', 'region', 'North'), pick('b', 'stage', 'Won')]
+ const rows = rowsOf(doc, KPI, sel, filters)
+ must(same(rows, [0, 6]), `region=North AND stage=Won is rows 0,6; got ${JSON.stringify(rows)}`)
+}
+
+/** The check that the categories of a column partition the sheet. */
+function checkPartition(cat: (v: unknown) => string | null, filters: FilterFn): void {
+ const doc = fresh()
+ const sheet = sheetOf(doc)
+ const get = sheetGet(sheet)
+ const cats = [...new Set([0, 1, 2, 3, 4, 5, 6].map((i) => cat(get('region', i))))]
+ const sets = cats.map((c) => rowsOf(doc, KPI, [pick('t', 'region', c)], filters))
+ const union = sets.flat().sort((a, b) => a - b)
+ // Disjointness first, so an over-covering break reports itself as one rather
+ // than as a coverage failure with a confusing list.
+ must(union.length === new Set(union).size,
+ `a row is in two categories at once: ${JSON.stringify(union)}`)
+ must(same(union, [0, 1, 2, 3, 4, 5, 6]),
+ `the categories do not cover the sheet: ${JSON.stringify(union)}`)
+}
+
+/** The check that an emptied tile is empty rather than zero. */
+function checkEmpty(td: TileData): void {
+ must(td.kind === 'empty', `an emptied tile derived as ${td.kind} — an axis with no bars reads as zero`)
+}
+
+/** The check that an average divides by the values present. */
+function checkAvg(v: number | null): void {
+ must(v === 210, `average is ${v}: divided by rows, not by the values present`)
+}
+
+/** The check that a tile re-derives after an edit. */
+function checkNoCache(derive: (doc: DashDoc, tile: DashTile) => TileData): void {
+ const store = new Store(fresh())
+ const a = asChart(derive(store.doc, CHART))
+ store.commit({ op: 'setCells', sheet: 'sales', col: 'value', rids: [1], v: [999] })
+ const b = asChart(derive(store.doc, CHART))
+ must(a.series[0].data[0] !== b.series[0].data[0], 'the tile did not move when the data did')
+}
+
+/**
+ * The check that a stored dashboard round-trips byte-identical.
+ *
+ * Parameterised by the PARSER, not by the json: mutating the input would only
+ * prove that a smaller document is still itself. The fault has to sit in the
+ * thing that reads the file, which is where it would really sit.
+ */
+type Parse = (json: string) => DashDoc
+
+const ROUNDTRIP_JSON = JSON.stringify({
+ ...FIXTURE,
+ views: [{ id: 'v', name: 'n', w: 12, h: 2, legend: 'right', tiles: [{ ...CHART, depth: 4 }] }],
+})
+
+function checkRoundTrip(parse: Parse): void {
+ const doc = parse(ROUNDTRIP_JSON)
+ must(JSON.stringify(doc) === ROUNDTRIP_JSON, 'a dashboard field was dropped on the way in')
+}
+
+const realParse: Parse = (json) => {
+ const r = parseDoc(json)
+ if (!r.ok) throw new CheckFailed('the workbook did not parse')
+ return r.doc
+}
+
+// --- the mutants -----------------------------------------------------------
+
+/** M1: the exemption is forgotten — the naive "apply every entry" filter. */
+const noExemption: FilterFn = (sel, tile) =>
+ selectionFilters(sel.map((e) => ({ ...e, from: '' })), tile)
+
+/** M2: `byCol` is ASSIGNED rather than merged — the last click wins. */
+const lastWins: FilterFn = (sel, tile) => {
+ const byCol = new Map<string, Set<unknown>>()
+ for (const e of sel) {
+ if (e.from === tile.id || e.sheet !== tile.bind?.sheet) continue
+ byCol.set(e.col, new Set([e.v]))
+ }
+ const all = [...byCol]
+ return all.length ? [{ col: all[all.length - 1][0], pred: { op: 'isOneOf', set: all[all.length - 1][1] } }] : []
+}
+
+/** M3: the naive stringify — `null` becomes the string "null", which is a
+ * category no row is in, so the blank rows fall out of the dashboard. */
+const naiveCat = (v: unknown): string | null => String(v)
+
+/** M4: blanks match every selection — "an unknown region is everywhere". */
+const blanksMatchAll: FilterFn = (sel, tile) => {
+ const f = selectionFilters(sel, tile)
+ return f.map((x) => (x.pred.op === 'isOneOf'
+ ? { col: x.col, pred: { op: 'isOneOf', set: new Set([...x.pred.set, null]) } as ColumnFilter['pred'] }
+ : x))
+}
+
+/** M5: the fast path leaks — one selected value is treated as "no filter". */
+const leakyFastPath: FilterFn = (sel, tile) => {
+ const f = selectionFilters(sel, tile)
+ return f.filter((x) => !(x.pred.op === 'isOneOf' && x.pred.set.size === 1))
+}
+
+/** M6: the memo, keyed by tile id, that a profiler talks you into. */
+const memo = new Map<string, TileData>()
+const cachedDerive = (doc: DashDoc, tile: DashTile): TileData => {
+ const hit = memo.get(tile.id)
+ if (hit) return hit
+ const td = deriveTile(doc, tile, null)
+ memo.set(tile.id, td)
+ return td
+}
+
+mutated('a tile that applies its own click', () => checkSelfExemption(noExemption))
+mutated('a byCol map assigned instead of merged (last click wins)', () => checkCompose(lastWins))
+mutated('String(v) categories, so blanks belong to no category', () => checkPartition(naiveCat, selectionFilters))
+mutated('blanks added to every selection, so a row is in two categories', () => checkPartition(catOf, blanksMatchAll))
+mutated('a single-value filter dropped as if it were no filter', () => checkCompose(leakyFastPath))
+mutated('an emptied chart falling through to the renderer', () => checkEmpty({
+ kind: 'chart', chart: 'bar', cats: [], series: [{ name: 'Value', data: [] }], colors: [], rows: 0,
+}))
+mutated('an emptied KPI rendered as 0', () => checkEmpty({
+ kind: 'kpi', value: 0, agg: 'sum', rows: 0, baseline: null, delta: null, pct: null, share: null,
+}))
+mutated('an average divided by rows rather than by values present', () => checkAvg(1050 / 7))
+mutated('a series memoised by tile id', () => checkNoCache(cachedDerive))
+/** M7: the parser that "tidies" a tile down to the keys this build knows —
+ * which is precisely how a file written by a newer dash loses half of itself
+ * the first time an older one saves it (PLATFORM §3). */
+const tidyingParse: Parse = (json) => {
+ const doc = realParse(json)
+ const views = viewsOf(doc).map((v) => ({
+ id: v.id, name: v.name, w: v.w, h: v.h,
+ tiles: v.tiles.map((tl) => ({ id: tl.id, kind: tl.kind, x: tl.x, y: tl.y, w: tl.w, h: tl.h, bind: tl.bind })),
+ }))
+ return { ...doc, views: views as never }
+}
+
+mutated('a parser that tidies unknown tile and view fields away', () => checkRoundTrip(tidyingParse))
+
+console.log('\nand the real implementation passes every one of them')
+{
+ const run = (name: string, fn: () => void): void => {
+ try { fn(); ok(true, name) } catch (e) { ok(false, `${name} — ${(e as Error).message}`) }
+ }
+ run('self-exemption', () => checkSelfExemption(selectionFilters))
+ run('composition', () => checkCompose(selectionFilters))
+ run('partition', () => checkPartition(catOf, selectionFilters))
+ run('empty', () => checkEmpty(tileOf(fresh(), CHART, [pick('a', 'region', 'East'), pick('b', 'stage', 'Won')], selectionFilters)))
+ run('average', () => checkAvg(asKpi(deriveTile(fresh(), { ...KPI, bind: { sheet: 'sales', col: 'value', agg: 'avg' } }, null)).value))
+ run('no cache', () => checkNoCache((doc, tile) => deriveTile(doc, tile, null)))
+ run('round trip', () => checkRoundTrip(realParse))
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-filter.ts b/scripts/test-dash-filter.ts
new file mode 100644
index 00000000..16ede38e
--- /dev/null
+++ b/scripts/test-dash-filter.ts
@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash filter + multi-key sort rig.
+//
+// node scripts/test-dash-filter.ts
+//
+// WHAT THIS PROVES. Filtering and sorting never touch the document — they build
+// an order vector — so nothing here can corrupt a file. What they can do is
+// show the reader the WRONG ROWS, confidently, with no error state anywhere on
+// screen. Every failure in this file is of that shape:
+//
+// 1. LEXICAL COMPARISON OF NUMBERS. "9" < "10" is false as text. A column of
+// digits that arrived as strings then sorts 1, 10, 100, 2 and a "less than
+// 10" filter hides the 9 — and the grid looks perfectly sorted.
+// 2. A BLANK TREATED AS A VALUE. `null < 5` is TRUE in JavaScript and
+// `Number(null)` is 0, so the naive implementation files every empty cell
+// under "less than 5" and stacks them at the top of an ascending sort.
+// 3. A SECOND SORT KEY THAT IS SILENTLY DROPPED. A single-key comparator
+// returns 0 on a tie and lets the engine decide; the dialog says "then by
+// Date" and the rows are in insertion order.
+// 4. A TOP-N THAT RANKED THE WRONG POPULATION. Rank before filter and "top 3
+// in the North" is the top 3 overall intersected with the North — usually
+// fewer than three rows, sometimes none, never an error.
+// 5. A CHECKBOX THAT WILL NOT TICK. `Set.has(10)` does not match the cell
+// holding "10", so a box the user just ticked filters its own rows away.
+// 6. AN AGGREGATE OVER THE ROWS THAT ARE NOT SHOWN. The status bar must total
+// the visible rows; totalling the column is a real number that answers a
+// question nobody asked.
+
+import {
+ passes, buildOrder, distinctValues, summarize, compare, isBlank,
+ needsWholeColumn, type Get, type Predicate,
+} from '../dash/src/filter.ts'
+import type { TableSheet } from '../dash/src/model.ts'
+import { readCell } from '../dash/src/store.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+/** A `get` over plain columns — the same shape the grid builds from readCell. */
+const over = (cols: Record<string, unknown[]>): Get =>
+ (c, r) => (cols[c] ? cols[c][r] : undefined)
+
+const eq = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b)
+
+// The working set. `qty` is the case that matters: digits that arrived as TEXT,
+// which is every CSV column import declined to type.
+const cols: Record<string, unknown[]> = {
+ region: ['North', 'South', 'north', 'South', null, 'North'],
+ rep: ['Ada', 'Bob', 'Cara', 'Ada', 'Dan', 'Bob'],
+ amount: [10, 9, 100, 2, 1000, null],
+ qty: ['9', '10', '100', '2', '', '3'],
+ when: ['2026-01-15', '2026-02-03', '2026-10-01', null, '2026-03-30', '2026-01-15'],
+}
+const get = over(cols)
+const N = 6
+const order = (f: Parameters<typeof buildOrder>[2], s: Parameters<typeof buildOrder>[3]) =>
+ buildOrder(N, get, f, s)
+
+// ------------------------------------------------- 1. numbers are numbers
+ok(passes('9', { op: 'less', v: '10' }) === true,
+ '"9" < "10" is TRUE — a column of digits compares numerically')
+ok(('9' < '10') === false,
+ 'and that is NOT what text comparison says: the bug this exists to prevent')
+ok(passes(9, { op: 'less', v: '10' }) === true,
+ 'a number cell against the string a menu hands back still compares numerically')
+ok(passes('1,200', { op: 'greater', v: 999 }) === true,
+ 'a grouped "1,200" reads as 1200, not as text beginning with 1')
+ok(passes('50%', { op: 'greater', v: 1 }) === false,
+ '"50%" is NOT read as 50 — a percent column stores the fraction 0.5, so ' +
+ 'reading the notation as a number would be wrong by 100x')
+ok(('50%' > '1') === true && ('1 unit' < '10') === true,
+ 'as TEXT, "50%" is greater than 1 and "1 unit" is less than 10: both arbitrary')
+ok(passes('1 unit', { op: 'less', v: 10 }) === false,
+ 'so a NUMBER filter refuses a TEXT cell rather than answering arbitrarily')
+ok(passes('Cara', { op: 'greater', v: 'Bob' }) === true,
+ 'while text against text still orders — that is how "after M" works on names')
+{
+ const m = over({ mix: [10, 'n/a', 2, 'abc'] })
+ ok(eq(buildOrder(4, m, [], [{ col: 'mix', dir: 'asc' }]), [2, 0, 3, 1]),
+ 'a column holding both sorts numbers first, then text — Excel\'s order, and ' +
+ 'the only stable one: comparing 10 against "n/a" as strings drops the ' +
+ 'number wherever its digits happen to fall')
+}
+ok(eq(order([], [{ col: 'qty', dir: 'asc' }]), [3, 5, 0, 1, 2, 4]),
+ 'sorting text digits gives 2, 3, 9, 10, 100 — and the blank last')
+ok(order([], [{ col: 'qty', dir: 'asc' }])[0] !== 1,
+ 'a lexical sort would have put "10" first; this one does not')
+
+// -------------------------------------------------------------- 2. dates
+ok(passes('2026-02-03', { op: 'less', v: '2026-10-01' }) === true,
+ 'ISO dates compare chronologically as text — which is why import stores them so')
+ok(compare('2026-10-01', '2026-02-03') > 0, 'October sorts after February, not before')
+ok(eq(order([], [{ col: 'when', dir: 'asc' }]), [0, 5, 1, 4, 2, 3]),
+ 'a date sort is chronological, ties keep document order, and the blank sinks')
+
+// --------------------------------------------------------------- 3. text
+ok(passes('North', { op: 'equals', v: 'north' }) === true, 'text equality ignores case')
+ok(passes(10, { op: 'equals', v: '10' }) === true,
+ 'and equality is type-aware: the cell 10 equals the typed "10"')
+ok(passes('Ada', { op: 'contains', v: 'A' }) === true, 'contains ignores case')
+ok(passes('Bob', { op: 'contains', v: 'a' }) === false, 'and still says no when it means no')
+ok(passes('Bob', { op: 'notContains', v: 'a' }) === true, 'notContains is its complement')
+ok(passes(null, { op: 'notContains', v: 'a' }) === true, 'a blank does not contain anything')
+ok(passes('Cara', { op: 'startsWith', v: 'ca' }) === true
+ && passes('Cara', { op: 'endsWith', v: 'RA' }) === true, 'startsWith / endsWith')
+ok(passes('Cara', { op: 'startsWith', v: 'ra' }) === false, 'startsWith is not contains')
+
+// ----------------------------------------------- 4. blanks are not values
+ok(((null as unknown as number) < 5) === true,
+ 'JavaScript says null < 5, which is where the whole blank problem comes from')
+ok(passes(null, { op: 'less', v: 5 }) === false,
+ 'but a blank cell is NOT less than 5 — it is not a value at all')
+ok(passes(null, { op: 'greater', v: 5 }) === false, 'nor greater than 5')
+ok(passes(' ', { op: 'greaterOrEqual', v: 0 }) === false,
+ 'whitespace is blank too, and Number(" ") being 0 is not a reason to show it')
+ok(passes(0, { op: 'isBlank' }) === false && isBlank(0) === false,
+ 'ZERO IS NOT BLANK — it is an answer the author entered')
+ok(passes(false, { op: 'isBlank' }) === false, 'and neither is false')
+ok(passes(null, { op: 'isBlank' }) === true && passes('', { op: 'isBlank' }) === true,
+ 'null and "" are blank')
+ok(passes(null, { op: 'notEquals', v: 5 }) === true,
+ 'a blank cell DOES "not equal" 5, or equals/notEquals fail to partition the rows')
+ok(passes(null, { op: 'equals', v: null }) === true,
+ 'and equals against nothing is how a menu asks for the empties')
+ok(eq(order([], [{ col: 'amount', dir: 'asc' }]), [3, 1, 0, 2, 4, 5]),
+ 'ascending: blanks SINK to the bottom')
+ok(eq(order([], [{ col: 'amount', dir: 'desc' }]), [4, 2, 0, 1, 3, 5]),
+ 'descending: blanks sink to the bottom AGAIN — a blank is not "smallest"')
+ok(order([], [{ col: 'amount', dir: 'desc' }])[0] !== 5,
+ 'specifically, the blank is not the largest value either')
+
+// ------------------------------------------------------------- 5. between
+ok(passes(10, { op: 'between', lo: 10, hi: 20 }) === true
+ && passes(20, { op: 'between', lo: 10, hi: 20 }) === true, 'between includes both ends')
+ok(passes(9.99, { op: 'between', lo: 10, hi: 20 }) === false, 'and excludes just outside')
+ok(passes(15, { op: 'between', lo: 20, hi: 10 }) === true,
+ 'bounds typed in the wrong order still mean the range between them')
+ok(passes(1e6, { op: 'between', lo: 10, hi: null }) === true,
+ 'an empty upper box is an OPEN end, not an empty grid')
+ok(passes(null, { op: 'between', lo: 10, hi: 20 }) === false, 'a blank is in no range')
+
+// ----------------------------------------------- 6. the checkbox list ticks
+ok(new Set<unknown>([10]).has('10') === false,
+ 'Set.has is identity: a set holding 10 does not contain "10" — the checkbox bug')
+ok(passes('10', { op: 'isOneOf', set: new Set([10]) }) === true,
+ 'so isOneOf matches on a canonical key instead, and the box ticks its own rows')
+ok(passes('North', { op: 'isOneOf', set: new Set(['north']) }) === true,
+ 'and matches text case-insensitively, as the list deduped it')
+ok(passes(null, { op: 'isOneOf', set: new Set([null]) }) === true,
+ 'null in the set is the "(Blanks)" box')
+ok(passes('North', { op: 'isOneOf', set: new Set(['south']) }) === false,
+ 'and a value nobody ticked is still filtered out')
+ok(eq(order([{ col: 'region', pred: { op: 'isOneOf', set: new Set(['north']) } }], []),
+ [0, 2, 5]),
+'buildOrder\'s pre-keyed fast path agrees with passes(), case-folding and all')
+
+// ------------------------------------------------------ 7. filters AND
+ok(eq(order([
+ { col: 'region', pred: { op: 'isOneOf', set: new Set(['North', 'South']) } },
+ { col: 'amount', pred: { op: 'greater', v: 9 } },
+], []), [0, 2]),
+'two filters intersect: North/South AND over 9')
+
+// ------------------------------------------------------ 8. multi-key sort
+{
+ const m = over({
+ a: ['x', 'x', 'x', 'y', 'y'],
+ b: [2, 1, 2, 1, 1],
+ c: ['q', 'r', 'p', 's', 't'],
+ })
+ const three = buildOrder(5, m, [], [
+ { col: 'a', dir: 'asc' }, { col: 'b', dir: 'asc' }, { col: 'c', dir: 'asc' },
+ ])
+ ok(eq(three, [1, 2, 0, 3, 4]),
+ 'three keys: a, then b breaks its ties, then c breaks b\'s')
+ const one = buildOrder(5, m, [], [{ col: 'a', dir: 'asc' }])
+ ok(eq(one, [0, 1, 2, 3, 4]) && !eq(one, three),
+ 'and the one-key answer is DIFFERENT — which is what a dropped second key looks like')
+ ok(eq(buildOrder(5, m, [], [{ col: 'a', dir: 'asc' }, { col: 'b', dir: 'desc' }]),
+ [0, 2, 1, 3, 4]),
+ 'each key carries its OWN direction: a ascending, b descending')
+ ok(eq(buildOrder(5, m, [], [{ col: 'b', dir: 'asc' }, { col: 'a', dir: 'asc' }]),
+ [1, 3, 4, 0, 2]),
+ 'and key ORDER matters — b then a is a different sort from a then b')
+}
+{
+ // blanks tie on the first key, so the second key still has to order them
+ const m = over({ p: ['x', null, null, 'w'], q: [2, 5, 1, 1] })
+ ok(eq(buildOrder(4, m, [], [{ col: 'p', dir: 'asc' }, { col: 'q', dir: 'asc' }]),
+ [3, 0, 2, 1]),
+ 'rows blank on the first key sink together, and the second key orders them')
+ ok(eq(buildOrder(4, m, [], [{ col: 'p', dir: 'desc' }, { col: 'q', dir: 'asc' }]),
+ [0, 3, 2, 1]),
+ 'reversing the first key does not float the blanks to the top')
+}
+{
+ const m = over({ same: ['a', 'a', 'a', 'a'] })
+ ok(eq(buildOrder(4, m, [], [{ col: 'same', dir: 'desc' }]), [0, 1, 2, 3]),
+ 'rows equal on every key keep document order — the sort is deterministic')
+}
+
+// ------------------------------------------------------------ 9. rank filters
+ok(needsWholeColumn({ op: 'topN', n: 3 }) === true
+ && needsWholeColumn({ op: 'greater', v: 3 }) === false,
+'needsWholeColumn tells a per-row caller which predicates it cannot evaluate')
+{
+ let threw = false
+ try { passes(1, { op: 'topN', n: 3 } as Predicate) } catch { threw = true }
+ ok(threw,
+ 'passes() REFUSES topN rather than answering: true would show every row and ' +
+ 'false would show none, and both look like a working filter')
+}
+ok(eq(order([{ col: 'amount', pred: { op: 'topN', n: 2 } }], []), [2, 4]),
+ 'top 2 by amount is 100 and 1000, returned in row order')
+ok(eq(order([{ col: 'amount', pred: { op: 'bottomN', n: 2 } }], []), [1, 3]),
+ 'bottom 2 is 2 and 9 — the BLANK is not the bottom, it has no rank')
+ok(eq(order([
+ { col: 'region', pred: { op: 'isOneOf', set: new Set(['north']) } },
+ { col: 'amount', pred: { op: 'topN', n: 1 } },
+], []), [2]),
+'"top 1 in the North" ranks what SURVIVED the other filters — ranking first ' +
+ 'would intersect 1000 (region blank) with North and return nothing')
+ok(order([
+ { col: 'region', pred: { op: 'isOneOf', set: new Set(['north']) } },
+ { col: 'amount', pred: { op: 'topN', n: 1 } },
+], []).length !== 0, 'and specifically it is not empty')
+ok(eq(order([{ col: 'amount', pred: { op: 'topN', n: 99 } }], []), [0, 1, 2, 3, 4]),
+ 'a top-N larger than the column keeps every ranked row — still not the blank')
+ok(eq(order([{ col: 'amount', pred: { op: 'topN', n: 0 } }], []), []),
+ '"top 0" is nothing, not everything')
+{
+ const m = over({ v: [5, 5, 5, 1] })
+ const r = buildOrder(4, m, [{ col: 'v', pred: { op: 'topN', n: 2 } }], [])
+ ok(r.length === 3 && eq(r, [0, 1, 2]),
+ 'the cut is a THRESHOLD, so three tied values all survive a top 2 — ' +
+ 'dropping one of them would be a coin flip the reader cannot see')
+}
+
+// ------------------------------------------------------- 10. distinct values
+{
+ const d = distinctValues(get, 'region', N)
+ ok(d.values.length === 3 && d.values[2] === null,
+ '"North"/"north" dedupe to one entry, and "(Blanks)" is one box at the end')
+ ok(d.values[0] === 'North',
+ 'the entry shown is the first-seen ORIGINAL, not a normalised copy')
+ ok(d.truncated === false, 'and nothing is claimed to be truncated when it is not')
+}
+{
+ const m = over({ n: ['10', 10, ' 10 ', '9'] })
+ const d = distinctValues(m, 'n', 4)
+ ok(d.values.length === 2, '10, "10" and " 10 " are ONE checkbox, not three')
+ ok(d.values[0] === '9', 'and the list is in value order: 9 before 10, not "10" before "9"')
+}
+{
+ const m = over({ n: ['a', 'b', 'c', 'd', 'e'] })
+ const d = distinctValues(m, 'n', 5, 3)
+ ok(d.truncated === true && d.values.length === 3,
+ 'past the cap the list SAYS it is partial rather than showing three as if they were five')
+}
+{
+ // the blank arrives after the cap is already reached
+ const m = over({ n: ['a', 'b', 'c', 'd', null] })
+ const d = distinctValues(m, 'n', 5, 2)
+ ok(d.truncated === true && d.values.length === 3 && d.values[2] === null,
+ 'a truncated list still reports its "(Blanks)" box — otherwise that filter ' +
+ 'cannot be expressed at all')
+}
+{
+ // the round trip the whole canonical-key design exists for
+ const d = distinctValues(get, 'region', N)
+ const all = buildOrder(N, get, [
+ { col: 'region', pred: { op: 'isOneOf', set: new Set(d.values) } },
+ ], [])
+ ok(all.length === N,
+ 'ticking every box the list offered shows every row — list and filter agree by construction')
+ const some = buildOrder(N, get, [
+ { col: 'region', pred: { op: 'isOneOf', set: new Set([d.values[1]]) } },
+ ], [])
+ ok(eq(some, [1, 3]), 'and unticking all but one leaves exactly that value\'s rows')
+}
+
+// ------------------------------------------------------------- 11. summarize
+{
+ const all = buildOrder(N, get, [], [])
+ const s = summarize(get, 'amount', all)
+ ok(s.count === 5 && s.blanks === 1, 'count is the values present; blanks are reported apart')
+ ok(s.sum === 1121 && s.min === 2 && s.max === 1000, 'sum / min / max')
+ ok(s.avg === 224.2, 'avg')
+}
+{
+ const visible = buildOrder(N, get, [{ col: 'amount', pred: { op: 'less', v: 11 } }], [])
+ const s = summarize(get, 'amount', visible)
+ ok(eq(visible, [0, 1, 3]), 'a filter leaves three rows visible')
+ ok(s.sum === 21,
+ 'and the status bar totals THOSE rows — 1121 would be the honest answer to a ' +
+ 'question nobody asked')
+}
+{
+ const m = over({ mix: [10, 'n/a', null, 20] })
+ const s = summarize(m, 'mix', [0, 1, 2, 3])
+ ok(s.count === 3 && s.numeric === 2 && s.blanks === 1,
+ 'a mixed column counts values, numbers and blanks separately')
+ ok(s.avg === 15,
+ 'avg divides by the NUMBERS (30/2), not by the visible rows (30/4) or the values (30/3)')
+}
+{
+ const s = summarize(get, 'rep', [0, 1, 2, 3, 4, 5])
+ ok(s.count === 6 && s.numeric === 0, 'a text column still counts its values')
+ ok(s.sum === null, 'but its sum is null — 0 would read as "these add up to nothing"')
+ ok(s.min === null && s.max === null,
+ 'and min/max are null, NOT the Infinity that Math.min() of an empty list returns')
+ ok(s.avg === null, 'and avg is null, not NaN')
+}
+{
+ const s = summarize(get, 'amount', [])
+ ok(s.count === 0 && s.blanks === 0 && s.sum === null,
+ 'an empty selection aggregates to nothing at all')
+}
+
+// -------------------------------------------- 12. wired to a real sheet
+{
+ const sheet: TableSheet = {
+ id: 'sh', name: 'S', kind: 'table',
+ rids: [[1, 4]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'money' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, null, 0] },
+ amount: { enc: 'raw', v: [10, 9, 100, 2] },
+ },
+ steps: [],
+ }
+ const sget: Get = (c, r) => readCell(sheet.data[c], r)
+ ok(eq(buildOrder(4, sget, [], [{ col: 'region', dir: 'asc' }]), [0, 3, 1, 2]),
+ 'reading through readCell, a dictionary column sorts and its null sinks')
+ ok(eq(buildOrder(4, sget,
+ [{ col: 'region', pred: { op: 'isOneOf', set: new Set(['north']) } }],
+ [{ col: 'amount', dir: 'desc' }]), [0, 3]),
+ 'and filter + sort compose over the encoded column the grid actually reads')
+ ok(JSON.stringify(sheet.data.amount) === JSON.stringify({ enc: 'raw', v: [10, 9, 100, 2] })
+ && sheet.rids.length === 1,
+ 'THE DOCUMENT IS UNTOUCHED: sorting and filtering are view state, so no ' +
+ 'checkpoint, no dirty flag, no collab op')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-functions.ts b/scripts/test-dash-functions.ts
new file mode 100644
index 00000000..04cc9b3f
--- /dev/null
+++ b/scripts/test-dash-functions.ts
@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash function-pack rig — lookups, multi-criteria, finance, statistics.
+//
+// node scripts/test-dash-functions.ts
+//
+// WHAT THIS PROVES. These are the functions people reach for when the answer
+// MATTERS — a loan payment, an internal rate of return, a lookup joining two
+// tables, a two-condition total in a board pack. Nobody re-derives them by
+// hand, which means a wrong one is not caught by the person using it.
+//
+// So the checks below are mostly not "does it compute" but "does it REFUSE".
+// The three failure shapes that actually bite:
+//
+// AN APPROXIMATE MATCH ON UNSORTED DATA. VLOOKUP's legacy 4th argument
+// defaults to TRUE in Excel and returns a confidently wrong row. Ours
+// defaults to exact, and that difference is tested.
+// A MULTI-CRITERIA FILTER THAT ORs INSTEAD OF ANDs. The total still looks
+// like a total; it is just the wrong population.
+// AN IRR THAT CONVERGED ON NOTHING. Newton-Raphson returns a number for cash
+// flows that have no root. A refusal beats a plausible rate.
+
+import { evaluate, isErr, FUNCTIONS, type Cell, type Vec } from '../dash/src/formula.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+/** Evaluate `src` over named columns; returns the first row's value. */
+const ev = (src: string, cols: Record<string, Vec> = {}): Cell => {
+ const map = new Map<string, Vec>()
+ let n = 1
+ for (const [k, v] of Object.entries(cols)) { map.set(k, v); n = Math.max(n, v.length) }
+ return evaluate(src, { cols: map, n })[0] ?? null
+}
+const code = (v: Cell): string => (isErr(v) ? String(v) : `not an error (${JSON.stringify(v)})`)
+const near = (v: Cell, want: number, eps = 1e-6): boolean =>
+ typeof v === 'number' && Math.abs(v - want) < eps
+
+const REGION = ['North', 'South', 'North', 'East', 'South']
+const STAGE = ['Won', 'Open', 'Won', 'Open', 'Won']
+const VALUE = [10, 20, 30, 40, 50]
+const T = { region: REGION, stage: STAGE, value: VALUE }
+
+// --------------------------------------------------------------- lookups
+{
+ ok(ev('XLOOKUP("East", region, value)', T) === 40, 'XLOOKUP finds the row and returns from the other column')
+ ok(code(ev('XLOOKUP("West", region, value)', T)) === '#N/A', 'a miss is #N/A, not a nearby row')
+ ok(ev('XLOOKUP("West", region, value, 0)', T) === 0, 'unless a not-found value was supplied')
+ ok(ev('MATCH("North", region)', T) === 1, 'MATCH is 1-based, as Excel reports it')
+ ok(code(ev('MATCH("West", region)', T)) === '#N/A', 'and a miss is #N/A')
+ ok(ev('INDEX(value, 3)', T) === 30, 'INDEX takes the nth value')
+ ok(code(ev('INDEX(value, 99)', T)) === '#REF!', 'past the end is #REF!, not the last row')
+}
+{
+ // THE ONE THAT MATTERS. Excel's VLOOKUP defaults to an APPROXIMATE match, so
+ // on unsorted data it returns whatever row the binary search lands on and
+ // reports no problem at all.
+ const unsorted = { k: ['Zebra', 'Apple', 'Mango'] as Vec, v: [1, 2, 3] as Vec }
+ ok(code(ev('VLOOKUP("Cherry", k, 1)', unsorted)) === '#N/A',
+ 'a VLOOKUP miss on UNSORTED data is #N/A — exact is the default here, unlike Excel')
+ ok(ev('VLOOKUP("Mango", k, 1)', unsorted) === 'Mango', 'an exact hit still works')
+ ok(code(ev('VLOOKUP("Apple", k, 5)', unsorted)) === '#REF!',
+ 'a column index past the range is #REF!')
+}
+
+// ------------------------------------------------------- multi-criteria
+{
+ // North AND Won = rows 1 and 3 = 10 + 30 = 40.
+ // An implementation that ORs gets 10+20+30+50 = 110 and looks just as tidy.
+ ok(ev('SUMIFS(value, region, "North", stage, "Won")', T) === 40,
+ 'SUMIFS requires EVERY criterion — North AND Won, not North OR Won')
+ ok(ev('COUNTIFS(region, "North", stage, "Won")', T) === 2, 'COUNTIFS counts the same population')
+ ok(ev('AVERAGEIFS(value, region, "North")', T) === 20, 'AVERAGEIFS averages it')
+ ok(ev('MINIFS(value, stage, "Won")', T) === 10, 'MINIFS takes the smallest of the matches')
+ ok(ev('MAXIFS(value, stage, "Won")', T) === 50, 'and MAXIFS the largest')
+ ok(ev('SUMIFS(value, value, ">25")', T) === 120, 'a comparison criterion works too (30+40+50)')
+ ok(ev('SUMIFS(value, region, "Nowhere")', T) === 0, 'no matches sums to 0')
+ ok(code(ev('AVERAGEIFS(value, region, "Nowhere")', T)) === '#DIV/0!',
+ 'but AVERAGING no matches is #DIV/0!, never 0 — an average of nothing is not zero')
+}
+
+// -------------------------------------------------------------- finance
+{
+ // £10,000 over 12 periods at 1% per period. Excel: PMT(0.01,12,10000)
+ ok(near(ev('PMT(0.01, 12, 10000)'), -888.487887, 1e-4),
+ 'PMT matches Excel, and is NEGATIVE — a payment leaves the account')
+ ok(near(ev('PMT(0, 12, 1200)'), -100), 'a zero rate divides evenly rather than dividing by zero')
+ ok(near(ev('FV(0.01, 12, -100)'), 1268.250301, 1e-4), 'FV compounds a series of payments')
+ ok(near(ev('PV(0.01, 12, -100)'), 1125.507747, 1e-4), 'PV discounts one')
+ ok(near(ev('NPV(0.1, 100, 200, 300)'), 481.592787, 1e-4),
+ 'NPV discounts the first flow by ONE period, as Excel does')
+}
+{
+ const flows = { f: [-1000, 300, 400, 500] as Vec }
+ const r = ev('IRR(f)', flows)
+ ok(near(r as Cell, 0.0885, 1e-3), 'IRR finds the rate where NPV is zero')
+ // and the case that makes Newton-Raphson invent an answer
+ const noRoot = { f: [100, 200, 300] as Vec }
+ ok(isErr(ev('IRR(f)', noRoot)),
+ 'cash flows that never change sign have NO rate — that is #NUM!, not a number')
+}
+
+// ----------------------------------------------------------- statistics
+{
+ const s = { v: [2, 4, 4, 4, 5, 5, 7, 9] as Vec }
+ ok(near(ev('VARP(v)', s), 4), 'VARP is the population variance')
+ ok(near(ev('VAR(v)', s), 4.571428, 1e-5), 'VAR is the sample one (n−1) — a different number, not a rounding')
+ ok(near(ev('STDEVP(v)', s), 2), 'STDEVP is its square root')
+ ok(ev('MODE(v)', s) === 4, 'MODE is the most common value')
+ ok(code(ev('MODE(v)', { v: [1, 2, 3] })) === '#N/A', 'with no repeat there is no mode — #N/A, not the first value')
+ ok(ev('COUNTUNIQUE(region)', T) === 3, 'COUNTUNIQUE counts distinct values')
+ ok(near(ev('PERCENTILE(v, 0.5)', s), 4.5), 'PERCENTILE interpolates, matching PERCENTILE.INC')
+ ok(isErr(ev('PERCENTILE(v, 90)', s)),
+ 'and takes a FRACTION — 90 is #NUM! rather than being clamped to the maximum, which would answer a question nobody asked')
+ ok(near(ev('CORREL(a, b)', { a: [1, 2, 3, 4], b: [2, 4, 6, 8] }), 1), 'CORREL of a perfect line is 1')
+ ok(near(ev('CORREL(a, b)', { a: [1, 2, 3, 4], b: [8, 6, 4, 2] }), -1), 'and −1 inverted')
+ ok(ev('RANK(30, value)', T) === 3, 'RANK is 1-based and descending by default')
+}
+
+// ---------------------------------------------------------------- logic
+{
+ ok(ev('TRUE()') === true && ev('FALSE()') === false,
+ 'TRUE() and FALSE() are functions — without them `IF(TRUE(), …)` took the FALSE branch, silently')
+ ok(ev('IFS(FALSE(), "a", TRUE(), "b")') === 'b', 'IFS returns the first branch whose test holds')
+ ok(code(ev('IFS(1>2, "a")')) === '#N/A', 'and #N/A when none does, rather than blank')
+ ok(ev('SWITCH("b", "a", 1, "b", 2)') === 2, 'SWITCH matches a value')
+ ok(ev('SWITCH("z", "a", 1, "b", 2, 99)') === 99, 'with a trailing default')
+ ok(ev('XOR(1>0, 2>1)') === false, 'XOR of two truths is false')
+ ok(ev('XOR(1>0, 2>3)') === true, 'and of one truth, true')
+}
+
+// ----------------------------------------------------------------- text
+{
+ ok(ev('PROPER("hello WORLD")') === 'Hello World', 'PROPER title-cases')
+ ok(ev('REPT("ab", 3)') === 'ababab', 'REPT repeats')
+ ok(isErr(ev('REPT("ab", -1)')), 'a negative count is an error rather than an empty string')
+ ok(ev('TEXTJOIN(", ", TRUE(), region)', T) === 'North, South, North, East, South', 'TEXTJOIN joins a column')
+ ok(ev('TEXTJOIN("-", TRUE(), a)', { a: ['x', '', 'y'] }) === 'x-y', 'and skips blanks when asked')
+ ok(ev('TEXTJOIN("-", FALSE(), a)', { a: ['x', '', 'y'] }) === 'x--y', 'or keeps them when not')
+}
+
+// ---------------------------------------------------------------- dates
+//
+// Dates are ISO strings in dash, and every one of these computes in UTC. A
+// local-timezone implementation moves a date across midnight for half the
+// world, which is the kind of bug that only shows up in other people's files.
+{
+ ok(ev('DATE(2026, 2, 3)') === '2026-02-03', 'DATE builds an ISO date')
+ ok(ev('DATE(2026, 13, 1)') === '2027-01-01', 'and rolls a 13th month into the next year')
+ ok(ev('EOMONTH("2026-02-10", 0)') === '2026-02-28', 'EOMONTH finds the last day')
+ ok(ev('EOMONTH("2024-02-10", 0)') === '2024-02-29', 'including a leap February')
+ ok(ev('EDATE("2026-01-31", 1)') === '2026-03-03',
+ 'EDATE adds months arithmetically — 31 Jan + 1 month overflows, as JavaScript dates do')
+ ok(ev('DAYS("2026-03-01", "2026-02-01")') === 28, 'DAYS counts between two dates')
+ ok(ev('WEEKDAY("2026-08-05")') === 4, 'WEEKDAY is 1-based from Sunday')
+ ok(isErr(ev('EOMONTH("not a date", 0)')), 'a non-date is an error rather than 1970')
+}
+
+// ---------------------------------------------------------- registration
+{
+ for (const f of ['XLOOKUP', 'VLOOKUP', 'MATCH', 'INDEX', 'SUMIFS', 'COUNTIFS',
+ 'IRR', 'NPV', 'PMT', 'PERCENTILE', 'CORREL', 'IFS', 'SWITCH', 'TEXTJOIN', 'EOMONTH',
+ 'TRUE', 'FALSE']) {
+ ok(FUNCTIONS.includes(f), `${f} is in FUNCTIONS, so the editor can offer it`)
+ }
+ ok(new Set(FUNCTIONS).size === FUNCTIONS.length, 'and no name is registered twice')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-gl.ts b/scripts/test-dash-gl.ts
new file mode 100644
index 00000000..6e278f5d
--- /dev/null
+++ b/scripts/test-dash-gl.ts
@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash WebGL layer — the MATHS rig.
+//
+// node scripts/test-dash-gl.ts
+//
+// WHAT THIS PROVES. Nothing here can be checked by looking at the screen:
+// every bug in this file renders SOMETHING, plausibly, and the reader has no
+// way to know the picture is a lie. The four that matter:
+//
+// 1. A TRANSPOSED MULTIPLY. `multiply(a,b)` meaning "b then a" or "a then b"
+// both produce a scene. They differ only when the operands do not
+// commute, and — because the identity matrix is symmetric — the obvious
+// M·I = M check passes either way. Composition order is pinned against a
+// translate/rotate pair whose two orders give different points.
+// 2. A FLIPPED SCREEN Y. NDC counts up, CSS counts down. Get it wrong and
+// every label sits mirrored about the horizon, which on a symmetric
+// scatter plot looks entirely correct. Pinned to an exact pixel.
+// 3. A POINT BEHIND THE CAMERA. Negative clip w mirrors x and y back INTO
+// the viewport, so a label for something behind you is drawn in front of
+// you at a confident position. The rig asserts the depth flag that lets
+// a caller reject it.
+// 4. THE GIMBAL FLIP. At exactly ±90° elevation the view direction is
+// parallel to `up`, the camera basis collapses, and the scene flips or
+// vanishes. Every hand-rolled orbit control ships this once. Asserted
+// both as a strict clamp AND as continuity of the picture across it — a
+// naive `Math.min(el, PI/2)` passes neither.
+//
+// Plus the arithmetic that everything else rests on: invert(m)·m = I, and a
+// known camera projecting a known point to a known pixel.
+
+import {
+ identity, multiply, perspective, lookAt, translate, scale,
+ rotateX, rotateY, rotateZ, transformPoint, invert, project,
+ add, sub, dot, cross, normalize, length, vscale, V3,
+ Orbit, supportsWebGL2,
+ type Mat4, type Vec3,
+} from '../dash/src/gl.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+const close = (a: number, b: number, eps = 1e-9) => Math.abs(a - b) <= eps
+const closeV = (a: Vec3, b: Vec3, eps = 1e-9) =>
+ close(a[0], b[0], eps) && close(a[1], b[1], eps) && close(a[2], b[2], eps)
+const closeM = (a: Mat4, b: Mat4, eps = 1e-9) => {
+ for (let i = 0; i < 16; i++) if (!close(a[i], b[i], eps)) return false
+ return true
+}
+const finiteM = (m: Mat4) => {
+ for (let i = 0; i < 16; i++) if (!Number.isFinite(m[i])) return false
+ return true
+}
+
+// ------------------------------------------------------------------ vectors
+{
+ const a: Vec3 = [1, 2, 3], b: Vec3 = [4, 5, 6]
+ ok(closeV(add(a, b), [5, 7, 9]), 'add')
+ ok(closeV(sub(b, a), [3, 3, 3]), 'sub')
+ ok(dot(a, b) === 32, 'dot')
+ ok(closeV(vscale(a, 2), [2, 4, 6]), 'scale')
+ ok(close(length([3, 4, 0]), 5), 'length')
+ ok(close(length(normalize([0, 0, 7])), 1), 'normalize gives a unit vector')
+
+ // right-handed: x cross y is +z. The sign error here inverts the whole
+ // camera basis and the scene renders mirrored, not broken.
+ ok(closeV(cross([1, 0, 0], [0, 1, 0]), [0, 0, 1]), 'cross is right-handed (x×y = +z)')
+ ok(closeV(cross([0, 1, 0], [1, 0, 0]), [0, 0, -1]), 'and anti-commutative (y×x = -z)')
+
+ // the silent-NaN case: one degenerate vector otherwise poisons every
+ // projected point in the scene and the canvas just goes empty
+ ok(closeV(normalize([0, 0, 0]), [0, 0, 0]), 'normalizing the zero vector gives zero, NOT NaN')
+ ok(!Number.isNaN(normalize([0, 0, 0])[0]), 'and specifically not NaN')
+
+ ok(V3.scale === vscale && V3.length === length, 'V3 exposes the ops under their plain names')
+}
+
+// ----------------------------------------------------------------- matrices
+{
+ const m = multiply(translate([1, 2, 3]), rotateY(0.7))
+ ok(closeM(multiply(m, identity()), m), 'M · I = M')
+ ok(closeM(multiply(identity(), m), m), 'I · M = M')
+ ok(closeM(invert(identity())!, identity()), 'the identity inverts to itself')
+}
+{
+ // Composition order. `multiply(A, B)` is the maths product A·B, so B is
+ // applied FIRST — and the two orders must give different answers or the
+ // convention is untested.
+ const T = translate([1, 0, 0])
+ const R = rotateZ(Math.PI / 2)
+ const p: Vec3 = [1, 0, 0]
+ const rotThenMove = transformPoint(multiply(T, R), p)
+ const moveThenRot = transformPoint(multiply(R, T), p)
+ ok(closeV(rotThenMove, [1, 1, 0]), 'multiply(T,R) rotates first, then translates')
+ ok(closeV(moveThenRot, [0, 2, 0]), 'multiply(R,T) translates first, then rotates')
+ ok(!closeV(rotThenMove, moveThenRot), 'the two orders differ — so the convention is actually pinned')
+}
+{
+ // A sign slip in any one of these renders a scene that looks fine until
+ // something is asymmetric.
+ ok(closeV(transformPoint(rotateX(Math.PI / 2), [0, 1, 0]), [0, 0, 1]), 'rotateX(90°): +y → +z')
+ ok(closeV(transformPoint(rotateY(Math.PI / 2), [0, 0, 1]), [1, 0, 0]), 'rotateY(90°): +z → +x')
+ ok(closeV(transformPoint(rotateZ(Math.PI / 2), [1, 0, 0]), [0, 1, 0]), 'rotateZ(90°): +x → +y')
+ ok(closeV(transformPoint(translate([1, 2, 3]), [1, 1, 1]), [2, 3, 4]), 'translate')
+ ok(closeV(transformPoint(scale([2, 3, 4]), [1, 1, 1]), [2, 3, 4]), 'scale')
+ ok(closeV(transformPoint(scale(2), [1, 1, 1]), [2, 2, 2]), 'scale takes a uniform number too')
+}
+{
+ // The gnarliest matrix the app builds: a full view-projection with a model
+ // transform on the end. If invert survives this it survives anything.
+ const m = multiply(
+ multiply(perspective(1.1, 1.7, 0.25, 900), lookAt([3, 4, 5], [1, 0, -2], [0, 1, 0])),
+ multiply(translate([7, -2, 0.5]), multiply(rotateX(0.3), scale([2, 0.5, 3]))),
+ )
+ const inv = invert(m)!
+ ok(!!inv, 'a view-projection matrix inverts')
+ ok(closeM(multiply(inv, m), identity(), 1e-9), 'invert(m) · m is the identity within 1e-9')
+ ok(closeM(multiply(m, inv), identity(), 1e-9), 'and m · invert(m) too')
+
+ // the failure: a collapsed matrix has NO inverse, and answering with the
+ // identity would let a hit-test report screen pixels as world coordinates
+ ok(invert(scale([1, 0, 1])) === null, 'a singular matrix inverts to null, not to a plausible matrix')
+ ok(invert(new Float64Array(16) as Mat4) === null, 'the zero matrix inverts to null')
+}
+
+// -------------------------------------------------------------- projection
+{
+ const near = 0.1, far = 100
+ const P = perspective(Math.PI / 2, 1, near, far)
+ // GL clip space is [-1, +1] in z. D3D's [0, 1] convention would put the near
+ // plane at 0 — everything still draws, and the depth buffer resolution is
+ // silently halved.
+ ok(close(transformPoint(P, [0, 0, -near])[2], -1, 1e-12), 'the near plane maps to ndc z = -1')
+ ok(close(transformPoint(P, [0, 0, -far])[2], 1, 1e-12), 'the far plane maps to ndc z = +1 (GL, not D3D)')
+ const wide = perspective(Math.PI / 2, 2, near, far)
+ ok(wide[0] < P[0], 'a wider aspect ratio shrinks x in clip space (it fits more world in)')
+}
+{
+ const V = lookAt([0, 0, 5], [0, 0, 0], [0, 1, 0])
+ ok(closeV(transformPoint(V, [0, 0, 5]), [0, 0, 0]), 'lookAt puts the eye at the view-space origin')
+ ok(transformPoint(V, [0, 0, 0])[2] < 0, 'and the target down -Z, the direction GL looks')
+
+ // the public-API degenerate case: "look straight down" is the first thing
+ // anyone tries, and cross(up, forward) is zero there
+ const D = lookAt([0, 5, 0], [0, 0, 0], [0, 1, 0])
+ ok(finiteM(D), 'looking straight down with up=+Y still yields a finite matrix, not NaN')
+ ok(closeV(transformPoint(D, [0, 5, 0]), [0, 0, 0]), 'and it is still a valid view matrix')
+}
+{
+ // A camera we can do the arithmetic for by hand: at z=5, 90° vertical fov,
+ // square aspect, so the visible half-width at the origin is exactly 5.
+ const vp = multiply(perspective(Math.PI / 2, 1, 0.1, 100), lookAt([0, 0, 5], [0, 0, 0], [0, 1, 0]))
+ const W = 100, H = 100
+
+ const c = project(vp, [0, 0, 0], W, H)
+ ok(close(c.x, 50, 1e-9) && close(c.y, 50, 1e-9), 'the target projects to the centre of the screen')
+ ok(c.z > -1 && c.z < 1, 'and sits inside the depth range')
+
+ const r = project(vp, [1, 0, 0], W, H)
+ ok(close(r.x, 60, 1e-9), 'a point 1 unit right of the target lands at x = 60px (1/5 of the half-width)')
+ ok(close(r.y, 50, 1e-9), 'and does not move in y')
+
+ const u = project(vp, [0, 1, 0], W, H)
+ ok(close(u.y, 40, 1e-9), 'a point 1 unit ABOVE the target lands at y = 40px — screen y counts DOWN')
+ ok(!close(u.y, 60, 1e-3), 'and NOT at 60px, which is the unflipped-y bug')
+
+ // behind the camera: the mirrored x/y are the trap, z is the escape
+ const behind = project(vp, [1, 0, 10], W, H)
+ ok(behind.z > 1, 'a point BEHIND the camera reports z > 1, so `-1<=z<=1` rejects it')
+ ok(behind.x < W && behind.x > 0, 'even though its x lands inside the viewport — which is why z must be checked')
+ const far = project(vp, [0, 0, -200], W, H)
+ ok(far.z > 1, 'a point beyond the far plane is rejected by the same test')
+
+ // project ∘ unproject: the pair the label layer and the picker both need
+ const world: Vec3 = [1.5, -0.5, 2]
+ const s = project(vp, world, W, H)
+ const back = transformPoint(invert(vp)!, [(s.x / W) * 2 - 1, 1 - (s.y / H) * 2, s.z])
+ ok(closeV(back, world, 1e-9), 'unprojecting a projected point through invert(vp) returns the world point')
+}
+
+// ------------------------------------------------------------------- orbit
+const camera = () => {
+ const o = new Orbit()
+ o.azimuth = 0; o.elevation = 0; o.distance = 5
+ o.fovY = Math.PI / 2; o.near = 0.1; o.far = 100
+ o.target = [0, 0, 0]
+ return o
+}
+{
+ const o = camera()
+ ok(closeV(o.eye(), [0, 0, 5]), 'at azimuth 0, elevation 0 the camera sits on +Z')
+ const hand = multiply(perspective(Math.PI / 2, 1, 0.1, 100), lookAt([0, 0, 5], [0, 0, 0], [0, 1, 0]))
+ ok(closeM(o.matrix(1), hand), 'Orbit.matrix is exactly perspective · lookAt')
+
+ o.azimuth = 0.9; o.elevation = -0.3
+ ok(close(length(sub(o.eye(), o.target)), o.distance, 1e-9),
+ 'the eye stays exactly `distance` from the target at any angle')
+ o.target = [10, -4, 2]
+ ok(close(length(sub(o.eye(), o.target)), o.distance, 1e-9), 'including around a moved target')
+}
+{
+ // THE CLAMP.
+ const o = camera()
+ o.rotate(0, 1e6)
+ ok(o.elevation < Math.PI / 2, 'elevation stays STRICTLY below +90° after a huge drag')
+ ok(o.elevation !== Math.PI / 2, 'and is not exactly 90° — the naive clamp that gimbal-flips')
+ ok(Math.PI / 2 - o.elevation < 1e-3, 'but stops JUST short, so the limit is invisible')
+ ok(finiteM(o.matrix(1)), 'the view-projection at the top pole is finite')
+
+ o.rotate(0, -1e6)
+ ok(o.elevation > -Math.PI / 2, 'the bottom pole clamps too')
+ ok(o.elevation + Math.PI / 2 < 1e-3, 'symmetrically')
+ ok(finiteM(o.matrix(1)), 'and is finite there as well')
+}
+{
+ // The clamp has to keep the PICTURE continuous, not just the number: a
+ // camera that reaches the pole exactly swaps its right-vector for the
+ // opposite one, and the scene mirrors in a single frame.
+ const o = camera()
+ o.elevation = Math.PI / 2 - 0.02
+ const before = project(o.matrix(1), [1, 0, 0], 100, 100)
+ o.rotate(0, 1e6) // slam into the clamp
+ const after = project(o.matrix(1), [1, 0, 0], 100, 100)
+ ok(Math.abs(after.x - before.x) < 3,
+ `the image does not jump at the clamp (moved ${Math.abs(after.x - before.x).toFixed(2)}px)`)
+ ok(before.x > 50 && after.x > 50, 'the marker stays on the same side of the screen (no mirror flip)')
+}
+{
+ const o = camera()
+ o.azimuth = 0
+ o.rotate(1000, 0)
+ ok(Math.abs(o.azimuth) <= Math.PI + 1e-12, 'azimuth wraps into [-π, π] rather than growing forever')
+ ok(!close(o.azimuth, 0), 'and it did actually rotate')
+}
+{
+ // distance may never reach zero: lookAt of a zero-length forward is NaN,
+ // and one NaN in the matrix empties the whole canvas
+ const o = camera()
+ o.zoom(1e-9)
+ ok(o.distance === o.minDistance, 'zooming in past the limit clamps to minDistance')
+ ok(o.distance > 0, 'and never reaches 0')
+ ok(finiteM(o.matrix(1)), 'so the matrix is still finite at full zoom-in')
+
+ o.distance = 5
+ o.zoom(0)
+ ok(o.distance === 5, 'a zoom factor of 0 is ignored, not applied')
+ o.zoom(-2)
+ ok(o.distance === 5, 'and a negative factor is ignored — it would pull the camera through the target')
+ o.zoom(1e9)
+ ok(o.distance === o.maxDistance, 'zooming out clamps to maxDistance')
+ o.distance = 5
+ o.zoom(0.5)
+ ok(close(o.distance, 2.5), 'an ordinary zoom just scales the distance')
+}
+{
+ // pan must track the pointer: at 90° fov the visible world height at the
+ // target equals 2 * distance, so half a viewport of drag moves exactly
+ // `distance` units.
+ const o = camera()
+ o.height = 100
+ o.pan(0, 50)
+ ok(closeV(o.target, [0, 5, 0], 1e-9), 'dragging down half the viewport moves the target up by distance·tan(fov/2)')
+
+ const o2 = camera()
+ o2.height = 100
+ o2.distance = 10
+ o2.pan(0, 50)
+ ok(closeV(o2.target, [0, 10, 0], 1e-9), 'the same drag moves twice as far from twice the distance')
+
+ const o3 = camera()
+ o3.height = 100
+ o3.pan(50, 0)
+ ok(closeV(o3.target, [-5, 0, 0], 1e-9), 'dragging right moves the target left — the model follows the pointer')
+
+ // and from an arbitrary angle, panning stays in the screen plane
+ const o4 = camera()
+ o4.azimuth = 1.1; o4.elevation = 0.6; o4.height = 100
+ const fwd = normalize(sub(o4.target, o4.eye()))
+ const t0 = o4.target
+ o4.pan(23, -17)
+ const moved = sub(o4.target, t0)
+ ok(close(dot(moved, fwd), 0, 1e-9), 'a pan never moves the target along the view direction')
+ ok(length(moved) > 0, 'but it does move it')
+}
+
+// --------------------------------------------------------- the GL boundary
+ok(supportsWebGL2() === false,
+ 'supportsWebGL2() answers false where there is no DOM instead of throwing (node, and the scriptless preview)')
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-model.ts b/scripts/test-dash-model.ts
index 00da8ad1..a14b8e53 100644
--- a/scripts/test-dash-model.ts
+++ b/scripts/test-dash-model.ts
@@ -211,5 +211,31 @@ ok(DOC_BUDGET_DOWNLOAD < DOC_BUDGET_FSA,
ok(!Object.keys({ FORMAT, FORMAT_VERSION }).includes('ROW_MAX'),
'there is no row cap: rows are the wrong unit (1M x 12 is 65 MB; 1M x 2 is ~10 MB)')
+// ADDITIVITY OF THE SHEET KIND (PLATFORM §3). A build that has never heard of a
+// sheet kind must keep the file intact. This branch used to fall through, so
+// every non-canvas sheet came back as `kind: 'table'` with empty
+// rids/columns/data/steps bolted on — the sheet was rewritten into a different
+// thing and what made it one was dropped. Old builds are frozen code, so a file
+// from a newer dash has to survive a round trip through them untouched.
+{
+ const r = parseDoc(JSON.stringify({
+ format: 'bento/dash', version: 1, policy: 'bento-dash-1', docId: 'd', title: 't',
+ sheets: [
+ { id: 'p1', name: 'P', kind: 'pivot', pivot: { from: 's1', rows: ['region'] } },
+ { id: 'f1', name: 'F', kind: 'from-the-future', mystery: { a: 1 } },
+ ],
+ }))
+ ok(r.ok, 'a workbook of unknown sheet kinds still parses')
+ if (r.ok) {
+ const [p, f] = r.doc.sheets as unknown as Array<Record<string, unknown>>
+ ok(p.kind === 'pivot', 'an unrecognised kind is PRESERVED, not coerced to table')
+ ok(!!p.pivot, 'and the field that makes it that kind survives')
+ ok(!('rids' in p) && !('columns' in p) && !('data' in p),
+ 'with no table scaffolding bolted on to a sheet that is not a table')
+ ok(f.kind === 'from-the-future' && JSON.stringify(f.mystery) === '{"a":1}',
+ 'a kind this build has never heard of round-trips whole')
+ }
+}
+
console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)
diff --git a/scripts/test-dash-panels.ts b/scripts/test-dash-panels.ts
new file mode 100644
index 00000000..234ad42a
--- /dev/null
+++ b/scripts/test-dash-panels.ts
@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash side-panel patch-factory rig.
+//
+// node scripts/test-dash-panels.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. The panel is chrome, so almost none of it is testable and
+// almost none of it needs to be — a chevron that points the wrong way is a
+// thing you can see. What is NOT visible is what the controls WRITE, and every
+// failure below leaves a workbook that looks exactly right on screen:
+//
+// 1. A SETTING THAT WILL NOT SWITCH OFF. `sheet.totals` and `sheet.frozen`
+// are additive fields where ABSENT means "no". Clearing the last one by
+// storing `{}` leaves the file changed after a round trip: every reader
+// diffs it, and collab ships an op for a document that is back where it
+// started. The same clear spelled `props: {totals: undefined}` is worse —
+// applySheetProps refuses it outright, because JSON.stringify drops the
+// key and the delete would reach every other replica as a no-op.
+// 2. A FREEZE THAT COUNTS THE WRONG COLUMNS. "Freeze to here" counts VISIBLE
+// position — what the reader pointed at. Counting stored position freezes
+// one column too many the moment anything to the left is hidden, and the
+// pane looks plausible either way. Frozen ROWS must survive the write, or
+// one setting silently resets another.
+// 3. A SHEET NOBODY CAN OPEN. Two sheets sharing an id makes `sheets.find`
+// answer with the first one forever: the second sheet's data is in the
+// file and nothing in the app can reach it.
+// 4. A NEW SHEET THAT IS MALFORMED TO EVERYONE ELSE. A column whose stored
+// values are shorter than the sheet has rows READS correctly inside this
+// build (`readCell` answers `?? null` past the end) and is ragged to every
+// other reader of that JSON — an agent, a chart binding, a re-encode to
+// `pack`, whose `n` is authoritative. rowcol.ts pads for this reason; a
+// sheet minted whole has to be born right.
+//
+// So the checks assert the WRONG answer is refused, not merely that a right one
+// is reachable. The round-trip check is the load-bearing one: mint → commit →
+// undo has to leave the document BYTE-identical, which is the only statement
+// that catches an orphaned `{}` or a key left holding undefined.
+
+import { registerHooks } from 'node:module'
+
+// panels.ts imports its stylesheet, which is Vite's job and not Node's. Stub
+// the extension rather than moving the import out of the module: `import
+// './panels.css'` is how every other Bento app co-locates a panel with its
+// styles, and a rig is not a reason to break the pattern.
+registerHooks({
+ load(url, context, next) {
+ if (url.endsWith('.css')) {
+ return { format: 'module', source: 'export {}', shortCircuit: true }
+ }
+ return next(url, context)
+ },
+})
+
+const {
+ totalsPatch, freezeThroughPatch, renameSheetPatch, mintSheetId, mintSheetName, blankSheet,
+} = await import('../dash/src/panels.ts')
+
+const { parseDoc } = await import('../dash/src/model.ts')
+type DashDoc = import('../dash/src/model.ts').DashDoc
+type TableSheet = import('../dash/src/model.ts').TableSheet
+
+const { Store } = await import('../dash/src/store.ts')
+type Patch = import('../dash/src/store.ts').Patch
+
+const { readFrozen, hiddenSet } = await import('../dash/src/rowcol.ts')
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+// --------------------------------------------------------------- fixtures
+
+const fresh = (): DashDoc => {
+ const r = parseDoc(JSON.stringify({
+ format: 'bento/dash', version: 1, policy: 'bento-dash-1',
+ docId: 'd', title: 'test',
+ sheets: [{
+ id: 'sh1', name: 'S', kind: 'table',
+ rids: [[1, 4]],
+ columns: [
+ // `region` is HIDDEN: every visible-position check below is only a real
+ // check because something to the left of the target is not on screen.
+ { id: 'region', name: 'Region', type: 'text', hidden: true },
+ { id: 'amount', name: 'Amount', type: 'number' },
+ { id: 'note', name: 'Note', type: 'text' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, 0, 1] },
+ amount: { enc: 'raw', v: [10, 20, 30, 40] },
+ note: { enc: 'raw', v: ['a', 'b', 'c', 'd'] },
+ },
+ totals: { amount: 'sum' },
+ frozen: { rows: 2, cols: 0 },
+ steps: [{ op: 'import', from: 'q3.csv', at: '2026-08-03T00:00:00Z', rows: 4 }],
+ }, {
+ id: 'sh2', name: 'Sheet', kind: 'table',
+ rids: [[1, 1]], columns: [{ id: 'x', name: 'X', type: 'text' }],
+ data: { x: { enc: 'raw', v: ['q'] } }, steps: [],
+ }],
+ }))
+ if (!r.ok) throw new Error('fixture does not parse')
+ return r.doc
+}
+
+const sheetOf = (d: DashDoc, i = 0): TableSheet => d.sheets[i] as TableSheet
+
+/** Sorted keys, `modified` dropped — see test-dash-rowcol.ts for why both. */
+const canon = (v: unknown): unknown => {
+ if (Array.isArray(v)) return v.map(canon)
+ if (v && typeof v === 'object') {
+ const o = v as Record<string, unknown>
+ const out: Record<string, unknown> = {}
+ for (const k of Object.keys(o).sort()) out[k] = canon(o[k])
+ return out
+ }
+ return v
+}
+const content = (d: DashDoc): string => {
+ const { modified: _m, ...rest } = d
+ return JSON.stringify(canon(rest))
+}
+const j = (v: unknown): string => JSON.stringify(v)
+
+/** mint → commit → undo → is the document byte-identical again? */
+function roundTrip(name: string, make: (s: TableSheet) => Patch) {
+ const st = new Store(fresh())
+ const before = content(st.doc)
+ st.commit(make(sheetOf(st.doc)))
+ const changed = content(st.doc) !== before
+ st.undo()
+ ok(changed && content(st.doc) === before,
+ `${name}: applies, and undo puts the document back byte-for-byte`)
+}
+
+// ============================================================ totals
+
+console.log('\ntotals — an additive field where absent means "no"')
+{
+ const s = sheetOf(fresh())
+ const p = totalsPatch(s, 'note', 'count')
+ ok(j((p.props as { totals: unknown }).totals) === j({ amount: 'sum', note: 'count' }),
+ 'adding an aggregate keeps the ones already there')
+ ok(p.drop === undefined, 'adding never drops')
+ ok(j(s.totals) === j({ amount: 'sum' }), 'minting the patch did not touch the sheet')
+}
+{
+ const s = sheetOf(fresh())
+ const p = totalsPatch(s, 'amount', null)
+ ok(j(p.drop) === j(['totals']) && j(p.props) === j({}),
+ 'clearing the LAST aggregate drops `totals` rather than storing {} — an absent field is what "no totals" looks like')
+ ok(!('totals' in (p.props as Record<string, unknown>)),
+ 'and it is spelled `drop`, never `props: {totals: undefined}` — that spelling evaporates in JSON and applySheetProps refuses it')
+}
+{
+ const st = new Store(fresh())
+ st.commit(totalsPatch(sheetOf(st.doc), 'note', 'max'))
+ const p = totalsPatch(sheetOf(st.doc), 'note', null)
+ ok(j((p.props as { totals: unknown }).totals) === j({ amount: 'sum' }) && p.drop === undefined,
+ 'clearing one of two keeps the other and leaves the field in place')
+}
+roundTrip('totals set', (s) => totalsPatch(s, 'note', 'avg'))
+roundTrip('totals cleared to empty', (s) => totalsPatch(s, 'amount', null))
+
+// ============================================================ freeze
+
+console.log('\nfreeze to here — visible position, and the other axis survives')
+{
+ const s = sheetOf(fresh())
+ ok(hiddenSet(s).has('region'), 'fixture really does hide a column to the left')
+ const p = freezeThroughPatch(s, 'amount')
+ const f = (p.props as { frozen?: { rows: number; cols: number } }).frozen
+ ok(f?.cols === 1,
+ 'freezing through the FIRST VISIBLE column freezes one column — not two, which is what counting stored position would give')
+ ok(f?.rows === 2, 'and the frozen ROWS are carried through, not reset to zero')
+}
+{
+ const st = new Store(fresh())
+ st.commit(freezeThroughPatch(sheetOf(st.doc), 'note'))
+ ok(readFrozen(sheetOf(st.doc)).cols === 2, 'through the second visible column freezes two')
+ const off = freezeThroughPatch(sheetOf(st.doc), 'note')
+ st.commit(off)
+ const f = readFrozen(sheetOf(st.doc))
+ ok(f.cols === 0 && f.rows === 2,
+ 'asking again at the same column unfreezes the columns and leaves the rows alone')
+}
+{
+ // Every column hidden but one, and that one is the LAST stored column: the
+ // arithmetic that reads `columns.indexOf` would freeze three.
+ const d = fresh()
+ const s = sheetOf(d)
+ s.columns[1].hidden = true
+ const p = freezeThroughPatch(s, 'note')
+ ok((p.props as { frozen?: { cols: number } }).frozen?.cols === 1,
+ 'with two of three columns hidden, the only visible one freezes exactly one')
+}
+roundTrip('freeze to here', (s) => freezeThroughPatch(s, 'amount'))
+
+// ============================================================ sheets
+
+console.log('\nsheet identity and naming')
+{
+ const d = fresh()
+ ok(mintSheetId(d, 0) === 'sheet-0', 'a seed with no collision is used as-is (deterministic under test)')
+ d.sheets.push({ ...sheetOf(d), id: 'sheet-0' })
+ ok(mintSheetId(d, 0) === 'sheet-1',
+ 'a taken id walks on — two sheets sharing one id makes the second unreachable forever')
+ ok(!d.sheets.some((s) => s.id === mintSheetId(d)),
+ 'and the unseeded mint is unused too')
+}
+{
+ const d = fresh()
+ ok(mintSheetName(d, 'Sheet') === 'Sheet 2', 'a taken name gets the first free suffix')
+ ok(mintSheetName(d, 'Pipeline') === 'Pipeline', 'a free name is left alone')
+}
+{
+ const s = sheetOf(fresh())
+ ok(renameSheetPatch(s, ' ') === null, 'a blank rename is refused — a nameless sheet is unclickable')
+ ok(renameSheetPatch(s, 'S') === null, 'renaming to the same name mints nothing rather than an empty undo step')
+ ok(renameSheetPatch(s, ' Q3 ')?.props.name === 'Q3', 'and a real one is trimmed')
+}
+roundTrip('rename', (s) => renameSheetPatch(s, 'Renamed')!)
+
+// ============================================================ new sheet
+
+console.log('\na new sheet is born well-formed')
+{
+ const s = blankSheet('sheet-new', 'Sheet 2', '2026-08-05T00:00:00Z')
+ const rows = s.rids.reduce((n, [, c]) => n + c, 0)
+ const lengths = s.columns.map((c) => {
+ const dcol = s.data[c.id]
+ return dcol.enc === 'raw' ? dcol.v.length : dcol.enc === 'dict' ? dcol.idx.length : dcol.n
+ })
+ ok(lengths.every((n) => n === rows),
+ 'every column carries exactly as many values as the sheet has rows — short reads fine here and is ragged to every other reader of the JSON')
+ ok(new Set(s.columns.map((c) => c.id)).size === s.columns.length,
+ 'column ids are unique — a duplicate makes two columns share one set of values and overrides')
+ ok(s.columns.every((c) => c.id.startsWith('sheet-new')),
+ 'and they are namespaced by the sheet, so an id cannot collide across a copy-paste')
+ ok(s.steps.length === 1 && s.steps[0].op === 'import',
+ 'steps[0] is the provenance record even for a hand-made sheet — a dash file always answers where its rows came from')
+ ok(s.kind === 'table' && rows > 0, 'it opens with rows to type into')
+}
+{
+ // the round trip that matters for a new sheet: it has to survive parse
+ const d = fresh()
+ d.sheets.push(blankSheet(mintSheetId(d, 7), mintSheetName(d, 'Sheet'), '2026-08-05T00:00:00Z'))
+ const r = parseDoc(JSON.stringify(d))
+ ok(r.ok && r.repairs.length === 0,
+ 'a workbook with a freshly minted sheet parses with NO id repairs — the mint is the thing that keeps repair off')
+}
+
+// ============================================================ purity
+
+console.log('\nthe factories are factories')
+{
+ const d = fresh()
+ const s = sheetOf(d)
+ const before = content(d)
+ totalsPatch(s, 'note', 'sum')
+ totalsPatch(s, 'amount', null)
+ freezeThroughPatch(s, 'note')
+ renameSheetPatch(s, 'Other')
+ mintSheetId(d, 3)
+ mintSheetName(d, 'Sheet')
+ ok(content(d) === before,
+ 'minting six patches from one document mutates nothing — the same rule rowcol.ts holds itself to, and the reason a patch has an inverse at all')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-pivot.ts b/scripts/test-dash-pivot.ts
new file mode 100644
index 00000000..1b48509b
--- /dev/null
+++ b/scripts/test-dash-pivot.ts
@@ -0,0 +1,740 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash pivot rig.
+//
+// node scripts/test-dash-pivot.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. A pivot is the one surface in a spreadsheet where being
+// wrong is invisible: the rows that made the number are not on screen, so there
+// is nothing to check it against by eye. Every failure below prints a full,
+// well-aligned table of plausible figures.
+//
+// 1. A GAP THAT READS AS A ZERO. "North sold nothing in Q3" is a claim about
+// the world; "we have no rows for North in Q3" is a claim about the data.
+// A pivot that prints 0 for both makes the second one into the first.
+// 2. AN AVERAGE OVER THE WRONG DENOMINATOR. Dividing by rows instead of by
+// values present drags every average toward zero in exact proportion to
+// how patchy the column is — so the patchier the data, the more confident
+// and the more wrong the number.
+// 3. TEXT SUMMED AS ZERO. `Number('n/a') || 0`. The sum is short by an unknown
+// amount and nothing on screen says which rows did it.
+// 4. SUBTOTALS ADDED UP FROM THE CELLS ABOVE THEM. Right for sum, wrong for
+// average, median and distinct-count — and the wrongness is small enough
+// to look like rounding.
+// 5. ALPHABETICAL CATEGORIES. A fiscal year that starts in April sorts to
+// Apr, Aug, Dec and the trend line becomes noise.
+// 6. A DRILL-DOWN THAT DOES NOT MATCH ITS CELL. The one feature here that
+// Excel cannot do honestly, and useless the moment it can disagree with
+// the number it is explaining.
+// 7. THE DICTIONARY PATH DISAGREEING WITH THE RAW PATH. The engine reads
+// dictionary-encoded columns through a different code path than raw ones
+// — that is the whole performance argument — so the two have to be proved
+// identical on identical data or the encoding silently changes answers.
+//
+// The load-bearing checks are the CROSS-CHECKS, not the literals: a grand total
+// that equals the sum of its leaves, a subtotal that equals a re-aggregation of
+// its own drill-down, `scanned` that equals the grand-total cell's row count.
+// A literal can be updated to match a bug; those cannot.
+
+import { registerHooks } from 'node:module'
+
+// pivot.ts imports its stylesheet, which is Vite's job and not Node's — the
+// same stub test-dash-panels.ts uses, for the same reason.
+registerHooks({
+ load(url, context, next) {
+ if (url.endsWith('.css')) {
+ return { format: 'module', source: 'export {}', shortCircuit: true }
+ }
+ return next(url, context)
+ },
+})
+
+const {
+ runPivot, drillDown, readPivotSpec, isPivotSheet, defaultPivot, newPivotSheet,
+ valueName, label, mountPivot, _internals,
+} = await import('../dash/src/pivot.ts')
+type PivotSpec = import('../dash/src/pivot.ts').PivotSpec
+type PivotResult = import('../dash/src/pivot.ts').PivotResult
+type AggFn = import('../dash/src/pivot.ts').AggFn
+
+const { parseDoc } = await import('../dash/src/model.ts')
+type TableSheet = import('../dash/src/model.ts').TableSheet
+type ColumnData = import('../dash/src/model.ts').ColumnData
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+const near = (a: number | null, b: number, eps = 1e-9): boolean =>
+ a !== null && Math.abs(a - b) < eps
+
+// --------------------------------------------------------------- fixtures
+//
+// Twelve rows carrying, on purpose, every shape that breaks a naive pivot:
+// a blank grouping value, a blank measure, a measure that is TEXT, a measure
+// written as a numeric STRING, two spellings of one category, and two spellings
+// of one customer. The category order is deliberately NOT alphabetical.
+
+const REGION = ['North', 'North', 'North', 'south', 'South', 'South', 'East', 'East', 'North', '', 'East', 'East']
+const QUARTER = ['Q1', 'Q1', 'Q2', 'Q1', 'Q1', 'Q2', 'Q1', 'Q1', 'Q2', 'Q3', 'Q3', 'Q3']
+const AMOUNT: Array<string | number | null> = [10, 20, 30, 5, 'n/a', null, 100, 9, '40', 7, 1, 3]
+const CUSTOMER = ['alpha', 'beta', 'alpha', 'gamma', 'delta', 'alpha', 'alpha', 'beta', 'alpha', 'epsilon', 'alpha', ' Alpha ']
+const FLAG = [true, false, true, true, false, false, true, true, false, true, false, true]
+
+/** Dictionary-encode a column the way import.ts would. */
+function dict(vals: Array<string | number | null>): ColumnData {
+ const d: string[] = []
+ const idx: Array<number | null> = vals.map((v) => {
+ if (v == null) return null
+ const s = String(v)
+ let k = d.indexOf(s)
+ if (k < 0) { k = d.length; d.push(s) }
+ return k
+ })
+ return { enc: 'dict', dict: d, idx }
+}
+
+const raw = (vals: unknown[]): ColumnData =>
+ ({ enc: 'raw', v: vals as Array<number | string | boolean | null> })
+
+function sheet(enc: 'dict' | 'raw'): TableSheet {
+ const pick = (v: Array<string | number | null>): ColumnData => (enc === 'dict' ? dict(v) : raw(v))
+ return {
+ id: 'src', name: 'Sales', kind: 'table',
+ rids: [[1, 12]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'quarter', name: 'Quarter', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'money', format: '$#,##0' },
+ { id: 'customer', name: 'Customer', type: 'text' },
+ { id: 'flag', name: 'Flag', type: 'bool' },
+ ],
+ data: {
+ region: pick(REGION),
+ quarter: pick(QUARTER),
+ amount: pick(AMOUNT),
+ customer: pick(CUSTOMER),
+ // a bool column stays raw in both fixtures: dictionary-encoding booleans
+ // is not something import.ts does, and pretending otherwise would test a
+ // shape no file contains
+ flag: raw(FLAG),
+ },
+ steps: [],
+ }
+}
+
+const spec = (over: Partial<PivotSpec> = {}): PivotSpec => ({
+ from: 'src', rows: ['region'], cols: [], values: [{ col: 'amount', fn: 'sum' }], ...over,
+})
+
+/** The one row whose kind and path match. */
+const findRow = (res: PivotResult, kind: string, ...path: string[]) =>
+ res.rows.find((r) => r.kind === kind && r.path.map((p) => String(p ?? '')).join('|') === path.join('|'))
+
+const findCol = (res: PivotResult, kind: string, ...path: string[]) =>
+ res.columns.findIndex((c) => c.kind === kind && c.path.map((p) => String(p ?? '')).join('|') === path.join('|'))
+
+// ============================================================ grouping order
+
+console.log('\ncategories come out in DATA order, not alphabetically')
+{
+ const res = runPivot(sheet('dict'), spec())
+ const got = res.rows.filter((r) => r.kind === 'leaf').map((r) => String(r.path[0] ?? '(blank)'))
+ ok(JSON.stringify(got) === JSON.stringify(['North', 'south', 'East', '(blank)']),
+ `first-seen order is kept — got ${JSON.stringify(got)}, and the alphabetical answer would be East, North, south`)
+ ok(got[1] === 'south',
+ 'the label is the FIRST-SEEN original: "south" appears before "South" in the data, and they are one group')
+ ok(res.rows.filter((r) => r.kind === 'leaf').length === 4,
+ '"south" and "South" merged into one group — the same canonical key the filter menu ticks by')
+}
+
+console.log('\na blank grouping value is its own group, and it is labelled')
+{
+ const res = runPivot(sheet('dict'), spec())
+ const blank = res.rows.find((r) => r.kind === 'leaf' && r.path[0] === null)
+ ok(!!blank, 'the row with no region is grouped under a blank, not dropped and not merged into another region')
+ ok(label(blank!.path[0]) === '(blank)',
+ 'and it renders as "(blank)" — an unlabelled line in an outline reads as a rendering bug')
+ ok(near(blank!.cells[0].v, 7), 'its 7 is in the table where a reader can see it')
+}
+
+// ============================================================ gap vs zero
+
+console.log('\nan empty group and a zero never look the same')
+{
+ const res = runPivot(sheet('dict'), spec({ cols: ['quarter'] }))
+ const q3 = findCol(res, 'leaf', 'Q3')
+ const north = findRow(res, 'leaf', 'North')!
+ const gap = north.cells[q3]
+ ok(gap.v === null && gap.rows === 0,
+ 'North × Q3 has no rows at all: v is null and rows is 0 — a GAP, never a 0')
+
+ // South × Q2 is the other half of the same distinction: the rows exist, the
+ // measure is blank in all of them. That is a different fact and has to read
+ // differently from both a gap and a zero.
+ const q2 = findCol(res, 'leaf', 'Q2')
+ const south = findRow(res, 'leaf', 'south')!
+ const present = south.cells[q2]
+ ok(present.rows === 1 && present.present === 0 && present.v === null,
+ 'south × Q2 HAS a row and no value: rows 1, present 0, sum null — distinguishable from the gap by `rows`')
+
+ const counted = runPivot(sheet('dict'), spec({ cols: ['quarter'], values: [{ col: 'amount', fn: 'count' }] }))
+ ok(counted.rows.find((r) => r.path[0] === 'south')!.cells[q2].v === 0,
+ 'the same cell COUNTED is 0, which is an answer — count is the one function whose zero is a fact')
+ ok(counted.rows.find((r) => r.path[0] === 'North')!.cells[q3].v === null,
+ 'and the true gap still counts null, not 0 — otherwise count would erase the distinction the others keep')
+}
+
+// ============================================================ text and averages
+
+console.log('\ntext in a numeric aggregation is counted, never coerced to 0')
+{
+ const res = runPivot(sheet('dict'), spec({ values: [{ col: 'amount', fn: 'sum' }, { col: 'amount', fn: 'avg' }, { col: 'amount', fn: 'count' }] }))
+ const s = findRow(res, 'leaf', 'south')!
+ // rows 3,4,5 hold 5, "n/a", (blank)
+ ok(near(s.cells[0].v, 5),
+ 'sum of [5, "n/a", blank] is 5 — the naive `Number(v)||0` answer is also 5, so the shape below is what proves it')
+ ok(s.cells[0].skipped === 1 && s.cells[0].present === 2 && s.cells[0].numeric === 1,
+ 'and the cell REPORTS it: 2 values present, 1 numeric, 1 skipped — model.ts\'s `failed` at the aggregate level')
+ ok(near(s.cells[1].v, 5),
+ 'the average is 5 (5 ÷ 1 numeric), not 2.5 (5 ÷ 2 present) and not 1.67 (5 ÷ 3 rows)')
+ ok(s.cells[2].v === 2,
+ 'count is 2 — non-blank values, which includes the text: it is present, it is just not a number')
+}
+
+console.log('\nmin and max of a group with no numbers are nothing, not zero')
+{
+ const res = runPivot(sheet('dict'), spec({
+ rows: ['region'], cols: ['quarter'],
+ values: [{ col: 'amount', fn: 'min' }, { col: 'amount', fn: 'max' }],
+ }))
+ const q2 = findCol(res, 'leaf', 'Q2')
+ const south = findRow(res, 'leaf', 'south')!
+ ok(south.cells[q2].v === null && south.cells[q2 + 1].v === null,
+ 'south × Q2 has a row whose amount is blank: min and max are null — `Math.min()` of an empty list is Infinity and `?? 0` is a zero nobody measured')
+ ok(south.cells[q2].rows === 1,
+ 'and the row is still counted, so the cell is not a gap either')
+
+ const q1 = findCol(res, 'leaf', 'Q1')
+ ok(south.cells[q1].v === 5 && south.cells[q1 + 1].v === 5,
+ 'south × Q1 holds 5 and "n/a": both min and max are 5 — text has no magnitude, so it cannot be the smallest thing in the group')
+}
+
+console.log('\naverages divide by values PRESENT, as chart.ts already established')
+{
+ const res = runPivot(sheet('dict'), spec({ values: [{ col: 'amount', fn: 'avg' }] }))
+ const grand = findRow(res, 'grand')!
+ ok(near(grand.cells[0].v, 22.5),
+ 'grand average is 225 ÷ 10 numerics = 22.5 — dividing by the 12 rows would give 18.75')
+ ok(grand.cells[0].numeric === 10 && grand.cells[0].rows === 12,
+ 'the divisor and the row count are both carried, and they differ')
+}
+
+// ============================================================ subtotals
+
+console.log('\nsubtotals are COMPUTED from the rows, never summed from the cells')
+{
+ const res = runPivot(sheet('dict'), spec({
+ values: [{ col: 'amount', fn: 'avg' }, { col: 'customer', fn: 'countDistinct' }, { col: 'amount', fn: 'median' }],
+ }))
+ const leaves = res.rows.filter((r) => r.kind === 'leaf')
+ const grand = findRow(res, 'grand')!
+
+ const meanOfMeans = leaves.reduce((a, r) => a + (r.cells[0].v ?? 0), 0) / leaves.length
+ ok(!near(grand.cells[0].v, meanOfMeans),
+ `an average of averages is a DIFFERENT number (${meanOfMeans.toFixed(4)} vs ${grand.cells[0].v}) — this check exists to make sure we are not computing it`)
+ ok(near(grand.cells[0].v, 22.5), 'the grand average is the one over the source rows')
+
+ const sumOfDistincts = leaves.reduce((a, r) => a + (r.cells[1].v ?? 0), 0)
+ ok(grand.cells[1].v === 5 && sumOfDistincts === 8,
+ `distinct customers overall is 5 while the per-region counts add to ${sumOfDistincts} — the same customer buys in two regions, and distincts do not add`)
+
+ ok(near(grand.cells[2].v, 9.5),
+ 'the grand median is 9.5 over [1,3,5,7,9,10,20,30,40,100] — a median of medians would not be')
+ const east = findRow(res, 'leaf', 'East')!
+ ok(near(east.cells[2].v, 6),
+ 'East median over [1,3,9,100] is 6 — a LEXICAL sort would answer 51.5, which is the default Array.sort behaviour')
+}
+
+console.log('\nsubtotals appear after their children, grand total last')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: ['region', 'quarter'] }))
+ const shape = res.rows.map((r) => `${r.kind}:${r.path.map((p) => String(p ?? '_')).join('/')}`)
+ ok(JSON.stringify(shape) === JSON.stringify([
+ 'leaf:North/Q1', 'leaf:North/Q2', 'subtotal:North',
+ 'leaf:south/Q1', 'leaf:south/Q2', 'subtotal:south',
+ 'leaf:East/Q1', 'leaf:East/Q3', 'subtotal:East',
+ 'leaf:_/Q3', 'subtotal:_',
+ 'grand:',
+ ]), `outline order is children-then-subtotal, grand total last — got ${JSON.stringify(shape)}`)
+
+ const sub = findRow(res, 'subtotal', 'North')!
+ ok(near(sub.cells[0].v, 100) && sub.cells[0].rows === 4,
+ 'the North subtotal is 100 over its own 4 rows')
+}
+
+console.log('\nthe grand total equals the sum of the leaves — for sum, which is the one function where it must')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: ['region', 'quarter'] }))
+ const leaves = res.rows.filter((r) => r.kind === 'leaf')
+ const total = leaves.reduce((a, r) => a + (r.cells[0].v ?? 0), 0)
+ const grand = findRow(res, 'grand')!
+ ok(near(grand.cells[0].v, total) && near(grand.cells[0].v, 225),
+ `every leaf adds to ${total} and the grand total says ${grand.cells[0].v} — a reader who adds the column up by hand has to be right`)
+ ok(grand.cells[0].rows === res.scanned,
+ 'and the grand total covers exactly the rows the footer claims were scanned')
+}
+
+console.log('\nrow and column totals cross-foot')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: ['region'], cols: ['quarter'] }))
+ const gi = findCol(res, 'grand')
+ ok(gi >= 0, 'a column grand total exists when there are column fields')
+ const grandRow = findRow(res, 'grand')!
+ const leafCols = res.columns.map((c, i) => (c.kind === 'leaf' ? i : -1)).filter((i) => i >= 0)
+ for (const r of res.rows) {
+ const across = leafCols.reduce((a, i) => a + (r.cells[i].v ?? 0), 0)
+ if (!near(r.cells[gi].v, across)) {
+ ok(false, `row [${r.path}] adds across to ${across} but its total column says ${r.cells[gi].v}`)
+ break
+ }
+ }
+ ok(near(grandRow.cells[gi].v, 225), 'the corner cell is the grand total both ways')
+ checks++; console.log(' ok every row adds across to its own total column')
+}
+
+// ============================================================ no column fields
+
+console.log('\nno column fields is a legitimate pivot, not a degenerate one')
+{
+ const res = runPivot(sheet('dict'), spec({ cols: [] }))
+ ok(res.columns.length === 1 && res.columns[0].kind === 'leaf',
+ 'one column group, and it is a LEAF — emitting a grand total there too would print the same numbers twice')
+ ok(res.header.length === 1 && res.header[0].length === 1,
+ 'the value name is still shown, or a reader cannot tell a sum from a count')
+ ok(String(res.header[0][0].label).includes('Amount'), 'and it names the column it summarises')
+}
+
+console.log('\nno row fields either: one grand number, correctly')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: [], cols: [] }))
+ ok(res.rows.length === 1 && res.rows[0].kind === 'leaf', 'exactly one row, and no phantom grand total beside it')
+ ok(near(res.rows[0].cells[0].v, 225), 'and it is the whole sheet')
+}
+
+// ============================================================ header shape
+
+console.log('\nthe header spans the columns exactly')
+{
+ const res = runPivot(sheet('dict'), spec({
+ rows: ['region'], cols: ['quarter'],
+ values: [{ col: 'amount', fn: 'sum' }, { col: 'amount', fn: 'count' }],
+ }))
+ for (const hrow of res.header) {
+ const span = hrow.reduce((a, h) => a + h.span, 0)
+ if (span !== res.columns.length) {
+ ok(false, `a header row spans ${span} of ${res.columns.length} columns — the table would shear`)
+ break
+ }
+ }
+ checks++; console.log(` ok every header row spans exactly ${res.columns.length} columns`)
+ ok(res.header.length === 2, 'one row per column field plus a value row, because there are two values')
+ const top = res.header[0]
+ ok(top.filter((h) => h.total).length === 1 && top[top.length - 1].total,
+ 'the grand-total caption is one cell, at the end, and it is marked as a total rather than as a category')
+ ok(top[0].span === 2, 'Q1 spans its two value columns')
+
+ // The span sum alone cannot catch a MERGE — merging two header cells keeps
+ // the total. So walk the covered columns and prove every one of them really
+ // does belong under the caption above it.
+ let bad = ''
+ res.header.forEach((hrow, l) => {
+ let at = 0
+ for (const h of hrow) {
+ const under = res.columns.slice(at, at + h.span)
+ at += h.span
+ if (l >= res.colFields.length) return // the value row spans one each
+ const keys = new Set(under.map((c) => (l >= c.codes.length
+ ? `T${c.kind}`
+ : c.codes.slice(0, l + 1).join(','))))
+ if (keys.size > 1) bad ||= `"${String(h.label)}" at level ${l} spans ${keys.size} different groups`
+ }
+ })
+ ok(bad === '', bad || 'and every header cell covers exactly the columns that belong to it — a merged caption keeps the span sum right and lies about the table')
+}
+
+// ============================================================ blanks policy
+
+console.log('\nexcluding blanks excludes the ROW, so the totals still foot')
+{
+ const kept = runPivot(sheet('dict'), spec({ rows: ['region'] }))
+ const dropped = runPivot(sheet('dict'), spec({ rows: ['region'], blanks: false }))
+ ok(near(kept.rows.find((r) => r.kind === 'grand')!.cells[0].v, 225), 'with blanks, the grand total is 225')
+ ok(dropped.rows.filter((r) => r.kind === 'leaf').length === 3,
+ 'without blanks the "(blank)" group is gone')
+ const grand = dropped.rows.find((r) => r.kind === 'grand')!
+ ok(near(grand.cells[0].v, 218),
+ 'and its 7 left the GRAND TOTAL too (225 → 218) — hiding the group while still totalling its rows is the failure this guards')
+ const leaves = dropped.rows.filter((r) => r.kind === 'leaf')
+ .reduce((a, r) => a + (r.cells[0].v ?? 0), 0)
+ ok(near(grand.cells[0].v, leaves), 'the visible leaves still add to the grand total')
+ ok(dropped.scanned === 11 && grand.cells[0].rows === 11,
+ '`scanned` reports the rows that reached an accumulator (11), not the 12 the filters admitted — the footer must not disagree with the total above it')
+}
+
+// ============================================================ dict vs raw
+
+console.log('\nthe dictionary path and the raw path answer identically')
+{
+ // `codes` are deliberately NOT compared: they are opaque handles into the
+ // encoding — dictionary indices on one side, intern positions on the other —
+ // and requiring them to match would be requiring the fast path not to be a
+ // fast path. Everything a reader can see is compared.
+ const drop = (o: unknown): unknown => {
+ if (Array.isArray(o)) return o.map(drop)
+ if (o && typeof o === 'object') {
+ const out: Record<string, unknown> = {}
+ for (const [k, v] of Object.entries(o)) if (k !== 'codes') out[k] = drop(v)
+ return out
+ }
+ return o
+ }
+ const strip = (r: PivotResult) => JSON.stringify(drop({
+ rows: r.rows, columns: r.columns, header: r.header, scanned: r.scanned, findings: r.findings,
+ }))
+ for (const s of [
+ spec({ rows: ['region'], cols: ['quarter'] }),
+ spec({ rows: ['region', 'quarter'], values: [{ col: 'amount', fn: 'avg' }, { col: 'customer', fn: 'countDistinct' }, { col: 'amount', fn: 'median' }] }),
+ spec({ rows: ['customer'], values: [{ col: 'amount', fn: 'max' }, { col: 'amount', fn: 'min' }] }),
+ spec({ rows: ['region'], blanks: false }),
+ ]) {
+ const a = strip(runPivot(sheet('dict'), s))
+ const b = strip(runPivot(sheet('raw'), s))
+ if (a !== b) {
+ ok(false, `encoding changed the answer for ${JSON.stringify(s.rows)}×${JSON.stringify(s.cols)} — the dictionary fast path has drifted from the general one`)
+ break
+ }
+ }
+ checks++
+ console.log(' ok four specs give byte-identical results under dict and raw encoding')
+}
+
+// ============================================================ drill-down
+
+console.log('\na drill-down reproduces the number it explains')
+{
+ const s = sheet('dict')
+ const res = runPivot(s, spec({
+ rows: ['region', 'quarter'], cols: ['quarter'],
+ values: [{ col: 'amount', fn: 'sum' }, { col: 'amount', fn: 'count' }],
+ }))
+ const amounts = AMOUNT.map((v) => _internals.asNumber(v))
+ let worst = ''
+ for (let ri = 0; ri < res.rows.length && !worst; ri++) {
+ for (let ci = 0; ci < res.columns.length; ci++) {
+ const cell = res.rows[ri].cells[ci]
+ const d = drillDown(res, ri, ci)
+ if (d.total !== cell.rows) {
+ worst = `[${res.rows[ri].path}]×[${res.columns[ci].path}] cell claims ${cell.rows} rows, the drill-down finds ${d.total}`
+ break
+ }
+ if (res.columns[ci].value.fn !== 'sum') continue
+ const nums = d.rows.map((r) => amounts[r]).filter((n): n is number => n !== null)
+ const re = nums.length ? nums.reduce((a, b) => a + b, 0) : null
+ if (!(re === null ? cell.v === null : near(cell.v, re))) {
+ worst = `[${res.rows[ri].path}]×[${res.columns[ci].path}] shows ${cell.v}, its own rows add to ${re}`
+ break
+ }
+ }
+ }
+ ok(worst === '', worst || 'every cell in a 12×8 pivot — leaf, subtotal and grand alike — re-aggregates from its own drill-down')
+
+ const north = res.rows.findIndex((r) => r.kind === 'subtotal' && r.path[0] === 'North')
+ const gi = findCol(res, 'grand')
+ ok(JSON.stringify(drillDown(res, north, gi).rows) === JSON.stringify([0, 1, 2, 8]),
+ 'the North subtotal drills to source rows 0,1,2,8 — indices into the LIVE sheet, not a copied snapshot the way Excel does it')
+
+ const gapRow = res.rows.findIndex((r) => r.kind === 'leaf' && r.path[0] === 'North' && r.path[1] === 'Q1')
+ const q3 = findCol(res, 'leaf', 'Q3')
+ ok(drillDown(res, gapRow, q3).total === 0,
+ 'a gap drills to nothing rather than to the whole sheet — an unpinned code would match everything')
+
+ const capped = drillDown(res, res.rows.length - 1, gi, 3)
+ ok(capped.rows.length === 3 && capped.total === 12 && capped.truncated,
+ 'the cap TRUNCATES and says so, rather than quietly showing the first three of twelve')
+}
+
+console.log('\na drill-down honours the pivot\'s own filters')
+{
+ const s = sheet('dict')
+ const res = runPivot(s, spec({
+ rows: ['region'], filters: [{ col: 'quarter', pred: { op: 'equals', v: 'Q1' } }],
+ }))
+ ok(res.scanned === 6, 'six rows are in Q1')
+ ok(near(res.rows.find((r) => r.kind === 'grand')!.cells[0].v, 144),
+ 'and they total 10+20+5+100+9 = 144 — "n/a" is not among them, and not a zero either')
+ const north = res.rows.findIndex((r) => r.kind === 'leaf' && r.path[0] === 'North')
+ ok(JSON.stringify(drillDown(res, north, 0).rows) === JSON.stringify([0, 1]),
+ 'the drill-down shows only filtered rows — offering row 2 (a Q2 row) would be offering evidence for a number it is not part of')
+}
+
+console.log('\nthe reader\'s row set is opt-in, never the default')
+{
+ const s = sheet('dict')
+ const all = runPivot(s, spec())
+ const some = runPivot(s, spec(), { rows: [0, 1, 2] })
+ ok(all.scanned === 12, 'by default a pivot is over the whole sheet — it is a document, and a document does not change shape per reader')
+ ok(some.scanned === 3 && near(some.rows[0].cells[0].v, 60),
+ 'and `opts.rows` narrows it when the caller explicitly asks')
+}
+
+// ============================================================ aggregations
+
+console.log('\nthe aggregations themselves')
+{
+ const fns: AggFn[] = ['sum', 'avg', 'count', 'min', 'max', 'median', 'countDistinct']
+ const res = runPivot(sheet('dict'), spec({ rows: [], values: fns.map((fn) => ({ col: 'amount', fn })) }))
+ const c = res.rows[0].cells
+ const want: Array<[AggFn, number]> = [
+ ['sum', 225], ['avg', 22.5], ['count', 11], ['min', 1], ['max', 100], ['median', 9.5], ['countDistinct', 11],
+ ]
+ want.forEach(([fn, v], i) => {
+ ok(near(c[i].v, v), `${fn} over the whole sheet is ${v} (got ${c[i].v})`)
+ })
+ ok(c[2].v === 11 && c[0].numeric === 10,
+ 'count is 11 and the numeric divisor is 10 — the "n/a" is present but not a number, and only one of those two numbers is allowed to include it')
+ ok(c[6].v === 11,
+ 'distinct counts the "n/a" as a value: it is a distinct thing that was recorded, which is a different question from what it sums to')
+}
+
+console.log('\nnumbers written as text group and total as numbers')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: ['region'] }))
+ const north = findRow(res, 'leaf', 'North')!
+ ok(near(north.cells[0].v, 100),
+ 'North includes the row whose amount is the STRING "40" — 10+20+30+40')
+ ok(_internals.asNumber('40') === 40 && _internals.asNumber('1,234') === 1234,
+ 'the strict numeric shape reads "40" and "1,234"')
+ ok(_internals.asNumber('') === null && _internals.asNumber(' ') === null,
+ 'and refuses the empty string, which is how `Number(v)` turns a blank into a zero')
+ ok(_internals.asNumber('50%') === null && _internals.asNumber('2026-01-15') === null,
+ 'and refuses a percent (a percent column stores the fraction) and an ISO date (which must stay text to sort chronologically)')
+ ok(_internals.asNumber(true) === 1 && _internals.asNumber(false) === 0,
+ 'booleans DO read as 1/0 — the one deliberate divergence from filter.ts, because "how many are flagged" is what a bool column is for')
+}
+
+console.log('\nsumming a bool column answers the question it is asked')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: [], values: [{ col: 'flag', fn: 'sum' }, { col: 'flag', fn: 'count' }] }))
+ ok(near(res.rows[0].cells[0].v, 7), '7 of the 12 rows are flagged')
+ ok(res.rows[0].cells[1].v === 12,
+ 'and `false` counts as present — a checkbox that is off is an answer, not a blank')
+}
+
+console.log('\ncountDistinct canonicalises the way the filter menu does')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: [], values: [{ col: 'customer', fn: 'countDistinct' }] }))
+ ok(res.rows[0].cells[0].v === 5,
+ 'alpha / " Alpha " are one customer, so the answer is 5 — a set keyed on the raw string would say 6')
+ ok(_internals.matchKey(10) === _internals.matchKey('10') && _internals.matchKey('North') === _internals.matchKey(' north '),
+ 'the key is filter.ts\'s: a box the reader ticks in the filter menu selects the same rows the pivot grouped')
+}
+
+// ============================================================ findings
+
+console.log('\na field naming a column that is gone is reported, never silently grouped')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: ['region', 'ghost'] }))
+ ok(res.rowFields.length === 1 && res.rowFields[0] === 'region', 'the dead field is dropped')
+ ok(res.findings.some((f) => f.kind === 'missing-column' && f.detail.includes('ghost')),
+ 'and reported — grouping the whole sheet under one "(blank)" would look like a pivot of nothing')
+ ok(res.rows.filter((r) => r.kind === 'leaf').length === 4,
+ 'the surviving field still groups normally')
+}
+
+console.log('\nan aggregation this build does not know refuses rather than inventing a number')
+{
+ const res = runPivot(sheet('dict'), spec({ values: [{ col: 'amount', fn: 'mode' as AggFn }] }))
+ ok(res.values.length === 0 && res.columns.length === 0, 'no column is produced for it')
+ ok(res.findings.some((f) => f.kind === 'unknown-agg'),
+ 'and the reader is told — model.ts:174\'s rule: unresolved shows no number, never a zero')
+ const back = readPivotSpec({ pivot: spec({ values: [{ col: 'amount', fn: 'mode' as AggFn }] }) })
+ ok(back!.values[0].fn === 'mode',
+ 'while the spec still ROUND-TRIPS it, so a build that knows "mode" gets its pivot back (PLATFORM §3)')
+}
+
+console.log('\na packed column is refused rather than pivoted as one blank group')
+{
+ const s = sheet('dict')
+ s.data.region = { enc: 'pack', b64: 'AAAA', n: 12 }
+ let threw = ''
+ try { runPivot(s, spec()) } catch (e) { threw = e instanceof Error ? e.message : String(e) }
+ ok(threw.includes('packed'),
+ 'readCell answers null for every row of a packed column, so pivoting one would silently produce ONE group holding the whole sheet')
+}
+
+// ============================================================ the spec
+
+console.log('\nreading a spec out of a file is defensive')
+{
+ ok(readPivotSpec(null) === null && readPivotSpec({}) === null && readPivotSpec({ pivot: 7 }) === null,
+ 'garbage is not a pivot')
+ ok(readPivotSpec({ pivot: { rows: ['a'] } }) === null,
+ 'and neither is a spec with no source sheet — everything else is optional')
+ const p = readPivotSpec({ pivot: { from: 'src', rows: ['a', 3, null], values: 'nope' } })!
+ ok(JSON.stringify(p.rows) === '["a"]' && JSON.stringify(p.values) === '[]',
+ 'a hand-edited field list keeps what is readable and drops what is not, rather than throwing on open')
+ const keep = readPivotSpec({ pivot: { from: 'src', rows: [], cols: [], values: [], future: 42 } })!
+ ok(keep.future === 42, 'unknown spec fields survive the read — the format is additive forever (PLATFORM §3)')
+}
+
+console.log('\na pivot sheet survives today\'s parseDoc, which rewrites its kind')
+{
+ const doc = {
+ format: 'bento/dash', version: 1, docId: 'd', title: 'w',
+ sheets: [
+ { id: 'src', name: 'Sales', kind: 'table', rids: [[1, 1]], columns: [], data: {}, steps: [] },
+ newPivotSheet('pv', 'By region', spec()),
+ ],
+ }
+ const r = parseDoc(JSON.stringify(doc))
+ ok(r.ok, 'the workbook parses')
+ if (r.ok) {
+ const pv = r.doc.sheets[1] as unknown as Record<string, unknown>
+ ok(pv.kind === 'pivot',
+ 'parseDoc PRESERVES the pivot kind — the additivity hook landed, so this check has flipped from asserting the coercion to asserting its absence')
+ ok(isPivotSheet(pv),
+ 'and the pivot is still found, because detection keys off the surviving `pivot` field rather than off `kind`')
+ ok(readPivotSpec(pv)!.rows[0] === 'region', 'with its fields intact')
+ }
+}
+
+console.log('\ndefaultPivot refuses what it cannot summarise')
+{
+ ok(defaultPivot(sheet('dict'))!.rows[0] === 'region', 'the first category column becomes the rows')
+ ok(defaultPivot(sheet('dict'))!.cols[0] === 'quarter', 'the second becomes the columns')
+ ok(defaultPivot(sheet('dict'))!.values[0].col === 'amount', 'and the first magnitude column is summed')
+
+ // A near-unique text column makes one group per row: the source table with
+ // extra lines and a worse layout.
+ const wide = sheet('dict')
+ wide.columns = wide.columns.filter((c) => c.id === 'customer' || c.id === 'amount')
+ wide.data.customer = dict(['a', 'b', 'c', 'd', 'e', 'f', 'g', 'h', 'i', 'j', 'k', 'l'])
+ ok(defaultPivot(wide) === null,
+ 'a column with one distinct value per row is refused as a default grouping — one group per row is the source table with extra lines')
+ wide.data.customer = dict(['a', 'b', 'a', 'b', 'a', 'b', 'a', 'b', 'a', 'b', 'a', 'b'])
+ ok(defaultPivot(wide)?.rows[0] === 'customer',
+ 'and the SAME column with two distinct values is accepted, so the refusal is about cardinality and not about the column')
+
+ const nonums = sheet('dict')
+ nonums.columns = nonums.columns.filter((c) => c.type === 'text')
+ ok(defaultPivot(nonums) === null, 'and a sheet with nothing to measure gets no default pivot at all')
+}
+
+console.log('\nvalue captions are generated, so renaming a column renames the header')
+{
+ const nameOf = (id: string) => (id === 'amount' ? 'Revenue' : id)
+ ok(valueName({ col: 'amount', fn: 'sum' }, nameOf) === 'Sum of Revenue', 'generated from the live column name')
+ ok(valueName({ col: 'amount', fn: 'sum', as: 'Take' }, nameOf) === 'Take', 'unless the author named it')
+}
+
+// ============================================================ purity
+
+console.log('\nrunning a pivot changes nothing')
+{
+ const s = sheet('dict')
+ const before = JSON.stringify(s)
+ const res = runPivot(s, spec({ rows: ['region', 'quarter'], cols: ['quarter'], values: [{ col: 'amount', fn: 'median' }] }))
+ drillDown(res, 0, 0)
+ ok(JSON.stringify(s) === before,
+ 'the source sheet is untouched — the numbers are DERIVED, and nothing here can write one into the document (chart.ts\'s rule)')
+
+ const again = runPivot(sheet('dict'), spec({ rows: ['region', 'quarter'] }))
+ const once = runPivot(sheet('dict'), spec({ rows: ['region', 'quarter'] }))
+ ok(JSON.stringify(again.rows) === JSON.stringify(once.rows),
+ 'and two runs agree, so a repaint cannot change a number')
+}
+
+console.log('\na gap cell cannot be decorated into every other gap')
+{
+ const res = runPivot(sheet('dict'), spec({ rows: ['region'], cols: ['quarter'] }))
+ const gap = res.rows.find((r) => r.path[0] === 'North')!.cells[findCol(res, 'leaf', 'Q3')]
+ let threw = false
+ try { (gap as { v: number | null }).v = 0 } catch { threw = true }
+ ok(threw || gap.v === null,
+ 'the shared empty cell is frozen — it is returned by reference for every gap in the table')
+}
+
+// ============================================================ the renderer
+//
+// Not a layout test — a chevron that points the wrong way is a thing you can
+// see. What is NOT visible is whether a GAP is clickable: a cell with no rows
+// behind it that opens a drill-down showing every row in the sheet is the
+// failure mode this whole file exists to refuse, and it looks like a working
+// feature. Twelve lines of DOM is enough to ask.
+
+console.log('\nthe renderer draws, and a gap is not clickable')
+{
+ interface Node { tag: string; cls: string; text: string; kids: Node[]; attrs: Record<string, unknown>; listeners: string[] }
+ const mk = (tag: string): Node => {
+ const n: Node = { tag, cls: '', text: '', kids: [], attrs: {}, listeners: [] }
+ return new Proxy(n, {
+ get(o, k) {
+ if (k === 'className') return o.cls
+ if (k === 'textContent') return o.text
+ if (k === 'append') return (...xs: Node[]) => { for (const x of xs) { o.kids.push(x); o.text += x.text } }
+ if (k === 'classList') return { add: (c: string) => { o.cls += ` ${c}` }, contains: (c: string) => o.cls.includes(c) }
+ if (k === 'addEventListener') return (ev: string) => o.listeners.push(ev)
+ if (k === 'scrollIntoView') return () => {}
+ if (k in o) return (o as unknown as Record<string, unknown>)[k as string]
+ return o.attrs[k as string]
+ },
+ set(o, k, v) {
+ if (k === 'className') o.cls = String(v)
+ else if (k === 'textContent') { o.text = String(v); if (v === '') o.kids.length = 0 }
+ else o.attrs[k as string] = v
+ return true
+ },
+ }) as unknown as Node
+ }
+ ;(globalThis as unknown as { document: unknown }).document = { createElement: (tag: string) => mk(tag) }
+
+ const s = sheet('dict')
+ const res = runPivot(s, spec({ rows: ['region'], cols: ['quarter'] }))
+ const host = mk('div')
+ let down: (() => void) | null = null
+ let threw = ''
+ try { down = mountPivot(host as unknown as HTMLElement, res, { sheet: s }) } catch (e) {
+ threw = e instanceof Error ? e.message : String(e)
+ }
+ ok(threw === '', threw || 'mountPivot renders a two-axis pivot without throwing')
+
+ const all: Node[] = []
+ const walk = (n: Node) => { all.push(n); for (const k of n.kids) walk(k) }
+ walk(host)
+ // by TOKEN, not by substring: 'dxp-corner' contains 'dxp-c', and a matcher
+ // that counted the corner would have made the two counts below agree for the
+ // wrong reason
+ const has = (n: Node, c: string) => n.cls.trim().split(/\s+/).includes(c)
+ const cells = all.filter((n) => has(n, 'dxp-c'))
+ ok(cells.length === res.rows.length * res.columns.length,
+ `every cell reaches the DOM (${cells.length} of ${res.rows.length * res.columns.length})`)
+ const gaps = cells.filter((n) => has(n, 'dxp-gap'))
+ ok(gaps.length > 0, 'the fixture has gaps to check')
+ ok(gaps.every((n) => n.listeners.length === 0 && n.attrs.tabIndex === undefined),
+ 'and NONE of them is clickable or focusable — a gap has nothing to drill into, and offering the whole sheet instead would be the worst possible answer')
+ ok(cells.filter((n) => !has(n, 'dxp-gap')).every((n) => n.listeners.includes('click')),
+ 'every cell that does have rows behind it opens them')
+ ok(all.some((n) => has(n, 'dxp-skipped')),
+ 'the cell holding "n/a" is marked, so a short sum says so on screen')
+ down?.()
+ ok(host.text === '', 'the teardown empties the host, as renderChart\'s does')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-preview.ts b/scripts/test-dash-preview.ts
new file mode 100644
index 00000000..e22db6ab
--- /dev/null
+++ b/scripts/test-dash-preview.ts
@@ -0,0 +1,342 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash first-sheet preview rig.
+//
+// node scripts/test-dash-preview.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. Every save writes a static rendering of the first sheet
+// into the shell so file managers can thumbnail the workbook (kernel/src/save.ts
+// for the placement, dash/src/preview.ts for the drawing). Everything about
+// that feature fails SILENTLY — nobody proofreads markup they cannot see — and
+// none of it is recoverable once files are on disk:
+//
+// 1. THE ENCRYPTION VETO. A `bento/enc` workbook must never carry a plaintext
+// rendering of its first sheet. Getting this wrong publishes real rows of
+// real numbers beside the ciphertext that exists to hide them, in every
+// password-protected workbook ever saved, and the owner has no way to
+// notice. The kernel owns the real gate (two independent signals, one of
+// which a provider cannot see); dash repeats the half it CAN see, and this
+// pins that it still does.
+// 2. THE OUTPUT REFUSAL. The preview is drawn from author data — cell values,
+// column names, the sheet name, the title. A script tag reaching the file
+// unbalances it and breaks the frozen splice contract every shipped
+// updater relies on (PLATFORM §2).
+// 3. CSS INJECTION, which is the refusal HTML escaping does not cover. Theme
+// colours are author data too and they land inside a `<style>` block,
+// where `}` ends a rule and `<` means nothing. A workbook whose accent is
+// `#fff}body{display:none` would otherwise ship a preview that blanks the
+// page it sits in — or, with `url(…)`, one that phones home from a file
+// the reader believed was self-contained (PLATFORM §1).
+// 4. NUMBERS NOBODY COMPUTED. Formula columns store an expression, not
+// values. Past the recalculation ceiling the preview must draw them EMPTY
+// — never 0, never a stale figure. A partial totals row is the same
+// failure with a bigger audience: it is dash's answer to `=SUM(B2:B41)`
+// falling out of range, so a total computed over the sixteen rows the
+// thumbnail happens to draw would put exactly that bug into the picture.
+// 5. THE BYTE BUDGET, which is paid in every saved file and cannot be
+// compressed (the audience never runs the loader). It must hold against
+// adversarial content, and the last tier must be reachable — a budget with
+// no terminating fallback is an infinite loop or an overrun.
+//
+// Laying the page out and fitting it to a viewport need a DOM and are verified
+// in a browser and against the real macOS thumbnailer (`qlmanage -t`). Every
+// check below is a pure decision, so it gets pinned here where a regression
+// costs one CI run instead of one release. `scripts/test-preview.ts` is the
+// slides counterpart and covers the kernel gate itself.
+
+import { previewAllowed, previewIsSafe, setEncryptionPassword } from '../kernel/src/save.ts'
+import { previewMarkup, cssColor, byteLength, PREVIEW_BUDGET } from '../dash/src/preview.ts'
+import { FORMAT, FORMAT_VERSION, type DashDoc, type Sheet } from '../dash/src/model.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) {
+ failures++
+ console.error(` ✗ ${msg}`)
+ } else {
+ console.log(` ✓ ${msg}`)
+ }
+}
+
+// Never write these literals (AGENTS.md #1): this file is not bundled, but the
+// fixtures need them as data, and the habit is the rule.
+const SCRIPT_OPEN = '<scr' + 'ipt>'
+const SCRIPT_CLOSE = '</scr' + 'ipt>'
+const NOSCRIPT_CLOSE = '</nosc' + 'ript>'
+
+const wb = (sheets: Sheet[], extra: Partial<DashDoc> = {}): DashDoc => ({
+ format: FORMAT,
+ version: FORMAT_VERSION,
+ docId: 'doc-test',
+ title: 'Q3 pipeline',
+ sheets,
+ ...extra,
+} as DashDoc)
+
+const simple = (): Sheet => ({
+ id: 'sh1',
+ name: 'Pipeline',
+ kind: 'table',
+ rids: [[1, 3]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'value', name: 'Value', type: 'money', format: '£#,##0' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, 0] },
+ value: { enc: 'raw', v: [12400, 8200, 15600] },
+ },
+ steps: [],
+})
+
+/**
+ * Run a check that might THROW, and turn a throw into a failed check.
+ *
+ * A rig that dies mid-run reports one crash and leaves everything after it
+ * unverified — which is what happened the first time the no-sheets guard was
+ * deliberately removed: the degenerate-document checks took the process down
+ * and the whole "scope" section silently stopped existing.
+ */
+const attempt = <T>(fn: () => T): T | 'threw' => {
+ try { return fn() } catch { return 'threw' }
+}
+
+const markup = (doc: DashDoc): string => {
+ const html = previewMarkup(doc)
+ if (html === null) throw new Error('expected a preview, got none')
+ return html
+}
+
+// --- 1. the encryption veto -------------------------------------------------
+
+console.log('\nencryption veto')
+
+setEncryptionPassword(null)
+ok(previewMarkup(wb([simple()])) !== null, 'a plain workbook previews')
+
+setEncryptionPassword('hunter2')
+ok(previewMarkup(wb([simple()])) === null,
+ 'an active password vetoes the preview at the provider, not only at the kernel')
+
+setEncryptionPassword(null)
+ok(previewMarkup(wb([simple()])) !== null, 'clearing the password restores the preview')
+
+// The other half of the gate is the kernel's and dash cannot see it — a
+// provider is handed a document, never the block that will be written. Pinned
+// here so the pairing is visible from dash's side too.
+const ENVELOPE = JSON.stringify({
+ format: 'bento/enc', v: 1, it: 300000, salt: 'c2FsdA==', iv: 'aXY=', data: 'ZGF0YQ==',
+})
+ok(previewAllowed(ENVELOPE) === false,
+ 'the kernel still vetoes an already-encrypted body with no password flag set')
+
+// --- 2. the output refusal --------------------------------------------------
+
+console.log('\noutput refusal')
+
+ok(previewIsSafe(markup(wb([simple()]))) === true, 'an ordinary workbook produces safe markup')
+
+const hostile = (): Sheet => ({
+ id: 'sh1',
+ name: `Sheet ${SCRIPT_CLOSE}`,
+ kind: 'table',
+ rids: [[1, 2]],
+ columns: [
+ { id: 'a', name: `${SCRIPT_OPEN}alert(1)${SCRIPT_CLOSE}`, type: 'text' },
+ { id: 'b', name: `${NOSCRIPT_CLOSE}x`, type: 'text' },
+ ],
+ data: {
+ // both encodings: a dictionary hides the string one level down, and it is
+ // the encoding import chooses for repetitive columns — i.e. the likely one
+ a: { enc: 'dict', dict: [`${SCRIPT_OPEN}steal()${SCRIPT_CLOSE}`, '"><b>'], idx: [0, 1] },
+ b: { enc: 'raw', v: [`x${NOSCRIPT_CLOSE}`, `<scr` + `ipt src=//evil>`] },
+ },
+ steps: [],
+})
+
+const nasty = markup(wb([hostile()], {
+ title: `Deck ${SCRIPT_CLOSE}`,
+ meta: { author: SCRIPT_OPEN },
+}))
+ok(previewIsSafe(nasty) === true, 'script tags in values, names, the sheet name and the title are neutralised')
+ok(!nasty.toLowerCase().includes('<scr' + 'ipt'), 'no script open survives into the markup')
+ok(!nasty.toLowerCase().includes('</scr' + 'ipt'), 'no script close survives into the markup')
+ok(!nasty.toLowerCase().includes('</nosc' + 'ript'), 'no noscript close survives into the markup')
+ok(nasty.includes('&lt;'), 'the hostile content is present — escaped, not silently dropped')
+
+// A cell override carries a hand-typed value and wins over the stored one
+// (grid.ts precedence), so it is its own path into the markup.
+const overridden = wb([{
+ ...(simple() as Record<string, unknown>),
+ cells: { 'region:1': { v: `OVERRIDDEN${SCRIPT_CLOSE}`, by: 'someone' } },
+} as unknown as Sheet])
+const overHtml = markup(overridden)
+ok(previewIsSafe(overHtml) === true, 'a hand override reaches the markup escaped too')
+// …and is actually HONOURED. Asserting only that the markup is safe passed
+// against an implementation that ignored overrides entirely — a preview that
+// shows the imported value where a human wrote a correction is a wrong number
+// in the one artefact nobody proofreads.
+ok(overHtml.includes('OVERRIDDEN'), 'a hand override BEATS the stored value, as it does in the grid')
+
+// The canvas sheet is a second renderer with a second set of call sites.
+const canvas = wb([{
+ id: 'c1', name: 'Scratch', kind: 'canvas',
+ cells: { A1: { v: `${SCRIPT_OPEN}x${SCRIPT_CLOSE}` }, B2: { v: 42 }, C3: { f: '=A1' } },
+} as Sheet])
+const canvasHtml = markup(canvas)
+ok(previewIsSafe(canvasHtml) === true, 'a canvas sheet escapes its cells')
+ok(canvasHtml.includes('>42<'), 'a canvas sheet draws its values')
+ok(canvasHtml.includes('>A<') && canvasHtml.includes('>B<'), 'a canvas sheet draws A1 headers')
+
+// --- 3. CSS injection through the theme -------------------------------------
+
+console.log('\nCSS injection')
+
+ok(cssColor('#F7A600', '#000') === '#F7A600', 'an ordinary hex colour passes')
+ok(cssColor('rgb(30, 41, 59)', '#000') === 'rgb(30, 41, 59)', 'rgb() passes')
+ok(cssColor('hsl(20 30% 40% / 0.5)', '#000') === 'hsl(20 30% 40% / 0.5)', 'modern hsl() passes')
+ok(cssColor('#fff}body{display:none', '#000') === '#000', 'a rule-closing brace is refused')
+ok(cssColor('red;position:fixed', '#000') === '#000', 'a declaration separator is refused')
+ok(cssColor('url(https://evil.example/x.png)', '#000') === '#000', 'url() is refused — a preview never fetches')
+ok(cssColor('#'.repeat(64), '#000') === '#000', 'an absurdly long colour is refused')
+ok(cssColor(42, '#000') === '#000', 'a non-string colour is refused')
+
+const poisoned = markup(wb([simple()], {
+ theme: {
+ background: 'url(https://evil.example/beacon)',
+ color: '#111',
+ accent: '#fff}body{display:none;background:url(https://evil.example/b)',
+ fontFamily: 'x',
+ },
+}))
+ok(!poisoned.includes('display:none'), 'an injected declaration never reaches the stylesheet')
+ok(!poisoned.includes('evil.example'), 'no external URL reaches the stylesheet')
+ok(poisoned.includes('#111'), 'a legitimate theme colour in the same document still applies')
+
+// --- 4. numbers nobody computed ---------------------------------------------
+
+console.log('\nnumbers nobody computed')
+
+const withFormula = (rows: number): Sheet => ({
+ id: 'sh1', name: 'Model', kind: 'table',
+ rids: [[1, rows]],
+ columns: [
+ { id: 'value', name: 'Value', type: 'number' },
+ { id: 'dbl', name: 'Doubled', type: 'number', formula: 'value * 2' },
+ ],
+ // Only the first rows carry data; a huge sheet is faked by its rid runs,
+ // which is what every row count in the app reads.
+ //
+ // The numbers are chosen so that no stored value, no doubled value and no
+ // total collide. They did once — 111 doubled is 222, which is also the second
+ // stored value — and "a stored value is drawn" passed against an
+ // implementation that drew no stored values at all.
+ data: { value: { enc: 'raw', v: [111, 205, 337] } },
+ steps: [],
+})
+
+const small = markup(wb([withFormula(3)]))
+ok(small.includes('>205<'), 'a stored value is drawn')
+ok(small.includes('>410<'), 'a formula column IS computed when the sheet is small enough to be free')
+// Assert on the CLASS ATTRIBUTE, never the bare class name: every class also
+// appears in the preview's own stylesheet, so `includes('dxp-fx')` is true of
+// any preview at all. Three checks here were vacuous until the rig's negative
+// control showed them passing against an implementation that drew no chip.
+ok(small.includes('class="dxp-fx"'), 'a formula column is marked fx')
+
+const huge = markup(wb([withFormula(250_000)]))
+ok(huge.includes('class="dxp-fx"'), 'a formula column past the recalculation ceiling is still marked fx')
+ok(!huge.includes('>0<'), 'and its cells are EMPTY — never zero, which would be a number, which would be a lie')
+ok(huge.includes('>111<'), 'the stored column beside it is still drawn')
+ok(huge.includes('250,000 rows'), 'the real row count is reported even though only a window is drawn')
+
+const totals = (rows: number): Sheet => ({
+ ...(withFormula(rows) as Record<string, unknown>),
+ totals: { value: 'sum' },
+} as unknown as Sheet)
+
+const totalled = markup(wb([totals(3)]))
+ok(totalled.includes('class="dxp-tot"') && totalled.includes('>653<'),
+ 'a totals row is computed over the whole column')
+
+const bigTotals = markup(wb([totals(250_000)]))
+ok(!bigTotals.includes('class="dxp-tot"'),
+ 'past the scan ceiling the totals row is OMITTED — a partial total is the bug dash exists to refuse')
+
+// --- 5. the byte budget ------------------------------------------------------
+
+console.log('\nbyte budget')
+
+const fat = (): Sheet => ({
+ id: 'sh1', name: 'Wide', kind: 'table',
+ rids: [[1, 400]],
+ columns: Array.from({ length: 60 }, (_, i) => ({
+ id: `c${i}`, name: `A very long column heading number ${i} `.repeat(4), type: 'text' as const, w: 400,
+ })),
+ data: Object.fromEntries(Array.from({ length: 60 }, (_, i) => [
+ `c${i}`,
+ { enc: 'raw' as const, v: Array.from({ length: 400 }, (_, r) => `value ${i}/${r} `.repeat(30)) },
+ ])),
+ steps: [],
+})
+
+const wide = markup(wb([fat()]))
+ok(byteLength(wide) <= PREVIEW_BUDGET,
+ `an adversarially wide workbook fits the budget (${byteLength(wide)} ≤ ${PREVIEW_BUDGET})`)
+
+// The last tier has to be REACHABLE, and bounded by construction: a title is
+// unbounded in the format, so a workbook can defeat every table tier.
+const monstrous = markup(wb([fat()], { title: 'T'.repeat(200_000) }))
+ok(monstrous.includes('class="dxp-card"'), 'a workbook that defeats every tier falls back to the title card')
+ok(byteLength(monstrous) <= PREVIEW_BUDGET,
+ `and the card itself is bounded (${byteLength(monstrous)} ≤ ${PREVIEW_BUDGET})`)
+ok(previewIsSafe(monstrous) === true, 'the card is safe markup too')
+
+const ordinary = markup(wb([simple()]))
+ok(byteLength(ordinary) < 6_000, `an ordinary workbook costs little (${byteLength(ordinary)} bytes)`)
+
+// --- 6. what it draws, and what it must not ---------------------------------
+
+console.log('\nscope')
+
+const two = markup(wb([simple(), {
+ id: 'sh2', name: 'Second', kind: 'table', rids: [[1, 1]],
+ columns: [{ id: 'x', name: 'Secret', type: 'text' }],
+ data: { x: { enc: 'raw', v: ['SENTINEL'] } }, steps: [],
+} as Sheet]))
+ok(two.includes('North'), 'the FIRST sheet is what a workbook opens on, and what it thumbnails as')
+ok(!two.includes('SENTINEL'), 'later sheets are not drawn')
+
+const hiddenCol = markup(wb([{
+ ...(simple() as Record<string, unknown>),
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'value', name: 'Value', type: 'money', hidden: true },
+ ],
+} as unknown as Sheet]))
+ok(!hiddenCol.includes('12,400') && !hiddenCol.includes('£12,400'),
+ 'a hidden column stays hidden — the preview shows what the grid shows')
+
+ok(attempt(() => previewMarkup(wb([]))) === null,
+ 'a workbook with no sheets has no preview rather than an empty frame')
+ok(attempt(() => previewMarkup({ format: FORMAT, version: 1, docId: 'x', title: 'T' } as DashDoc)) === null,
+ 'a document with no sheets array at all does not throw')
+
+const emptySheet = attempt(() => markup(wb([{
+ id: 'e', name: 'Empty', kind: 'table', rids: [], columns: [], data: {}, steps: [],
+} as Sheet])))
+ok(emptySheet !== 'threw' && emptySheet.includes('0 rows'), 'an empty sheet still identifies the workbook')
+
+// A width read straight out of a hand-edited file must not reach the CSS as
+// NaN — that one token takes the whole preview down, in every saved file.
+const badWidth = markup(wb([{
+ ...(simple() as Record<string, unknown>),
+ columns: [{ id: 'region', name: 'Region', type: 'text', w: 'wide' }],
+} as unknown as Sheet]))
+ok(!badWidth.includes('NaN') && !badWidth.includes('Infinity'), 'a nonsense column width falls back')
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-rowcol.ts b/scripts/test-dash-rowcol.ts
new file mode 100644
index 00000000..8b596356
--- /dev/null
+++ b/scripts/test-dash-rowcol.ts
@@ -0,0 +1,672 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash row + column structure rig.
+//
+// node scripts/test-dash-rowcol.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. Structural edits are the operations where a spreadsheet
+// silently changes what a number MEANS, and every failure below looks like a
+// working grid:
+//
+// 1. A RID THAT COMES BACK. Row ids are what hand corrections, notes and
+// (soon) CRDT identity attach to. Mint a fresh row the number of a deleted
+// one and the deleted row's override lands on it — an attributed human
+// correction, with an author and a reason, applied to data nobody checked.
+// 2. A DELETE THAT LEAVES SOMETHING BEHIND. `removeColumn` drops the column
+// and its values and stops; the `"<colId>:<rid>"` overrides survive. Import
+// derives column ids by slugging the header, so the next import of the same
+// CSV re-creates the id and the ghosts attach to fresh data.
+// 3. AN OFF-BY-ONE IN A MOVE. Remove-then-insert lands one short in one
+// direction and exactly right in the other, so the bug only shows when a
+// column is dragged leftwards — or rightwards, depending on which half of
+// the mistake you made.
+// 4. A ROW COUNT THAT DRIFTS FROM A COLUMN. `insertRows` splices `raw` and
+// `dict` columns and skips `pack` entirely, so one packed column shifts
+// every other column by one against it — invisibly, and forever. A column
+// added with too few values is the quieter half: it reads correctly inside
+// this build and is malformed to everything that reads the FILE.
+//
+// So the checks below assert the WRONG answer is refused, not merely that a
+// right one is possible.
+
+import { parseDoc, type Column, type DashDoc, type TableSheet } from '../dash/src/model.ts'
+import { RID_BLOCK, RID_BLOCKS, ridBase, ridBlockFor } from '../dash/src/model.ts'
+import { Store, applyPatch, readCell, _internals as store_, type Patch } from '../dash/src/store.ts'
+import { insertRowsAt, deleteRowsAt, insertColumn, deleteColumn, moveColumn, resizeColumn,
+ autoFitWidth, freezeAt, readFrozen, applySheetProps, hiddenSet, setHidden,
+ _internals, type SetSheetProps, setRidBlock } from '../dash/src/rowcol.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+// --------------------------------------------------------------- fixtures
+
+const fresh = (): DashDoc => {
+ const r = parseDoc(JSON.stringify({
+ format: 'bento/dash', version: 1, policy: 'bento-dash-1',
+ docId: 'd', title: 'test',
+ sheets: [{
+ id: 'sh1', name: 'S', kind: 'table',
+ rids: [[1, 4]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'number' },
+ { id: 'note', name: 'Note', type: 'text' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, 0, 1] },
+ amount: { enc: 'raw', v: [10, 20, 30, 40] },
+ note: { enc: 'raw', v: ['a', 'b', 'c', 'd'] },
+ },
+ // a hand correction on the SECOND row — the thing every check below is
+ // ultimately protecting
+ cells: { 'amount:2': { v: 21, was: 20, by: 'andy', why: 'invoice 4471' } },
+ steps: [{ op: 'import', from: 'q3.csv', at: '2026-08-03T00:00:00Z', rows: 4 }],
+ }],
+ }))
+ if (!r.ok) throw new Error('fixture does not parse')
+ return r.doc
+}
+
+const sheetOf = (d: DashDoc): TableSheet => d.sheets[0] as TableSheet
+
+/**
+ * The document minus `modified`, with keys sorted.
+ *
+ * `modified` legitimately moves — undo IS an edit. Key ORDER is sorted because
+ * it is not document meaning: deleting `cells` and restoring it puts the key
+ * back at the end of the object, and asserting on that would be asserting on
+ * JavaScript's insertion order rather than on the round trip.
+ */
+const canon = (v: unknown): unknown => {
+ if (Array.isArray(v)) return v.map(canon)
+ if (v && typeof v === 'object') {
+ const o = v as Record<string, unknown>
+ const out: Record<string, unknown> = {}
+ for (const k of Object.keys(o).sort()) out[k] = canon(o[k])
+ return out
+ }
+ return v
+}
+const content = (d: DashDoc): string => {
+ const { modified: _m, ...rest } = d
+ return JSON.stringify(canon(rest))
+}
+
+/** every value of one column, in row order */
+const vals = (s: TableSheet, col: string): unknown[] => {
+ const n = s.rids.reduce((a, [, c]) => a + c, 0)
+ return Array.from({ length: n }, (_, i) => readCell(s.data[col], i))
+}
+const ridList = (s: TableSheet): number[] => _internals.ridsInOrder(s)
+const j = (v: unknown): string => JSON.stringify(v)
+
+const throws = (fn: () => unknown): boolean => {
+ try { fn(); return false } catch { return true }
+}
+
+/**
+ * The rid watermark is the one field undo may NOT restore: a rid that has
+ * existed must never be minted again, because overrides, comments and a peer's
+ * CRDT node all assume a rid names one row forever. Comparing it would assert
+ * the opposite of what the format requires, so it is excluded here and checked
+ * directly in the store rig instead. Everything else is compared byte for byte.
+ */
+const noMark = (d: DashDoc): string => {
+ const { modified: _m, ...rest } = d
+ // through `canon`, like `content` — key ORDER changes freely when a delete's
+ // inverse re-inserts a property, and comparing raw JSON would fail on that
+ // rather than on anything anybody could observe.
+ return JSON.stringify(canon(rest), (k, v) => (k === 'nextRid' ? undefined : v))
+}
+
+/** mint → commit → undo → is the document semantically where it started? */
+function roundTrip(name: string, make: (s: TableSheet) => Patch | Patch[]) {
+ const st = new Store(fresh())
+ const before = content(st.doc)
+ const beforeMark = noMark(st.doc)
+ const patches = make(sheetOf(st.doc))
+ st.commit(patches)
+ const changed = content(st.doc) !== before
+ const undone = st.undo()
+ ok(changed, `${name}: the patch actually changed something`)
+ ok(undone && noMark(st.doc) === beforeMark,
+ `${name}: undo restores the document exactly (bar the monotonic rid watermark)`)
+}
+
+// ============================================================ INSERT ROWS
+
+{
+ const st = new Store(fresh())
+ st.commit(insertRowsAt(sheetOf(st.doc), 2, 2))
+ const s = sheetOf(st.doc)
+ ok(j(vals(s, 'amount')) === j([10, 20, null, null, 30, 40]),
+ 'inserting in the MIDDLE opens a gap and shifts nothing above it')
+ ok(j(vals(s, 'region')) === j(['North', 'South', null, null, 'North', 'South']),
+ 'and a dict-encoded column splices with it, not beside it')
+ ok(j(ridList(s)) === j([1, 2, 5, 6, 3, 4]),
+ 'the new rows take fresh rids at the insert POSITION — position and identity are different things')
+ ok(new Set(ridList(s)).size === 6, 'every rid in the sheet is still unique')
+ ok(readCell(s.data.amount, store_.ridIndex(s, 2)) === 20,
+ 'rid 2 still names the value it named before the insert')
+ ok(s.cells?.['amount:2']?.v === 21,
+ "and the override attached to rid 2 still lands on rid 2's row")
+}
+
+// THE ONE THE COMMENT IN rowcol.ts IS ABOUT: a row deleted by some other path
+// (a raw patch, an older build, a merge) leaves its override behind. Minting
+// that rid again would re-apply a stranger's correction to a brand-new row.
+{
+ const st = new Store(fresh())
+ const s0 = sheetOf(st.doc)
+ s0.cells!['amount:9'] = { v: 999, by: 'someone', why: 'a row that was deleted' }
+ const p = insertRowsAt(s0, 4, 1)[0] as Extract<Patch, { op: 'insertRows' }>
+ ok(p.rids[0] === 10,
+ 'a rid is minted above every rid an ORPHANED override still names (9 → 10)')
+ ok(p.rids[0] !== 5,
+ 'and NOT above the live rows alone, which would hand the new row rid 5 and then 9 next time')
+ st.commit([p])
+ ok(sheetOf(st.doc).cells!['amount:9'].v === 999,
+ 'the orphan is left alone — it is evidence, and deleting it here would hide the problem')
+}
+{
+ // the durable path: a stamped water mark wins even when nothing else shows it
+ const st = new Store(fresh())
+ const s = sheetOf(st.doc)
+ s.nextRid = 500
+ ok(_internals.nextRidFloor(s) === 500, 'an explicit nextRid stamp is honoured when the file carries one')
+ s.nextRid = 2
+ ok(_internals.nextRidFloor(s) === 5, 'a stale stamp never LOWERS the floor below the live rows')
+}
+{
+ const st = new Store(fresh())
+ st.commit(insertRowsAt(sheetOf(st.doc), 999, 1))
+ ok(j(vals(sheetOf(st.doc), 'amount')) === j([10, 20, 30, 40, null]),
+ 'a position past the end appends rather than throwing — a drag can run off the sheet')
+ st.commit(insertRowsAt(sheetOf(st.doc), -3, 1))
+ ok(vals(sheetOf(st.doc), 'amount')[0] === null, 'and a negative position clamps to the top')
+}
+{
+ const s = sheetOf(fresh())
+ ok(insertRowsAt(s, 1, 0).length === 0 && insertRowsAt(s, 1, -2).length === 0,
+ 'inserting zero rows produces NO patch — an empty commit is an undo step that does nothing visible')
+}
+{
+ const st = new Store(fresh())
+ const s = sheetOf(st.doc)
+ s.data.packed = { enc: 'pack', b64: 'AAAA', n: 4 }
+ ok(throws(() => insertRowsAt(s, 1, 1)),
+ 'inserting a row into a sheet with a PACKED column is refused, not silently misaligned')
+ ok(throws(() => deleteRowsAt(s, 1, 1)), 'and so is deleting one')
+}
+
+roundTrip('insertRowsAt', (s) => insertRowsAt(s, 2, 3))
+
+// ============================================================ DELETE ROWS
+
+{
+ const st = new Store(fresh())
+ st.commit(deleteRowsAt(sheetOf(st.doc), 1, 2))
+ const s = sheetOf(st.doc)
+ ok(j(vals(s, 'amount')) === j([10, 40]), 'deleteRowsAt removes the rows at the positions asked for')
+ ok(j(ridList(s)) === j([1, 4]), 'and the surviving rows keep their own rids')
+ ok(s.cells === undefined,
+ 'the override attached to a deleted row goes with it, and the empty container goes too')
+}
+{
+ // The same delete through the RAW patch. This check has flipped: it used to
+ // assert that a bare `deleteRows` stranded the override — the ghost
+ // `deleteRowsAt` existed to sweep up — and that stranding was a real
+ // divergence, because `insertRows`' own inverse is a bare `deleteRows`, so
+ // undoing an insert took the raw path and left the orphan behind on the
+ // undoing replica only. applyPatch takes the overrides with the row now, and
+ // hands them to the inverse, so both routes agree.
+ const st = new Store(fresh())
+ st.commit({ op: 'deleteRows', sheet: 'sh1', rids: [2, 3] })
+ ok(sheetOf(st.doc).cells?.['amount:2'] === undefined,
+ 'a bare deleteRows patch takes the override with it too — both routes agree now')
+ st.undo()
+ ok(sheetOf(st.doc).cells?.['amount:2']?.v === 21,
+ 'and undoing it brings the override back, not just the values')
+}
+{
+ const st = new Store(fresh())
+ const before = vals(sheetOf(st.doc), 'amount')
+ st.commit(deleteRowsAt(sheetOf(st.doc), 1, 2))
+ st.undo()
+ const s = sheetOf(st.doc)
+ ok(j(vals(s, 'amount')) === j(before), 'undoing a delete brings the VALUES back, not empty rows')
+ ok(s.cells?.['amount:2']?.v === 21 && s.cells?.['amount:2']?.why === 'invoice 4471',
+ 'and brings the hand correction back with its author and its reason')
+}
+{
+ const st = new Store(fresh())
+ st.commit(deleteRowsAt(sheetOf(st.doc), 3, 99))
+ ok(j(vals(sheetOf(st.doc), 'amount')) === j([10, 20, 30]),
+ 'a count past the end deletes what exists rather than throwing')
+ const s = sheetOf(st.doc)
+ ok(deleteRowsAt(s, 9, 1).length === 0, 'and a start past the end deletes nothing at all')
+}
+
+roundTrip('deleteRowsAt', (s) => deleteRowsAt(s, 0, 2))
+
+// =========================================================== INSERT COLUMN
+
+{
+ const st = new Store(fresh())
+ const qty: Column = { id: 'qty', name: 'Qty', type: 'number' }
+ st.commit(insertColumn(sheetOf(st.doc), 1, qty, { enc: 'raw', v: [1, 2, 3, 4] }))
+ const s = sheetOf(st.doc)
+ ok(s.columns[1].id === 'qty', 'insertColumn lands at the index asked for')
+ ok(j(vals(s, 'qty')) === j([1, 2, 3, 4]), 'and its data comes with it')
+}
+{
+ // A short `raw` column READS like a padded one (readCell answers `?? null`
+ // past the end), so the check has to be on the stored LENGTH — which is what
+ // every other reader of the file sees.
+ const st = new Store(fresh())
+ st.commit(insertColumn(sheetOf(st.doc), 0, { id: 'short', name: 'Short', type: 'text' },
+ { enc: 'raw', v: ['x', 'y'] }))
+ const len = (s: TableSheet, c: string): number => {
+ const d = s.data[c]
+ return d.enc === 'raw' ? d.v.length : d.enc === 'dict' ? d.idx.length : d.n
+ }
+ ok(len(sheetOf(st.doc), 'short') === 4,
+ 'a short column is PADDED to the row count — 2 values on a 4-row sheet is a malformed file')
+ ok(j(vals(sheetOf(st.doc), 'short')) === j(['x', 'y', null, null]), 'and the values it had are where it had them')
+ st.commit(insertRowsAt(sheetOf(st.doc), 0, 1))
+ const s = sheetOf(st.doc)
+ ok([...s.columns].every((c) => len(s, c.id) === 5),
+ 'so every column still stores exactly one value per row after a later insert — including the padded one')
+}
+{
+ const s = sheetOf(fresh())
+ ok(throws(() => insertColumn(s, 0, { id: 'amount', name: 'Dup', type: 'number' })),
+ 'a duplicate column id is REFUSED — two columns sharing one data key is silent overwriting')
+ ok(throws(() => insertColumn(s, 0, { id: 'f', name: 'F', type: 'number', formula: 'amount*2' },
+ { enc: 'raw', v: [1, 2, 3, 4] })),
+ 'a formula column may not also carry stored values — the file could then disagree with itself')
+ ok(throws(() => insertColumn(s, 0, { id: 'long', name: 'L', type: 'number' },
+ { enc: 'raw', v: [1, 2, 3, 4, 5] })),
+ 'data LONGER than the sheet is refused rather than trimmed to an arbitrary prefix')
+ ok(insertColumn(s, 0, { id: 'f2', name: 'F', type: 'number', formula: 'amount*2' }).length === 1,
+ 'a formula column with no data is fine')
+ const at = insertColumn(s, 99, { id: 'z', name: 'Z', type: 'text' })[0] as Extract<Patch, { op: 'addColumn' }>
+ ok(at.at === 3, 'an index past the end appends')
+}
+
+roundTrip('insertColumn', (s) => insertColumn(s, 1, { id: 'qty', name: 'Qty', type: 'number' },
+ { enc: 'raw', v: [1, 2, 3, 4] }))
+
+// =========================================================== DELETE COLUMN
+
+{
+ const st = new Store(fresh())
+ st.commit(deleteColumn(sheetOf(st.doc), 'amount'))
+ const s = sheetOf(st.doc)
+ ok(s.columns.length === 2 && !s.columns.some((c) => c.id === 'amount'), 'deleteColumn removes the column')
+ ok(!('amount' in s.data), 'and its data goes with it')
+ ok(!Object.keys(s.cells ?? {}).some((k) => k.startsWith('amount:')),
+ 'and every override keyed to it goes with it — the bug class this helper exists for')
+}
+{
+ const st = new Store(fresh())
+ st.commit({ op: 'removeColumn', sheet: 'sh1', col: 'amount' })
+ ok(sheetOf(st.doc).cells?.['amount:2']?.v === 21,
+ 'a bare removeColumn leaves the override orphaned — so this check can fail, and once did')
+}
+{
+ // THE RESURRECTION. Column ids are slugged from the CSV header, so the next
+ // import of the same file re-creates the id exactly.
+ const raw = new Store(fresh())
+ raw.commit({ op: 'removeColumn', sheet: 'sh1', col: 'amount' })
+ raw.commit({ op: 'addColumn', sheet: 'sh1', column: { id: 'amount', name: 'Amount', type: 'number' },
+ data: { enc: 'raw', v: [7, 7, 7, 7] } })
+ ok(sheetOf(raw.doc).cells?.['amount:2']?.v === 21,
+ "re-importing after a bare delete re-applies a stranger's correction to fresh data (21 over 7)")
+
+ const st = new Store(fresh())
+ st.commit(deleteColumn(sheetOf(st.doc), 'amount'))
+ st.commit(insertColumn(sheetOf(st.doc), 1, { id: 'amount', name: 'Amount', type: 'number' },
+ { enc: 'raw', v: [7, 7, 7, 7] }))
+ ok(sheetOf(st.doc).cells?.['amount:2'] === undefined,
+ 'through deleteColumn there is nothing left to resurrect')
+}
+{
+ const s = sheetOf(fresh())
+ ok(throws(() => deleteColumn(s, 'nope')), 'deleting a column that is not there is refused')
+}
+
+roundTrip('deleteColumn', (s) => deleteColumn(s, 'amount'))
+
+// ============================================================= MOVE COLUMN
+// columns start as [region, amount, note]
+
+const order = (s: TableSheet): string[] => s.columns.map((c) => c.id)
+
+{
+ const st = new Store(fresh())
+ st.commit(moveColumn(sheetOf(st.doc), 'region', 2)) // leftmost, rightwards
+ const got = order(sheetOf(st.doc))
+ ok(got.indexOf('region') === 2, 'moving RIGHT lands at the requested index')
+ ok(j(got) === j(['amount', 'note', 'region']), 'and the others close the gap in order')
+ ok(j(got) !== j(['amount', 'region', 'note']),
+ 'not one short of it — the remove-then-insert off-by-one, which only shows in this direction')
+}
+{
+ const st = new Store(fresh())
+ st.commit(moveColumn(sheetOf(st.doc), 'note', 0)) // rightmost, leftwards
+ const got = order(sheetOf(st.doc))
+ ok(got.indexOf('note') === 0, 'moving LEFT lands at the requested index too')
+ ok(j(got) === j(['note', 'region', 'amount']), 'and it means the same index in both directions')
+}
+{
+ const st = new Store(fresh())
+ st.commit(moveColumn(sheetOf(st.doc), 'region', 1))
+ ok(j(order(sheetOf(st.doc))) === j(['amount', 'region', 'note']), 'a one-step move right')
+ st.commit(moveColumn(sheetOf(st.doc), 'region', 0))
+ ok(j(order(sheetOf(st.doc))) === j(['region', 'amount', 'note']), 'and back again — the move is its own inverse')
+}
+{
+ const s = sheetOf(fresh())
+ const p = moveColumn(s, 'region', 99)[0] as Extract<Patch, { op: 'reorderColumns' }>
+ ok(p.order.length === 3 && new Set(p.order).size === 3,
+ 'the emitted order is a FULL permutation: reorderColumns DELETES any column an order omits')
+ ok(p.order.indexOf('region') === 2, 'an index past the end lands at the last position')
+ // `splice` truncates a fractional index by itself, so the clamp earns its
+ // keep at the NO-OP test: 1.7 against a column already at index 1 has to
+ // compare equal, or the move commits an undo step that reorders nothing.
+ ok(moveColumn(s, 'amount', 1.7).length === 0 && moveColumn(s, 'region', NaN).length === 0,
+ 'a fractional or non-finite index resolves BEFORE the "already there" test')
+ ok(moveColumn(s, 'region', 0).length === 0, 'moving a column where it already is produces no patch')
+ ok(throws(() => moveColumn(s, 'nope', 0)), 'moving a column that is not there is refused')
+}
+{
+ // A frozen document is never id-repaired (it declares rules this build does
+ // not have, so it round-trips byte-exact) — duplicate column ids therefore
+ // reach this code, and removing "the column with this id" by FILTER would
+ // remove both of them.
+ const r = parseDoc(JSON.stringify({
+ format: 'bento/dash', version: 1, policy: 'bento-dash-99', docId: 'd', title: 't',
+ sheets: [{
+ id: 'sh1', name: 'S', kind: 'table', rids: [[1, 1]],
+ columns: [{ id: 'dup', name: 'A', type: 'text' }, { id: 'dup', name: 'B', type: 'text' },
+ { id: 'note', name: 'N', type: 'text' }],
+ data: {}, steps: [],
+ }],
+ }))
+ const frozen = r.ok ? sheetOf(r.doc) : sheetOf(fresh())
+ ok(r.ok && r.frozen === 'policy' && frozen.columns.length === 3,
+ 'a frozen document keeps its duplicate column ids, unrepaired')
+ const p = moveColumn(frozen, 'dup', 2)[0] as Extract<Patch, { op: 'reorderColumns' }>
+ ok(p.order.length === 3 && p.order.filter((i) => i === 'dup').length === 2,
+ 'and moving one of them moves ONE — a filter by id would drop the twin and its data with it')
+}
+{
+ // why the permutation matters, demonstrated against the store itself
+ const st = new Store(fresh())
+ st.commit({ op: 'reorderColumns', sheet: 'sh1', order: ['region'] })
+ const lost = order(sheetOf(st.doc)).length === 1
+ st.undo()
+ ok(lost && order(sheetOf(st.doc)).length === 1,
+ 'a PARTIAL order drops columns and undo cannot bring them back — moveColumn never emits one')
+}
+
+roundTrip('moveColumn', (s) => moveColumn(s, 'region', 2))
+
+// =========================================================== RESIZE COLUMN
+
+{
+ const s = sheetOf(fresh())
+ const w = (px: number) => (resizeColumn(s, 'amount', px) as Extract<Patch, { op: 'setColumn' }>).patch.w
+ ok(w(10) === _internals.MIN_W, 'a width below the minimum clamps rather than throwing mid-drag')
+ ok(w(9999) === _internals.MAX_W, 'and above the maximum')
+ ok(w(130.6) === 131, 'widths are integers — fractional px bloat the JSON and never render differently')
+ ok(Number.isFinite(w(NaN) as number),
+ 'a NaN from a drag computation clamps: JSON.stringify(NaN) is null, and width:nullpx renders nothing')
+ ok(throws(() => resizeColumn(s, 'nope', 100)), 'resizing a column that is not there is refused')
+}
+
+roundTrip('resizeColumn', (s) => resizeColumn(s, 'amount', 240))
+
+// ============================================================== AUTO-FIT
+
+const col = (over: Partial<Column>): Column =>
+ ({ id: 'c', name: 'C', type: 'text', ...over } as Column)
+const from = (v: unknown[]) => (row: number) => v[row]
+
+{
+ const short = autoFitWidth(from(['a', 'b']), col({}), 2)
+ const long = autoFitWidth(from(['a', 'antidisestablishmentarianism']), col({}), 2)
+ ok(long > short, 'a column with longer content fits wider')
+ ok(Number.isInteger(long) && long >= _internals.MIN_W, 'the answer is a whole number of px, never below the minimum')
+ ok(autoFitWidth(from(['x'.repeat(400)]), col({}), 1) === _internals.MAX_W, 'and never above the maximum')
+ ok(autoFitWidth(from(['x'.repeat(400)]), col({}), 1, { max: 200 }) === 200, 'opts.max caps it')
+}
+{
+ // the header is a floor: a wide name with empty cells must still show
+ const wide = autoFitWidth(from([]), col({ name: 'Gross margin before rebates' }), 0)
+ const narrow = autoFitWidth(from([]), col({ name: 'A' }), 0)
+ ok(wide > narrow + 100, 'a long column NAME widens the column even when every cell is empty')
+ // Digits are wider than lowercase in the grid's font, which is the whole
+ // reason for the per-type weight table. The numbers are literal on purpose:
+ // asserting against CHAR_W would read the same constant the code reads and
+ // pass whatever it said. 8 chars x 7.2 + 20 padding = 78; x 8.0 = 84.
+ ok(autoFitWidth(from(['12345678']), col({ name: 'A', type: 'text' }), 1) === 78,
+ 'eight characters of text get a lowercase weight')
+ ok(autoFitWidth(from([12345678]), col({ name: 'A', type: 'number', format: '0' }), 1) === 84,
+ 'and eight DIGITS get a wider one — a clipped digit is a wrong number')
+ ok(autoFitWidth(from([12345678]), col({ name: 'A', type: 'number' }), 1) === 100,
+ 'while the same number GROUPED is ten glyphs, not eight — the separators need room too')
+}
+{
+ // FORMATTED, not raw: the reader sees the formatted string and that is what
+ // has to fit. 1234.5 is 6 characters; "$1,234.50" is 9.
+ const money = col({ name: 'Amt', type: 'money', format: '$#,##0.00' })
+ const fitted = autoFitWidth(from([1234.5]), money, 1)
+ ok(fitted === 92, 'auto-fit measures the FORMATTED value ($1,234.50), not the stored number')
+ ok(fitted !== 88, 'a String(v) implementation gets 6 characters, falls under the header floor, and clips')
+}
+{
+ // stride sampling, spread across the column rather than taken off the top
+ const many: unknown[] = Array.from({ length: 5000 }, () => 'ab')
+ const flat = autoFitWidth(from(many), col({ name: 'A' }), 5000)
+ many[4999] = 'a very long value that only appears in the last row of the file'
+ const tail = autoFitWidth(from(many), col({ name: 'A' }), 5000)
+ ok(tail > flat,
+ 'the last row is always read — a CSV sorted by name keeps its longest value at the end')
+ many[4999] = 'ab'
+ many[2500] = 'a value in the middle that a first-500 sample would miss entirely'
+ ok(autoFitWidth(from(many), col({ name: 'A' }), 5000) > flat,
+ 'and the sample is spread by stride, not taken off the top')
+}
+
+// ================================================================= FREEZE
+
+{
+ const s = sheetOf(fresh())
+ const before = JSON.stringify(canon(s))
+ const p = freezeAt(s, 1, 1) as SetSheetProps
+ ok(p.op === 'setSheetProps' && p.sheet === 'sh1', 'freezeAt names the sheet it applies to')
+ ok(readFrozen(s).rows === 0, 'and mints WITHOUT touching the sheet — every helper here is a factory')
+
+ const { inverse } = applySheetProps(s, p)
+ ok(j(readFrozen(s)) === j({ rows: 1, cols: 1 }), 'applying it freezes one row and one column')
+ applySheetProps(s, inverse)
+ ok(JSON.stringify(canon(s)) === before,
+ 'and the inverse removes the KEY, not just its value — a first freeze must undo to no field at all')
+ ok(!('frozen' in s), 'so the sheet is exactly as it was found')
+}
+{
+ const s = sheetOf(fresh()) // 4 rows, 3 columns
+ applySheetProps(s, freezeAt(s, 1e9, 1e9) as SetSheetProps)
+ ok(j(readFrozen(s)) === j({ rows: 3, cols: 2 }),
+ 'freezing more than exists clamps to leave something to scroll')
+ ok(j(readFrozen(s)) !== j({ rows: 4, cols: 3 }),
+ 'and NOT to the full sheet, which would render a grid that cannot move')
+ applySheetProps(s, freezeAt(s, -5, 0) as SetSheetProps)
+ ok(!('frozen' in s), 'freezing nothing DROPS the field rather than storing zeroes')
+}
+{
+ const s = sheetOf(fresh())
+ ok(j(readFrozen(s)) === j({ rows: 0, cols: 0 }), 'an unfrozen sheet reads as zero/zero')
+ s.frozen = 3
+ ok(j(readFrozen(s)) === j({ rows: 0, cols: 0 }), 'junk in an additive field reads as NOT frozen')
+ s.frozen = { rows: 'two', cols: -1 }
+ ok(j(readFrozen(s)) === j({ rows: 0, cols: 0 }), 'and so does a half-written one')
+ s.frozen = { rows: 2.7, cols: 1 }
+ ok(j(readFrozen(s)) === j({ rows: 2, cols: 1 }), 'a fractional count floors — you cannot freeze 0.7 of a row')
+}
+{
+ const s = sheetOf(fresh())
+ ok(throws(() => applySheetProps(s, { op: 'setSheetProps', sheet: 'sh1', props: { data: {} } })),
+ 'setSheetProps refuses to write `data` — structure moves through patches that can invert it')
+ ok(throws(() => applySheetProps(s, { op: 'setSheetProps', sheet: 'sh1', props: {}, drop: ['rids'] })),
+ 'and refuses to drop `rids`')
+ ok(throws(() => applySheetProps(s, { op: 'setSheetProps', sheet: 'sh1', props: { frozen: 1 }, drop: ['frozen'] })),
+ 'and refuses to set and drop one key in the same patch')
+ ok(j(vals(s, 'amount')) === j([10, 20, 30, 40]), 'a refused props patch changed nothing on the way out')
+}
+{
+ // the round trip that matters for a field that already exists
+ const s = sheetOf(fresh())
+ applySheetProps(s, freezeAt(s, 2, 1) as SetSheetProps)
+ const mid = JSON.stringify(canon(s))
+ const { inverse } = applySheetProps(s, freezeAt(s, 1, 0) as SetSheetProps)
+ ok(j(readFrozen(s)) === j({ rows: 1, cols: 0 }), 'a second freeze replaces the first')
+ applySheetProps(s, inverse)
+ ok(JSON.stringify(canon(s)) === mid, 'and its inverse restores the previous freeze, not the absence of one')
+}
+
+// ================================================================= HIDDEN
+
+{
+ const st = new Store(fresh())
+ ok(hiddenSet(sheetOf(st.doc)).size === 0, 'nothing is hidden in a fresh sheet')
+ st.commit(setHidden(sheetOf(st.doc), 'note', true))
+ const s = sheetOf(st.doc)
+ ok(hiddenSet(s).has('note') && hiddenSet(s).size === 1, 'setHidden hides exactly one column, by id')
+ ok(s.columns.length === 3 && j(vals(s, 'note')) === j(['a', 'b', 'c', 'd']),
+ 'hiding is a view flag on the column — the data is still there')
+
+ st.commit(setHidden(sheetOf(st.doc), 'note', false))
+ ok(hiddenSet(sheetOf(st.doc)).size === 0, 'and showing it again unhides it')
+ // The original assertion here was that showing a column leaves NO `hidden`
+ // key, achieved by patching `{hidden: undefined}`. That is tidier in the
+ // file and WRONG on the wire: JSON.stringify drops an undefined value, so
+ // the patch arrives as `{}` and the un-hide silently does nothing — for a
+ // collaborator, for the agent API, for anything that serializes a patch.
+ // A dead `"hidden": false` costs 16 bytes on a column somebody has touched.
+ // An un-hide that does not travel costs the user their action.
+ ok(JSON.parse(JSON.stringify(setHidden(sheetOf(st.doc), 'note', false))).patch.hidden === false,
+ 'the un-hide SURVIVES a JSON round trip — `undefined` would arrive as an empty patch and do nothing')
+}
+{
+ const s = sheetOf(fresh())
+ s.columns[0].hidden = 1
+ ok(!hiddenSet(s).has('region'),
+ 'a foreign truthy value is not hidden: a column that shows is recoverable, a column that vanishes is not')
+ ok(throws(() => setHidden(s, 'nope', true)), 'hiding a column that is not there is refused')
+}
+
+roundTrip('setHidden', (s) => setHidden(s, 'note', true))
+
+// ================================================== the patches still apply
+// Everything above goes through Store.commit, which is applyPatch — but the
+// helpers claim to be pure factories, so check that too.
+{
+ const s = sheetOf(fresh())
+ const before = j(s.columns.map((c) => c.id))
+ const minted: (Patch | Patch[])[] = [
+ insertRowsAt(s, 1, 2), deleteRowsAt(s, 0, 1), insertColumn(s, 0, { id: 'n', name: 'N', type: 'text' }),
+ deleteColumn(s, 'note'), moveColumn(s, 'region', 2), resizeColumn(s, 'amount', 200),
+ setHidden(s, 'note', true),
+ ]
+ ok(minted.length === 7 && j(s.columns.map((c) => c.id)) === before && j(vals(s, 'amount')) === j([10, 20, 30, 40]),
+ 'minting seven patches from one sheet mutates nothing — they are factories, not edits')
+}
+{
+ // and a patch built from a stale read still applies cleanly to a live doc
+ const st = new Store(fresh())
+ const patches: Patch[] = [
+ ...insertColumn(sheetOf(st.doc), 3, { id: 'qty', name: 'Qty', type: 'number' }, { enc: 'raw', v: [1, 2, 3, 4] }),
+ ]
+ const r = applyPatch(st.doc, patches[0])
+ ok(r.touched.structural === true && r.touched.cols?.includes('qty') === true,
+ 'the store reports a structural invalidation naming the column, so the grid relayouts instead of repainting')
+}
+
+// RID PARTITIONING — the correctness precondition collaboration rests on.
+//
+// The watermark stops a rid being REUSED after a delete. It cannot touch the
+// concurrent case: two people insert at the same moment, both compute "one past
+// the highest I know about", and both get the same number. rid is IDENTITY — the
+// CRDT keys a row node on it — so two different rows sharing one merge into a
+// single row and one of them is silently lost.
+{
+ const A = 'actor-aaaa'
+ const B = 'actor-bbbb'
+ ok(ridBlockFor(A) !== ridBlockFor(B), 'two actors derive different rid blocks')
+ ok(ridBlockFor(A) === ridBlockFor(A), 'and the derivation is deterministic')
+ ok(ridBlockFor(A) > 0 && ridBlockFor(B) > 0,
+ 'never block 0, which is reserved for solo documents')
+ ok(ridBase(0) === 1, 'so an unshared workbook still numbers its rows from 1')
+ ok(ridBase(RID_BLOCKS - 1) + RID_BLOCK - 1 <= Number.MAX_SAFE_INTEGER,
+ 'and the very top block still lands inside exact integer arithmetic')
+
+ /** Mint `n` rows as `actor`, from the same starting document. */
+ const mintAs = (actor: string | null, n: number): number[] => {
+ setRidBlock(actor === null ? null : ridBase(ridBlockFor(actor)))
+ const st = new Store(fresh())
+ const out: number[] = []
+ for (let i = 0; i < n; i++) {
+ const p = insertRowsAt(sheetOf(st.doc), 0, 1) as Patch[]
+ st.commit(p)
+ out.push((p[0] as { rids: number[] }).rids[0])
+ }
+ setRidBlock(null)
+ return out
+ }
+
+ // THE CASE THAT MATTERS: both replicas start from the SAME document and both
+ // insert. Without partitioning they mint the identical numbers.
+ const fromA = mintAs(A, 25)
+ const fromB = mintAs(B, 25)
+ const clash = fromA.filter((r) => fromB.includes(r))
+ ok(clash.length === 0,
+ `two replicas inserting concurrently from the same document share NO rid (${clash.length} collisions)`)
+ ok(new Set(fromA).size === fromA.length, 'and one replica never repeats itself')
+
+ // reuse after a delete, INSIDE a block — the watermark cannot help here,
+ // because it is a maximum across every actor and would push this replica out
+ // of its own block entirely
+ setRidBlock(ridBase(ridBlockFor(A)))
+ {
+ const st = new Store(fresh())
+ const seen: number[] = []
+ for (let i = 0; i < 6; i++) {
+ const p = insertRowsAt(sheetOf(st.doc), 0, 1) as Patch[]
+ st.commit(p)
+ const rid = (p[0] as { rids: number[] }).rids[0]
+ seen.push(rid)
+ st.commit(deleteRowsAt(sheetOf(st.doc), 0, 1)) // delete it again at once
+ }
+ ok(new Set(seen).size === seen.length,
+ 'a rid deleted inside a block is never minted again in that session')
+ }
+ setRidBlock(null)
+
+ // and the solo path is byte-for-byte what it always was
+ const solo = mintAs(null, 3)
+ ok(JSON.stringify(solo) === JSON.stringify([5, 6, 7]),
+ `a solo document still mints small consecutive rids (${solo.join(',')})`)
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-select.ts b/scripts/test-dash-select.ts
new file mode 100644
index 00000000..d1f6b863
--- /dev/null
+++ b/scripts/test-dash-select.ts
@@ -0,0 +1,455 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash selection + keyboard rig.
+//
+// node scripts/test-dash-select.ts
+//
+// WHAT THIS PROVES. Selection is the only part of a grid that is judged by
+// FEEL, and feel is not a thing you can eyeball once and call done — every one
+// of these behaviours is invisible when it is right and infuriating when it is
+// wrong, in a way users report as "it's weird" rather than as a bug. So the
+// motor memory gets written down as assertions:
+//
+// 1. TAB AND ENTER ARE A PAIR. Tab across a row, Enter, and you land under
+// where the run STARTED. An implementation that moves Enter down from
+// wherever Tab left off walks the user diagonally across their own table,
+// and it looks plausible in every single-cell test.
+// 2. TAB MEANS TWO DIFFERENT THINGS. Inside a selected block it walks the
+// active cell and wraps, and the block must not move. On a single cell it
+// moves plainly. One implementation for both is always wrong for one.
+// 3. ⌘↓ IS BOUNDED AND HAS THREE CASES. Run to the end of a block, cross the
+// blanks to the next one, stop at the sheet's last row. "Walk until blank"
+// passes the first case and never moves from an empty cell.
+// 4. THE CLIPBOARD ROUND-TRIPS. A cell holding a tab, a newline or a quote is
+// the whole reason TSV has quoting; a naive split() loses the row count and
+// the paste lands shifted, silently.
+// 5. FILL READS A SERIES OR ADMITS IT CANNOT. 1,2,3 continues 4,5,6; "a","b"
+// repeats. Continuing a non-series invents data, and repeating a series is
+// the thing people notice within one second of dragging.
+
+import { readFileSync } from 'node:fs'
+import {
+ Selection, normalize, contains, size, rangeOf, keyToAction, applyMotion,
+ tsvFromRange, parseTsv, fillDown, fillSeries,
+ type Action, type CellRef,
+} from '../dash/src/select.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+const j = (v: unknown): string => JSON.stringify(v)
+function eq(got: unknown, want: unknown, msg: string) {
+ const same = j(got) === j(want)
+ ok(same, same ? msg : `${msg} — got ${j(got)}, wanted ${j(want)}`)
+}
+const at = (s: Selection): [number, number] => [s.cursor.row, s.cursor.col]
+
+// ------------------------------------------------------------------ ranges
+{
+ const r = rangeOf(1, 2, 4, 5)
+ eq(normalize(r), { top: 1, left: 2, bottom: 4, right: 5 }, 'normalize of a forward range')
+ // a range dragged up-and-left has its head BEFORE its anchor
+ const back = { anchor: { row: 4, col: 5 }, head: { row: 1, col: 2 } }
+ eq(normalize(back), { top: 1, left: 2, bottom: 4, right: 5 },
+ 'normalize of a BACKWARDS range gives the same box — anchor and head are not min and max')
+ eq(size(r), { rows: 4, cols: 4 }, 'size counts both endpoints')
+ ok(contains(r, 1, 2) && contains(r, 4, 5) && contains(r, 3, 3), 'contains includes the corners')
+ ok(!contains(r, 0, 2) && !contains(r, 1, 6), 'and excludes what is outside')
+ ok(!contains(r, 4, 1), 'a cell on the right row but the wrong column is NOT contained')
+}
+
+// -------------------------------------------------------------- key mapping
+{
+ const a = (key: string, mods: Partial<Record<'shiftKey' | 'metaKey' | 'ctrlKey' | 'altKey', boolean>> = {}) =>
+ keyToAction({ key, ...mods })
+
+ eq(a('ArrowDown'), { kind: 'move', dr: 1, dc: 0, unit: 'cell', extend: false }, 'ArrowDown moves one cell')
+ eq(a('ArrowRight', { shiftKey: true }), { kind: 'move', dr: 0, dc: 1, unit: 'cell', extend: true },
+ 'shift+Arrow EXTENDS')
+ eq(a('ArrowDown', { metaKey: true }), { kind: 'move', dr: 1, dc: 0, unit: 'edge', extend: false },
+ '⌘Arrow jumps to the edge of the data')
+ eq(a('ArrowDown', { ctrlKey: true }), { kind: 'move', dr: 1, dc: 0, unit: 'edge', extend: false },
+ 'ctrl+Arrow is the same jump — one binding for both platforms')
+ eq(a('ArrowDown', { metaKey: true, shiftKey: true }), { kind: 'move', dr: 1, dc: 0, unit: 'edge', extend: true },
+ '⌘⇧Arrow jumps AND extends')
+ // the wrong answer: a modifier we do not own must not become the bare key
+ ok(a('ArrowDown', { altKey: true }) === null,
+ 'alt+ArrowDown is NOT a move — alt opens a menu in every spreadsheet, and swallowing it steals the shortcut')
+
+ eq(a('Tab'), { kind: 'tab', back: false }, 'Tab')
+ eq(a('Tab', { shiftKey: true }), { kind: 'tab', back: true }, 'shift+Tab goes back')
+ eq(a('Enter'), { kind: 'enter', back: false }, 'Enter')
+ eq(a('Enter', { shiftKey: true }), { kind: 'enter', back: true }, 'shift+Enter goes up')
+ eq(a('Home'), { kind: 'home', whole: false, extend: false }, 'Home')
+ eq(a('Home', { metaKey: true }), { kind: 'home', whole: true, extend: false }, '⌘Home is the whole sheet')
+ eq(a('End', { shiftKey: true }), { kind: 'end', whole: false, extend: true }, 'shift+End extends to the row end')
+ eq(a('PageDown'), { kind: 'move', dr: 1, dc: 0, unit: 'page', extend: false }, 'PageDown is a page-unit move')
+ eq(a('PageUp'), { kind: 'move', dr: -1, dc: 0, unit: 'page', extend: false }, 'PageUp')
+ eq(a('Escape'), { kind: 'cancel' }, 'Escape')
+ eq(a('Delete'), { kind: 'clear' }, 'Delete clears')
+ eq(a('Backspace'), { kind: 'clear' }, 'Backspace clears too — a Mac keyboard has no Delete key')
+ eq(a('F2'), { kind: 'edit' }, 'F2 edits')
+
+ eq(a('a', { metaKey: true }), { kind: 'selectAll' }, '⌘A selects all')
+ eq(a('c', { metaKey: true }), { kind: 'copy' }, '⌘C')
+ eq(a('x', { metaKey: true }), { kind: 'cut' }, '⌘X')
+ eq(a('v', { metaKey: true }), { kind: 'paste' }, '⌘V')
+ eq(a('z', { metaKey: true }), { kind: 'undo' }, '⌘Z undoes')
+ eq(a('Z', { metaKey: true, shiftKey: true }), { kind: 'redo' },
+ '⌘⇧Z redoes — and the key arrives UPPERCASE, which is why the mapping folds case')
+ eq(a('y', { metaKey: true }), { kind: 'redo' }, '⌘Y redoes (Windows)')
+ eq(a(' ', { shiftKey: true }), { kind: 'selectRow' }, '⇧Space selects the row')
+ eq(a(' ', { ctrlKey: true }), { kind: 'selectCol' }, '^Space selects the column')
+
+ // the wrong answers: unmodified typing must reach the cell, not the shortcut
+ ok(a('a') === null, 'a bare "a" is NOT select-all — it is the user typing')
+ ok(a('z') === null, 'a bare "z" is not undo')
+ ok(a(' ') === null, 'a bare space is not a selection command')
+ ok(a('F5') === null, 'a key this model does not own returns null rather than being swallowed')
+}
+
+// ------------------------------------------------- moving, clamping, extend
+{
+ const s = new Selection(10, 4)
+ eq(at(s), [0, 0], 'a fresh selection sits on the first cell')
+ s.move(1, 1)
+ eq(at(s), [1, 1], 'move is relative')
+ s.move(-5, -5)
+ eq(at(s), [0, 0], 'and clamps at the top-left rather than going negative')
+ s.move(99, 99)
+ eq(at(s), [9, 3], 'and at the bottom-right rather than off the sheet')
+
+ s.moveTo(2, 2)
+ s.extend(1, 1)
+ eq(normalize(s.active), { top: 2, left: 2, bottom: 3, right: 3 }, 'shift+arrow grows the range')
+ eq(at(s), [2, 2], 'and the ACTIVE CELL does not move — only the head does')
+ s.extend(-2, -2)
+ eq(normalize(s.active), { top: 1, left: 1, bottom: 2, right: 2 },
+ 'extending back THROUGH the anchor flips the box rather than collapsing it')
+}
+{
+ // the cursor may never be left outside the highlight
+ const s = new Selection(10, 10)
+ s.moveTo(0, 0)
+ s.extendTo(5, 5)
+ s.tab()
+ eq(at(s), [0, 1], 'Tab inside a range walks the active cell')
+ s.extendTo(0, 0)
+ eq(at(s), [0, 0], 'shrinking the range past the active cell snaps it back to the anchor')
+}
+
+// ------------------------------------------------- Tab: single cell vs range
+{
+ const s = new Selection(6, 3)
+ s.moveTo(1, 0)
+ s.tab()
+ eq(at(s), [1, 1], 'with ONE cell selected, Tab moves plainly right')
+ eq(size(s.active), { rows: 1, cols: 1 }, 'and the selection stays a single cell')
+ s.tab()
+ s.tab()
+ eq(at(s), [1, 2], 'and stops at the last column')
+ ok(!(s.cursor.row === 2), 'a single-cell Tab does NOT wrap to the next row — that is a jump nobody asked for')
+ s.tab(true)
+ eq(at(s), [1, 1], 'shift+Tab goes back')
+}
+{
+ const s = new Selection(8, 6)
+ s.moveTo(1, 1)
+ s.extendTo(3, 3) // a 3×3 block
+ const box = normalize(s.active)
+ s.tab(); s.tab()
+ eq(at(s), [1, 3], 'inside a range, Tab walks to the range edge')
+ s.tab()
+ eq(at(s), [2, 1], 'and WRAPS to the next row of the range — this is how data entry works')
+ ok(!(s.cursor.col === 4), 'it does not walk out of the right-hand side of the block')
+ eq(normalize(s.active), box, 'and the block itself never moved')
+ // round the corner
+ for (let i = 0; i < 6; i++) s.tab()
+ eq(at(s), [1, 1], 'tabbing past the bottom-right corner comes back to the top-left')
+ s.tab(true)
+ eq(at(s), [3, 3], 'shift+Tab from the top-left wraps back round to the bottom-right')
+
+ s.moveTo(1, 1); s.extendTo(3, 3)
+ s.enter(); s.enter()
+ eq(at(s), [3, 1], 'inside a range, Enter walks down it')
+ s.enter()
+ eq(at(s), [1, 2], 'and wraps into the next COLUMN at the bottom')
+}
+
+// ------------------------------------------------------------- the Tab run
+{
+ const s = new Selection(10, 5)
+ s.moveTo(2, 0)
+ s.tab(); s.tab()
+ eq(at(s), [2, 2], 'Tab, Tab across a row')
+ s.enter()
+ eq(at(s), [3, 0], 'Enter returns to the COLUMN THE RUN STARTED IN, one row down')
+ ok(!(s.cursor.col === 2),
+ 'and NOT under the last cell typed — that is the bug that walks a typist diagonally across their table')
+ s.tab()
+ s.enter()
+ eq(at(s), [4, 0], 'the landing cell becomes the new run start, so the next row does the same')
+ s.enter()
+ eq(at(s), [5, 0], 'Enter with no Tab since simply moves down')
+
+ s.moveTo(2, 0)
+ s.tab(); s.tab()
+ s.move(1, 0) // an arrow key
+ s.enter()
+ eq(at(s), [4, 2], 'an arrow key ENDS the run: Enter then moves plainly down from where it is')
+ ok(!(s.cursor.col === 0), 'it does not come home to a run that was abandoned')
+
+ s.moveTo(0, 0)
+ s.enter(true)
+ eq(at(s), [0, 0], 'shift+Enter at the top row stays put rather than clamping into a lie')
+ s.moveTo(3, 1)
+ s.enter(true)
+ eq(at(s), [2, 1], 'shift+Enter moves up')
+}
+
+// ------------------------------------------------------------ the ⌘↓ jump
+{
+ // one column of data: rows 0-4 filled, 5-7 blank, 8-9 filled, 10-11 blank
+ const ROWS = 12
+ const filled = (row: number, col: number): boolean =>
+ col === 0 && ((row >= 0 && row <= 4) || row === 8 || row === 9)
+ const s = new Selection(ROWS, 3)
+ const jump = (row: number, col: number, dr: number, dc = 0): [number, number] => {
+ s.moveTo(row, col)
+ s.move(dr, dc, { jump: true, filled })
+ return at(s)
+ }
+
+ eq(jump(0, 0, 1), [4, 0], '⌘↓ from inside a block lands on the LAST filled cell of the block')
+ ok(!(s.cursor.row === 1), 'it is not a one-cell move')
+ ok(!(s.cursor.row === ROWS - 1), 'and it does not run past the block to the end of the sheet')
+ eq(jump(4, 0, 1), [8, 0], '⌘↓ from the end of a block crosses the blanks to the next block')
+ eq(jump(5, 0, 1), [8, 0], '⌘↓ from a BLANK cell lands on the next filled cell')
+ ok(!(s.cursor.row === 5), 'the naive "walk while filled" never leaves a blank cell; this does')
+ eq(jump(8, 0, 1), [9, 0], '⌘↓ inside the second block runs to its end')
+ eq(jump(9, 0, 1), [ROWS - 1, 0], 'with nothing below, ⌘↓ stops at the last row OF THIS SHEET')
+ ok(s.cursor.row === ROWS - 1,
+ 'the jump lands EXACTLY on this sheet\'s last row — not one past it, and not at some notional Excel row limit')
+ eq(jump(ROWS - 1, 0, 1), [ROWS - 1, 0], '⌘↓ already at the boundary stays put')
+ eq(jump(9, 0, -1), [8, 0], '⌘↑ runs to the near end of the block it is in')
+ eq(jump(6, 0, -1), [4, 0], '⌘↑ from a blank crosses back to the previous block')
+ eq(jump(2, 1, 1), [ROWS - 1, 1], 'an entirely empty column jumps to the sheet boundary')
+
+ s.moveTo(0, 0)
+ s.move(1, 0, { jump: true })
+ eq(at(s), [ROWS - 1, 0], 'a jump with no data probe degenerates to the boundary — bounded, not stuck')
+
+ s.moveTo(0, 0)
+ s.move(1, 0, { jump: true, extend: true, filled })
+ eq(normalize(s.active), { top: 0, left: 0, bottom: 4, right: 0 }, '⌘⇧↓ selects the block')
+ eq(at(s), [0, 0], 'and leaves the active cell at the anchor')
+}
+
+// --------------------------------------------- select all / row / col / add
+{
+ const s = new Selection(5, 4)
+ s.moveTo(2, 2)
+ s.selectAll()
+ eq(normalize(s.active), { top: 0, left: 0, bottom: 4, right: 3 }, '⌘A selects the whole grid')
+ eq(at(s), [2, 2], 'and leaves the active cell where it was')
+
+ s.selectRow(3)
+ eq(normalize(s.active), { top: 3, left: 0, bottom: 3, right: 3 }, 'selectRow spans every column')
+ eq(at(s), [3, 2], 'and the active cell moves onto that ROW, keeping its column')
+ s.selectCol(1)
+ eq(normalize(s.active), { top: 0, left: 1, bottom: 4, right: 1 }, 'selectCol spans every row')
+ eq(at(s), [3, 1], 'and onto that COLUMN, keeping its row — the active cell is never outside the selection')
+
+ s.moveTo(0, 0)
+ s.addRange(rangeOf(2, 2, 3, 3))
+ eq(normalize(s.active), { top: 2, left: 2, bottom: 3, right: 3 },
+ 'a ⌘-clicked range becomes the ACTIVE one — it is what the next shift+arrow must extend')
+ eq(s.extra.length, 1, 'and the previous range is kept alongside')
+ eq(s.bounds(), { top: 0, left: 0, bottom: 3, right: 3 }, 'bounds covers every range')
+}
+{
+ const s = new Selection(5, 5)
+ s.moveTo(0, 0); s.extendTo(1, 1) // 4 cells
+ s.addRange(rangeOf(1, 1, 2, 2)) // 4 cells, overlapping at (1,1)
+ const list = [...s.cells()]
+ eq(list.length, 7, 'cells() yields each cell ONCE across overlapping ranges')
+ ok(!(list.length === 8), 'the shared corner is not counted twice')
+ const key = (c: CellRef) => `${c.row}:${c.col}`
+ ok(new Set(list.map(key)).size === list.length, 'and there are no duplicates in the output')
+
+ const one = new Selection(3, 3)
+ one.moveTo(0, 0); one.extendTo(2, 2)
+ eq([...one.cells()].length, 9, 'a single range yields its whole box')
+ eq(key([...one.cells()][1]), '0:1', 'in row-major order')
+}
+{
+ const s = new Selection(20, 5)
+ s.moveTo(19, 4)
+ s.resize(4, 2)
+ eq(at(s), [3, 1], 'resize pulls a selection that is now off the grid back on to it')
+ eq(normalize(s.active), { top: 3, left: 1, bottom: 3, right: 1 }, 'range included')
+}
+
+// ----------------------------------------------------- key → motion, joined
+{
+ const s = new Selection(30, 5)
+ const filled = (row: number, col: number) => col === 0 && row <= 6
+ const press = (key: string, mods: Record<string, boolean> = {}): boolean => {
+ const a: Action | null = keyToAction({ key, ...mods })
+ return a ? applyMotion(s, a, { page: 10, filled }) : false
+ }
+ s.moveTo(0, 0)
+ press('ArrowDown')
+ eq(at(s), [1, 0], 'a plain ArrowDown, all the way from a key event')
+ press('ArrowDown', { metaKey: true })
+ eq(at(s), [6, 0], 'and ⌘↓ through the same path lands on the end of the block')
+ press('PageDown')
+ eq(at(s), [16, 0], 'PageDown moves by the caller-supplied page size, not by one')
+ press('Home')
+ eq(at(s), [16, 0], 'Home goes to the first column of the row')
+ press('End')
+ eq(at(s), [16, 4], 'End goes to the last column of the row')
+ press('Home', { metaKey: true })
+ eq(at(s), [0, 0], '⌘Home is the first cell of the sheet')
+ press('End', { metaKey: true })
+ eq(at(s), [29, 4], '⌘End is the last cell of the sheet')
+ ok(press('ArrowUp') === true, 'applyMotion reports a motion it handled')
+ ok(press('c', { metaKey: true }) === false,
+ 'and reports FALSE for ⌘C — the clipboard is not a selection operation, and pretending it is loses the copy')
+ ok(press('F5') === false, 'an unmapped key is not consumed')
+}
+
+// ----------------------------------------------------------------- TSV out
+{
+ const g = [['a', 'b'], ['c', 'd']]
+ const text = tsvFromRange((r, c) => g[r][c], rangeOf(0, 0, 1, 1))
+ eq(text, 'a\tb\nc\td', 'a plain block serialises tab-separated, newline-delimited')
+ eq(parseTsv(text), g, 'and parses straight back')
+
+ eq(tsvFromRange(() => null, rangeOf(0, 0, 0, 1)), '\t', 'an empty cell is an empty field, not the word "null"')
+ eq(tsvFromRange((r, c) => (r * 10 + c), rangeOf(1, 1, 2, 2)), '11\t12\n21\t22',
+ 'a range that does not start at the origin serialises its own box')
+}
+
+// ---------------------------------------------------------- TSV round trip
+{
+ const nasty = [
+ ['plain', 'has\ttab'],
+ ['has\nnewline', 'has"quote'],
+ ['', 'a,b'],
+ ]
+ const text = tsvFromRange((r, c) => nasty[r][c], rangeOf(0, 0, 2, 1))
+ eq(parseTsv(text), nasty,
+ 'a cell containing a TAB, a NEWLINE or a QUOTE survives tsvFromRange → parseTsv unchanged')
+ ok(text.includes('"has\ttab"'), 'the tab cell is quoted on the way out')
+ ok(text.includes('"has""quote"'), 'and an embedded quote is doubled')
+ // the assertion that proves the quoting is load-bearing
+ ok(text.split('\n').length !== nasty.length,
+ 'the serialised text has MORE newlines than rows — a naive split() would paste the block shifted')
+
+ eq(parseTsv('a,b'), [['a,b']], 'a comma is data here: TSV is not CSV and there is no delimiter sniffing')
+ eq(parseTsv('5" pipe\tx'), [['5" pipe', 'x']],
+ 'a quote in the MIDDLE of a field is literal — only a leading quote opens a quoted field')
+ eq(parseTsv('"a""b"'), [['a"b']], 'a doubled quote inside a quoted field is one quote')
+ eq(parseTsv('a\r\nb'), [['a'], ['b']], 'CRLF rows (what Excel puts on the clipboard)')
+ eq(parseTsv('"x\r\ny"'), [['x\ny']], 'and a CRLF INSIDE a quoted cell is one line break, not two characters')
+ eq(parseTsv('a\n'), [['a']], 'a trailing newline ends the last row rather than starting an empty one')
+ eq(parseTsv('a\t'), [['a', '']], 'but a trailing TAB is a real trailing empty cell')
+ eq(parseTsv(''), [['']],
+ 'empty text is ONE EMPTY CELL: a copied blank must paste as a blank and clear what it lands on')
+ ok(!(j(parseTsv('')) === j([])),
+ 'returning nothing there would make pasting a blank a silent no-op over a value the user thinks they replaced')
+ eq(parseTsv('a\n\nb'), [['a'], [''], ['b']], 'a blank row inside a paste is a blank row')
+}
+
+// ------------------------------------------------------------------- fills
+{
+ eq(fillDown([1, 2, 3], 6), [1, 2, 3, 1, 2, 3], 'fillDown repeats the seeds')
+ eq(fillDown([1, 2, 3], 2), [1, 2], 'a target shorter than the seeds truncates')
+ eq(fillDown(['x'], 3), ['x', 'x', 'x'], 'one seed repeats')
+ eq(fillDown([], 3), [], 'no seeds, nothing to fill')
+ eq(fillDown([1], 0), [], 'no target, nothing to fill')
+
+ eq(fillSeries([1, 2, 3], 6), [1, 2, 3, 4, 5, 6], 'fillSeries continues an arithmetic progression')
+ eq(fillSeries([1, 2, 3], 6).slice(3), [4, 5, 6], 'fillSeries on [1,2,3] gives 4,5,6')
+ ok(!(j(fillSeries([1, 2, 3], 6)) === j([1, 2, 3, 1, 2, 3])), 'and NOT 1,2,3 repeated')
+ eq(fillSeries([10, 20], 4), [10, 20, 30, 40], 'a step of ten continues by ten')
+ eq(fillSeries([1, 3, 5], 5), [1, 3, 5, 7, 9], 'odd numbers')
+ eq(fillSeries([5, 3, 1], 5), [5, 3, 1, -1, -3], 'a DESCENDING progression keeps descending, through zero')
+ eq(fillSeries([1, 2, 4], 5), [1, 2, 4, 1, 2], 'a non-progression repeats rather than inventing a rule')
+ // THREE seeds, not two: constantStep only compares gaps from the third
+ // element onward, so a two-seed fixture never reaches the tolerance branch
+ // and the check passes against an exact-equality implementation. Mutation
+ // testing proved the two-seed version vacuous.
+ eq(fillSeries([0.1, 0.2, 0.3], 6), [0.1, 0.2, 0.3, 0.4, 0.5, 0.6],
+ 'a decimal progression continues — 0.3-0.2 and 0.2-0.1 are DIFFERENT doubles, so exact equality refuses it')
+ eq(fillSeries([0.8, 0.9], 4), [0.8, 0.9, 1, 1.1],
+ 'and the step is rounded to the SEEDS precision, not the float artefact (0.09999999999999998)')
+ eq(fillSeries(['0.8', '0.9'], 4), ['0.8', '0.9', '1.0', '1.1'],
+ 'a TEXT column of decimals continues numerically — the label path would read "0." + 8 and emit "0.10", which is SMALLER than what it follows')
+ eq(fillSeries([7], 3), [7, 7, 7], 'a LONE number is a constant, not the start of a count')
+ eq(fillSeries([5, 5], 4), [5, 5, 5, 5], 'and a flat run stays flat')
+
+ eq(fillSeries(['a', 'b'], 4), ['a', 'b', 'a', 'b'], 'text with no progression repeats')
+ ok(!(j(fillSeries(['a', 'b'], 4)) === j(['a', 'b', 'c', 'd'])), 'it does not invent an alphabet')
+ eq(fillSeries(['Q1'], 4), ['Q1', 'Q2', 'Q3', 'Q4'], 'a LONE numbered label continues — "Q1" → "Q2"')
+ eq(fillSeries(['Q1', 'Q3'], 4), ['Q1', 'Q3', 'Q5', 'Q7'], 'and honours the step it was given')
+ eq(fillSeries(['Item 01', 'Item 02'], 4), ['Item 01', 'Item 02', 'Item 03', 'Item 04'],
+ 'zero padding is part of the label and is kept')
+ eq(fillSeries(['Q1', 'P2'], 4), ['Q1', 'P2', 'Q1', 'P2'], 'two different labels are not a series')
+ eq(fillSeries(['1', '2'], 4), ['1', '2', '3', '4'], 'numeric TEXT continues as text — a text column stays text')
+ ok(typeof fillSeries(['1', '2'], 4)[3] === 'string', 'and does not quietly become a number')
+
+ eq(fillSeries(['2026-01-01'], 3), ['2026-01-01', '2026-01-02', '2026-01-03'],
+ 'a LONE date continues by a day — the one place a single seed is a series')
+ eq(fillSeries(['2026-01-01', '2026-01-08'], 4),
+ ['2026-01-01', '2026-01-08', '2026-01-15', '2026-01-22'], 'a weekly step')
+ eq(fillSeries(['2026-01-01', '2026-02-01'], 4),
+ ['2026-01-01', '2026-02-01', '2026-03-01', '2026-04-01'], 'a MONTHLY step stays on the first of the month')
+ ok(!(fillSeries(['2026-01-01', '2026-02-01'], 3)[2] === '2026-03-04'),
+ 'a month is not 31 days — reading the gap as days would land on 4 March')
+ eq(fillSeries(['2025-12-31', '2026-01-31'], 3), ['2025-12-31', '2026-01-31', '2026-02-28'],
+ 'a month step CLAMPS to the end of a short month rather than spilling into March')
+ eq(fillSeries(['2026-02-27', '2026-02-28'], 4),
+ ['2026-02-27', '2026-02-28', '2026-03-01', '2026-03-02'], 'a daily step crosses a month boundary')
+ eq(fillSeries(['2026-12-30', '2026-12-31'], 4),
+ ['2026-12-30', '2026-12-31', '2027-01-01', '2027-01-02'], 'and a year boundary')
+ eq(fillSeries(['not-a-date', 'either'], 3), ['not-a-date', 'either', 'not-a-date'], 'text that is not a date repeats')
+
+ eq(fillSeries([1, 'a'], 4), [1, 'a', 1, 'a'], 'mixed types are not a series')
+ eq(fillSeries([true, false], 3), [true, false, true], 'booleans repeat')
+ eq(fillSeries([null, null], 3), [null, null, null], 'blanks repeat')
+ eq(fillSeries([1, 2, 3], 2), [1, 2], 'a series target shorter than the seeds truncates too')
+}
+
+// ROW HEIGHT IS DECLARED TWICE and the two must agree.
+//
+// grid.ts positions every virtualised row at `top: i * ROW_H` while its height
+// comes from the stylesheet's `--row-h`. When they disagree the grid
+// PERFORATES — cells shrink, row boxes do not — and that is what stopped the
+// Excel-density change the first time it was attempted. The grid writes the
+// property from the constant when it mounts, so the running app cannot drift;
+// this guards the stylesheet FALLBACK, which is what renders in the moment
+// before the grid exists.
+{
+ const src = readFileSync(new URL('../dash/src/grid.ts', import.meta.url), 'utf8')
+ const css = readFileSync(new URL('../dash/src/styles.css', import.meta.url), 'utf8')
+ const fromTs = Number(src.match(/^const ROW_H = (\d+)$/m)?.[1])
+ const fromCss = Number(css.match(/--row-h:\s*(\d+)px/)?.[1])
+ ok(Number.isFinite(fromTs), `grid.ts declares ROW_H (${fromTs})`)
+ ok(Number.isFinite(fromCss), `styles.css declares --row-h (${fromCss})`)
+ ok(fromTs === fromCss,
+ `and they AGREE (${fromTs} vs ${fromCss}) — disagreement perforates the grid`)
+ ok(fromTs <= 26,
+ `row height is spreadsheet density, not web-table density (${fromTs}px; Excel is 20, Sheets 21)`)
+ ok(src.includes("setProperty('--row-h'"),
+ 'and grid.ts WRITES the property from the constant, so the running app cannot drift at all')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-store.ts b/scripts/test-dash-store.ts
index 3f80cb05..beb80842 100644
--- a/scripts/test-dash-store.ts
+++ b/scripts/test-dash-store.ts
@@ -64,20 +64,67 @@ const content = (d: DashDoc): string => {
return JSON.stringify(rest)
}
+/**
+ * The rid watermark is the ONE field undo may not restore.
+ *
+ * A rid that has existed must never be minted again — overrides, comments and
+ * a peer's CRDT node all assume a rid names one row forever. So insert and
+ * delete leave `nextRid` raised, deliberately, and comparing it would assert
+ * the opposite of what the format requires. Everything else in the sheet is
+ * still compared byte for byte.
+ */
+const withoutWatermark = (d: DashDoc): string => {
+ const { modified: _m, ...rest } = d
+ return JSON.stringify(rest, (k, v) => (k === 'nextRid' ? undefined : v))
+}
+
/** apply → undo → is the document exactly where it started? */
function roundTrip(name: string, patches: Patch | Patch[]) {
const s = new Store(fresh())
const before = content(s.doc)
+ const beforeW = withoutWatermark(s.doc)
s.commit(patches)
const changed = content(s.doc) !== before
const undone = s.undo()
ok(changed, `${name}: the patch actually changed something`)
- ok(undone && content(s.doc) === before, `${name}: undo restores the document exactly`)
+ ok(undone && withoutWatermark(s.doc) === beforeW,
+ `${name}: undo restores the document exactly (bar the monotonic rid watermark)`)
const afterUndo = content(s.doc)
s.redo()
ok(content(s.doc) !== afterUndo, `${name}: redo re-applies it`)
}
+// an override delete has to survive a JSON round trip: the patch is also the
+// collab wire format, and an array cannot carry `undefined`
+{
+ const s = new Store(fresh())
+ s.commit({ op: 'setOverrides', sheet: 'sh1', keys: ['amount:2'], v: [{ note: 'x' }] })
+ ok(!!(s.doc.sheets[0] as any).cells['amount:2'], 'an override is set')
+ const del = { op: 'setOverrides', sheet: 'sh1', keys: ['amount:2'], v: [undefined] } as Patch
+ const overWire = JSON.parse(JSON.stringify(del)) as Patch
+ ok(JSON.stringify(overWire).includes('null'),
+ 'a delete sent over the wire arrives as null, because JSON has no undefined in an array')
+ s.commit(overWire)
+ ok(!('amount:2' in ((s.doc.sheets[0] as any).cells ?? {})),
+ 'and it still DELETES rather than writing a null override the other replica would not have')
+}
+
+// THE WATERMARK ITSELF: a rid must never be minted twice, and undo must not
+// hand one back. This is the precondition collaboration needs — two replicas
+// minting the same rid for two different rows merge them into one row.
+{
+ const s = new Store(fresh())
+ const sheet = () => s.doc.sheets[0] as any
+ s.commit({ op: 'deleteRows', sheet: 'sh1', rids: [4] })
+ ok(sheet().nextRid === 5, 'deleting the last row RAISES the watermark past it')
+ s.commit({ op: 'insertRows', sheet: 'sh1', rids: [5] })
+ ok(!sheet().rids.some(([st, c]: [number, number]) => 4 >= st && 4 < st + c),
+ 'so the next insert does not mint the deleted rid again')
+ s.undo(); s.undo()
+ ok(sheet().nextRid >= 5,
+ 'and undo does NOT hand the rid back — a peer may already have attached to it')
+}
+
// ------------------------------------------------------------ round trips
roundTrip('setCells (raw)', { op: 'setCells', sheet: 'sh1', col: 'amount', rids: [2, 3], v: [99, 98] })
roundTrip('setCells (dict)', { op: 'setCells', sheet: 'sh1', col: 'region', rids: [1], v: ['East'] })
@@ -94,6 +141,99 @@ roundTrip('setMeasure', {
measure: { name: 'Revenue', expr: 'SUM(amount)', grain: 'sh1', additive: true },
})
roundTrip('setTitle', { op: 'setTitle', title: 'renamed' })
+roundTrip('setSheetProps', {
+ op: 'setSheetProps', sheet: 'sh1',
+ props: { condfmt: { amount: [{ kind: 'dataBar', color: '#F7A600' }] } },
+})
+{
+ // a property whose new value is `undefined` is REMOVED, not set to undefined
+ const s = new Store(fresh())
+ s.commit({ op: 'setSheetProps', sheet: 'sh1', props: { condfmt: { a: 1 } } })
+ ok('condfmt' in (s.doc.sheets[0] as any), 'a sheet property is set')
+ s.commit({ op: 'setSheetProps', sheet: 'sh1', props: {}, drop: ['condfmt'] })
+ ok(!('condfmt' in (s.doc.sheets[0] as any)),
+ 'and a listed `drop` REMOVES the key rather than leaving a dead one')
+ let refused = ''
+ try { s.commit({ op: 'setSheetProps', sheet: 'sh1', props: { condfmt: undefined } }) }
+ catch (e) { refused = String(e) }
+ ok(refused.includes('drop'),
+ 'while props:{k:undefined} is REFUSED — it evaporates in JSON.stringify, so the delete would never reach another replica')
+ s.undo()
+ ok('condfmt' in (s.doc.sheets[0] as any), 'undo brings it back')
+}
+// SHEETS ARE PATCHES NOW, so adding or deleting one is undoable. Both used to
+// go through `replaceDoc`, which CLEARS the undo stack — so creating a pivot or
+// importing a CSV silently threw away every edit you could previously take back.
+{
+ const s = new Store(fresh())
+ const blank = { id: 'sh2', name: 'Second', kind: 'table', rids: [], columns: [], data: {}, steps: [] }
+ s.commit({ op: 'setCells', sheet: 'sh1', col: 'amount', rids: [1], v: [111] })
+ s.commit({ op: 'setSheet', id: 'sh2', sheet: blank as never })
+ ok(s.doc.sheets.length === 2, 'a sheet can be added by patch')
+ s.undo()
+ ok(s.doc.sheets.length === 1, 'and removed again by undo')
+ ok(s.canUndo, 'AND the edit before it is still on the stack — replaceDoc would have cleared it')
+ s.undo()
+ ok(readCell((s.doc.sheets[0] as any).data.amount, 0) === 10,
+ 'so the earlier edit is still reachable')
+
+ // position, because sheet order is the tab order
+ const t = new Store(fresh())
+ const mk = (id: string) => ({ id, name: id, kind: 'table', rids: [], columns: [], data: {}, steps: [] })
+ t.commit({ op: 'setSheet', id: 'a', sheet: mk('a') as never })
+ t.commit({ op: 'setSheet', id: 'b', sheet: mk('b') as never })
+ t.commit({ op: 'setSheet', id: 'a', sheet: undefined })
+ ok(JSON.stringify(t.doc.sheets.map((x) => x.id)) === JSON.stringify(['sh1', 'b']), 'deleting removes it')
+ t.undo()
+ ok(JSON.stringify(t.doc.sheets.map((x) => x.id)) === JSON.stringify(['sh1', 'a', 'b']),
+ 'and undo puts it back WHERE IT WAS, not at the end — sheet order is the tab order')
+}
+
+roundTrip('setView', {
+ op: 'setView', id: 'v1',
+ view: { id: 'v1', name: 'Overview', w: 12, h: 8, tiles: [] },
+})
+{
+ // views is an ARRAY — order is the tab order, so a replacement must keep its
+ // place rather than moving to the end
+ const s = new Store(fresh())
+ const mk = (id: string, name: string) => ({ id, name, w: 12, h: 8, tiles: [] })
+ s.commit({ op: 'setView', id: 'a', view: mk('a', 'A') })
+ s.commit({ op: 'setView', id: 'b', view: mk('b', 'B') })
+ s.commit({ op: 'setView', id: 'a', view: mk('a', 'A2') })
+ ok(JSON.stringify(s.doc.views?.map((v) => v.id)) === JSON.stringify(['a', 'b']),
+ 'replacing a view keeps its position, rather than moving it to the end')
+ ok(s.doc.views?.[0].name === 'A2', 'and it is the new one')
+ s.commit({ op: 'setView', id: 'a', view: undefined })
+ ok(JSON.stringify(s.doc.views?.map((v) => v.id)) === JSON.stringify(['b']), 'undefined removes it')
+ s.undo()
+ ok(s.doc.views?.[0].id === 'a', 'and undo puts it back where it was')
+}
+
+roundTrip('setDocProps', { op: 'setDocProps', props: { story: { steps: [] } } })
+{
+ // the document-level twin of setSheetProps, with the same wire discipline
+ const s = new Store(fresh())
+ s.commit({ op: 'setDocProps', props: { story: { steps: [{ id: 'a' }] } } })
+ ok('story' in (s.doc as any), 'a document field is set')
+ s.commit({ op: 'setDocProps', props: {}, drop: ['story'] })
+ ok(!('story' in (s.doc as any)), 'and a listed `drop` removes it')
+ s.undo()
+ ok('story' in (s.doc as any), 'undo brings it back')
+
+ let refused = ''
+ try { s.commit({ op: 'setDocProps', props: { story: undefined } }) } catch (e) { refused = String(e) }
+ ok(refused.includes('drop'),
+ 'props:{k:undefined} is REFUSED — JSON.stringify erases it, so the delete would reach no other replica')
+
+ for (const k of ['sheets', 'docId', 'format']) {
+ let threw = ''
+ try { s.commit({ op: 'setDocProps', props: { [k]: 1 } }) } catch (e) { threw = String(e) }
+ ok(threw.includes(k),
+ `setDocProps refuses "${k}" — structure and identity move through typed patches, not an unbounded props write`)
+ }
+}
+
roundTrip('addColumn', {
op: 'addColumn', sheet: 'sh1',
column: { id: 'computed', name: 'Computed', type: 'number', formula: 'amount * 2' },
@@ -152,6 +292,59 @@ roundTrip('a multi-patch commit', [
'a structural commit closes the run first — text and structure never merge')
}
+// A single EDIT may be several patches — the grid writes a value and clears the
+// formula it replaced — and they have to undo as ONE step, in reverse.
+{
+ const s = new Store(fresh())
+ const before = content(s.doc)
+ s.commit({ op: 'setOverrides', sheet: 'sh1', keys: ['amount:1'], v: [{ f: '=A1*2' }] })
+ const withFormula = content(s.doc)
+ s.runEdit('amount:1', [
+ { op: 'setCells', sheet: 'sh1', col: 'amount', rids: [1], v: [42] },
+ { op: 'setOverrides', sheet: 'sh1', keys: ['amount:1'], v: [null], dropEmpty: true },
+ ])
+ s.endRun()
+ ok(readCell((s.doc.sheets[0] as any).data.amount, 0) === 42 &&
+ !((s.doc.sheets[0] as any).cells?.['amount:1']),
+ 'typing over a formula writes the value AND removes the formula')
+ s.undo()
+ ok(content(s.doc) === withFormula,
+ 'and ONE undo restores both — the value and the formula, which only works if the inverses replay in reverse')
+ s.undo()
+ ok(content(s.doc) === before, 'the step before that is still there')
+}
+{
+ // AND THE ORDER HAS TO BE REVERSED, which the check above cannot show: those
+ // two patches write different structures, so their inverses commute and a
+ // forward replay passes by luck. These two write the SAME key, so replaying
+ // the inverses forward re-creates what the first one deleted.
+ const s = new Store(fresh())
+ const before = content(s.doc)
+ s.runEdit('amount:1', [
+ { op: 'setOverrides', sheet: 'sh1', keys: ['amount:1'], v: [{ note: 'a' }] },
+ { op: 'setOverrides', sheet: 'sh1', keys: ['amount:1'], v: [{ note: 'b' }] },
+ ])
+ s.endRun()
+ ok((s.doc.sheets[0] as any).cells['amount:1'].note === 'b', 'the last write wins going forward')
+ s.undo()
+ ok(content(s.doc) === before,
+ 'and undo leaves NO override — replaying the inverses forward would restore the first one instead')
+}
+{
+ // the multi-patch run must still collapse repeated typing into one step
+ const s = new Store(fresh())
+ const before = content(s.doc)
+ for (let i = 0; i < 5; i++) {
+ s.runEdit('amount:1', [
+ { op: 'setCells', sheet: 'sh1', col: 'amount', rids: [1], v: [i] },
+ { op: 'setColumn', sheet: 'sh1', col: 'amount', patch: { unit: `U${i}` } },
+ ])
+ }
+ s.endRun()
+ s.undo()
+ ok(content(s.doc) === before, 'five multi-patch edits in one cell are still ONE undo step')
+}
+
// ------------------------------------------ history costs the EDIT, not the doc
{
const s = new Store(fresh())
diff --git a/scripts/test-dash-story.ts b/scripts/test-dash-story.ts
new file mode 100644
index 00000000..108c784f
--- /dev/null
+++ b/scripts/test-dash-story.ts
@@ -0,0 +1,572 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash data-story rig.
+//
+// node scripts/test-dash-story.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. Everything visible about a story — the overlay, the dots,
+// the fullscreen — is a thing you can look at. What is NOT visible is whether
+// the animation between two steps is telling the truth, and every failure below
+// produces a smooth, confident, wrong picture:
+//
+// 1. A GAP THAT GROWS OUT OF THE FLOOR. A category with no value is `null`
+// (chart.ts: "a gap, never a zero"). Interpolate that as 0 and the bar
+// rises from the axis, which is a claim that the value USED TO BE ZERO.
+// Nothing in the data ever said so, and there is no frame of the animation
+// where a reader could tell. The whole point of the module is this one
+// rule, so it gets the most checks.
+// 2. A BAR THAT CHANGES WHAT IT MEANS. Two steps rarely have the same
+// categories or the same series — that is what a story IS. Align them by
+// POSITION rather than by name and "Revenue" tweens into "Cost" while the
+// legend keeps saying Revenue.
+// 3. A FILTER THAT REACHES THE CHART HALFWAY. The step's filter narrows the
+// chart by handing `optionFor` the visible slice of every bound column.
+// Hand it the slice for SOME columns and it zips a four-row x axis against
+// a six-row series: every label carries a number from a different row, and
+// the chart looks entirely normal.
+// 4. A STORY THAT DOES NOT SURVIVE THE FILE. A filter's checkbox list is a
+// `Set`, and `JSON.stringify(new Set([1]))` is `{}` — the step would come
+// back matching nothing, which reads as "the data vanished" rather than as
+// a broken round trip. And a step field this build has never heard of has
+// to come back out unchanged (PLATFORM §3): there is no server to migrate
+// the files already on disk.
+// 5. A SETTING THAT WILL NOT SWITCH OFF. `filters`, `sorts` and `caption` are
+// additive fields where ABSENT means none. Storing `[]` or `""` leaves the
+// document changed after a round trip; every reader diffs it, and collab
+// ships an op for a document that is back where it started. Same rule
+// panels.ts follows for `totals` and `frozen`.
+//
+// The last section runs ELEVEN NEGATIVE CONTROLS: each one is a plausible
+// implementation of something above, and each has to be caught by a check that
+// the real implementation passes. A rig where every mutation still passes is a
+// rig that proves nothing.
+
+import { registerHooks } from 'node:module'
+
+// story.ts imports its stylesheet, which is Vite's job and not Node's — the
+// same stub test-dash-panels.ts uses, and for the same reason: `import
+// './story.css'` is how every Bento module co-locates a surface with its
+// styles, and a rig is not a reason to break the pattern.
+registerHooks({
+ load(url, context, next) {
+ if (url.endsWith('.css')) {
+ return { format: 'module', source: 'export {}', shortCircuit: true }
+ }
+ return next(url, context)
+ },
+})
+
+const {
+ normalizeStory, readStory, toPredicate, fromPredicate, toFilters, fromFilters,
+ stepOrder, viewColumns, stepOption, mergeCats, alignOptions, canMorph, morphOption,
+ captureStep, moveStep, addStep, removeStep, editStep, storyPatch, sheetOf, STORY_OP,
+} = await import('../dash/src/story.ts')
+
+type Story = import('../dash/src/story.ts').Story
+type StoryStep = import('../dash/src/story.ts').StoryStep
+type StoredFilter = import('../dash/src/story.ts').StoredFilter
+
+const { optionFor } = await import('../dash/src/chart.ts')
+type ChartBinding = import('../dash/src/chart.ts').ChartBinding
+
+type TableSheet = import('../dash/src/model.ts').TableSheet
+type DashDoc = import('../dash/src/model.ts').DashDoc
+type ColumnFilter = import('../dash/src/filter.ts').ColumnFilter
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string): void {
+ checks++
+ if (!cond) { failures++; console.error(` ✗ ${msg}`) }
+}
+function section(name: string): void {
+ console.log(`\n${name}`)
+}
+
+type Opt = Record<string, any>
+
+const eq = (a: unknown, b: unknown): boolean => JSON.stringify(a) === JSON.stringify(b)
+
+// --- the fixture -------------------------------------------------------------
+//
+// Six rows over four regions, with West holding no number at all — so the
+// derived chart carries a REAL gap produced by chart.ts's own aggregate path,
+// not one this rig invented to make a point.
+
+function fixture(): TableSheet {
+ return {
+ id: 'sales',
+ name: 'Sales',
+ kind: 'table',
+ rids: [[1, 6]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'number' },
+ { id: 'cost', name: 'Cost', type: 'number' },
+ ],
+ data: {
+ region: { enc: 'raw', v: ['North', 'South', 'East', 'North', 'South', 'West'] },
+ amount: { enc: 'raw', v: [10, 20, 30, 40, 50, null] },
+ cost: { enc: 'raw', v: [5, 8, 12, 15, 20, 3] },
+ },
+ steps: [],
+ } as unknown as TableSheet
+}
+
+const doc = (): DashDoc => ({
+ format: 'bento/dash', version: 1, docId: 'd-test', title: 'T', sheets: [fixture()],
+} as unknown as DashDoc)
+
+const BAR: ChartBinding = { x: 'region', series: ['amount'], kind: 'bar', aggregate: 'sum' }
+
+const step = (over: Partial<StoryStep> = {}): StoryStep =>
+ ({ id: 's1', sheet: 'sales', chart: BAR, ...over }) as StoryStep
+
+const dataOf = (opt: Opt, i = 0): Array<number | null> => opt.series[i].data
+const catsOf = (opt: Opt): string[] => opt.xAxis.data
+
+// --- 1. the document field ---------------------------------------------------
+
+section('the step model is additive')
+{
+ const raw = {
+ steps: [
+ { id: 'a', sheet: 'sales', caption: 'One', chart: BAR, hologram: { spin: 3 } },
+ { id: 'b', sheet: 'sales', transition: 'kaleidoscope', duration: 1.2 },
+ ],
+ // A whole story-level field from a build that does not exist yet.
+ soundtrack: 'asset:mp3',
+ }
+ const s = normalizeStory(structuredClone(raw))
+ ok(eq(s, raw), 'a story round-trips through normalizeStory byte-identically, unknown fields and all')
+ ok((s.steps[0] as any).hologram.spin === 3, 'an unknown STEP field survives')
+ ok((s as any).soundtrack === 'asset:mp3', 'an unknown STORY field survives')
+ ok(s.steps[1].transition === 'kaleidoscope', 'an unknown transition parses rather than throwing')
+
+ const minted = normalizeStory({ steps: [{ sheet: 'sales' }] })
+ ok(typeof minted.steps[0].id === 'string' && minted.steps[0].id.length > 0,
+ 'a step with no id gets one — the step is somebody work, the id is bookkeeping')
+
+ ok(readStory({ sheets: [] } as unknown as DashDoc) === null, 'a document with no story reads as null')
+ ok(readStory({ sheets: [], story: { steps: [] } } as unknown as DashDoc)?.steps.length === 0,
+ 'a document with an empty story reads as an empty story, not null')
+
+ ok(normalizeStory({ steps: 'nope' as unknown as [] }).steps.length === 0,
+ 'a malformed steps field degrades to no steps rather than throwing in front of an audience')
+ ok(normalizeStory({ steps: [1, null, { sheet: 'x' }] as unknown as [] }).steps.length === 1,
+ 'non-object entries in steps are dropped')
+}
+
+section('the patch the store still needs')
+{
+ const p = storyPatch({ steps: [step()] })
+ ok(p.op === STORY_OP && eq(Object.keys(p.props), ['story']), 'a story writes as one document-level prop')
+ const clear = storyPatch({ steps: [] })
+ ok(eq(clear.drop, ['story']) && eq(clear.props, {}),
+ 'clearing the last step DROPS the key by name — `props:{story:undefined}` would vanish in JSON and reach every replica as a no-op')
+}
+
+// --- 2. filters survive JSON -------------------------------------------------
+
+section('filters survive the file')
+{
+ const live: ColumnFilter[] = [
+ { col: 'region', pred: { op: 'isOneOf', set: new Set(['North', 'South', null]) } },
+ { col: 'amount', pred: { op: 'greater', v: 15 } },
+ { col: 'amount', pred: { op: 'between', lo: 1, hi: 99 } },
+ { col: 'amount', pred: { op: 'topN', n: 2 } },
+ { col: 'region', pred: { op: 'notBlank' } },
+ ]
+ const stored = fromFilters(live)
+ const json = JSON.parse(JSON.stringify(stored)) as StoredFilter[]
+ ok(eq((json[0].pred as any).values, ['North', 'South', null]),
+ 'the checkbox list stores as an ARRAY — a Set stringifies to {} and the step would come back matching nothing')
+ const back = toFilters(json)
+ const set = (back[0].pred as { op: 'isOneOf'; set: Set<unknown> }).set
+ ok(set.has('North') && set.has(null) && set.size === 3, 'and comes back as a Set with the blanks box intact')
+ ok(eq(fromFilters(back), stored), 'live → stored → live → stored is a fixed point')
+
+ ok(toPredicate({ op: 'wormhole', v: 1 } as never) === null,
+ 'a predicate op this build cannot evaluate is dropped AT USE')
+ const kept = normalizeStory({ steps: [{ id: 'a', sheet: 's', filters: [{ col: 'c', pred: { op: 'wormhole', v: 1 } }] }] })
+ ok((kept.steps[0].filters as any)[0].pred.op === 'wormhole',
+ '…and KEPT in the document — dropping it at use is not the same as deleting it')
+ ok(toFilters(kept.steps[0].filters).length === 0, 'so the unknown filter narrows nothing rather than everything')
+
+ ok(toPredicate({ op: 'topN', n: 'lots' } as never) === null, 'a non-numeric topN is refused, not coerced to NaN')
+ ok(eq(fromPredicate({ op: 'contains', v: 'th' }), { op: 'contains', v: 'th' }),
+ 'every predicate that is already JSON passes through untouched')
+}
+
+// --- 3. deriving a step ------------------------------------------------------
+
+section('a step derives its numbers from the sheet, every time')
+{
+ const sheet = fixture()
+ const all = stepOption(sheet, step())!
+ ok(eq(catsOf(all), ['North', 'South', 'East', 'West']),
+ 'categories are first-seen order, matching chart.ts — alphabetical would give Apr, Aug, Dec')
+ ok(eq(dataOf(all), [50, 70, 30, null]),
+ 'the sums are right and West — which has no number at all — is a GAP, not a zero')
+
+ const filtered = stepOption(sheet, step({
+ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }],
+ }))!
+ ok(eq(catsOf(filtered), ['North', 'South']), "a step's filter reaches the chart")
+ ok(eq(dataOf(filtered), [50, 70]), 'and the surviving numbers are unchanged by it')
+
+ const sorted = stepOption(sheet, step({ sorts: [{ col: 'amount', dir: 'desc' }] }))!
+ ok(eq(catsOf(sorted), ['South', 'North', 'East', 'West']),
+ 'a sort reorders the CATEGORIES, because aggregate order is first-seen over the visible rows')
+ ok(eq(dataOf(sorted), [70, 50, 30, null]), 'and every bar keeps its own number through the reorder')
+
+ ok(stepOrder(sheet, step()).length === 6, 'no filter and no sort is every row')
+ ok(eq(stepOrder(sheet, step({ filters: [{ col: 'amount', pred: { op: 'greater', v: 25 } }] })), [2, 3, 4]),
+ 'the order vector is row POSITIONS, and a blank never satisfies "greater than"')
+
+ // The zip hazard: every bound column or none.
+ const order = stepOrder(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] }))
+ const view = viewColumns(sheet, order, ['region', 'amount'])
+ ok(view.get('region')!.length === 4 && view.get('amount')!.length === 4,
+ 'viewColumns narrows EVERY bound column to the same length')
+ ok(eq(view.get('amount'), [10, 20, 40, 50]), 'and carries the visible rows values, in view order')
+
+ ok(stepOption(sheet, step({ chart: undefined })) === null, 'a step with no binding has no option, rather than an empty one')
+ ok(stepOption(sheet, step({ chart: { x: 'region', series: [], kind: 'bar' } })) === null,
+ 'a binding with no series is refused too — an empty chart reads as "no data", which is a claim')
+
+ ok(sheetOf(doc(), 'sales')?.id === 'sales' && sheetOf(doc(), 'nope') === null,
+ 'a step naming a deleted sheet resolves to null, never to whichever sheet is first')
+}
+
+// --- 4. alignment ------------------------------------------------------------
+
+section('two steps are aligned before they are tweened')
+{
+ ok(eq(mergeCats(['a', 'b', 'c'], ['a', 'b', 'c']), ['a', 'b', 'c']), 'identical axes merge to themselves')
+ ok(eq(mergeCats(['a', 'b', 'c'], ['a', 'c']), ['a', 'b', 'c']),
+ 'a category only the FROM side has is kept, in the place it was standing')
+ ok(eq(mergeCats(['a', 'c'], ['a', 'b', 'c']), ['a', 'b', 'c']), 'a category only the TO side has is kept')
+ ok(eq(mergeCats(['c', 'a'], ['a', 'c']), ['a', 'c']),
+ "the destination's order wins for shared categories, because that is where the reader is going")
+ ok(eq(mergeCats([], ['a']), ['a']) && eq(mergeCats(['a'], []), ['a']), 'an empty side is not a wipe')
+
+ const sheet = fixture()
+ const wide = stepOption(sheet, step())!
+ const narrow = stepOption(sheet, step({
+ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }],
+ }))!
+
+ const a = alignOptions(wide, narrow)
+ ok(a.refused === '', 'two bar options align')
+ ok(eq(catsOf(a.from), catsOf(a.to)), 'both sides end up on ONE category axis')
+ ok(eq(catsOf(a.to), ['North', 'South', 'East', 'West']), 'which is the union, in a stable order')
+ ok(eq(dataOf(a.from), [50, 70, 30, null]), 'the from side keeps every number it had')
+ ok(eq(dataOf(a.to), [50, 70, null, null]),
+ 'and the categories the filter removed are NULL on the to side — not 0, which would be a bar shrinking to the axis')
+ ok(a.introduced === true, 'alignment reports that it introduced gaps, so canMorph can judge the renderer risk')
+ ok(!dataOf(a.from).includes(0 as never) && !dataOf(a.to).includes(0 as never),
+ 'NO ALIGNED POSITION HOLDS ZERO — zero is a number, and no step of this story contains it')
+
+ // series matched by name, not by index
+ const twoSeries = optionFor(sheet, { x: 'region', series: ['amount', 'cost'], kind: 'bar', aggregate: 'sum' })
+ const oneSeries = optionFor(sheet, { x: 'region', series: ['cost'], kind: 'bar', aggregate: 'sum' })
+ const b = alignOptions(twoSeries as Opt, oneSeries as Opt)
+ ok(b.from.series.length === b.to.series.length, 'both sides carry the same series list')
+ const names = (o: Opt) => o.series.map((s: Opt) => s.name)
+ ok(eq(names(b.from), names(b.to)), 'in the same order')
+ const costFrom = b.from.series[names(b.from).indexOf('Cost')].data
+ const costTo = b.to.series[names(b.to).indexOf('Cost')].data
+ ok(eq(costFrom, costTo), 'Cost lines up with Cost, so the bars that stay put do not move')
+ const amountTo = b.to.series[names(b.to).indexOf('Amount')].data
+ ok(amountTo.every((v: unknown) => v === null), 'a series the destination lacks is all gaps, never all zeroes')
+ ok(b.to.series.every((s: Opt) => s.type === 'bar'), 'a borrowed series still has a TYPE, or nothing can tween')
+
+ // refusals
+ const pie = optionFor(sheet, { x: 'region', series: ['amount'], kind: 'pie', aggregate: 'sum' })
+ ok(alignOptions(wide, pie as Opt).refused === 'pie', 'a pie is refused — its data is not on a category axis at all')
+ const perRow = optionFor(sheet, { x: 'region', series: ['amount'], kind: 'bar', aggregate: 'none' })
+ ok(alignOptions(perRow as Opt, wide).refused === 'duplicate categories',
+ 'duplicate x labels (aggregate:none is one bar per ROW) are refused, because matching by label would swap two bars silently')
+ ok(alignOptions({ series: [] }, wide).refused === 'no category axis', 'an option with no category axis is refused')
+}
+
+section('canMorph refuses what the renderer would draw as a lie')
+{
+ const sheet = fixture()
+ const wide = stepOption(sheet, step())!
+ const narrow = stepOption(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] }))!
+ ok(canMorph(alignOptions(wide, narrow)), 'bars morph across a filter: a null renders as a zero-height rect, which is what absent looks like')
+
+ const lineWide = optionFor(sheet, { x: 'region', series: ['amount'], kind: 'line', aggregate: 'sum' })
+ const lineNarrow = optionFor(sheet, {
+ x: 'region', series: ['amount'], kind: 'line', aggregate: 'sum',
+ }, viewColumns(sheet, stepOrder(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] })), ['region', 'amount']))
+ const la = alignOptions(lineWide as Opt, lineNarrow as Opt)
+ ok(la.introduced, 'the same filter introduces gaps on a line chart')
+ ok(!canMorph(la),
+ 'and the morph is REFUSED — charts-lite reads a line value through num(v,0), so the polyline would dive to the axis and back')
+
+ const lineSame = alignOptions(lineWide as Opt, lineWide as Opt)
+ ok(!lineSame.introduced && canMorph(lineSame), 'a line whose categories do not change still morphs')
+
+ const barOpt = stepOption(sheet, step())!
+ const lineOpt = lineWide as Opt
+ ok(!canMorph(alignOptions(barOpt, lineOpt)),
+ 'a bar → line step is refused by the type signature, and takes the cross-type sweep instead')
+
+ const huge = { xAxis: { type: 'category', data: [] as string[] }, series: [{ type: 'bar', name: 'A', data: [] as number[] }] }
+ for (let i = 0; i < 5000; i++) { huge.xAxis.data.push(`c${i}`); huge.series[0].data.push(i) }
+ ok(!canMorph(alignOptions(huge, huge)),
+ 'past the point budget a morph CUTS — a transition that misses frames reads as a broken app')
+}
+
+// --- 5. the interpolation ----------------------------------------------------
+
+section('the interpolation never invents a number')
+{
+ ok(morphOption(10, 20, 0) === 10 && morphOption(10, 20, 1) === 20, 'the ends are exact')
+ ok(morphOption(10, 20, 0.5) === 15, 'numbers interpolate')
+ ok(morphOption(-10, 10, 0.5) === 0, 'a real crossing through zero is fine — the data goes there')
+
+ // THE RULE.
+ for (const t of [0, 0.01, 0.25, 0.5, 0.75, 0.99]) {
+ ok(morphOption(null, 100, t) === null, `a gap entering stays a gap at t=${t} — never 0, never 100`)
+ ok(morphOption(100, null, t) === 100, `a gap leaving holds its true value at t=${t}`)
+ }
+ ok(morphOption(null, 100, 1) === 100, 'and the gap resolves at the end of the transition')
+ ok(morphOption(100, null, 1) === null, 'as does the departure')
+
+ const frames = [0, 0.1, 0.3, 0.5, 0.7, 0.9, 1].map((t) => morphOption(null, 100, t))
+ ok(frames.every((v) => v === null || v === 100),
+ 'EVERY frame of an entering gap is either absent or the true value — there is no in-between to misread')
+
+ // A non-finite number CUTS. `NaN + (10 - NaN) * t` is NaN for every frame,
+ // and a NaN reaching charts-lite's `num(v, 0)` comes out as a bar at zero —
+ // the exact lie, arriving through arithmetic rather than through a gap.
+ ok(Number.isNaN(morphOption(NaN, 10, 0.5) as number),
+ 'a non-finite from-value holds rather than poisoning every frame with NaN')
+ ok(morphOption(NaN, 10, 1) === 10, 'and still lands on the destination')
+
+ // arrays and objects
+ ok(eq(morphOption([1, 2], [3, 4], 0.5), [2, 3]), 'arrays interpolate element-wise')
+ ok(eq(morphOption([1, 2, 3], [3, 4], 0.5), [1, 2, 3]),
+ 'arrays of different lengths CUT — a length mismatch means the two frames are not the same chart, and that is what alignment is for')
+ ok(eq(morphOption([1, 2, 3], [3, 4], 1), [3, 4]), '…and land on the destination')
+ ok(eq(morphOption({ a: 1, b: 'x' }, { a: 3, b: 'y' }, 0.5), { a: 2, b: 'x' }),
+ 'numeric leaves interpolate and strings cut, so an axis type never half-changes')
+ ok(eq(morphOption({ a: 1 }, { a: 3, c: 9 }, 0.5), { a: 2, c: 9 }),
+ 'a key only the destination has arrives whole rather than growing from nothing')
+
+ // end to end: the frames of a real transition
+ const sheet = fixture()
+ const wide = stepOption(sheet, step())!
+ const narrow = stepOption(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] }))!
+ const al = alignOptions(wide, narrow)
+ const mid = morphOption(al.from, al.to, 0.5) as Opt
+ ok(eq(catsOf(mid), ['North', 'South', 'East', 'West']), 'mid-transition the axis is the union')
+ ok(eq(dataOf(mid), [50, 70, 30, null]),
+ 'North and South hold, East holds its LAST TRUE VALUE until the cut, and West is still a gap')
+ const end = morphOption(al.from, al.to, 1) as Opt
+ ok(eq(dataOf(end), [50, 70, null, null]), 'and the final frame is exactly the destination step')
+
+ const allFrames = [0, 0.2, 0.4, 0.6, 0.8, 1].map((t) => dataOf(morphOption(al.from, al.to, t) as Opt))
+ ok(allFrames.every((row) => row.every((v) => v === null || (typeof v === 'number' && v > 0))),
+ 'NO FRAME OF THE WHOLE TRANSITION CONTAINS A ZERO — not one bar ever touches the axis')
+}
+
+// --- 6. authoring ------------------------------------------------------------
+
+section('authoring: capture, order, caption')
+{
+ const captured = captureStep({
+ sheet: 'sales',
+ filters: [{ col: 'region', pred: { op: 'isOneOf', set: new Set(['North']) } }],
+ sorts: [{ col: 'amount', dir: 'desc' }],
+ chart: BAR,
+ })
+ ok(captured.sheet === 'sales' && captured.chart?.kind === 'bar', 'capture takes the view on screen')
+ ok(eq((captured.filters as any)[0].pred, { op: 'isOneOf', values: ['North'] }),
+ 'and stores the filter in its JSON spelling')
+ ok(captured.chart !== BAR && captured.chart!.series !== BAR.series,
+ 'the binding is COPIED — a captured step that aliased the live binding would rewrite itself when the author changed the chart')
+
+ const bare = captureStep({ sheet: 'sales' })
+ ok(!('filters' in bare) && !('sorts' in bare) && !('caption' in bare),
+ 'empty collections are ABSENT, not [] — absent is what "none" means in an additive field')
+ ok(eq(Object.keys(bare).sort(), ['id', 'sheet']), 'so a bare step is two keys')
+
+ const viz3d = captureStep({ sheet: 'sales', chart: BAR, viz: { kind: 'scatter', x: 'a', y: 'b', z: 'c' } })
+ ok(!!viz3d.viz && !viz3d.chart, 'a 3D binding wins — the two cannot both be on screen')
+
+ const s0: Story = { steps: [step({ id: 'a' }), step({ id: 'b' }), step({ id: 'c' })] }
+ ok(eq(moveStep(s0, 0, 2).steps.map((s) => s.id), ['b', 'c', 'a']), 'a step moves forward')
+ ok(eq(moveStep(s0, 2, 0).steps.map((s) => s.id), ['c', 'a', 'b']), 'and backward')
+ ok(eq(moveStep(s0, 1, 1).steps.map((s) => s.id), ['a', 'b', 'c']), 'moving onto itself is a no-op')
+ ok(moveStep(s0, 0, -1) === s0 && moveStep(s0, 0, 9) === s0,
+ 'an out-of-range move is a no-op, never a silent reshuffle')
+ ok(eq(s0.steps.map((s) => s.id), ['a', 'b', 'c']), 'and none of it mutated the story it was given')
+
+ ok(eq(addStep(null, step({ id: 'x' })).steps.map((s) => s.id), ['x']), 'the first capture makes the story')
+ ok(eq(addStep(s0, step({ id: 'x' }), 1).steps.map((s) => s.id), ['a', 'x', 'b', 'c']), 'and a later one inserts')
+ ok(eq(removeStep(s0, 'b').steps.map((s) => s.id), ['a', 'c']), 'a step is removed by id, not by position')
+ ok(eq(removeStep(s0, 'nope').steps.map((s) => s.id), ['a', 'b', 'c']), 'removing a stranger removes nothing')
+
+ const cap = editStep(s0, 'b', { caption: 'The dip' })
+ ok(cap.steps[1].caption === 'The dip', 'a caption writes')
+ const uncap = editStep(cap, 'b', { caption: '' })
+ ok(!('caption' in uncap.steps[1]),
+ 'and clearing it REMOVES the key — a key holding "" is a document that differs from one that never had it')
+ ok(eq(uncap.steps[1], step({ id: 'b' })), 'so caption → clear is a true round trip')
+
+ const story: Story = { steps: [captured] }
+ ok(eq(normalizeStory(JSON.parse(JSON.stringify(story))), story),
+ 'a captured story survives the file byte-identically')
+}
+
+// --- 7. NEGATIVE CONTROLS ----------------------------------------------------
+//
+// Each mutation is a plausible implementation. Each has to be CAUGHT by a check
+// the real code passes — a mutation that survives means the check above it is
+// decorative.
+
+section('negative controls')
+
+let mutations = 0
+let survived = 0
+function mutant(name: string, broken: () => boolean): void {
+ mutations++
+ // `broken()` returns true when the CHECK still passes on the broken code,
+ // i.e. the mutation went undetected.
+ let undetected: boolean
+ try { undetected = broken() } catch { undetected = false }
+ if (undetected) {
+ survived++
+ console.error(` ✗ SURVIVED: ${name}`)
+ } else {
+ console.log(` ✓ caught: ${name}`)
+ }
+}
+
+const sheet = fixture()
+const wide = stepOption(sheet, step())!
+const narrow = stepOption(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] }))!
+const aligned = alignOptions(wide, narrow)
+
+// M1 — the kernel's leaf fallback (`a ?? b`), which is what mountChart uses.
+function morphKernelFallback(a: any, b: any, t: number): any {
+ if (typeof a === 'number' && typeof b === 'number') return a + (b - a) * t
+ if (Array.isArray(a) && Array.isArray(b) && a.length === b.length) return b.map((v, i) => morphKernelFallback(a[i], v, t))
+ if (a && b && typeof a === 'object' && typeof b === 'object') {
+ const out: any = { ...b }
+ for (const k of Object.keys(b)) if (k in a) out[k] = morphKernelFallback(a[k], b[k], t)
+ return out
+ }
+ return t < 1 ? a ?? b : b
+}
+mutant('leaf fallback `a ?? b`: an entering gap shows its destination value for the whole tween',
+ () => morphKernelFallback(null, 100, 0.5) === null)
+
+// M2 — the classic: treat a gap as a zero and lerp it.
+function morphNullIsZero(a: any, b: any, t: number): any {
+ const n = (v: any) => (typeof v === 'number' ? v : v === null ? 0 : null)
+ const na = n(a); const nb = n(b)
+ if (na !== null && nb !== null) return na + (nb - na) * t
+ return t < 1 ? a : b
+}
+mutant('null coerced to 0 before lerping: the bar grows out of the floor',
+ () => [0, 0.25, 0.5, 0.75].every((t) => morphNullIsZero(null, 100, t) === null))
+
+// M3 — a merge that keeps only the destination's categories.
+const mergeToOnly = (_a: string[], b: string[]): string[] => b.slice()
+mutant('mergeCats keeps only the destination axis: a departing bar teleports off screen',
+ () => eq(mergeToOnly(['North', 'South', 'East', 'West'], ['North', 'South']), ['North', 'South', 'East', 'West']))
+
+// M4 — fill the absences with 0 instead of null.
+const zeroFilled = JSON.parse(JSON.stringify(aligned.to)) as Opt
+zeroFilled.series[0].data = zeroFilled.series[0].data.map((v: number | null) => (v === null ? 0 : v))
+mutant('alignment fills absences with 0: every removed category shrinks to the axis',
+ () => !zeroFilled.series[0].data.includes(0))
+
+// M5 — match series by position instead of by name.
+function alignByIndex(from: Opt, to: Opt): { from: Opt; to: Opt } {
+ const n = Math.max(from.series.length, to.series.length)
+ const pick = (o: Opt, i: number) => o.series[i] ?? { type: 'bar', name: '', data: [] }
+ return {
+ from: { ...from, series: Array.from({ length: n }, (_, i) => pick(from, i)) },
+ to: { ...to, series: Array.from({ length: n }, (_, i) => pick(to, i)) },
+ }
+}
+{
+ const two = optionFor(sheet, { x: 'region', series: ['amount', 'cost'], kind: 'bar', aggregate: 'sum' }) as Opt
+ const one = optionFor(sheet, { x: 'region', series: ['cost'], kind: 'bar', aggregate: 'sum' }) as Opt
+ const byIdx = alignByIndex(two, one)
+ mutant('series matched by index: Amount tweens into Cost while the legend still says Amount',
+ () => byIdx.from.series.every((s: Opt, i: number) => s.name === byIdx.to.series[i].name))
+}
+
+// M6 — ignore the introduced-null rule, so a line chart morphs.
+const canMorphNoNullRule = (a: { refused: string }): boolean => a.refused === ''
+{
+ const lineWide = optionFor(sheet, { x: 'region', series: ['amount'], kind: 'line', aggregate: 'sum' }) as Opt
+ const order = stepOrder(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] }))
+ const lineNarrow = optionFor(sheet, { x: 'region', series: ['amount'], kind: 'line', aggregate: 'sum' },
+ viewColumns(sheet, order, ['region', 'amount'])) as Opt
+ const la = alignOptions(lineWide, lineNarrow)
+ mutant('canMorph ignores introduced nulls: a filtered LINE dives to the axis and back',
+ () => !canMorphNoNullRule(la))
+}
+
+// M7 — store empty collections rather than omitting them.
+const captureKeepsEmpty = (sheetId: string): StoryStep =>
+ ({ id: 'x', sheet: sheetId, caption: '', filters: [], sorts: [] })
+mutant('capture stores filters: [] and caption: "": a semantically unchanged document diffs on every reader',
+ () => eq(Object.keys(captureKeepsEmpty('sales')).sort(), ['id', 'sheet']))
+
+// M8 — insert before removing, so a backward move lands one place off.
+function moveNaive(s: Story, from: number, to: number): Story {
+ const next = s.steps.slice()
+ next.splice(to, 0, next[from])
+ next.splice(from > to ? from + 1 : from, 1)
+ // the classic off-by-one: the removal index is not adjusted for a forward move
+ return { ...s, steps: next }
+}
+{
+ const s = { steps: [step({ id: 'a' }), step({ id: 'b' }), step({ id: 'c' })] }
+ mutant('moveStep splices before removing: a forward move silently reorders the wrong pair',
+ () => eq(moveNaive(s, 0, 2).steps.map((x) => x.id), ['b', 'c', 'a']))
+}
+
+// M9 — keep the empty caption key.
+const editKeepsEmpty = (s: Story, id: string, caption: string): Story =>
+ ({ ...s, steps: s.steps.map((x) => (x.id === id ? { ...x, caption } : x)) })
+mutant('clearing a caption leaves caption: "": the step no longer round-trips',
+ () => !('caption' in editKeepsEmpty({ steps: [step({ id: 'b' })] }, 'b', '').steps[0]))
+
+// M10 — narrow only SOME of the bound columns.
+{
+ const order = stepOrder(sheet, step({ filters: [{ col: 'region', pred: { op: 'contains', v: 'th' } }] }))
+ const partial = new Map<string, unknown[]>()
+ partial.set('region', viewColumns(sheet, order, ['region']).get('region')!)
+ const opt = optionFor(sheet, BAR, partial) as Opt
+ // region is 4 long, amount is read whole (6) — every label now carries some
+ // other row's number, and the chart looks entirely normal.
+ mutant('only the x column is narrowed: labels are zipped against the wrong rows',
+ () => eq(opt.series[0].data, [50, 70]))
+}
+
+// M11 — serialise the checkbox Set directly.
+const storeSetRaw = (f: ColumnFilter): unknown => JSON.parse(JSON.stringify(f))
+mutant('the checkbox list is stored as a Set: it comes back as {} and matches nothing',
+ () => {
+ const back = storeSetRaw({ col: 'region', pred: { op: 'isOneOf', set: new Set(['North']) } }) as any
+ return Array.isArray(back.pred.values) && back.pred.values.length === 1
+ })
+
+// --- report ------------------------------------------------------------------
+
+console.log(`\n${checks} checks, ${failures} failed`)
+console.log(`${mutations} mutations, ${survived} survived`)
+if (failures || survived) process.exit(1)
+console.log('data story: ok')
diff --git a/scripts/test-dash-sync.ts b/scripts/test-dash-sync.ts
new file mode 100644
index 00000000..59181efb
--- /dev/null
+++ b/scripts/test-dash-sync.ts
@@ -0,0 +1,956 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash convergence rig — the check that matters.
+//
+// node scripts/test-dash-sync.ts (Node >= 23.6 strips types)
+// SEEDS=200 STEPS=300 ACTORS=4 node scripts/test-dash-sync.ts
+// SEED_ONLY=137 DBG_NODE='r<US>s1<US>7' node scripts/test-dash-sync.ts
+//
+// Property-based, modelled on scripts/test-sync.ts (which caught 15+ ordering
+// bugs in slides): N simulated actors mutate their own replica through the SAME
+// patches the editor commits, ops travel over per-(from,to) FIFO queues in
+// random interleavings, and at quiescence every replica's materialized workbook
+// AND sync state must be identical.
+//
+// Plus targeted cases for everything dash does that slides does not: per-cell
+// LWW inside a columnar sheet, the row RGA over rids (concurrent inserts at one
+// anchor, an insert anchored to a row someone else deleted), delete-vs-edit,
+// undo resurrection with stashed cell values, column add/remove/reorder, sheet
+// delete, dictionary columns surviving a re-ordering, and two-way snapshot
+// merge of offline forks.
+
+import { DashSync, committable, mergeOrder, keyBetween, spreadKey, rowNode, _internals } from '../dash/src/sync/crdt.ts'
+import type { Op } from '../dash/src/sync/crdt.ts'
+import { applyPatch } from '../dash/src/store.ts'
+import type { Patch } from '../dash/src/store.ts'
+import type { DashDoc, TableSheet } from '../dash/src/model.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) {
+ failures++
+ console.error(` ✗ ${msg}`)
+ }
+}
+
+function mulberry32(seed: number) {
+ let t = seed >>> 0
+ return () => {
+ t += 0x6d2b79f5
+ let r = Math.imul(t ^ (t >>> 15), 1 | t)
+ r = (r + Math.imul(r ^ (r >>> 7), 61 | r)) ^ r
+ return ((r ^ (r >>> 14)) >>> 0) / 4294967296
+ }
+}
+
+function stable(v: unknown): string {
+ if (Array.isArray(v)) return `[${v.map(stable).join(',')}]`
+ if (v && typeof v === 'object') {
+ const o = v as Record<string, unknown>
+ return `{${Object.keys(o)
+ .sort()
+ .filter((k) => o[k] !== undefined)
+ .map((k) => `${JSON.stringify(k)}:${stable(o[k])}`)
+ .join(',')}}`
+ }
+ return JSON.stringify(v)
+}
+
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T
+
+// ---------------------------------------------------------------------------
+// order-key + merge-order unit properties
+// ---------------------------------------------------------------------------
+{
+ console.log('order keys and the symmetric row-order merge…')
+ const rnd = mulberry32(3)
+ const DIGITS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+ const randKey = () => {
+ let k = ''
+ const n = 1 + Math.floor(rnd() * 6)
+ for (let i = 0; i < n; i++) k += DIGITS[Math.floor(rnd() * 62)]
+ while (k.endsWith('0') && k.length > 1) k = k.slice(0, -1)
+ return k === '0' ? '1' : k
+ }
+ for (let i = 0; i < 10000; i++) {
+ let a = randKey()
+ let b = randKey()
+ if (a === b) continue
+ if (a > b) [a, b] = [b, a]
+ const m = keyBetween(a, b)
+ ok(a < m && m < b, `between(${a},${b}) = ${m} out of range`)
+ }
+ for (let n = 1; n <= 40; n++) {
+ for (let i = 0; i + 1 < n; i++) ok(spreadKey(i, n) < spreadKey(i + 1, n), `spreadKey(${i},${n}) not increasing`)
+ }
+ // SYMMETRY is the whole requirement: two forks that swap snapshots must land
+ // on one order, so mergeOrder(a,b) === mergeOrder(b,a) for every input.
+ for (let i = 0; i < 4000; i++) {
+ const universe = [1, 2, 3, 4, 5, 6, 7, 8]
+ const pick = (p: number) => universe.filter(() => rnd() < p)
+ const a = pick(0.7)
+ const b = pick(0.7)
+ const births = new Map<number, [number, string]>()
+ for (const r of universe) if (rnd() < 0.5) births.set(r, [Math.floor(rnd() * 5), rnd() < 0.5 ? 'A' : 'B'])
+ const bo = (r: number) => births.get(r)
+ const x = mergeOrder(a, b, bo)
+ const y = mergeOrder(b, a, bo)
+ ok(x.join(',') === y.join(','), `mergeOrder asymmetric: ${a} / ${b} → ${x} vs ${y}`)
+ ok(new Set(x).size === x.length, `mergeOrder duplicated: ${x}`)
+ ok(x.length === new Set([...a, ...b]).size, `mergeOrder lost rows: ${a} / ${b} → ${x}`)
+ }
+}
+
+// ---------------------------------------------------------------------------
+// simulated replicas
+// ---------------------------------------------------------------------------
+
+function baseDoc(): DashDoc {
+ return {
+ format: 'bento/dash',
+ version: 1,
+ docId: 'doc-1',
+ title: 'Rig workbook',
+ theme: { background: '#0D1B2E', color: '#F2F0EA', accent: '#FF9E8A', fontFamily: 'x' },
+ measures: { Revenue: { name: 'Revenue', expr: 'SUM(amount)', grain: 's1', additive: true } },
+ sheets: [
+ {
+ id: 's1',
+ name: 'Deals',
+ kind: 'table',
+ // one dict column (the default encoding, and the one with an interning
+ // hazard) and two raw ones, so every random run exercises both writers
+ rids: [[1, 6]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'money', scale: 2 },
+ { id: 'prob', name: 'Probability', type: 'percent' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['EMEA', 'AMER', 'APAC'], idx: [0, 1, 2, 0, 1, 2] },
+ amount: { enc: 'raw', v: [1200, 800, 4400, 150, 990, 2000] },
+ prob: { enc: 'raw', v: [0.4, 0.9, 0.25, 1, 0.6, 0.75] },
+ },
+ cells: { 'amount:3': { v: 4400, was: 4000, why: 'restated', by: 'rig' } },
+ totals: { amount: 'sum' },
+ steps: [{ op: 'import', from: 'rig.csv', at: '2026-08-01T00:00:00.000Z', rows: 6 }],
+ } as unknown as TableSheet,
+ {
+ id: 's2',
+ name: 'Rates',
+ kind: 'table',
+ rids: [[1, 3]],
+ columns: [
+ { id: 'ccy', name: 'Currency', type: 'text' },
+ { id: 'rate', name: 'Rate', type: 'number' },
+ ],
+ data: {
+ ccy: { enc: 'dict', dict: ['USD', 'EUR', 'GBP'], idx: [0, 1, 2] },
+ rate: { enc: 'raw', v: [1, 0.92, 0.79] },
+ },
+ steps: [],
+ } as unknown as TableSheet,
+ ],
+ modified: 'never',
+ } as unknown as DashDoc
+}
+
+const tables = (d: DashDoc): TableSheet[] => d.sheets.filter((s) => s.kind === 'table') as TableSheet[]
+
+/**
+ * Every column array must be exactly as long as the sheet has rows.
+ *
+ * Columnar storage addresses cells by POSITION, so a column that is one entry
+ * short does not report an error — it silently returns the next row's number
+ * for every row below the gap. That is the single worst failure this app can
+ * have, and it is invisible in a diff of the two documents until the values
+ * happen to differ. Checked after every single apply, on every replica.
+ */
+function checkShape(r: Replica, where: string): void {
+ for (const s of tables(r.doc)) {
+ const n = ridsOf(s).length
+ for (const [col, d] of Object.entries(s.data)) {
+ const len = d.enc === 'raw' ? d.v.length : d.enc === 'dict' ? d.idx.length : n
+ if (len !== n) {
+ ok(false, `${where} @${r.actor}: ${s.id}.${col} holds ${len} values for ${n} rows`)
+ return
+ }
+ }
+ }
+}
+/**
+ * A sheet's `rids` must be SORTED by (order key, rid), always.
+ *
+ * That is the fractional index's whole contract: order is a pure function of
+ * the keys, and `rowIndexFor` binary-searches the live list on the strength of
+ * it. Let the list fall out of sort once and every later insert lands somewhere
+ * arbitrary — the row order diverges while every register, birth and tomb still
+ * agrees, which is exactly what class 1 looked like from the outside.
+ * TRACE_ORDER=1 asserts it after every apply and names the first inversion.
+ */
+function checkOrder(r: Replica, where: string): void {
+ for (const s of tables(r.doc)) {
+ const rids = ridsOf(s)
+ for (let i = 1; i < rids.length; i++) {
+ const ka = r.state.rowOrderKey(s.id, rids[i - 1])
+ const kb = r.state.rowOrderKey(s.id, rids[i])
+ if (ka < kb || (ka === kb && rids[i - 1] < rids[i])) continue
+ ok(false, `${where} @${r.actor}: ${s.id} out of order at ${i}: rid ${rids[i - 1]} (${ka}) before rid ${rids[i]} (${kb})`)
+ return
+ }
+ }
+}
+const ridsOf = (s: TableSheet): number[] => _internals.rleExpand(s.rids)
+const dataCols = (s: TableSheet): string[] => s.columns.filter((c) => s.data[c.id]).map((c) => c.id)
+
+/**
+ * Take a deleted row's or column's overrides with it.
+ *
+ * rowcol.deleteRowsAt / deleteColumn do exactly this, in the same commit, and
+ * the rig has to model it or it is testing a patch the app never sends. It
+ * lives HERE rather than in the mutation menu because the store's inverses
+ * need it too: undoing an insertRows produces a bare `deleteRows`, and if the
+ * row picked up an override in the meantime the undo orphans it — on the
+ * undoing replica only, since every peer's engine strips it. That asymmetry is
+ * the one store.ts change this design actually needs (see docs/dash-collab.md).
+ */
+function normalize(doc: DashDoc, patches: Patch[]): Patch[] {
+ const out: Patch[] = []
+ for (const p of patches) {
+ const sheet = tables(doc).find((s) => s.id === (p as { sheet?: string }).sheet)
+ const keys = !sheet ? [] : Object.keys(sheet.cells ?? {}).filter((k) => {
+ if (p.op === 'deleteRows') return p.rids.includes(Number(k.slice(k.indexOf(':') + 1)))
+ if (p.op === 'removeColumn') return k.slice(0, k.indexOf(':')) === p.col
+ return false
+ })
+ if (keys.length) out.push({ op: 'setOverrides', sheet: sheet!.id, keys, v: keys.map(() => null), dropEmpty: true })
+ out.push(p)
+ }
+ return out
+}
+
+class Replica {
+ doc: DashDoc
+ state: DashSync
+ log: Op[] = []
+ undoStack: Patch[][] = []
+ actor: string
+ counter = 0
+ ridBase: number
+
+ constructor(actor: string, ridBase: number) {
+ this.actor = actor
+ this.ridBase = ridBase
+ this.doc = baseDoc()
+ this.state = new DashSync(actor)
+ this.state.adopt(this.doc)
+ }
+
+ /** the editor's commit path: mint ops for the patches, then apply them */
+ commit(patches: Patch[]): Op[] {
+ const list = normalize(this.doc, patches).filter((p) => committable(this.doc, p))
+ if (!list.length) return []
+ const ops = this.state.local(this.doc, list)
+ const inverse: Patch[] = []
+ for (const p of list) {
+ inverse.unshift(applyPatch(this.doc, p).inverse)
+ if (process.env.TRACE_SHAPE) {
+ const before = failures
+ checkShape(this, 'patch')
+ if (failures !== before) console.error(` patch was: ${JSON.stringify(p).slice(0, 300)}`)
+ }
+ }
+ if (process.env.TRACE_SHAPE) checkShape(this, 'pre-settle')
+ // a local change can be what a parked remote op was waiting for
+ this.state.settle(this.doc)
+ checkShape(this, 'commit')
+ if (process.env.TRACE_ORDER) checkOrder(this, 'commit')
+ this.undoStack.push(inverse)
+ this.log.push(...ops)
+ return ops
+ }
+
+ undo(): Op[] {
+ const e = this.undoStack.pop()
+ if (!e) return []
+ // NOT pushed back as a redo entry — the rig only needs the forward/inverse
+ // pair to exercise resurrection (undo of a delete = insert with values).
+ const list = normalize(this.doc, e).filter((p) => committable(this.doc, p))
+ if (!list.length) return []
+ const ops = this.state.local(this.doc, list)
+ for (const p of list) {
+ applyPatch(this.doc, p)
+ if (process.env.TRACE_SHAPE) {
+ const before = failures
+ checkShape(this, 'undo-patch')
+ if (failures !== before) console.error(` undo patch was: ${JSON.stringify(p).slice(0, 400)}`)
+ }
+ }
+ this.state.settle(this.doc)
+ checkShape(this, 'undo')
+ if (process.env.TRACE_ORDER) checkOrder(this, 'undo')
+ this.log.push(...ops)
+ return ops
+ }
+
+ /** sheet structure has no patch op in store.ts yet (see the design doc) */
+ addSheet(id: string, rid: number): Op[] {
+ const sheet = {
+ id, name: id, kind: 'table', rids: [[rid, 2]],
+ columns: [{ id: 'k', name: 'K', type: 'text' }, { id: 'n', name: 'N', type: 'number' }],
+ data: { k: { enc: 'dict', dict: ['a', 'b'], idx: [0, 1] }, n: { enc: 'raw', v: [1, 2] } },
+ steps: [],
+ } as unknown as TableSheet
+ this.doc.sheets.push(sheet)
+ const op = this.state.sheetIns(this.doc, sheet)
+ this.state.settle(this.doc)
+ this.log.push(op)
+ return [op]
+ }
+
+ delSheet(id: string): Op[] {
+ const i = this.doc.sheets.findIndex((s) => s.id === id)
+ if (i < 0) return []
+ const op = this.state.sheetDel(id)
+ this.doc.sheets.splice(i, 1)
+ this.state.settle(this.doc)
+ this.log.push(op)
+ return [op]
+ }
+
+ receive(ops: Op[]) {
+ this.state.apply(this.doc, ops)
+ checkShape(this, 'receive')
+ if (process.env.TRACE_ORDER) checkOrder(this, 'receive')
+ for (const o of ops) if (!this.log.some((x) => x.a === o.a && x.s === o.s)) this.log.push(o)
+ }
+
+ fingerprint(): string {
+ const d = clone(this.doc) as unknown as Record<string, unknown>
+ delete d.modified
+ // Dictionary ORDER is a local artefact: two replicas that interned the same
+ // strings in a different sequence hold the same values. Normalise to the
+ // materialized cell values, which is what the user and the file's readers
+ // see. (The saved file differs byte-for-byte; it does not differ in data.)
+ for (const s of (d.sheets as TableSheet[])) {
+ if (s.kind !== 'table') continue
+ const rids = ridsOf(s)
+ const flat: Record<string, unknown[]> = {}
+ for (const col of Object.keys(s.data)) {
+ const enc = s.data[col]
+ flat[col] = rids.map((_, i) =>
+ enc.enc === 'dict' ? (enc.idx[i] == null ? null : enc.dict[enc.idx[i]!] ?? null)
+ : enc.enc === 'raw' ? (enc.v[i] ?? null) : null)
+ }
+ ;(s as unknown as Record<string, unknown>).data = flat
+ }
+ return stable(d)
+ }
+
+ stateFingerprint(): string {
+ const j = this.state.toJSON() as unknown as Record<string, unknown>
+ // `stash` is deliberately excluded: it is a dead-window holding area whose
+ // contents legitimately differ (one replica parks a value at delete time,
+ // another never had it) and is only ever read through a register that both
+ // sides agree on. Same call slides' rig makes for dead-node text state.
+ return stable({ regs: j.regs, pos: j.pos, births: j.births, tombs: j.tombs, anchors: j.anchors, base: j.base, vv: j.vv })
+ }
+}
+
+// mutation menu — every entry is a patch the editor really commits
+function randomMutation(r: Replica, rnd: () => number): Patch[] {
+ const pick = <T>(xs: T[]): T => xs[Math.floor(rnd() * xs.length)]
+ const doc = r.doc
+ const sheets = tables(doc)
+ if (!sheets.length) return []
+ const sh = pick(sheets)
+ const rids = ridsOf(sh)
+ const kind = Math.floor(rnd() * 13)
+ switch (kind) {
+ case 0:
+ return [{ op: 'setTitle', title: `Workbook ${Math.floor(rnd() * 1000)}` }]
+ case 1: {
+ const name = pick(['Revenue', 'Margin', 'Pipeline'])
+ return rnd() < 0.3
+ ? [{ op: 'setMeasure', name }]
+ : [{ op: 'setMeasure', name, measure: { name, expr: `SUM(x${Math.floor(rnd() * 9)})`, grain: sh.id, additive: true } }]
+ }
+ case 2:
+ return [{ op: 'setSheetProps', sheet: sh.id, props: { name: `Sheet ${Math.floor(rnd() * 99)}` } }]
+ case 3: {
+ if (!sh.columns.length) return []
+ const c = pick(sh.columns)
+ return [{ op: 'setColumn', sheet: sh.id, col: c.id, patch: rnd() < 0.5 ? { name: `C${Math.floor(rnd() * 99)}` } : { w: 60 + Math.floor(rnd() * 200) } }]
+ }
+ case 4: {
+ const cols = dataCols(sh)
+ if (!cols.length || !rids.length) return []
+ const col = pick(cols)
+ const n = 1 + Math.floor(rnd() * Math.min(3, rids.length))
+ const chosen: number[] = []
+ while (chosen.length < n) {
+ const rid = pick(rids)
+ if (!chosen.includes(rid)) chosen.push(rid)
+ }
+ return [{ op: 'setCells', sheet: sh.id, col, rids: chosen, v: chosen.map(() => (rnd() < 0.3 ? pick(['EMEA', 'AMER', 'APAC', 'LATAM']) : Math.floor(rnd() * 9999))) }]
+ }
+ case 5: {
+ const cols = dataCols(sh)
+ if (!cols.length || !rids.length) return []
+ const key = `${pick(cols)}:${pick(rids)}`
+ return [{ op: 'setOverrides', sheet: sh.id, keys: [key], v: [rnd() < 0.35 ? null : { note: `n${Math.floor(rnd() * 99)}`, bg: '#eef' }], dropEmpty: true }]
+ }
+ case 6: {
+ const n = 1 + Math.floor(rnd() * 2)
+ const fresh = Array.from({ length: n }, () => r.ridBase + r.counter++)
+ const at = Math.floor(rnd() * (rids.length + 1))
+ const values: Record<string, unknown[]> = {}
+ for (const col of dataCols(sh)) values[col] = fresh.map(() => Math.floor(rnd() * 500))
+ return [{ op: 'insertRows', sheet: sh.id, rids: fresh, at: fresh.map((_, i) => at + i), values }]
+ }
+ case 7: {
+ if (rids.length < 2) return []
+ const n = 1 + Math.floor(rnd() * Math.min(2, rids.length - 1))
+ const chosen: number[] = []
+ while (chosen.length < n) {
+ const rid = pick(rids)
+ if (!chosen.includes(rid)) chosen.push(rid)
+ }
+ return [{ op: 'deleteRows', sheet: sh.id, rids: chosen }]
+ }
+ case 8: {
+ const id = `${r.actor}c${r.counter++}`
+ return [{
+ op: 'addColumn', sheet: sh.id, at: Math.floor(rnd() * (sh.columns.length + 1)),
+ column: { id, name: id, type: 'number' },
+ data: { enc: 'raw', v: rids.map(() => Math.floor(rnd() * 100)) },
+ }]
+ }
+ case 9: {
+ if (sh.columns.length < 2) return []
+ return [{ op: 'removeColumn', sheet: sh.id, col: pick(sh.columns).id }]
+ }
+ case 10: {
+ if (sh.columns.length < 2) return []
+ const order = sh.columns.map((c) => c.id)
+ const i = Math.floor(rnd() * order.length)
+ const [m] = order.splice(i, 1)
+ order.splice(Math.floor(rnd() * (order.length + 1)), 0, m)
+ return [{ op: 'reorderColumns', sheet: sh.id, order }]
+ }
+ default:
+ return []
+ }
+}
+
+// ---------------------------------------------------------------------------
+// random convergence runs
+// ---------------------------------------------------------------------------
+{
+ console.log('random convergence runs…')
+ const SEEDS = parseInt(process.env.SEEDS ?? '60', 10)
+ const SEED_ONLY = process.env.SEED_ONLY ? parseInt(process.env.SEED_ONLY, 10) : 0
+ const STEPS = parseInt(process.env.STEPS ?? '160', 10)
+ const W = parseInt(process.env.DIFF_WIDTH ?? '120', 10)
+ const ACTORS = parseInt(process.env.ACTORS ?? '3', 10)
+ if (process.env.DBG_NODE) (globalThis as Record<string, unknown>).__dbgNode = process.env.DBG_NODE
+ for (let seed = SEED_ONLY || 1; seed <= (SEED_ONLY || SEEDS); seed++) {
+ const rnd = mulberry32(seed * 7919)
+ const N = ACTORS
+ // rid spaces never overlap between actors: rids are minted at insert and
+ // NEVER reused (rowcol.ts), and two actors minting the same number would be
+ // two different rows claiming one identity — the exact failure this whole
+ // scheme rests on not happening.
+ const reps = Array.from({ length: N }, (_, i) => new Replica(`a${i}`, 1000 * (i + 1)))
+ const queues = new Map<string, Op[][]>()
+ const qk = (f: number, t: number) => `${f}>${t}`
+ for (let f = 0; f < N; f++) for (let t = 0; t < N; t++) if (f !== t) queues.set(qk(f, t), [])
+
+ for (let s = 0; s < STEPS; s++) {
+ if (rnd() < 0.45) {
+ const i = Math.floor(rnd() * N)
+ const r = reps[i]
+ ;(globalThis as Record<string, unknown>).__dbgTag = `mut@${r.actor}`
+ const dice = rnd()
+ const ops = dice < 0.06 ? r.undo()
+ : dice < 0.09 ? r.addSheet(`${r.actor}s${r.counter++}`, r.ridBase + 500 + r.counter)
+ : dice < 0.11 ? (tables(r.doc).length > 1 ? r.delSheet(tables(r.doc)[Math.floor(rnd() * tables(r.doc).length)].id) : [])
+ : r.commit(randomMutation(r, rnd))
+ if (ops.length) for (let t = 0; t < N; t++) if (t !== i) queues.get(qk(i, t))!.push(ops)
+ } else {
+ const edges = [...queues.entries()].filter(([, q]) => q.length)
+ if (!edges.length) continue
+ const [key, q] = edges[Math.floor(rnd() * edges.length)]
+ const to = parseInt(key.split('>')[1], 10)
+ ;(globalThis as Record<string, unknown>).__dbgTag = `recv@${reps[to].actor}`
+ reps[to].receive(q.shift()!)
+ }
+ }
+ let moved = true
+ while (moved) {
+ moved = false
+ for (const [key, q] of queues) {
+ if (!q.length) continue
+ moved = true
+ const to = parseInt(key.split('>')[1], 10)
+ ;(globalThis as Record<string, unknown>).__dbgTag = `drain@${reps[to].actor}`
+ reps[to].receive(q.shift()!)
+ }
+ }
+ const fp0 = reps[0].fingerprint()
+ const st0 = reps[0].stateFingerprint()
+ let bad = false
+ for (let i = 1; i < N; i++) {
+ ok(reps[i].fingerprint() === fp0, `seed ${seed}: workbook diverged (replica ${i})`)
+ ok(reps[i].stateFingerprint() === st0, `seed ${seed}: sync state diverged (replica ${i})`)
+ if (reps[i].fingerprint() !== fp0 || reps[i].stateFingerprint() !== st0) bad = true
+ }
+ if (bad) {
+ for (const part of ['regs', 'pos', 'births', 'tombs', 'anchors', 'vv'] as const) {
+ const p0 = stable((reps[0].state.toJSON() as unknown as Record<string, unknown>)[part])
+ for (let i = 1; i < N; i++) {
+ const pi = stable((reps[i].state.toJSON() as unknown as Record<string, unknown>)[part])
+ if (pi === p0) continue
+ let d = 0
+ while (d < p0.length && p0[d] === pi[d]) d++
+ console.error(` seed ${seed} ${part} differs @${d}:\n r0: …${p0.slice(Math.max(0, d - 60), d + 140)}\n r${i}: …${pi.slice(Math.max(0, d - 60), d + 140)}`)
+ }
+ }
+ for (let i = 1; i < N; i++) {
+ const fi = reps[i].fingerprint()
+ if (fi === fp0) continue
+ let d = 0
+ while (d < fp0.length && fp0[d] === fi[d]) d++
+ console.error(` seed ${seed} workbook differs @${d}:\n r0: …${fp0.slice(Math.max(0, d - W), d + W * 2)}\n r${i}: …${fi.slice(Math.max(0, d - W), d + W * 2)}`)
+ }
+ break
+ }
+ }
+}
+
+// ---------------------------------------------------------------------------
+// targeted semantics
+// ---------------------------------------------------------------------------
+
+const pair = () => [new Replica('A', 1000), new Replica('B', 2000)] as const
+const sheet1 = (r: Replica) => tables(r.doc)[0]
+const cellAt = (r: Replica, col: string, rid: number): unknown => {
+ const s = sheet1(r)
+ const i = ridsOf(s).indexOf(rid)
+ const d = s.data[col]
+ if (i < 0 || !d) return undefined
+ return d.enc === 'dict' ? (d.idx[i] == null ? null : d.dict[d.idx[i]!]) : d.enc === 'raw' ? d.v[i] : null
+}
+
+{
+ console.log('per-cell LWW: different cells in one row both survive…')
+ const [A, B] = pair()
+ const oa = A.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [2], v: [999] }])
+ const ob = B.commit([{ op: 'setCells', sheet: 's1', col: 'prob', rids: [2], v: [0.11] }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'per-cell converged')
+ ok(cellAt(A, 'amount', 2) === 999 && cellAt(A, 'prob', 2) === 0.11, 'both edits kept')
+}
+{
+ console.log('same cell concurrently: one wins, both agree…')
+ const [A, B] = pair()
+ const oa = A.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [1], v: [111] }])
+ const ob = B.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [1], v: [222] }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'same-cell race converged')
+ ok(cellAt(A, 'amount', 1) === cellAt(B, 'amount', 1), 'one value on both sides')
+}
+{
+ console.log('dictionary column: concurrent writes of new strings both intern…')
+ const [A, B] = pair()
+ const oa = A.commit([{ op: 'setCells', sheet: 's1', col: 'region', rids: [1], v: ['LATAM'] }])
+ const ob = B.commit([{ op: 'setCells', sheet: 's1', col: 'region', rids: [4], v: ['JAPAN'] }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'dict writes converged')
+ ok(cellAt(A, 'region', 1) === 'LATAM' && cellAt(A, 'region', 4) === 'JAPAN', 'both strings landed')
+ ok(cellAt(B, 'region', 1) === 'LATAM' && cellAt(B, 'region', 4) === 'JAPAN', 'both strings landed on B')
+}
+{
+ console.log('row RGA: concurrent inserts at the same anchor converge…')
+ const [A, B] = pair()
+ const oa = A.commit([{ op: 'insertRows', sheet: 's1', rids: [1001], at: [3], values: { amount: [7] } }])
+ const ob = B.commit([{ op: 'insertRows', sheet: 's1', rids: [2001], at: [3], values: { amount: [8] } }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'same-anchor inserts converged')
+ const order = ridsOf(sheet1(A))
+ ok(order.includes(1001) && order.includes(2001), 'both rows kept')
+ ok(Math.abs(order.indexOf(1001) - order.indexOf(2001)) === 1, `both landed at the anchor: ${order}`)
+ ok(order.indexOf(1001) === 3 || order.indexOf(2001) === 3, `first of the two sits at the anchor: ${order}`)
+}
+{
+ console.log('row RGA: insert anchored to a row the peer deleted…')
+ const [A, B] = pair()
+ // A inserts after rid 3; B deletes rid 3 concurrently. The insert must still
+ // land where rid 3 WAS — that is what the anchor chain is for.
+ const oa = A.commit([{ op: 'insertRows', sheet: 's1', rids: [1001], at: [3], values: { amount: [7] } }])
+ const ob = B.commit([{ op: 'deleteRows', sheet: 's1', rids: [3] }]) // normalize() adds the override sweep
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'insert-vs-delete-anchor converged')
+ const order = ridsOf(sheet1(A))
+ ok(!order.includes(3), 'deleted row gone')
+ ok(order.indexOf(1001) === 2, `insert kept its place: ${order}`)
+}
+{
+ console.log('delete-wins over a concurrent cell edit…')
+ const [A, B] = pair()
+ const oa = A.commit([{ op: 'deleteRows', sheet: 's1', rids: [2] }])
+ const ob = B.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [2], v: [5555] }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'delete-wins converged')
+ ok(!ridsOf(sheet1(A)).includes(2), 'row gone on A')
+ ok(!ridsOf(sheet1(B)).includes(2), 'row gone on B')
+}
+{
+ console.log('undo of a row delete resurrects it, and a dead-window edit wins…')
+ const [A, B] = pair()
+ const del = A.commit([{ op: 'deleteRows', sheet: 's1', rids: [2] }])
+ const edit = B.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [2], v: [5555] }])
+ B.receive(del)
+ const back = A.undo() // resurrect with A's values
+ A.receive(edit)
+ B.receive(back)
+ ok(A.fingerprint() === B.fingerprint(), 'resurrection converged')
+ ok(ridsOf(sheet1(A)).includes(2), 'row is back')
+ // B's edit carries a higher (lamport, actor) than the resurrection on both
+ // sides, so the stash has to replay it — otherwise the two replicas show
+ // different numbers for the same cell, which is the whole nightmare.
+ ok(cellAt(A, 'amount', 2) === cellAt(B, 'amount', 2), 'one value after resurrection')
+}
+{
+ // Regression for the divergence random seeds 124/307 found, built by hand so
+ // it can be read. TWO independent asymmetries lived under the same symptom
+ // (identical sync state, workbooks differing by one or two cells) and each
+ // one gets its own case, because each one fails on its own.
+ console.log('a column re-added by undo out-stamps a value parked in its dead window…')
+ // The interleaving, minimal (three replicas because it needs a delete and a
+ // write from DIFFERENT actors — per-actor delivery is contiguous, so one
+ // actor cannot hand B its write after its own delete):
+ //
+ // C deletes row 2 [1,C]
+ // A writes amount:2 = 5555 [1,A]
+ // B hears the delete, then the write → the value PARKS (its row is dead)
+ // C undoes the delete [2,C] (row 2 comes back)
+ // B removes the amount column [2,B]
+ // B undoes that [3,B] ← the column's REBIRTH
+ // B finally hears C's resurrection [2,C]
+ //
+ // A column insert is a whole-column assignment, so [3,B] supersedes the [1,A]
+ // write. Every replica that reaches the rebirth through resetColumnValues
+ // says so. B reaches it through replayStashRow instead — the row reappears
+ // after the column does — and that path used to weigh the parked value only
+ // against the ROW's birth, so B alone restored a number nobody else had.
+ const A = new Replica('A', 1000)
+ const B = new Replica('B', 2000)
+ const C = new Replica('C', 3000)
+ const cDel = C.commit([{ op: 'deleteRows', sheet: 's1', rids: [2] }])
+ const aWrite = A.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [2], v: [5555] }])
+ B.receive(cDel)
+ B.receive(aWrite) // row 2 is dead here: 5555 parks against [1,A]
+ const cBack = C.undo() // row 2 returns, carrying C's own values
+ const bDel = B.commit([{ op: 'removeColumn', sheet: 's1', col: 'amount' }])
+ const bBack = B.undo() // the column returns at a lamport ABOVE the parked write
+ B.receive(cBack)
+ for (const ops of [cDel, aWrite, cBack, bDel, bBack]) {
+ for (const r of [A, B, C]) r.receive(ops.filter((o) => o.a !== r.actor))
+ }
+ ok(A.fingerprint() === B.fingerprint(), 'column-rebirth vs parked value converged (A/B)')
+ ok(A.fingerprint() === C.fingerprint(), 'column-rebirth vs parked value converged (A/C)')
+ ok(sheet1(B).columns.some((c) => c.id === 'amount'), 'the column came back')
+ ok(ridsOf(sheet1(B)).includes(2), 'the row came back')
+ // The rebirth blanks it. What matters is that ALL THREE say the same thing;
+ // the value is asserted too so a future change cannot make them agree on the
+ // wrong answer by dropping the column entirely.
+ ok(cellAt(B, 'amount', 2) === null, `parked value loses to the column rebirth: ${cellAt(B, 'amount', 2)}`)
+ ok(cellAt(A, 'amount', 2) === null && cellAt(C, 'amount', 2) === null, 'and loses on every replica')
+}
+{
+ console.log('undo does not truncate a dictionary a collaborator grew…')
+ // The other half of the same symptom, and it needs no dead node at all.
+ //
+ // `setCells`'s inverse carries `dictLen`, the length the column's dictionary
+ // had before the edit, and store.ts honours it with `dict.length = dictLen`.
+ // Sound for one writer. Under collab a peer's write interns ITS strings into
+ // the same dictionary above that watermark, so the undo drops them and every
+ // cell pointing at them reads back null — on the undoing replica only, with
+ // not one register, birth or tomb moving. `local()` therefore disarms
+ // `dictLen` on the patch before the store sees it.
+ const [A, B] = pair()
+ const bWrite = B.commit([{ op: 'setCells', sheet: 's1', col: 'region', rids: [1], v: ['LATAM'] }])
+ const aWrite = A.commit([{ op: 'setCells', sheet: 's1', col: 'region', rids: [4], v: ['JAPAN'] }])
+ B.receive(aWrite) // 'JAPAN' interns ABOVE the watermark B's inverse recorded
+ const bUndo = B.undo() // restores region:1, and used to take 'JAPAN' with it
+ A.receive(bWrite)
+ A.receive(bUndo)
+ ok(A.fingerprint() === B.fingerprint(), 'undo-vs-interning converged')
+ ok(cellAt(B, 'region', 4) === 'JAPAN', `the collaborator's string survived the undo: ${cellAt(B, 'region', 4)}`)
+ ok(cellAt(B, 'region', 1) === 'EMEA', `the undo still restored its own cell: ${cellAt(B, 'region', 1)}`)
+}
+{
+ // Regression for the row-ORDER divergence that random seed 116 found at six
+ // actors, built by hand so the interleaving can be read.
+ console.log('a row resurrected twice takes the WINNING insert\'s place…')
+ //
+ // Baseline s1 is rids 1…6 with order keys 8r Hi QZ ZQ iH r8 (spreadKey(i,6)).
+ //
+ // C inserts row 3001 between rid 2 and rid 3 [1,C] key 'LC'
+ // A deletes rid 3, having never heard of 3001 [1,A]
+ // B deletes rid 3, having never heard of 3001 [1,B]
+ // A undoes → rins rid 3 at index 2 [2,A] key 'QA'
+ // A's shadow is 1,2,4,5,6 — no 3001 — so the key is minted against
+ // rid 4, and 'QA' lands AFTER 3001.
+ // B hears 3001, THEN undoes → rins rid 3 at index 2 [2,B] key 'JB'
+ // B's shadow is 1,2,3001,4,5,6, so the key is minted against 3001 and
+ // lands BEFORE it.
+ //
+ // [2,B] out-stamps [2,A] on the actor tiebreak, so rid 3 belongs at 'JB',
+ // before 3001, on every replica. D hears A's insert first and therefore has
+ // the row in the document ALREADY when B's winning insert arrives; E hears
+ // B's first and discards A's at the "an older create" gate. Both end holding
+ // the same `rpos`, the same births and the same tombs — and, before the fix,
+ // two different row sequences, because the already-here branch recorded the
+ // new key without moving the row. Worse, D's `rids` was then no longer sorted
+ // by (key, rid), so every later insert's binary search landed arbitrarily.
+ const A = new Replica('A', 1000)
+ const B = new Replica('B', 2000)
+ const C = new Replica('C', 3000)
+ const D = new Replica('D', 4000)
+ const E = new Replica('E', 5000)
+ const cIns = C.commit([{ op: 'insertRows', sheet: 's1', rids: [3001], at: [2], values: { amount: [55] } }])
+ const aDel = A.commit([{ op: 'deleteRows', sheet: 's1', rids: [3] }])
+ const bDel = B.commit([{ op: 'deleteRows', sheet: 's1', rids: [3] }])
+ const aIns = A.undo()
+ B.receive(cIns)
+ const bIns = B.undo()
+ // D: the loser's insert first, so the row is already present when the winner
+ // arrives. E: the winner's insert first.
+ for (const ops of [cIns, aDel, aIns, bDel, bIns]) D.receive(ops)
+ for (const ops of [cIns, bDel, bIns, aDel, aIns]) E.receive(ops)
+ for (const ops of [cIns, aDel, aIns, bDel, bIns]) for (const r of [A, B, C]) r.receive(ops.filter((o) => o.a !== r.actor))
+ const want = [1, 2, 3, 3001, 4, 5, 6].join(',')
+ for (const r of [A, B, C, D, E]) {
+ ok(ridsOf(sheet1(r)).join(',') === want, `${r.actor} row order: ${ridsOf(sheet1(r))}`)
+ checkOrder(r, 'twice-resurrected')
+ }
+ ok(D.fingerprint() === E.fingerprint(), 'loser-first and winner-first replicas agree')
+ ok(A.fingerprint() === D.fingerprint(), 'and so does every other replica')
+}
+{
+ // Regression for the value loss random seeds 374 and 184 found. Same
+ // symptom as 307 (identical sync state, one cell different) and a different
+ // asymmetry: nothing is deleted twice here except the ROW.
+ console.log('a second resurrection that does not name a column keeps its value…')
+ //
+ // A adds column `note`, values n1…n6 [1,A] ins + [2,A] cell
+ // B hears it
+ // A deletes rid 2 [3,A]
+ // A undoes → rins rid 2, payload NAMES `note` [4,A] (note = 'n2')
+ // C edits its own title three times [1,C]…[3,C]
+ // C deletes rid 2 — C has never heard of `note` [4,C]
+ // C undoes → rins rid 2, payload does NOT name `note` [5,C] ← wins
+ //
+ // C's insert wins the birth race, so `rnamed` for the row is rewritten to
+ // C's three columns and the record that [4,A] ever claimed `note` is gone.
+ // On every replica that processed A's pair first, 'n2' was parked under the
+ // [4,A] authority at C's delete; the replay then asked
+ // `cellAuth(…, fromRow:false)` for a verdict, got the bare cell register
+ // [2,A], failed the stale guard and dropped the value — leaving a blank.
+ // C itself never held a parked copy (it discards [4,A] as an older create
+ // and gets 'n2' straight from the pended cell op when the column finally
+ // lands), so the MINORITY replica was the correct one: an insert that does
+ // not name a column makes no claim on it, and nothing superseded the value.
+ const A = new Replica('A', 1000)
+ const B = new Replica('B', 2000)
+ const C = new Replica('C', 3000)
+ const D = new Replica('D', 4000)
+ const E = new Replica('E', 5000)
+ const aCol = A.commit([{ op: 'addColumn', sheet: 's1', column: { id: 'note', name: 'Note', type: 'text' }, data: { enc: 'raw', v: ['n1', 'n2', 'n3', 'n4', 'n5', 'n6'] } }])
+ B.receive(aCol)
+ const aDel = A.commit([{ op: 'deleteRows', sheet: 's1', rids: [2] }])
+ const aIns = A.undo()
+ const cT: Op[] = []
+ for (let i = 0; i < 3; i++) cT.push(...C.commit([{ op: 'setTitle', title: `t${i}` }]))
+ const cDel = C.commit([{ op: 'deleteRows', sheet: 's1', rids: [2] }])
+ const cIns = C.undo() // [5,C] — out-stamps A's [4,A] resurrection
+ // D takes A's pair before C's; E takes C's first. Neither may lose 'n2'.
+ for (const ops of [aCol, aDel, aIns, cT, cDel, cIns]) D.receive(ops)
+ for (const ops of [cT, cDel, cIns, aCol, aDel, aIns]) E.receive(ops)
+ for (const ops of [aCol, aDel, aIns, cT, cDel, cIns]) for (const r of [A, B, C]) r.receive(ops.filter((o) => o.a !== r.actor))
+ for (const r of [A, B, C, D, E]) {
+ ok(ridsOf(sheet1(r)).includes(2), `${r.actor}: the row is back`)
+ ok(cellAt(r, 'note', 2) === 'n2', `${r.actor}: the uncarried column keeps its value: ${cellAt(r, 'note', 2)}`)
+ }
+ ok(D.fingerprint() === E.fingerprint(), 'both delivery orders agree')
+ ok(C.fingerprint() === D.fingerprint(), 'and the second resurrector agrees with them')
+}
+{
+ // Regression for the third asymmetry of the same family, found by random
+ // seed 163 at six actors while sweeping the two above.
+ console.log('a row insert does not clobber a NEWER value parked for a buried column…')
+ //
+ // B deletes rid 2 [1,B]
+ // B undoes → rins rid 2, payload names `region` [2,B]
+ // C removes the `region` column [1,C]
+ // C undoes → the column comes back [2,C]
+ // A (hearing none of it) types four titles [1,A]…[4,A]
+ // A writes region:2 = '9917' [5,A] ← newest
+ // A then receives, in this order: B's delete, C's column removal,
+ // B's resurrection, C's column undo.
+ //
+ // A's write out-stamps everything, so '9917' is the answer on every replica.
+ // Every OTHER replica gets there without trying: the write reaches them while
+ // the column is buried, `applyCell` parks the op on the column node, and the
+ // column's return replays it. A is the author — its write went straight into
+ // a live document and was never queued anywhere, so the parked copy made at
+ // the row's death is the only record it has. B's resurrection then walked the
+ // columns its payload named and overwrote that copy with the payload's own
+ // (older) value, and the column's return read a stash entry whose stamp no
+ // longer matched the cell's authority and blanked the cell. Five replicas
+ // with a number, its author with a blank.
+ const A = new Replica('A', 1000)
+ const B = new Replica('B', 2000)
+ const C = new Replica('C', 3000)
+ const D = new Replica('D', 4000)
+ const bDel = B.commit([{ op: 'deleteRows', sheet: 's1', rids: [2] }])
+ const bIns = B.undo()
+ const cDel = C.commit([{ op: 'removeColumn', sheet: 's1', col: 'region' }])
+ const cAdd = C.undo()
+ const aOps: Op[] = []
+ for (let i = 0; i < 4; i++) aOps.push(...A.commit([{ op: 'setTitle', title: `t${i}` }]))
+ const aWrite = A.commit([{ op: 'setCells', sheet: 's1', col: 'region', rids: [2], v: ['9917'] }])
+ // the order that leaves A holding nothing but the parked copy
+ for (const ops of [bDel, cDel, bIns, cAdd]) A.receive(ops)
+ for (const ops of [bDel, bIns, cDel, cAdd, aOps, aWrite]) D.receive(ops)
+ for (const ops of [bDel, bIns, cDel, cAdd, aOps, aWrite]) for (const r of [A, B, C]) r.receive(ops.filter((o) => o.a !== r.actor))
+ for (const r of [A, B, C, D]) {
+ ok(sheet1(r).columns.some((c) => c.id === 'region'), `${r.actor}: the column came back`)
+ ok(cellAt(r, 'region', 2) === '9917', `${r.actor}: the newest write survived: ${cellAt(r, 'region', 2)}`)
+ }
+ ok(A.fingerprint() === D.fingerprint(), 'the write\'s author agrees with a replica that only received it')
+ ok(B.fingerprint() === C.fingerprint(), 'and the row and column undoers agree too')
+}
+{
+ console.log('column add/remove and reorder converge…')
+ const [A, B] = pair()
+ const oa = A.commit([{ op: 'addColumn', sheet: 's1', at: 1, column: { id: 'newA', name: 'New A', type: 'number' }, data: { enc: 'raw', v: [1, 2, 3, 4, 5, 6] } }])
+ const ob = B.commit([{ op: 'removeColumn', sheet: 's1', col: 'prob' }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'column add/remove converged')
+ ok(sheet1(A).columns.some((c) => c.id === 'newA'), 'added column present')
+ ok(!sheet1(A).columns.some((c) => c.id === 'prob'), 'removed column gone')
+ const oc = A.commit([{ op: 'reorderColumns', sheet: 's1', order: sheet1(A).columns.map((c) => c.id).reverse() }])
+ B.receive(oc)
+ ok(A.fingerprint() === B.fingerprint(), 'reorder converged')
+}
+{
+ console.log('column data arrives aligned by rid, not by position…')
+ const [A, B] = pair()
+ // B's row order diverges FIRST, so a positionally-copied column would land
+ // its values on the wrong rows — the silent-wrong-number failure.
+ const ob = B.commit([{ op: 'insertRows', sheet: 's1', rids: [2001], at: [0], values: { amount: [42] } }])
+ const oa = A.commit([{ op: 'addColumn', sheet: 's1', column: { id: 'tag', name: 'Tag', type: 'text' }, data: { enc: 'raw', v: ['r1', 'r2', 'r3', 'r4', 'r5', 'r6'] } }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'column-align converged')
+ ok(cellAt(B, 'tag', 1) === 'r1' && cellAt(B, 'tag', 6) === 'r6', 'values follow their rids')
+ ok(cellAt(B, 'tag', 2001) === null, 'the row A never saw gets a blank, not a shifted value')
+}
+{
+ console.log('sheet delete beats concurrent edits inside it…')
+ const [A, B] = pair()
+ const oa = A.delSheet('s2')
+ const ob = B.commit([{ op: 'setCells', sheet: 's2', col: 'rate', rids: [2], v: [1.11] }])
+ A.receive(ob)
+ B.receive(oa)
+ ok(A.fingerprint() === B.fingerprint(), 'sheet delete converged')
+ ok(!A.doc.sheets.some((s) => s.id === 's2'), 'sheet gone on A')
+ ok(!B.doc.sheets.some((s) => s.id === 's2'), 'sheet gone on B')
+}
+{
+ console.log('gap buffering + catch-up…')
+ const [A, B] = pair()
+ const b1 = A.commit([{ op: 'setTitle', title: 'one' }])
+ const b2 = A.commit([{ op: 'setTitle', title: 'two' }])
+ const b3 = A.commit([{ op: 'setTitle', title: 'three' }])
+ B.receive(b3)
+ ok(B.doc.title === 'Rig workbook', 'gapped op held back')
+ ok(B.state.gappedActors.includes('A'), 'gap detected for catch-up')
+ B.receive(b1)
+ ok(B.doc.title === 'one', 'first op applied, gap persists')
+ B.receive(b2)
+ ok(B.doc.title === 'three', 'gap drained in order')
+ ok(A.fingerprint() === B.fingerprint(), 'gap run converged')
+}
+{
+ console.log('op-log catch-up (missingFor)…')
+ const [A, B] = pair()
+ const first = A.commit([{ op: 'setTitle', title: 'x1' }])
+ A.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [1], v: [17] }])
+ A.commit([{ op: 'insertRows', sheet: 's1', rids: [1005], at: [1], values: { amount: [3] } }])
+ B.receive(first)
+ const missing = B.state.missingFor(A.log, B.state.toJSON().vv)
+ B.receive(missing)
+ ok(A.fingerprint() === B.fingerprint(), 'log catch-up converged')
+}
+{
+ console.log('snapshot merge: two offline forks, both ways…')
+ const [A, B] = pair()
+ A.commit([{ op: 'setTitle', title: 'A says' }])
+ A.commit([{ op: 'setCells', sheet: 's1', col: 'amount', rids: [1], v: [10] }])
+ A.commit([{ op: 'insertRows', sheet: 's1', rids: [1001], at: [2], values: { amount: [77] } }])
+ B.commit([{ op: 'setCells', sheet: 's1', col: 'prob', rids: [5], v: [0.05] }])
+ B.commit([{ op: 'deleteRows', sheet: 's1', rids: [6] }])
+ B.commit([{ op: 'addColumn', sheet: 's1', column: { id: 'owner', name: 'Owner', type: 'text' }, data: { enc: 'raw', v: ['a', 'b', 'c', 'd', 'e'] } }])
+ const aDoc = clone(A.doc)
+ const aState = clone(A.state.toJSON())
+ const bDoc = clone(B.doc)
+ const bState = clone(B.state.toJSON())
+ A.state.mergeSnapshot(A.doc, bDoc, bState)
+ B.state.mergeSnapshot(B.doc, aDoc, aState)
+ ok(A.fingerprint() === B.fingerprint(), 'fork merge converged')
+ ok(A.doc.title === 'A says', 'A title survived')
+ ok(!ridsOf(sheet1(A)).includes(6), 'B delete survived')
+ ok(ridsOf(sheet1(A)).includes(1001), 'A insert survived')
+ ok(sheet1(A).columns.some((c) => c.id === 'owner'), 'B column survived')
+ ok(cellAt(A, 'amount', 1) === 10 && cellAt(A, 'prob', 5) === 0.05, 'both cell edits survived')
+ // a pristine third copy catches up from one snapshot alone
+ const C = new Replica('C', 3000)
+ C.state.mergeSnapshot(C.doc, clone(A.doc), clone(A.state.toJSON()))
+ ok(C.fingerprint() === A.fingerprint(), 'late joiner converged from a snapshot')
+}
+{
+ console.log('unsupported patches raise the snapshot flag rather than vanishing…')
+ const A = new Replica('A', 1000)
+ const ops = A.state.local(A.doc, [{ op: 'applySteps', sheet: 's1', steps: [] }] as unknown as Patch[])
+ ok(ops.length === 0 && A.state.unsynced, 'unmapped patch flagged for a state snapshot')
+}
+{
+ console.log('a foreign sync-state version is discarded, not misread…')
+ const A = new Replica('A', 1000)
+ const before = A.fingerprint()
+ const r = A.state.mergeSnapshot(A.doc, baseDoc(), { v: 99 } as never)
+ ok(!r.changed && A.fingerprint() === before, 'future-version snapshot ignored')
+ const s = DashSync.fromJSON('A', { v: 99, lamport: 5 } as never)
+ ok(s.lamport === 0, 'future-version state ignored by fromJSON')
+}
+{
+ console.log('row node ids stay composite (sheet-scoped rids)…')
+ ok(rowNode('s1', 7) !== rowNode('s2', 7), 'the same rid on two sheets is two nodes')
+}
+
+console.log(failures === 0 ? `\nALL PASS (${checks} checks)` : `\n${failures} FAILURES of ${checks} checks`)
+process.exit(failures ? 1 : 0)
diff --git a/scripts/test-dash-viz3d.ts b/scripts/test-dash-viz3d.ts
new file mode 100644
index 00000000..5eb275f1
--- /dev/null
+++ b/scripts/test-dash-viz3d.ts
@@ -0,0 +1,587 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash 3D visualisation rig — the GEOMETRY.
+//
+// node scripts/test-dash-viz3d.ts
+//
+// WHAT THIS PROVES. Nothing in 3D can be checked by looking at it. Every bug in
+// this file draws SOMETHING, confidently, and the reader has no way to know the
+// picture is wrong. The classes that matter:
+//
+// 1. A FLIPPED WINDING. Reverse the two triangles of a quad and the surface's
+// normals all point DOWN. It still renders; it is just lit from
+// underneath, which on an unfamiliar dataset reads as "the data is like
+// that". Pinned by asserting the normal of a FLAT grid is exactly +Y — the
+// one case where the right answer is known without argument.
+// 2. NORMALS THAT ARE NOT UNIT LENGTH. A normal of length 1.4 shades 40%
+// brighter, so the mesh has bright patches where triangles happen to be
+// large. Nothing is malformed, nothing errors, the surface just has
+// features that are not in the data.
+// 3. A DEGENERATE INPUT BECOMING NaN. One constant column divides by a zero
+// extent; every position in the scene becomes NaN; GL draws nothing and
+// says nothing. Checked on every scene this rig builds, and specifically
+// on the constant-column case.
+// 4. A MISSING VALUE BECOMING A ZERO. In a surface a coerced zero is not a
+// visible gap, it is a CRATER — and craters look like findings. The rows
+// must be dropped, the count must be reported, and the quad must not be
+// emitted.
+// 5. A RAMP THAT DOES NOT REACH ITS ENDS, or that mixes in sRGB. Both make a
+// plausible picture; the second puts a band of mud through the middle of
+// every surface, which reads as a ridge.
+// 6. A BLANK BOX WITHOUT WebGL2. The fallback must be a picture of the same
+// scene, and an empty scene must be a SENTENCE, never an empty rectangle.
+
+import {
+ buildScene, defaultViz3d, fallbackSvg, frameCamera,
+ computeNormals, latLonToXyz, shade, shadeWith, dirToView,
+ rampColor, mixRgb, hexToRgb, rgbToHex, RAMPS, LIGHT, AMBIENT,
+ _internals,
+ type Scene, type Mesh, type Viz3dBinding,
+} from '../dash/src/viz3d.ts'
+import { Orbit, normalize, sub } from '../dash/src/gl.ts'
+import type { ColumnData, ColumnType, TableSheet } from '../dash/src/model.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+const close = (a: number, b: number, eps = 1e-6) => Math.abs(a - b) <= eps
+
+function sheetOf(cols: Record<string, unknown[]>, types: Record<string, ColumnType> = {}): TableSheet {
+ const n = Object.values(cols)[0]?.length ?? 0
+ const rids: Array<[number, number]> = n ? [[1, n]] : []
+ return {
+ id: 'sh', name: 'S', kind: 'table', rids,
+ columns: Object.keys(cols).map((id) => ({ id, name: id, type: types[id] ?? 'number' })),
+ data: Object.fromEntries(Object.entries(cols).map(([k, v]): [string, ColumnData] =>
+ [k, { enc: 'raw', v: v as Array<number | string | boolean | null> }])),
+ steps: [],
+ }
+}
+
+/** Every float the GPU would read, checked for NaN/Infinity. */
+function sceneFinite(s: Scene): boolean {
+ const fin = (a: Float32Array | undefined) => {
+ if (!a) return true
+ for (let i = 0; i < a.length; i++) if (!Number.isFinite(a[i])) return false
+ return true
+ }
+ for (const m of s.meshes) {
+ if (!fin(m.positions) || !fin(m.colors) || !fin(m.normals) || !fin(m.sizes)) return false
+ if (m.indices) for (let i = 0; i < m.indices.length; i++) {
+ if (!Number.isFinite(m.indices[i]) || m.indices[i] * 3 >= m.positions.length) return false
+ }
+ }
+ const b = [...s.bounds.min, ...s.bounds.max, ...s.center, s.radius]
+ return b.every((v) => Number.isFinite(v)) && s.radius > 0
+}
+
+const unitNormals = (m: Mesh, eps = 1e-5): boolean => {
+ if (!m.normals) return true
+ for (let i = 0; i + 2 < m.normals.length; i += 3) {
+ if (Math.abs(Math.hypot(m.normals[i], m.normals[i + 1], m.normals[i + 2]) - 1) > eps) return false
+ }
+ return true
+}
+
+const meshOf = (s: Scene, mode: Mesh['mode']) => s.meshes.find((m) => m.mode === mode)!
+const triCount = (m: Mesh) => (m.indices ? m.indices.length : m.positions.length / 3) / 3
+const vertCount = (m: Mesh) => m.positions.length / 3
+
+// ============================================================= colour & ramps
+
+{
+ const stops = RAMPS.viridis.map(hexToRgb)
+ const a = rampColor(0, stops)
+ const z = rampColor(1, stops)
+ ok(close(a[0], stops[0][0]) && close(a[1], stops[0][1]) && close(a[2], stops[0][2]),
+ 'the ramp at t=0 is EXACTLY the first stop')
+ ok(close(z[0], stops[4][0]) && close(z[1], stops[4][1]) && close(z[2], stops[4][2]),
+ 'the ramp at t=1 is EXACTLY the last stop')
+ const mid = rampColor(0.5, stops)
+ ok(!close(mid[0], a[0]) || !close(mid[2], a[2]),
+ 'and the middle is neither end — a ramp that clamps to one colour is refused')
+ ok(rampColor(2, stops).every((v, i) => close(v, z[i])) && rampColor(-1, stops).every((v, i) => close(v, a[i])),
+ 'out-of-range t clamps rather than wrapping or extrapolating')
+ ok(rampColor(NaN, stops).every(Number.isFinite), 'a NaN t gives a colour, not NaN channels')
+
+ // the assertion a naive sRGB lerp fails: the midpoint of black and white is
+ // sqrt(0.5), not 0.5 — mixing in the display curve is what puts mud in the
+ // middle of every hand-rolled ramp
+ const grey = mixRgb([0, 0, 0], [1, 1, 1], 0.5)
+ ok(close(grey[0], Math.SQRT1_2, 1e-6), 'colours mix in LINEAR light (0.7071), not in sRGB (0.5)')
+ ok(!close(grey[0], 0.5, 0.05), 'and the naive sRGB midpoint is refused')
+
+ ok(rgbToHex(hexToRgb('#3B1E54')) === '#3b1e54', 'hex round-trips')
+ ok(rgbToHex(hexToRgb('#abc')) === '#aabbcc', 'three-digit hex expands')
+ ok(hexToRgb('not a colour').every(Number.isFinite), 'an unparseable colour is grey, not NaN')
+}
+
+// ================================================================== lighting
+
+{
+ ok(shade(LIGHT) > shade([-LIGHT[0], -LIGHT[1], -LIGHT[2]]),
+ 'a face turned toward the light is brighter than one turned away')
+ const away = shade([-LIGHT[0], -LIGHT[1], -LIGHT[2]])
+ ok(away > 0, 'and a face turned away is NOT black — an unlit face reads as a hole in the mesh')
+ ok(away <= AMBIENT, 'the away-facing value is at most the ambient term')
+ ok(shade([0, 1, 0]) <= 1 && shade(LIGHT) <= 1, 'shading never exceeds 1 (it would clip to white)')
+ ok(shade([0, 1, 0]) > shade([0, -1, 0]),
+ 'the hemisphere fill makes an upward face brighter than a downward one, so an unlit shape still reads')
+
+ // the view-space variant used by the point sprites must agree with the world
+ // one when handed matching bases
+ const cam = new Orbit()
+ cam.azimuth = 0.9
+ cam.elevation = 0.3
+ const lv = dirToView(cam.view(), LIGHT)
+ ok(close(Math.hypot(lv[0], lv[1], lv[2]), 1, 1e-9), 'the light stays unit length through the view rotation')
+ const fwdWorld = normalize(sub(cam.target, cam.eye()))
+ const fwdView = dirToView(cam.view(), fwdWorld)
+ ok(close(fwdView[0], 0, 1e-9) && close(fwdView[1], 0, 1e-9) && close(fwdView[2], -1, 1e-9),
+ 'a DIRECTION through the view matrix ignores the translation: forward becomes -Z')
+ ok(close(
+ lv[0] * fwdView[0] + lv[1] * fwdView[1] + lv[2] * fwdView[2],
+ LIGHT[0] * fwdWorld[0] + LIGHT[1] * fwdWorld[1] + LIGHT[2] * fwdWorld[2], 1e-9),
+ 'and the angle between light and view is preserved — the lighting does not swim when the camera moves')
+ ok(shadeWith([0, 0, 1], lv) > 0, 'a sprite facing the camera is lit')
+}
+
+// ================================================================== normals
+
+{
+ // one flat quad, wound the way the surface builder winds it
+ const pos = new Float32Array([-1, 0, -1, 1, 0, -1, -1, 0, 1, 1, 0, 1])
+ const idx = new Uint32Array([0, 2, 1, 1, 2, 3])
+ const n = computeNormals(pos, idx)
+ ok([0, 1, 2, 3].every((v) => close(n[v * 3], 0) && close(n[v * 3 + 1], 1) && close(n[v * 3 + 2], 0)),
+ 'a flat quad wound our way has normals of exactly +Y — the check a flipped winding fails')
+
+ const flipped = computeNormals(pos, new Uint32Array([0, 1, 2, 1, 3, 2]))
+ ok(close(flipped[1], -1), 'and reversing the winding really does give -Y, so the check above can fail')
+
+ // an unreferenced vertex has no face to average
+ const lone = computeNormals(new Float32Array([0, 0, 0, 1, 0, 0, 0, 0, 1, 5, 5, 5]), new Uint32Array([0, 2, 1]))
+ ok(close(Math.hypot(lone[9], lone[10], lone[11]), 1),
+ 'a vertex no triangle references gets +Y, not a zero normal that would shade pure black')
+}
+
+// ================================================================== 3D scatter
+
+const scatterSheet = sheetOf({
+ x: [1, 2, 3, 4, 5],
+ y: [10, 20, 30, 40, 50],
+ z: [5, 4, 3, 2, 1],
+ heat: [0, 25, 50, 75, 100],
+ mag: [1, 4, 9, 16, 25],
+})
+
+{
+ const s = buildScene(scatterSheet, { kind: 'scatter', x: 'x', y: 'y', z: 'z', color: 'heat', size: 'mag' })
+ const pts = meshOf(s, 'points')
+ ok(!s.empty && vertCount(pts) === 5, 'five clean rows give five points')
+ ok(pts.positions.length === 15 && pts.colors.length === 15 && pts.sizes!.length === 5,
+ 'positions, colours and sizes are all in step')
+ ok(sceneFinite(s), 'nothing in the scene is NaN')
+ ok(s.dropped === 0 && s.rows === 5, 'nothing was dropped')
+
+ ok(close(pts.positions[0], -1) && close(pts.positions[12], 1),
+ 'the smallest X sits at -1 and the largest at +1')
+ ok(close(pts.positions[2], 1) && close(pts.positions[14], -1),
+ 'and Z is scaled on its OWN axis — a shared scale would flatten it')
+
+ const stops = RAMPS.viridis.map(hexToRgb)
+ ok(close(pts.colors[0], stops[0][0], 1e-6) && close(pts.colors[12], stops[4][0], 1e-6),
+ 'the colour column maps its extremes to the ramp extremes')
+ ok(!close(pts.colors[0], pts.colors[6], 1e-3), 'and the middle rows get different colours')
+
+ // AREA, not radius. mag runs 1,4,9,16,25, so t is 0, 0.125, 0.333, 0.625, 1.
+ const r0 = pts.sizes![0], r4 = pts.sizes![4], r2 = pts.sizes![2]
+ const areaFrac = (r2 * r2 - r0 * r0) / (r4 * r4 - r0 * r0)
+ ok(close(areaFrac, 1 / 3, 1e-5), 'point AREA is linear in the value — the readable encoding')
+ ok(!close((r2 - r0) / (r4 - r0), 1 / 3, 1e-3),
+ 'and the value is NOT mapped straight to the radius, which would exaggerate by the square')
+
+ ok(s.meshes.some((m) => m.mode === 'lines'), 'a bounding frame ships with the points (the depth cue)')
+ ok(s.axes.length === 3 && s.axes[0].min === 1 && s.axes[0].max === 5,
+ 'the axes carry the REAL numbers, since the geometry no longer does')
+}
+
+{
+ // one row with text where a coordinate belongs
+ const s = buildScene(sheetOf({ x: [1, 2, 'n/a', 4, 5], y: [1, 2, 3, 4, 5], z: [1, 2, 3, 4, 5] }),
+ { kind: 'scatter', x: 'x', y: 'y', z: 'z' })
+ ok(vertCount(meshOf(s, 'points')) === 4, 'a row without a number in every axis is DROPPED, not plotted at 0')
+ ok(s.dropped === 1 && s.rows === 5, 'and the drop is counted, so the view can say so')
+ ok(sceneFinite(s), 'the surviving geometry is finite')
+}
+
+{
+ // a categorical colour column
+ const s = buildScene(
+ sheetOf({ x: [1, 2, 3], y: [1, 2, 3], z: [1, 2, 3], r: ['North', 'South', 'North'] }, { r: 'text' }),
+ { kind: 'scatter', x: 'x', y: 'y', z: 'z', color: 'r' },
+ )
+ const pts = meshOf(s, 'points')
+ ok(close(pts.colors[0], pts.colors[6]) && !close(pts.colors[0], pts.colors[3]),
+ 'a text colour column gives equal categories equal colours and different ones different')
+ ok(s.legend?.kind === 'categories' && s.legend.items?.length === 2, 'and the legend lists the categories')
+}
+
+{
+ // the degenerate case that turns everything into NaN if it is not guarded
+ const s = buildScene(sheetOf({ x: [7, 7, 7], y: [1, 2, 3], z: [1, 2, 3] }),
+ { kind: 'scatter', x: 'x', y: 'y', z: 'z' })
+ const pts = meshOf(s, 'points')
+ ok(sceneFinite(s), 'a CONSTANT column does not divide by a zero extent — no NaN anywhere')
+ ok(close(pts.positions[0], 0) && close(pts.positions[3], 0) && close(pts.positions[6], 0),
+ 'its points collapse onto 0 rather than to NaN or to the edge of the box')
+}
+
+// ==================================================================== surface
+
+/** 3x3 samples of z over x,y in {0,1,2} — the known-answer grid. */
+function gridRows(skip: Array<[number, number]> = []) {
+ const x: number[] = [], y: number[] = [], z: number[] = []
+ for (let j = 0; j < 3; j++) {
+ for (let i = 0; i < 3; i++) {
+ if (skip.some(([a, b]) => a === i && b === j)) continue
+ x.push(i); y.push(j); z.push(i * 3 + j)
+ }
+ }
+ return sheetOf({ x, y, z })
+}
+
+{
+ const s = buildScene(gridRows(), { kind: 'surface', x: 'x', y: 'y', z: 'z' })
+ const m = meshOf(s, 'triangles')
+ ok(vertCount(m) === 9, 'a 3x3 grid is 9 vertices — one per SAMPLE, shared between quads')
+ ok(triCount(m) === 8, 'and 8 triangles: (3-1) x (3-1) quads, two triangles each')
+ ok(m.indices!.length === 24, 'so 24 indices')
+ ok(unitNormals(m), 'every surface normal is unit length')
+ ok(sceneFinite(s) && s.dropped === 0, 'the scene is finite and nothing was dropped')
+ ok(m.cull === false, 'the surface is NOT marked cullable — it must stay visible from below')
+
+ const stops = RAMPS.viridis.map(hexToRgb)
+ // z runs 0..8; cell (0,0) is the minimum, (2,2) the maximum
+ ok(close(m.colors[0], stops[0][0], 1e-6) && close(m.colors[1], stops[0][1], 1e-6),
+ 'the lowest sample takes the first ramp stop')
+ const last = (9 - 1) * 3
+ ok(close(m.colors[last], stops[4][0], 1e-6) && close(m.colors[last + 2], stops[4][2], 1e-6),
+ 'and the highest takes the last')
+ ok(close(m.positions[1], -1) && close(m.positions[last + 1], 1),
+ 'height spans the full [-1, 1] between the extremes')
+}
+
+{
+ // a FLAT field: the one case where the right normal is not a matter of taste
+ const flat = sheetOf({
+ x: [0, 1, 2, 0, 1, 2, 0, 1, 2],
+ y: [0, 0, 0, 1, 1, 1, 2, 2, 2],
+ z: [5, 5, 5, 5, 5, 5, 5, 5, 5],
+ })
+ const m = meshOf(buildScene(flat, { kind: 'surface', x: 'x', y: 'y', z: 'z' }), 'triangles')
+ let up = true
+ for (let i = 0; i + 2 < m.normals!.length; i += 3) {
+ if (!close(m.normals![i], 0) || !close(m.normals![i + 1], 1) || !close(m.normals![i + 2], 0)) up = false
+ }
+ ok(up, 'a flat surface has every normal at exactly +Y — the assertion a flipped winding fails')
+}
+
+{
+ const s = buildScene(gridRows([[0, 0]]), { kind: 'surface', x: 'x', y: 'y', z: 'z' })
+ const m = meshOf(s, 'triangles')
+ ok(triCount(m) === 6, 'a MISSING corner sample removes its quad: 6 triangles, not 8')
+ ok(s.dropped === 0 && s.rows === 8, 'the rows that were there are all used')
+ ok(sceneFinite(s), 'and the hole leaves no NaN behind')
+}
+
+{
+ // aggregation: two rows land in the same cell
+ const dup = sheetOf({
+ x: [0, 0, 1, 1, 0, 0, 1, 1, 0],
+ y: [0, 0, 0, 0, 1, 1, 1, 1, 0],
+ z: [10, 30, 1, 1, 1, 1, 1, 1, 20],
+ })
+ const sum = buildScene(dup, { kind: 'bars', x: 'x', y: 'y', z: 'z', agg: 'sum' })
+ const avg = buildScene(dup, { kind: 'bars', x: 'x', y: 'y', z: 'z', agg: 'avg' })
+ const cnt = buildScene(dup, { kind: 'bars', x: 'x', y: 'y', z: 'z', agg: 'count' })
+ ok(sum.axes[2].max === 60, 'sum of the three rows in cell (0,0) is 60')
+ ok(avg.axes[2].max === 20, 'and their average is 20')
+ ok(cnt.axes[2].max === 3, 'and their count is 3')
+ ok(sum.axes[2].title === 'sum of z' && cnt.axes[2].title === 'count',
+ 'the value axis says which aggregate produced it')
+
+ // A surface is a FIELD and bars are a TOTAL, so their defaults are opposite.
+ // With sum, a cell holding two samples reports twice the field's value, and a
+ // smooth surface renders as a comb of spikes whose period is the BINNING.
+ ok(buildScene(dup, { kind: 'bars', x: 'x', y: 'y', z: 'z' }).axes[2].title === 'sum of z',
+ 'bars default to SUM — a bar is a total')
+ const smooth = sheetOf({
+ x: [0, 0, 1, 1, 0, 0, 1, 1], y: [0, 0, 0, 0, 1, 1, 1, 1], z: [5, 5, 5, 5, 5, 5, 5, 5],
+ })
+ const surf = buildScene(smooth, { kind: 'surface', x: 'x', y: 'y', z: 'z' })
+ ok(surf.axes[2].title === 'avg of z', 'a surface defaults to AVERAGE — a surface is a field')
+ ok(surf.axes[2].min === 5 && surf.axes[2].max === 5,
+ 'so a constant field two-samples-deep is FLAT at 5, not a doubled 10 that varies with sampling density')
+}
+
+{
+ const s = buildScene(sheetOf({ x: [1, 1, 1], y: [1, 2, 3], z: [1, 2, 3] }),
+ { kind: 'surface', x: 'x', y: 'y', z: 'z' })
+ ok(!!s.empty && !s.meshes.length,
+ 'one distinct value on an axis is a LINE, not a surface — refused with a reason rather than drawn empty')
+}
+
+// ======================================================================= bars
+
+{
+ const four = sheetOf({
+ x: ['A', 'A', 'B', 'B'],
+ y: ['P', 'Q', 'P', 'Q'],
+ v: [10, 20, 30, 40],
+ }, { x: 'text', y: 'text', v: 'number' })
+ const s = buildScene(four, { kind: 'bars', x: 'x', y: 'y', z: 'v' })
+ const m = meshOf(s, 'triangles')
+ ok(vertCount(m) === 96, 'four bars are 96 vertices — 24 per box, so each face keeps its own normal')
+ ok(m.indices!.length === 144 && triCount(m) === 48, 'and 36 indices per box: 12 triangles, 6 faces')
+ ok(unitNormals(m), 'every bar normal is unit length')
+
+ // a box is flat-shaded, so each normal must be an AXIS — a smoothed corner is
+ // the tell that computeNormals was run over geometry that did not want it
+ let axisAligned = true
+ for (let i = 0; i + 2 < m.normals!.length; i += 3) {
+ const c = [m.normals![i], m.normals![i + 1], m.normals![i + 2]].map(Math.abs)
+ if (!(close(c[0] + c[1] + c[2], 1) && c.filter((v) => close(v, 1)).length === 1)) axisAligned = false
+ }
+ ok(axisAligned, 'and every one is axis-aligned: box corners are crisp, not melted')
+ ok(m.cull === true, 'bars are closed geometry, so the SVG fallback may cull their back faces')
+ ok(sceneFinite(s), 'the bar scene is finite')
+}
+
+{
+ const s = buildScene(sheetOf({
+ x: ['A', 'A', 'B', 'B'], y: ['P', 'Q', 'P', 'Q'], v: [10, -6, 3, 4],
+ }, { x: 'text', y: 'text', v: 'number' }), { kind: 'bars', x: 'x', y: 'y', z: 'v' })
+ ok(close(s.bounds.max[1], 1) && close(s.bounds.min[1], -0.6, 1e-6),
+ 'a NEGATIVE bar hangs below the floor, scaled against the largest magnitude')
+ ok(!close(s.bounds.min[1], 0, 1e-6),
+ 'the axis is not clipped at zero, which would hide the negative value entirely')
+}
+
+{
+ // one category too many on an axis
+ const many = sheetOf({
+ x: Array.from({ length: 200 }, (_, i) => `c${i}`),
+ y: Array.from({ length: 200 }, () => 'P'),
+ v: Array.from({ length: 200 }, () => 1),
+ }, { x: 'text', y: 'text', v: 'number' })
+ const s = buildScene(many, { kind: 'bars', x: 'x', y: 'y', z: 'v' })
+ ok(s.axes[0].labels!.length === _internals.AXIS_MAX_BARS,
+ `a bar axis caps at ${_internals.AXIS_MAX_BARS} categories rather than emitting 200 unreadable columns`)
+ ok(s.dropped === 200 - _internals.AXIS_MAX_BARS,
+ 'and the rows past the cap are counted as dropped, not folded into an "other" bar whose height is an artefact')
+}
+
+// ====================================================================== globe
+
+{
+ const a = latLonToXyz(0, 0, 1)
+ ok(close(a[0], 0) && close(a[1], 0) && close(a[2], 1), 'lat 0 / lon 0 is +Z, where the camera starts')
+ const b = latLonToXyz(90, 0, 1)
+ ok(close(b[0], 0) && close(b[1], 1) && close(b[2], 0), 'the north pole is +Y')
+ const c = latLonToXyz(0, 90, 1)
+ ok(close(c[0], 1) && close(c[1], 0) && close(c[2], 0), 'lon +90 is +X')
+ ok(close(latLonToXyz(-45, 123, 2).reduce((s, v) => s + v * v, 0), 4, 1e-9),
+ 'and every point lands exactly on the sphere of the radius asked for')
+
+ const sm = _internals.sphereMesh(1, 8, 4)
+ ok(sm.positions.length === 45 * 3, 'a UV sphere duplicates its seam column: (8+1) x (4+1) vertices')
+ ok(sm.indices.length === 144,
+ 'and skips the degenerate pole triangles: 48 triangles, not 64')
+ let unit = true
+ for (let i = 0; i + 2 < sm.normals.length; i += 3) {
+ if (!close(Math.hypot(sm.normals[i], sm.normals[i + 1], sm.normals[i + 2]), 1, 1e-6)) unit = false
+ if (!close(Math.hypot(sm.positions[i], sm.positions[i + 1], sm.positions[i + 2]), 1, 1e-6)) unit = false
+ }
+ ok(unit, 'sphere normals are exact (they ARE the positions), including at the poles')
+}
+
+{
+ const g = sheetOf({
+ lat: [51.5, -33.9, 35.7, 95, 40.7],
+ lon: [-0.1, 151.2, 139.7, 10, -74],
+ pop: [9, 5, 37, 1, 8],
+ })
+ const s = buildScene(g, { kind: 'globe', lat: 'lat', lon: 'lon', color: 'pop' })
+ const pts = meshOf(s, 'points')
+ ok(vertCount(pts) === 4, 'a latitude of 95 is REFUSED — a mis-bound column must not paint a confident band')
+ ok(s.dropped === 1, 'and the refusal is counted')
+ let onShell = true
+ for (let i = 0; i + 2 < pts.positions.length; i += 3) {
+ if (!close(Math.hypot(pts.positions[i], pts.positions[i + 1], pts.positions[i + 2]), 1.012, 1e-5)) onShell = false
+ }
+ ok(onShell, 'points sit just OFF the surface, so they cannot z-fight with it')
+ ok(s.meshes.some((m) => m.mode === 'triangles') && s.meshes.some((m) => m.mode === 'lines'),
+ 'the globe ships a lit sphere and a graticule — a featureless sphere does not read as rotating')
+ ok(sceneFinite(s), 'the globe scene is finite')
+}
+
+// ================================================== empty and degenerate input
+
+{
+ const cases: Array<[string, Scene]> = [
+ ['a sheet with no rows', buildScene(sheetOf({ x: [], y: [], z: [] }), { kind: 'scatter', x: 'x', y: 'y', z: 'z' })],
+ ['a scatter missing its Z column', buildScene(scatterSheet, { kind: 'scatter', x: 'x', y: 'y' })],
+ ['a scatter bound to a column that is not there', buildScene(scatterSheet, { kind: 'scatter', x: 'x', y: 'y', z: 'nope' })],
+ ['a globe with no lat/lon', buildScene(scatterSheet, { kind: 'globe' })],
+ ['a surface with no value column', buildScene(scatterSheet, { kind: 'surface', x: 'x', y: 'y' })],
+ ['an all-text scatter', buildScene(
+ sheetOf({ a: ['p', 'q'], b: ['r', 's'], c: ['t', 'u'] }, { a: 'text', b: 'text', c: 'text' }),
+ { kind: 'scatter', x: 'a', y: 'b', z: 'c' })],
+ ]
+ for (const [what, s] of cases) {
+ ok(!!s.empty && s.empty.length > 8 && !s.meshes.length,
+ `${what} gives an EMPTY scene carrying a sentence, not a box of NaN`)
+ ok(sceneFinite(s), ` ...and ${what} leaves the bounds and radius finite`)
+ }
+ const cam = frameCamera(cases[0][1])
+ const m = cam.matrix(1.5)
+ ok([...m].every(Number.isFinite),
+ 'and an empty scene still frames a finite camera — radius 1, never 0, or lookAt is NaN')
+}
+
+// ================================================================= 2D fallback
+
+{
+ const s = buildScene(gridRows(), { kind: 'surface', x: 'x', y: 'y', z: 'z' })
+ const svg = fallbackSvg(s, 640, 420)
+ ok(svg.startsWith('<svg') && svg.endsWith('</svg>'), 'the fallback is a complete SVG document')
+ ok(svg.includes('<polygon'), 'and it actually draws the mesh — not a blank rectangle')
+ ok(!svg.includes('NaN') && !svg.includes('Infinity'), 'with no NaN or Infinity anywhere in the geometry')
+ const polys = svg.match(/<polygon/g)!.length
+ ok(polys === 8, 'one polygon per triangle of the 3x3 surface')
+
+ const pts = fallbackSvg(buildScene(scatterSheet,
+ { kind: 'scatter', x: 'x', y: 'y', z: 'z', color: 'heat', size: 'mag' }), 400, 300)
+ ok((pts.match(/<circle/g) ?? []).length === 5, 'a scatter falls back to one circle per row')
+ ok(pts.includes('<line'), 'and keeps the bounding frame, so the projection still reads as 3D')
+}
+
+{
+ const s = buildScene(sheetOf({ x: [1], y: [1], z: [1] }), { kind: 'scatter', x: 'x', y: 'y' })
+ const svg = fallbackSvg(s, 300, 200)
+ ok(!svg.includes('<polygon') && !svg.includes('<circle'), 'an empty scene draws no geometry')
+ ok(svg.includes('<text') && svg.includes('three numeric columns'),
+ 'but says WHY in words — a workbook that opens to an empty rectangle is worse than one with no 3D at all')
+}
+
+{
+ // painter's algorithm: FAR first, or the near triangle is painted over
+ const far: Mesh = {
+ mode: 'triangles', lit: false,
+ positions: new Float32Array([-0.5, -0.5, -0.5, 0.5, -0.5, -0.5, 0, 0.5, -0.5]),
+ colors: new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1]),
+ }
+ const near: Mesh = {
+ mode: 'triangles', lit: false,
+ positions: new Float32Array([-0.5, -0.5, 0.5, 0.5, -0.5, 0.5, 0, 0.5, 0.5]),
+ colors: new Float32Array([1, 0, 0, 1, 0, 0, 1, 0, 0]),
+ }
+ const scene: Scene = {
+ kind: 'scatter', meshes: [near, far], // deliberately NEAR first in the list
+ bounds: { min: [-1, -1, -1], max: [1, 1, 1] }, center: [0, 0, 0], radius: 1.5,
+ axes: [], rows: 0, dropped: 0,
+ }
+ const svg = fallbackSvg(scene, 400, 400, { azimuth: 0, elevation: 0 })
+ const fills = [...svg.matchAll(/<polygon[^>]*fill="(#[0-9a-f]{6})"/g)].map((m) => m[1])
+ ok(fills.length === 2, 'both triangles are drawn')
+ ok(fills[0] === '#0000ff' && fills[1] === '#ff0000',
+ 'the FAR triangle is emitted first, so the near one paints over it — the reverse order is a wrong picture')
+}
+
+{
+ // column names are user data and go straight into markup
+ const s = buildScene(
+ sheetOf({ '<script>x</script>': [1, 2], b: [1, 2], c: [1, 2] }),
+ { kind: 'scatter', x: '<script>x</script>', y: 'b', z: 'c' },
+ )
+ const svg = fallbackSvg(s, 400, 300)
+ ok(!svg.includes('<script'), 'a column name cannot inject markup into the fallback SVG')
+ ok(svg.includes('&lt;script&gt;'), 'it is escaped, not stripped, so the name is still readable')
+}
+
+{
+ const s = buildScene(sheetOf({ x: [1, 2, 'x', 4], y: [1, 2, 3, 4], z: [1, 2, 3, 4] }),
+ { kind: 'scatter', x: 'x', y: 'y', z: 'z' })
+ ok(fallbackSvg(s, 400, 300).includes('1 of 4 rows had no value'),
+ 'the fallback says how many rows are missing from the picture')
+}
+
+// ============================================================ axes and binning
+
+{
+ const ax = _internals.categorise(['Jan', 'Feb', 'Mar', 'Jan'], 16, 64)
+ ok(ax.labels.join() === 'Jan,Feb,Mar' && !ax.numeric,
+ 'a text axis keeps FIRST-SEEN order — sorting month names alphabetically makes a surface out of noise')
+ ok(ax.slot[3] === 0, 'and a repeat lands in the slot it opened')
+
+ const nums = _internals.categorise([3, 1, 2, 2], 16, 64)
+ ok(nums.labels.join() === '1,2,3' && nums.numeric,
+ 'a numeric axis is ASCENDING — a surface interpolates between neighbours, so order is the shape')
+ ok(nums.slot[0] === 2 && nums.slot[1] === 0, 'and rows point at the right slots')
+
+ const wide = _internals.categorise(Array.from({ length: 100 }, (_, i) => i), 4, 64)
+ ok(wide.labels.length === 4, 'more distinct values than bins asked for gives equal-width bins')
+ ok(wide.slot[0] === 0 && wide.slot[99] === 3,
+ 'and the top edge belongs to the LAST bin, not to an out-of-range one')
+
+ const blanks = _internals.categorise([1, null, '', 5], 16, 64)
+ ok(blanks.slot[1] === -1 && blanks.slot[2] === -1, 'a blank has no slot, so its row is dropped rather than binned at 0')
+}
+
+{
+ const g = _internals.aggregateGrid(2, 1, [0, 0, 1], [0, 0, 0], [4, 6, null], 'sum')
+ ok(g.v[0] === 10 && g.present[0] === 1, 'cells sum')
+ ok(g.present[1] === 0, 'a cell whose only row has no value is ABSENT, not zero — a coerced zero is a crater')
+ ok(g.used === 2, 'and the rows actually used are counted')
+ const mx = _internals.aggregateGrid(1, 1, [0, 0], [0, 0], [4, 9], 'max')
+ const mn = _internals.aggregateGrid(1, 1, [0, 0], [0, 0], [4, 9], 'min')
+ ok(mx.v[0] === 9 && mn.v[0] === 4, 'min and max pick, they do not accumulate')
+}
+
+// ============================================================ default binding
+
+{
+ ok(defaultViz3d(scatterSheet)?.kind === 'scatter', 'three numeric columns default to a scatter')
+ const geo = sheetOf({ lat: [1], lon: [2], n: [3] })
+ ok(defaultViz3d(geo)?.kind === 'globe', 'named lat/lon columns default to a globe')
+ const trap = sheetOf({ platform: [1], longevity: [2], n: [3] })
+ ok(defaultViz3d(trap)?.kind === 'scatter',
+ '"platform" and "longevity" are not coordinates — the word-boundary check refuses them')
+ const cats = sheetOf({ a: ['x'], b: ['y'], v: [1] }, { a: 'text', b: 'text', v: 'number' })
+ ok(defaultViz3d(cats)?.kind === 'bars', 'two categories and a measure default to 3D bars')
+ ok(defaultViz3d(sheetOf({ a: ['x'] }, { a: 'text' })) === null,
+ 'and a sheet with nothing to plot gets NULL rather than a forced wrong view')
+}
+
+// ====================================================== formula columns ride in
+
+{
+ const s = sheetOf({ x: [1, 2, 3], y: [1, 2, 3] })
+ s.columns.push({ id: 'k', name: 'k', type: 'number', formula: 'x * 10' })
+ const computed = new Map<string, unknown[]>([['k', [10, 20, 30]]])
+ const b: Viz3dBinding = { kind: 'scatter', x: 'x', y: 'y', z: 'k' }
+ ok(!!buildScene(s, b).empty, 'a formula column with nothing computed for it is refused rather than plotted as blank')
+ const withIt = buildScene(s, b, computed)
+ ok(!withIt.empty && vertCount(meshOf(withIt, 'points')) === 3 && withIt.axes[2].max === 30,
+ 'and the values the grid just recalculated plot as themselves — chart.ts\'s `computed` contract, unchanged')
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-xlsx.ts b/scripts/test-dash-xlsx.ts
new file mode 100644
index 00000000..20e8feaa
--- /dev/null
+++ b/scripts/test-dash-xlsx.ts
@@ -0,0 +1,611 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash .xlsx rig.
+//
+// node scripts/test-dash-xlsx.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES. Every failure in this module is silent — the file opens,
+// the grid fills, the totals compute, and the numbers are wrong by four years
+// or a factor of a hundred. So the rig is organised around the ways that
+// happens rather than around the functions:
+//
+// 1. THE EPOCH. 1900 vs 1904 is 1,462 days. The 1900 system's phantom
+// 29 February 1900 means serials 1–59 and 61+ need DIFFERENT epochs.
+// Checked against dates computed by hand, in both systems, at the seam.
+// 2. PERCENT. Excel stores 15% as 0.15 and so does dash: the value must come
+// through UNCHANGED. A ×100 here is a margin column reading 1500%.
+// 3. FORMULAS THAT WOULD SILENTLY REBIND. `Sheet2!A1` imported live resolves
+// against THIS sheet's column A, because a1.ts (correctly) will not
+// rewrite a sheet-qualified name. The import must refuse to make it live.
+//
+// AND the export is judged by things that are not us:
+//
+// • `unzip -t` and python3's zipfile on the archive;
+// • LibreOffice actually OPENING the workbook and converting it to CSV — the
+// "does Excel show a repair dialog" question, answered by a real OOXML
+// consumer rather than by our own reader agreeing with our own writer.
+// • real .xlsx files off this machine, written by Excel, imported here.
+
+import { execFileSync } from 'node:child_process'
+import { mkdtempSync, writeFileSync, readFileSync, existsSync, readdirSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeZip } from '../dash/src/zip.ts'
+import {
+ importXlsx, exportXlsx, serialToIso, isoToSerial, classifyFormat, liveFormula,
+ escapeXml, unescapeXml, xlsxFileName, _internals,
+} from '../dash/src/xlsx.ts'
+import { parseDoc, type DashDoc, type TableSheet } from '../dash/src/model.ts'
+import { readCell } from '../dash/src/store.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'dash-xlsx-'))
+const enc = new TextEncoder()
+const have = (cmd: string, ...args: string[]): boolean => {
+ try { execFileSync(cmd, args, { stdio: 'ignore' }); return true } catch { return false }
+}
+
+// ============================================================ THE EPOCH
+{
+ // 1900 system, checked at the three points where a wrong epoch shows up.
+ ok(serialToIso(1, false) === '1900-01-01', '1900 system: serial 1 is 1 January 1900')
+ ok(serialToIso(59, false) === '1900-02-28', '1900 system: serial 59 is 28 February 1900')
+ ok(serialToIso(60, false) === '1900-02-29',
+ 'serial 60 is the day that never existed, and is reported rather than nudged to the 28th or the 1st')
+ ok(serialToIso(61, false) === '1900-03-01', '1900 system: serial 61 is 1 March 1900 (the epoch changes here)')
+ ok(serialToIso(45000, false) === '2023-03-15', '1900 system: a modern serial')
+ ok(serialToIso(25569, false) === '1970-01-01', '1900 system: the Unix epoch is serial 25569')
+
+ // 1904 system. THE FOUR-YEAR BUG: the same serial must be 1,462 days later.
+ ok(serialToIso(0, true) === '1904-01-01', '1904 system: serial 0 is 1 January 1904')
+ ok(serialToIso(45000, true) === '2027-03-16', '1904 system: the same serial is four years and a day on')
+ {
+ const a = Date.parse(serialToIso(45000, false)! + 'T00:00:00Z')
+ const b = Date.parse(serialToIso(45000, true)! + 'T00:00:00Z')
+ ok((b - a) / 86400000 === 1462,
+ 'and the gap between the two systems is exactly 1,462 days — the number a wrong guess costs')
+ }
+
+ // the inverse, including across the leap-bug seam
+ for (const s of [1, 59, 61, 25569, 45000, 45999]) {
+ const iso = serialToIso(s, false)!
+ checks++
+ if (isoToSerial(iso) === s) console.log(` ok serial ${s} → ${iso} → ${s}`)
+ else { failures++; console.log(` FAIL serial ${s} round trip gave ${isoToSerial(iso)}`) }
+ }
+ ok(isoToSerial('2023-03-15T06:00:00') === 45000.25, 'a time of day becomes the fraction of a serial')
+ ok(serialToIso(45000.25, false, true) === '2023-03-15T06:00:00', 'and comes back')
+ ok(isoToSerial('not a date') === null, 'and a non-date refuses rather than becoming serial 0 (= 1900)')
+}
+
+// ==================================================== NUMBER FORMAT → TYPE
+{
+ ok(classifyFormat('General') === 'number', 'General is a number')
+ ok(classifyFormat('yyyy-mm-dd') === 'date', 'an ISO date pattern is a date')
+ ok(classifyFormat('mm/dd/yyyy') === 'date', 'so is a US one')
+ ok(classifyFormat('0.00%') === 'percent', 'a percent pattern is a percent')
+ ok(classifyFormat('"£"#,##0.00') === 'money', 'a quoted currency symbol is money')
+ ok(classifyFormat('[$€-407]#,##0.00') === 'money', 'and so is a locale currency block')
+ ok(classifyFormat('h:mm:ss') === 'time', 'a clock pattern is a time')
+ ok(classifyFormat('[h]:mm') === 'time', 'elapsed hours are a time, not a colour')
+ ok(classifyFormat('@') === 'text', '@ is text')
+
+ // THE ONE THAT BIT: an ordinary accounting pattern read as a date, because
+ // `\(` and `\-` were not stripped and `d` was found inside an escape.
+ ok(classifyFormat('#,##0;\\(#,##0\\);\\-') === 'number',
+ 'an accounting pattern with escaped brackets is a NUMBER, not a date')
+ ok(classifyFormat('* #,##0.00_0\\ "GBP";* \\-\\ #,##0.00_0\\ "GBP"') === 'money',
+ 'and a quoted currency code with escapes is money, not a date (the m in "GBP" is not a month)')
+ ok(classifyFormat('[Red]#,##0.00') === 'number', 'a colour block is not a date (the d in Red)')
+ ok(classifyFormat('0.0"days"') === 'number', 'and neither is a quoted unit')
+}
+
+// ============================================================ ESCAPING
+{
+ ok(unescapeXml('a &amp; b &lt;c&gt; &quot;d&quot; &apos;e&apos;') === `a & b <c> "d" 'e'`,
+ 'the five named entities decode')
+ ok(unescapeXml('&#65;&#x42;') === 'AB', 'numeric entities decode, decimal and hex')
+ ok(unescapeXml('line_x000D_break') === 'line\rbreak', "Excel's _x000D_ escape decodes")
+ ok(unescapeXml('part_x0041_number') === 'part_x0041_number',
+ 'but _x0041_ does NOT — it is ordinary text far more often than it is an escape')
+ ok(escapeXml('a & b <c>') === 'a &amp; b &lt;c&gt;', 'text escapes on the way out')
+ ok(escapeXml('badbell\tkeep') === 'badbell\tkeep',
+ 'a control character is stripped (XML cannot carry it and Excel calls the file corrupt); tab stays')
+}
+
+// ============================================ FORMULAS THAT MUST NOT GO LIVE
+{
+ ok(liveFormula('A1*2').ok, 'plain arithmetic goes live')
+ ok(liveFormula('SUM(A1:A9)/COUNT(A1:A9)').ok, 'functions dash implements go live')
+ ok(!liveFormula('Sheet2!A1*2').ok,
+ 'a sheet-qualified reference does NOT — a1.ts leaves `Sheet2` alone and the `A1` after it would bind to THIS sheet')
+ ok(!liveFormula(`'Q1 data'!B7`).ok, 'nor a quoted sheet name')
+ ok(!liveFormula('[1]Other!A1').ok, 'nor an external workbook reference')
+ ok(!liveFormula('Table1[Amount]').ok, 'nor a structured table reference')
+ ok(liveFormula('VLOOKUP(A1,B1:C9,2,0)').ok, 'VLOOKUP goes live — dash implements it')
+ ok(!liveFormula('SUMPRODUCT(A1:A9,B1:B9)').ok,
+ 'but SUMPRODUCT does not, and a live #NAME? where a number used to be is not an import')
+ ok(liveFormula('IF(A1>0,"up","down")').ok, 'a string containing nothing special is fine')
+ ok(liveFormula('"a!b"&A1').ok, 'and a `!` inside a quoted string is not a sheet qualifier')
+}
+
+// ================================================= IMPORT: a hand-built workbook
+//
+// Built here as XML so every case is exactly the one being tested. This is the
+// input our reader has to survive; the real Excel files come later.
+
+function sheetXml(rows: string, extra = ''): string {
+ return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>' +
+ '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">' +
+ `<sheetData>${rows}</sheetData>${extra}</worksheet>`
+}
+
+async function buildXlsx(opts: {
+ sheets: Array<{ name: string; xml: string; state?: string }>
+ shared?: string[]
+ numFmts?: string[]
+ xfs?: number[]
+ date1904?: boolean
+}): Promise<Uint8Array> {
+ const M = 'http://schemas.openxmlformats.org/spreadsheetml/2006/main'
+ const R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships'
+ const shared = opts.shared ?? []
+ const numFmts = opts.numFmts ?? []
+ const xfs = opts.xfs ?? [0]
+ const parts = [
+ { name: '[Content_Types].xml', data: enc.encode('<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/></Types>') },
+ { name: '_rels/.rels', data: enc.encode(`<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="${R}/officeDocument" Target="xl/workbook.xml"/></Relationships>`) },
+ { name: 'xl/workbook.xml', data: enc.encode(`<?xml version="1.0"?><workbook xmlns="${M}" xmlns:r="${R}">` +
+ (opts.date1904 ? '<workbookPr date1904="1"/>' : '<workbookPr/>') +
+ `<sheets>${opts.sheets.map((s, i) => `<sheet name="${s.name}" sheetId="${i + 1}" r:id="rId${i + 1}"${s.state ? ` state="${s.state}"` : ''}/>`).join('')}</sheets></workbook>`) },
+ { name: 'xl/_rels/workbook.xml.rels', data: enc.encode(`<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">` +
+ opts.sheets.map((_, i) => `<Relationship Id="rId${i + 1}" Type="${R}/worksheet" Target="worksheets/sheet${i + 1}.xml"/>`).join('') +
+ `<Relationship Id="rIdS" Type="${R}/sharedStrings" Target="sharedStrings.xml"/>` +
+ `<Relationship Id="rIdY" Type="${R}/styles" Target="styles.xml"/></Relationships>`) },
+ { name: 'xl/sharedStrings.xml', data: enc.encode(`<?xml version="1.0"?><sst xmlns="${M}" count="${shared.length}" uniqueCount="${shared.length}">${shared.map((s) => `<si><t>${s}</t></si>`).join('')}</sst>`) },
+ { name: 'xl/styles.xml', data: enc.encode(`<?xml version="1.0"?><styleSheet xmlns="${M}">` +
+ (numFmts.length ? `<numFmts count="${numFmts.length}">${numFmts.map((c, i) => `<numFmt numFmtId="${164 + i}" formatCode="${c}"/>`).join('')}</numFmts>` : '') +
+ // a cellStyleXfs block FIRST, deliberately: it has the same <xf> shape as
+ // cellXfs, and a reader that scans for every <xf> indexes into the wrong one
+ '<cellStyleXfs count="2"><xf numFmtId="99"/><xf numFmtId="98"/></cellStyleXfs>' +
+ `<cellXfs count="${xfs.length}">${xfs.map((f) => `<xf numFmtId="${f}" fontId="0" fillId="0" borderId="0"/>`).join('')}</cellXfs></styleSheet>`) },
+ ]
+ opts.sheets.forEach((s, i) => parts.push({ name: `xl/worksheets/sheet${i + 1}.xml`, data: enc.encode(s.xml) }))
+ return writeZip(parts)
+}
+
+// --- values, types, shared strings, inline strings
+{
+ const bytes = await buildXlsx({
+ shared: ['Region', 'Amount', 'Share', 'When', 'Live', 'North', 'South'],
+ numFmts: ['&quot;£&quot;#,##0.00', '0.0%', 'yyyy-mm-dd'],
+ // 0=General 1=money(164) 2=percent(165) 3=date(166)
+ xfs: [0, 164, 165, 166],
+ sheets: [{
+ name: 'Data',
+ xml: sheetXml(
+ '<row r="1"><c r="A1" t="s"><v>0</v></c><c r="B1" t="s"><v>1</v></c><c r="C1" t="s"><v>2</v></c><c r="D1" t="s"><v>3</v></c><c r="E1" t="s"><v>4</v></c></row>' +
+ '<row r="2"><c r="A2" t="s"><v>5</v></c><c r="B2" s="1"><v>1200.5</v></c><c r="C2" s="2"><v>0.15</v></c><c r="D2" s="3"><v>45000</v></c><c r="E2" t="b"><v>1</v></c></row>' +
+ '<row r="3"><c r="A3" t="inlineStr"><is><t>Sou</t><t>th</t></is></c><c r="B3" s="1"><v>3400</v></c><c r="C3" s="2"><v>0.5</v></c><c r="D3" s="3"><v>45001</v></c><c r="E3" t="b"><v>0</v></c></row>'),
+ }],
+ })
+ const r = await importXlsx(bytes, { source: 'built.xlsx', idPrefix: 'sh' })
+ const s = r.sheets[0]
+ ok(r.sheets.length === 1 && s.columns.length === 5, 'five columns arrive')
+ ok(s.columns.map((c) => c.type).join() === 'text,money,percent,date,bool',
+ 'and are typed text/money/percent/date/bool from the NUMBER FORMATS, not from the digits')
+ ok(s.columns.map((c) => c.name).join() === 'Region,Amount,Share,When,Live',
+ 'the header row names them (shared strings resolved)')
+ ok(readCell(s.data.region, 1) === 'South',
+ 'a rich-text inline string is concatenated from its runs, not truncated to the first')
+ ok(readCell(s.data.amount, 0) === 1200.5, 'a money value is the plain number')
+ ok(readCell(s.data.share, 0) === 0.15,
+ 'A PERCENT IS NOT MULTIPLIED — 15% is 0.15 in Excel and 0.15 in dash')
+ ok(readCell(s.data.when, 0) === '2023-03-15', 'a date serial becomes an ISO date')
+ ok(readCell(s.data.live, 0) === true && readCell(s.data.live, 1) === false, 'booleans survive')
+ ok(s.rids.length === 1 && s.rids[0][1] === 2, 'two data rows, header consumed')
+
+ const doc = {
+ format: 'bento/dash', version: 1, policy: 'bento-dash-1',
+ docId: 'd', title: 'x', sheets: r.sheets,
+ }
+ const parsed = parseDoc(JSON.stringify(doc))
+ ok(parsed.ok === true && parsed.repairs.length === 0,
+ 'and the imported sheets parse as a legal bento/dash document with nothing to repair')
+}
+
+// --- THE 1904 EPOCH, end to end
+{
+ const make = (d1904: boolean) => buildXlsx({
+ shared: ['When'], numFmts: ['yyyy-mm-dd'], xfs: [0, 164], date1904: d1904,
+ sheets: [{ name: 'D', xml: sheetXml('<row r="1"><c r="A1" t="s"><v>0</v></c></row><row r="2"><c r="A2" s="1"><v>45000</v></c></row>') }],
+ })
+ const a = await importXlsx(await make(false), {})
+ const b = await importXlsx(await make(true), {})
+ ok(readCell(a.sheets[0].data.when, 0) === '2023-03-15', '1900 workbook: 15 March 2023')
+ ok(readCell(b.sheets[0].data.when, 0) === '2027-03-16', '1904 workbook: the SAME serial is 16 March 2027')
+ ok(b.findings.some((f) => f.code === 'date-system'),
+ 'and the 1904 system is REPORTED, because nothing on screen would otherwise say')
+ ok(!a.findings.some((f) => f.code === 'date-system'), 'a 1900 workbook says nothing (the default)')
+}
+
+// --- serial 60, the day that never existed
+{
+ const bytes = await buildXlsx({
+ shared: ['When'], numFmts: ['yyyy-mm-dd'], xfs: [0, 164],
+ sheets: [{ name: 'D', xml: sheetXml('<row r="1"><c r="A1" t="s"><v>0</v></c></row><row r="2"><c r="A2" s="1"><v>60</v></c></row>') }],
+ })
+ const r = await importXlsx(bytes, {})
+ ok(readCell(r.sheets[0].data.when, 0) === '1900-02-29', 'serial 60 keeps the impossible date it was written as')
+ ok(r.findings.some((f) => f.code === 'date-1900-bug'), 'and says so rather than moving it silently')
+}
+
+// --- SHARED FORMULAS, and the ones that must not go live
+{
+ const bytes = await buildXlsx({
+ shared: ['A', 'B'],
+ sheets: [{
+ name: 'F',
+ xml: sheetXml(
+ '<row r="1"><c r="A1" t="s"><v>0</v></c><c r="B1" t="s"><v>1</v></c></row>' +
+ '<row r="2"><c r="A2"><v>10</v></c><c r="B2"><f t="shared" si="0" ref="B2:B4">A2*2</f><v>20</v></c></row>' +
+ '<row r="3"><c r="A3"><v>20</v></c><c r="B3"><f t="shared" si="0"/><v>40</v></c></row>' +
+ '<row r="4"><c r="A4"><v>30</v></c><c r="B4"><f>Sheet2!A1*3</f><v>99</v></c></row>'),
+ }],
+ })
+ const r = await importXlsx(bytes, {})
+ const s = r.sheets[0]
+ ok(s.cells?.['b:1']?.f === '=A1*2',
+ 'the shared-formula MASTER imports, shifted up by the header row (A2 → A1)')
+ ok(s.cells?.['b:2']?.f === '=A2*2',
+ 'and its FOLLOWER is expanded by translation — otherwise 1 formula and N bare numbers arrive')
+ ok(s.cells?.['b:3']?.f === undefined && s.cells?.['b:3']?.xlsxF === '=Sheet2!A1*3',
+ 'a cross-sheet formula is NOT made live — it would bind to this sheet — and its source is kept beside the value')
+ ok(readCell(s.data.b, 2) === 99, 'and the value Excel last calculated is what the grid shows')
+ ok(r.findings.some((f) => f.code === 'formula-not-live'), 'and the refusal is reported')
+}
+
+// --- merged cells, hidden sheets, no header, mixed types
+{
+ const bytes = await buildXlsx({
+ shared: ['Quarterly report', 'Name', 'Value'],
+ sheets: [
+ {
+ name: 'Merged',
+ xml: sheetXml(
+ // no header: row 1 already holds numbers
+ '<row r="1"><c r="A1" t="s"><v>1</v></c><c r="B1"><v>1</v></c></row>' +
+ '<row r="2"><c r="A2" t="s"><v>2</v></c><c r="B2"><v>2</v></c></row>',
+ '<mergeCells count="1"><mergeCell ref="A1:C1"/></mergeCells>'),
+ },
+ { name: 'Hidden', state: 'hidden', xml: sheetXml('<row r="1"><c r="A1"><v>7</v></c></row>') },
+ ],
+ })
+ const r = await importXlsx(bytes, {})
+ ok(r.findings.some((f) => f.code === 'merged-cells'),
+ 'merged ranges are reported — the value stays in the top-left cell, never spread across the range')
+ ok(r.sheets.length === 2 && r.findings.some((f) => f.code === 'hidden-sheet'),
+ 'a hidden sheet is imported (hiding is not deleting) and reported')
+ ok(r.findings.some((f) => f.code === 'no-header'),
+ 'a sheet whose first row is data says so instead of eating a row as a header')
+}
+
+{
+ // A column that is half text and half numbers cannot be typed. Refuse.
+ const bytes = await buildXlsx({
+ shared: ['Mixed', 'n/a', 'tbd', 'later'],
+ sheets: [{
+ name: 'M',
+ xml: sheetXml(
+ '<row r="1"><c r="A1" t="s"><v>0</v></c></row>' +
+ '<row r="2"><c r="A2"><v>1</v></c></row>' +
+ '<row r="3"><c r="A3"><v>2</v></c></row>' +
+ '<row r="4"><c r="A4" t="s"><v>1</v></c></row>' +
+ '<row r="5"><c r="A5" t="s"><v>2</v></c></row>'),
+ }],
+ })
+ const r = await importXlsx(bytes, {})
+ ok(r.sheets[0].columns[0].type === 'text' && r.findings.some((f) => f.code === 'mixed-types'),
+ 'a genuinely mixed column is imported as text and REPORTED, not silently typed to the majority')
+}
+
+{
+ // 90% numbers with one word in it: typed, and the loss counted — import.ts's rule.
+ const rows = ['<row r="1"><c r="A1" t="s"><v>0</v></c></row>']
+ for (let i = 2; i <= 20; i++) rows.push(`<row r="${i}"><c r="A${i}"><v>${i}</v></c></row>`)
+ rows.push('<row r="21"><c r="A21" t="s"><v>1</v></c></row>')
+ const bytes = await buildXlsx({ shared: ['N', 'n/a'], sheets: [{ name: 'N', xml: sheetXml(rows.join('')) }] })
+ const r = await importXlsx(bytes, {})
+ ok(r.sheets[0].columns[0].type === 'number', 'a column that is 95% numbers is a number column')
+ ok(r.sheets[0].columns[0].failed === 1 && r.findings.some((f) => f.code === 'coerce-failed'),
+ 'and the one value that would not coerce is COUNTED and reported, never hidden')
+}
+
+// --- findings do not become a wall
+{
+ // 12 unnamed columns of mixed data: one finding per column would be 24 lines
+ // in a banner, and an unread warning is the same as an absent one.
+ const rows = ['<row r="1">' + Array.from({ length: 12 }, (_, i) =>
+ `<c r="${String.fromCharCode(65 + i)}1" t="str"><v></v></c>`).join('') + '</row>']
+ for (let r = 2; r <= 5; r++) {
+ rows.push(`<row r="${r}">` + Array.from({ length: 12 }, (_, i) =>
+ r % 2 ? `<c r="${String.fromCharCode(65 + i)}${r}"><v>${r}</v></c>`
+ : `<c r="${String.fromCharCode(65 + i)}${r}" t="str"><v>x</v></c>`).join('') + '</row>')
+ }
+ const r = await importXlsx(await buildXlsx({ sheets: [{ name: 'Wide', xml: sheetXml(rows.join('')) }] }), {})
+ const mixed = r.findings.filter((f) => f.code === 'mixed-types')
+ ok(mixed.length === 4 && /and 9 more columns/.test(mixed[3].message),
+ 'repeated findings collapse to the first three plus a count — the count is kept, the wall is not')
+}
+
+// --- the cellStyleXfs trap
+{
+ ok(_internals.readStyles(
+ '<styleSheet><cellStyleXfs count="1"><xf numFmtId="14"/></cellStyleXfs>' +
+ '<cellXfs count="2"><xf numFmtId="0"/><xf numFmtId="9"/></cellXfs></styleSheet>').xf.length === 2,
+ 'readStyles indexes cellXfs ONLY — cellStyleXfs comes first and has the identical <xf> shape')
+}
+
+// ============================================================ EXPORT
+//
+// The doc under test carries one of everything the exporter has to decide about.
+
+const doc: DashDoc = {
+ format: 'bento/dash', version: 1, policy: 'bento-dash-1',
+ docId: 'test-doc', title: 'Round trip',
+ sheets: [{
+ id: 'sheet-1', name: 'Pipeline', kind: 'table',
+ rids: [[1, 3]],
+ columns: [
+ { id: 'region', name: 'Region', type: 'text' },
+ { id: 'amount', name: 'Amount', type: 'money', unit: 'GBP', w: 96 },
+ { id: 'share', name: 'Share', type: 'percent' },
+ { id: 'when', name: 'When', type: 'date' },
+ { id: 'live', name: 'Live', type: 'bool' },
+ { id: 'adj', name: 'Adjusted', type: 'number' },
+ ],
+ data: {
+ region: { enc: 'dict', dict: ['North', 'South'], idx: [0, 1, 0] },
+ amount: { enc: 'raw', v: [1200.5, 3400, 900] },
+ share: { enc: 'raw', v: [0.15, 0.5, 0.075] },
+ when: { enc: 'raw', v: ['2023-03-15', '2023-03-16', '1900-01-01'] },
+ live: { enc: 'raw', v: [true, false, true] },
+ adj: { enc: 'raw', v: [10, 20, 30] },
+ },
+ // a per-cell formula on the last row of `adj`
+ cells: { 'adj:3': { f: '=F1+F2' } },
+ totals: { amount: 'sum', adj: 'max' },
+ steps: [{ op: 'import', from: 'rig', at: '2026-08-04T00:00:00Z' }],
+ } as TableSheet],
+}
+
+const exported = await exportXlsx(doc, {})
+const xlsxPath = join(tmp, 'roundtrip.xlsx')
+writeFileSync(xlsxPath, exported.bytes)
+
+// --- a REAL unzip and a REAL zip library must accept the package
+if (have('unzip', '-v')) {
+ const out = execFileSync('unzip', ['-t', xlsxPath], { encoding: 'utf8' })
+ ok(/No errors detected/.test(out), 'unzip -t accepts the exported .xlsx')
+} else console.log(' SKIP no unzip')
+
+if (have('python3', '-V')) {
+ const out = execFileSync('python3', ['-c',
+ 'import sys,zipfile\nz=zipfile.ZipFile(sys.argv[1])\nassert z.testzip() is None\nprint(len(z.namelist()))',
+ xlsxPath], { encoding: 'utf8' })
+ ok(Number(out.trim()) >= 7, 'python3 zipfile opens it and finds the OPC parts')
+} else console.log(' SKIP no python3')
+
+// --- OPC / SpreadsheetML PACKAGE CONFORMANCE
+//
+// This block exists because LIBREOFFICE IS TOO LENIENT to be the only witness.
+// Measured, as a negative control: delete every worksheet `<Override>` from
+// [Content_Types].xml, or write a styles part with no `cellStyleXfs` and no
+// fills, and LibreOffice still opens the file and converts it happily — while
+// Excel shows the repair dialog, which is the thing this exporter is actually
+// judged on and the thing there is no Excel on this machine to check.
+//
+// So the requirements Excel enforces are restated here, from the spec rather
+// than from our own writer: an unnamed part, an unresolvable relationship, a
+// style index past the end of cellXfs and a shared-string index past the end of
+// the table are each a "we found a problem with some content" dialog.
+{
+ const { readZip } = await import('../dash/src/zip.ts')
+ const pkg = await readZip(exported.bytes)
+ const dec = new TextDecoder()
+ const part = (n: string) => (pkg.has(n) ? dec.decode(pkg.get(n)!) : '')
+
+ const ct = part('[Content_Types].xml')
+ ok(ct.startsWith('<?xml'), '[Content_Types].xml is present')
+ ok(exported.bytes.indexOf(enc.encode('[Content_Types].xml')[0]) >= 0 &&
+ dec.decode(exported.bytes.subarray(30, 49)) === '[Content_Types].xml',
+ 'and it is the FIRST entry in the archive, which is the one ordering rule OPC states')
+ ok(/Extension="rels"/.test(ct) && /Extension="xml"/.test(ct), 'with Defaults for rels and xml')
+
+ const sheetParts = [...pkg.keys()].filter((k) => /^xl\/worksheets\/sheet\d+\.xml$/.test(k))
+ ok(sheetParts.length === 1, 'one worksheet part for the one sheet')
+ ok(sheetParts.every((p) => ct.includes(`PartName="/${p}"`) &&
+ ct.includes('spreadsheetml.worksheet+xml')),
+ 'EVERY worksheet part has a content-type Override (Excel refuses a package with an untyped part)')
+ for (const [p, type] of [
+ ['/xl/workbook.xml', 'sheet.main+xml'],
+ ['/xl/styles.xml', 'styles+xml'],
+ ['/xl/sharedStrings.xml', 'sharedStrings+xml'],
+ ]) {
+ ok(ct.includes(`PartName="${p}"`) && ct.includes(type), `${p} is typed as ${type}`)
+ }
+
+ // every relationship resolves to a part that exists
+ const rootRel = part('_rels/.rels')
+ ok(/Target="xl\/workbook\.xml"/.test(rootRel) && /officeDocument/.test(rootRel),
+ 'the package relationship points at the workbook')
+ const wbRels = part('xl/_rels/workbook.xml.rels')
+ const targets = [...wbRels.matchAll(/Target="([^"]+)"/g)].map((m) => `xl/${m[1]}`)
+ ok(targets.length >= 3 && targets.every((t) => pkg.has(t)),
+ `every workbook relationship resolves to a part that exists (${targets.length} of them)`)
+ const wb = part('xl/workbook.xml')
+ const used = [...wb.matchAll(/r:id="([^"]+)"/g)].map((m) => m[1])
+ ok(used.length > 0 && used.every((id) => wbRels.includes(`Id="${id}"`)),
+ 'and every r:id the workbook names is declared in its .rels')
+
+ // styles: the parts Excel requires, and no index past the end
+ const st = part('xl/styles.xml')
+ ok(/<cellStyleXfs count="\d+">[\s\S]*<xf[^>]*\/>[\s\S]*<\/cellStyleXfs>/.test(st),
+ 'styles.xml carries a cellStyleXfs block with at least one xf (Excel repairs a file without it)')
+ ok((st.match(/<fill>/g) ?? []).length >= 2 && /patternType="gray125"/.test(st),
+ 'and the two fills Excel requires, including the gray125 one nobody ever sees')
+ const xfCount = (part('xl/styles.xml').match(/<cellXfs count="(\d+)"/) ?? [])[1]
+ const sheet1 = part(sheetParts[0])
+ const styleIdx = [...sheet1.matchAll(/\ss="(\d+)"/g)].map((m) => Number(m[1]))
+ ok(styleIdx.length > 0 && styleIdx.every((i) => i < Number(xfCount)),
+ `every cell style index is inside cellXfs (${styleIdx.length} cells, ${xfCount} xfs)`)
+
+ // shared strings: every index resolves
+ const sst = part('xl/sharedStrings.xml')
+ const uniq = Number((sst.match(/uniqueCount="(\d+)"/) ?? [])[1])
+ const sIdx = [...sheet1.matchAll(/t="s"><v>(\d+)</g)].map((m) => Number(m[1]))
+ ok(sIdx.length > 0 && sIdx.every((i) => i < uniq),
+ `every shared-string index resolves (${sIdx.length} references, ${uniq} strings)`)
+ ok((sst.match(/<si>/g) ?? []).length === uniq, 'and uniqueCount matches the number of <si> elements')
+
+ // rows ascending, cell refs on their own row — Excel is strict about both
+ const rowNums = [...sheet1.matchAll(/<row r="(\d+)"/g)].map((m) => Number(m[1]))
+ ok(rowNums.every((n, i) => i === 0 || n > rowNums[i - 1]), 'rows are written in ascending order')
+ let refsOk = true
+ for (const m of sheet1.matchAll(/<row r="(\d+)">([\s\S]*?)<\/row>/g)) {
+ for (const c of m[2].matchAll(/<c r="([A-Z]+)(\d+)"/g)) if (c[2] !== m[1]) refsOk = false
+ }
+ ok(refsOk, 'and every cell reference names the row it is written in')
+}
+
+// --- LIBREOFFICE: the only check here that answers "does a real spreadsheet
+// application open this without a repair prompt?"
+{
+ const soffice = '/Applications/LibreOffice.app/Contents/MacOS/soffice'
+ if (existsSync(soffice)) {
+ const outDir = join(tmp, 'lo')
+ execFileSync(soffice, [
+ `-env:UserInstallation=file://${join(tmp, 'loprofile')}`,
+ '--headless', '--convert-to', 'csv', '--outdir', outDir, xlsxPath,
+ ], { stdio: 'ignore', timeout: 180_000 })
+ const csvName = readdirSync(outDir).find((f) => f.endsWith('.csv'))
+ const csv = csvName ? readFileSync(join(outDir, csvName), 'utf8') : ''
+ ok(!!csv, 'LibreOffice opens the exported workbook and converts it')
+ ok(/Region,Amount,Share,When,Live,Adjusted/.test(csv), 'with the header row intact')
+ // LibreOffice renders through the number formats, so these assert the
+ // FORMATS as well as the values.
+ ok(/North/.test(csv) && /1200\.5|1,200\.50|£1,200\.50/.test(csv), 'the money value is there')
+ ok(/2023-03-15/.test(csv), 'the date came out as a real date, on the right day')
+ ok(/15\.0%|15%/.test(csv), 'and the percent renders as 15%, not 1500% or 0.15')
+ ok(/TRUE/i.test(csv), 'booleans are booleans')
+ // the totals row: SUM(B2:B4) = 5500.5, MAX(F2:F4) = 30 (F4 is =F1+F2 → 30)
+ ok(/5500\.5|5,500\.50|£5,500\.50/.test(csv),
+ 'and LibreOffice CALCULATED the totals row from the SUM() we wrote')
+ if (!/5500\.5|5,500\.50|£5,500\.50/.test(csv)) console.log(csv)
+ } else console.log(' SKIP LibreOffice is not installed — the "does it open" check needs it')
+}
+
+// --- ROUND TRIP: dash → xlsx → dash
+{
+ const back = await importXlsx(exported.bytes, {})
+ const s = back.sheets[0]
+ ok(s.name === 'Pipeline', 'the sheet name survives')
+ ok(s.columns.map((c) => c.name).join() === 'Region,Amount,Share,When,Live,Adjusted',
+ 'every column name survives')
+ ok(s.columns.map((c) => c.type).join() === 'text,money,percent,date,bool,number',
+ 'and every TYPE survives, because the export wrote number formats that say so')
+ ok(readCell(s.data.region, 0) === 'North' && readCell(s.data.region, 1) === 'South',
+ 'a dictionary-encoded text column comes back')
+ ok(readCell(s.data.amount, 0) === 1200.5, 'money values are exact')
+ ok(readCell(s.data.share, 1) === 0.5, 'a percent is still a fraction after a full round trip')
+ ok(readCell(s.data.when, 0) === '2023-03-15', 'a date comes back as the same day')
+ ok(readCell(s.data.when, 2) === '1900-01-01',
+ 'INCLUDING a date before the phantom 29 February 1900, where a single epoch is off by one')
+ ok(readCell(s.data.live, 0) === true && readCell(s.data.live, 1) === false, 'booleans survive')
+ // the imported id is slugged from the column NAME, so `adj` comes back as `adjusted`
+ ok(s.cells?.['adjusted:3']?.f === '=F1+F2',
+ 'and the per-cell formula comes back pointing at the SAME cells (down one row on the way out, up one on the way in)')
+ ok(s.columns.find((c) => c.id === 'amount')?.w === 96 ||
+ Math.abs((s.columns.find((c) => c.id === 'amount')?.w as number) - 96) <= 4,
+ 'column width survives the character↔pixel conversion within a few pixels')
+}
+
+// --- what the export refuses to guess at
+{
+ const withFormula: DashDoc = JSON.parse(JSON.stringify(doc))
+ ;(withFormula.sheets[0] as TableSheet).columns.push({
+ id: 'calc', name: 'Weighted', type: 'number', formula: 'Amount * Share',
+ })
+ const r1 = await exportXlsx(withFormula, {})
+ ok(r1.findings.some((f) => f.code === 'formula-column'),
+ 'a COLUMN formula is reported rather than machine-translated into Excel syntax')
+ const r2 = await exportXlsx(withFormula, {
+ computed: { 'sheet-1': new Map([['calc', [180.075, 1700, 67.5]]]) },
+ })
+ const back = await importXlsx(r2.bytes, {})
+ ok(readCell(back.sheets[0].data.weighted, 1) === 1700,
+ 'and when the editor hands the computed values in, the NUMBERS travel')
+}
+
+{
+ const longName: DashDoc = JSON.parse(JSON.stringify(doc))
+ longName.sheets[0].name = 'A sheet name far longer than thirty-one characters [really]'
+ const r = await exportXlsx(longName, {})
+ ok(r.findings.some((f) => f.code === 'renamed-sheet'),
+ 'an illegal sheet name is fixed and reported — Excel refuses to OPEN the file rather than warning')
+ const back = await importXlsx(r.bytes, {})
+ ok(back.sheets[0].name.length <= 31 && !/[[\]:*?/\\]/.test(back.sheets[0].name),
+ 'and the name it was given is legal')
+}
+
+ok(_internals.safeSheetName('a/b:c', new Set()) === 'a-b-c', 'the forbidden characters are replaced')
+ok(_internals.safeSheetName('Sheet', new Set(['sheet'])) === 'Sheet 2', 'and a duplicate is disambiguated')
+ok(xlsxFileName('Q1 / plan') === 'Q1 - plan.xlsx', 'the download name is filesystem-safe')
+
+// =========================================== REAL .xlsx FILES OFF THIS MACHINE
+{
+ const candidates = [
+ '/Users/andy/devel/sxadc/raw_categories.xlsx',
+ '/Users/andy/Documents/Digitalise Growth-Initiatives-Cost-Model.xlsx',
+ '/Users/andy/Downloads/Digital_Sonar_Resource_Validation_v5.xlsx',
+ ].filter(existsSync)
+ if (!candidates.length) console.log(' SKIP no real .xlsx to import')
+ for (const path of candidates) {
+ const short = path.split('/').pop()!
+ let r
+ try {
+ r = await importXlsx(new Uint8Array(readFileSync(path)), { source: short })
+ } catch (e) {
+ failures++; checks++
+ console.log(` FAIL ${short}: ${e instanceof Error ? e.message : String(e)}`)
+ continue
+ }
+ const rows = r.sheets.reduce((n, s) => n + s.rids.reduce((m, [, c]) => m + c, 0), 0)
+ ok(r.sheets.length > 0 && rows > 0, `${short}: ${r.sheets.length} sheet(s), ${rows} rows`)
+ // and the result must be a legal document
+ const parsed = parseDoc(JSON.stringify({
+ format: 'bento/dash', version: 1, docId: 'd', title: short, sheets: r.sheets,
+ }))
+ ok(parsed.ok === true, `${short}: parses as a bento/dash document`)
+ // and it must export again without throwing
+ const out = await exportXlsx(parsed.ok ? parsed.doc : ({} as DashDoc), {})
+ ok(out.bytes.length > 0, `${short}: re-exports to a non-empty .xlsx`)
+ if (have('unzip', '-v')) {
+ const p = join(tmp, `re-${short}`)
+ writeFileSync(p, out.bytes)
+ ok(/No errors detected/.test(execFileSync('unzip', ['-t', p], { encoding: 'utf8' })),
+ `${short}: and that re-export is a valid archive`)
+ }
+ }
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)
diff --git a/scripts/test-dash-zip.ts b/scripts/test-dash-zip.ts
new file mode 100644
index 00000000..58644885
--- /dev/null
+++ b/scripts/test-dash-zip.ts
@@ -0,0 +1,314 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2026 The Bento authors
+// bento/dash ZIP rig.
+//
+// node scripts/test-dash-zip.ts (Node ≥ 23.6 strips types natively)
+//
+// WHAT THIS PROVES, and why it is not "the bytes look right". A reader and a
+// writer written by the same person on the same afternoon agree with each other
+// perfectly, including about their shared bugs — a round-trip through our own
+// code is worth almost nothing on its own. So every claim here is checked
+// against something that did NOT come out of dash/src/zip.ts:
+//
+// • CRC-32 against the published check value for "123456789" (0xCBF43926).
+// • our DEFLATE stream against node:zlib's inflateRawSync.
+// • our whole archive against /usr/bin/unzip — `unzip -t` (checksums), and
+// `unzip -p` (the actual bytes back out).
+// • our READER against `unzip -p` on REAL .xlsx files found on this machine,
+// written by Excel, Numbers and whatever server generated them.
+//
+// And the negative half: a truncated archive, a flipped byte and an encrypted
+// entry must all be REFUSED, because a ZIP reader that returns short data
+// silently is a spreadsheet importer that drops rows silently.
+
+import { execFileSync } from 'node:child_process'
+import { inflateRawSync, deflateRawSync } from 'node:zlib'
+import { mkdtempSync, writeFileSync, readFileSync, existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { readZip, writeZip, crc32, concat, ZipError } from '../dash/src/zip.ts'
+
+let failures = 0
+let checks = 0
+function ok(cond: boolean, msg: string) {
+ checks++
+ if (!cond) { failures++; console.log(` FAIL ${msg}`) }
+ else console.log(` ok ${msg}`)
+}
+
+const enc = new TextEncoder()
+const dec = new TextDecoder()
+const tmp = mkdtempSync(join(tmpdir(), 'dash-zip-'))
+
+/** Does the archive round-trip through a real unzip? Returns its report. */
+function realUnzip(bytes: Uint8Array, name: string): { test: string; get: (part: string) => string } {
+ const path = join(tmp, name)
+ writeFileSync(path, bytes)
+ return {
+ test: execFileSync('unzip', ['-t', path], { encoding: 'utf8' }),
+ get: (part: string) => execFileSync('unzip', ['-p', path, part], { encoding: 'utf8' }),
+ }
+}
+
+// ------------------------------------------------------------------- CRC-32
+{
+ // The check value every CRC-32 implementation is published against. Ours
+ // agreeing with itself proves nothing; agreeing with this proves the
+ // polynomial, the reflection and the final xor.
+ ok(crc32(enc.encode('123456789')) === 0xcbf43926, 'CRC-32 matches the published check value for "123456789"')
+ ok(crc32(new Uint8Array(0)) === 0, 'CRC-32 of nothing is 0')
+ ok(crc32(enc.encode('a')) !== crc32(enc.encode('b')), 'and it is not a constant')
+}
+
+// -------------------------------------------------- our DEFLATE, node's INFLATE
+{
+ const body = enc.encode('sheetData'.repeat(400))
+ const zipped = await writeZip([{ name: 'x.txt', data: body }])
+ // dig the stored bytes out by hand rather than through our own reader
+ const v = new DataView(zipped.buffer, zipped.byteOffset, zipped.byteLength)
+ const method = v.getUint16(8, true)
+ const csize = v.getUint32(18, true)
+ const at = 30 + v.getUint16(26, true) + v.getUint16(28, true)
+ ok(method === 8, 'a compressible part is DEFLATEd')
+ const back = inflateRawSync(Buffer.from(zipped.subarray(at, at + csize)))
+ ok(dec.decode(back) === dec.decode(body), 'and node:zlib inflates our stream to the original bytes')
+ ok(csize < body.length / 4, 'and it actually compressed (repetitive text, >4x)')
+}
+
+// --------------------------------------------------------- /usr/bin/unzip
+const have = (cmd: string, arg: string): boolean => {
+ try { execFileSync(cmd, [arg], { stdio: 'ignore' }); return true } catch { return false }
+}
+const haveUnzip = have('unzip', '-v')
+const havePython = have('python3', '-V')
+
+if (!haveUnzip) {
+ console.log(' SKIP /usr/bin/unzip is not on this machine — the external check is the point of this rig')
+} else {
+ const entries = [
+ { name: '[Content_Types].xml', data: enc.encode('<Types/>') },
+ { name: 'xl/workbook.xml', data: enc.encode('<workbook>' + 'x'.repeat(5000) + '</workbook>') },
+ { name: 'xl/empty.bin', data: new Uint8Array(0) },
+ { name: 'xl/tiny.txt', data: enc.encode('hi') },
+ { name: 'xl/ünïcode name.xml', data: enc.encode('<a>é</a>') },
+ ]
+ const bytes = await writeZip(entries)
+ const u = realUnzip(bytes, 'ours.zip')
+ ok(/No errors detected/.test(u.test), 'unzip -t accepts our archive (every CRC checks out)')
+ ok(u.get('xl/workbook.xml').includes('xxxxx'), 'unzip -p gets a DEFLATEd part back')
+ ok(u.get('xl/tiny.txt') === 'hi', 'and a STORED one')
+ // macOS's Info-ZIP 6.0 mangles UTF-8 member names on the way OUT (it maps
+ // the bytes through a local-charset table even with the UTF-8 flag set), so
+ // it cannot be the witness for this one — `unzip -l` prints `++n+»code`.
+ // That is Info-ZIP's bug, not the archive's, and the fix is a different third
+ // party rather than a weaker claim: python3's zipfile is an independent
+ // implementation that gets it right.
+ if (havePython) {
+ const out = execFileSync('python3', ['-c',
+ 'import sys,zipfile\n' +
+ 'z=zipfile.ZipFile(sys.argv[1])\n' +
+ 'assert z.testzip() is None\n' +
+ 'print("\\n".join(z.namelist()))\n' +
+ 'print(z.read("xl/\u00fcn\u00efcode name.xml").decode())',
+ join(tmp, 'ours.zip')], { encoding: 'utf8' })
+ ok(out.includes('xl/ünïcode name.xml') && out.includes('<a>é</a>'),
+ 'python3 zipfile reads our UTF-8 part name and its contents (and testzip passes)')
+ } else {
+ console.log(' SKIP python3 is not on this machine — the UTF-8 name check needs a second unzip')
+ }
+
+ // zipinfo reports the methods, so "we deflated" is checked by a third party
+ const info = execFileSync('zipinfo', ['-v', join(tmp, 'ours.zip')], { encoding: 'utf8' })
+ ok(/deflated/.test(info) && /stored/.test(info), 'zipinfo sees both deflated and stored members')
+
+ const stored = await writeZip(entries, { store: true })
+ ok(/No errors detected/.test(realUnzip(stored, 'stored.zip').test),
+ 'the STORED fallback (no CompressionStream) is also a valid archive')
+ ok(stored.length > bytes.length, 'and it is bigger, which is the trade it makes')
+}
+
+// ------------------------------------------------------------- round-trip
+{
+ const entries = [
+ { name: 'a.xml', data: enc.encode('<a/>') },
+ { name: 'deep/path/b.xml', data: enc.encode('<b>' + 'y'.repeat(9000) + '</b>') },
+ { name: 'zero.bin', data: new Uint8Array(0) },
+ ]
+ const parts = await readZip(await writeZip(entries))
+ ok(parts.size === 3, 'every entry comes back')
+ ok(dec.decode(parts.get('a.xml')!) === '<a/>', 'a stored part round-trips')
+ ok(dec.decode(parts.get('deep/path/b.xml')!).length === 9007, 'a deflated part round-trips at full length')
+ ok(parts.get('zero.bin')!.length === 0, 'and an empty part stays empty rather than vanishing')
+
+ // determinism: an export you can diff
+ const one = await writeZip(entries)
+ const two = await writeZip(entries)
+ ok(Buffer.from(one).equals(Buffer.from(two)), 'two writes of one input are byte-identical (fixed timestamp)')
+}
+
+// ----------------------------------------------- a zip node:zlib built for us
+{
+ // Hand-built central directory + local header around node's DEFLATE output,
+ // so the READER is fed bytes our writer never touched.
+ const body = enc.encode('<x>hand built</x>')
+ const z = new Uint8Array(deflateRawSync(Buffer.from(body)))
+ const name = enc.encode('hand.xml')
+ const lh = new Uint8Array(30 + name.length)
+ const lv = new DataView(lh.buffer)
+ lv.setUint32(0, 0x04034b50, true); lv.setUint16(4, 20, true)
+ lv.setUint16(8, 8, true); lv.setUint32(14, crc32(body), true)
+ lv.setUint32(18, z.length, true); lv.setUint32(22, body.length, true)
+ lv.setUint16(26, name.length, true); lh.set(name, 30)
+ const ch = new Uint8Array(46 + name.length)
+ const cv = new DataView(ch.buffer)
+ cv.setUint32(0, 0x02014b50, true); cv.setUint16(4, 20, true); cv.setUint16(6, 20, true)
+ cv.setUint16(10, 8, true); cv.setUint32(16, crc32(body), true)
+ cv.setUint32(20, z.length, true); cv.setUint32(24, body.length, true)
+ cv.setUint16(28, name.length, true); cv.setUint32(42, 0, true); ch.set(name, 46)
+ const eocd = new Uint8Array(22)
+ const ev = new DataView(eocd.buffer)
+ ev.setUint32(0, 0x06054b50, true); ev.setUint16(8, 1, true); ev.setUint16(10, 1, true)
+ ev.setUint32(12, ch.length, true); ev.setUint32(16, lh.length + z.length, true)
+ const built = concat([lh, z, ch, eocd])
+ const parts = await readZip(built)
+ ok(dec.decode(parts.get('hand.xml')!) === '<x>hand built</x>',
+ 'our reader reads an archive assembled from node:zlib bytes')
+}
+
+// ------------------------------------------------------------------- ZIP64
+// Both saturation paths, built by python3 (an implementation that is not ours):
+// the per-entry extra field, and the ZIP64 end-of-central-directory record that
+// appears once an archive has more than 65,535 members. Excel writes both.
+if (havePython) {
+ const script = (body: string) => execFileSync('python3', ['-c', body], { encoding: 'buffer', maxBuffer: 1 << 28 })
+
+ const one = script(
+ 'import zipfile,io,sys\n' +
+ 'b=io.BytesIO()\n' +
+ "with zipfile.ZipFile(b,'w',zipfile.ZIP_DEFLATED) as z:\n" +
+ " with z.open('xl/workbook.xml','w',force_zip64=True) as f: f.write(b'<workbook>zip64</workbook>')\n" +
+ 'sys.stdout.buffer.write(b.getvalue())')
+ const p1 = await readZip(new Uint8Array(one))
+ ok(dec.decode(p1.get('xl/workbook.xml')!) === '<workbook>zip64</workbook>',
+ 'a ZIP64 per-entry extra field is read (the sizes saturate to 0xFFFFFFFF and live in the extra)')
+
+ const many = script(
+ 'import zipfile,io,sys\n' +
+ 'b=io.BytesIO()\n' +
+ "with zipfile.ZipFile(b,'w',zipfile.ZIP_STORED) as z:\n" +
+ " [z.writestr('p%05d.txt'%i,'') for i in range(70000)]\n" +
+ " z.writestr('xl/workbook.xml','<workbook>many</workbook>')\n" +
+ 'sys.stdout.buffer.write(b.getvalue())')
+ const p2 = await readZip(new Uint8Array(many))
+ ok(p2.size === 70001 && dec.decode(p2.get('xl/workbook.xml')!) === '<workbook>many</workbook>',
+ 'and a ZIP64 end-of-central-directory record is followed — without it the count saturates at 65535 and the directory is read from offset 0xFFFFFFFF')
+} else {
+ console.log(' SKIP python3 is not on this machine — the ZIP64 archives need a second implementation to build')
+}
+
+// ---------------------------------------------------- REAL .xlsx off this disk
+{
+ const candidates = [
+ '/Users/andy/Documents/Digitalise Growth-Initiatives-Cost-Model.xlsx',
+ '/Users/andy/Downloads/Digital_Sonar_Resource_Validation_v5.xlsx',
+ '/Users/andy/devel/sxadc/raw_categories.xlsx',
+ ].filter((p) => existsSync(p))
+
+ if (!candidates.length) {
+ console.log(' SKIP no real .xlsx on this machine to read')
+ } else {
+ for (const path of candidates) {
+ const parts = await readZip(new Uint8Array(readFileSync(path)))
+ const short = path.split('/').pop()
+ ok(parts.has('[Content_Types].xml') && parts.has('xl/workbook.xml'),
+ `${short}: the OPC parts are there`)
+ if (haveUnzip) {
+ // byte-for-byte against a real unzip on a part we did not choose for
+ // being easy — the workbook, which Excel deflates.
+ const theirs = execFileSync('unzip', ['-p', path, 'xl/workbook.xml'], { maxBuffer: 1 << 28 })
+ ok(Buffer.from(parts.get('xl/workbook.xml')!).equals(theirs),
+ `${short}: our inflate matches unzip -p byte for byte`)
+ }
+ }
+ }
+}
+
+// ------------------------------------------------------- NEGATIVE: refusals
+async function refuses(fn: () => Promise<unknown>, want: RegExp, msg: string) {
+ checks++
+ try {
+ await fn()
+ failures++
+ console.log(` FAIL ${msg} (it accepted the input)`)
+ } catch (e) {
+ const m = e instanceof Error ? e.message : String(e)
+ if (e instanceof ZipError && want.test(m)) console.log(` ok ${msg}`)
+ else { failures++; console.log(` FAIL ${msg} — threw the wrong thing: ${m}`) }
+ }
+}
+
+{
+ const good = await writeZip([{ name: 'a.xml', data: enc.encode('<a>' + 'q'.repeat(3000) + '</a>') }])
+
+ await refuses(() => readZip(enc.encode('not a zip at all, just some text')),
+ /not an \.xlsx|central directory/, 'a non-ZIP is refused')
+
+ await refuses(() => readZip(new Uint8Array(4)), /too small/, 'a 4-byte file is refused')
+
+ // TRUNCATION: keep the directory, lose the data. This is the mail-gateway /
+ // partial-download case, and the one that must never return short data.
+ {
+ const cut = good.slice()
+ // blank the last 40 bytes of the compressed body (before the directory)
+ cut.fill(0, 40, 60)
+ await refuses(() => readZip(cut), /checksum|truncated|damaged|decompressed/,
+ 'a corrupted body fails its checksum rather than returning wrong bytes')
+ }
+
+ // A single flipped byte inside the compressed data.
+ {
+ const bent = good.slice()
+ bent[45] ^= 0xff
+ await refuses(() => readZip(bent), /checksum|truncated|damaged|decompressed/, 'one flipped byte is caught')
+ }
+
+ // A STORED entry with a flipped byte. This one is checked SEPARATELY from the
+ // deflated cases above, and it is the only check that isolates the CRC: a
+ // damaged deflate stream also fails to inflate and also comes out the wrong
+ // length, so it would pass with the checksum verification deleted. Stored
+ // bytes inflate perfectly and are exactly the right length; nothing but the
+ // CRC can tell they are not the bytes that were written.
+ {
+ const short = await writeZip([{ name: 'tiny.xml', data: enc.encode('<a>0123456789</a>') }])
+ const bent = short.slice()
+ const at = bent.indexOf(0x30) // the '0' inside the stored payload
+ bent[at] = 0x39
+ await refuses(() => readZip(bent), /checksum/,
+ 'a flipped byte in a STORED entry is caught by the CRC alone')
+ }
+
+ // ENCRYPTED: set general-purpose bit 0 in the central directory.
+ {
+ const locked = good.slice()
+ const v = new DataView(locked.buffer)
+ // find the central directory header and set its flag word
+ for (let i = 0; i < locked.length - 4; i++) {
+ if (v.getUint32(i, true) === 0x02014b50) { v.setUint16(i + 8, 1, true); break }
+ }
+ await refuses(() => readZip(locked), /encrypted/, 'an encrypted entry is refused by name, not half-read')
+ }
+
+ // An unsupported compression method (bzip2 = 12).
+ {
+ const odd = good.slice()
+ const v = new DataView(odd.buffer)
+ for (let i = 0; i < odd.length - 4; i++) {
+ if (v.getUint32(i, true) === 0x02014b50) { v.setUint16(i + 10, 12, true); break }
+ }
+ await refuses(() => readZip(odd), /compression method 12/, 'an unimplemented method is named, not guessed at')
+ }
+}
+
+console.log(`\n${checks - failures}/${checks} checks passed`)
+if (failures) process.exit(1)