Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
bento/dash: a spreadsheet you could use instead of Excel (#248)
nyblneta7f2e83aeabc
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 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 defaultdiff --git a/dash/index.html b/dash/index.htmlindex 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.tsnew file mode 100644index 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.cssnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.cssnew file mode 100644index 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.tsnew file mode 100644index 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) =>+ ({ '&': '&', '<': '<', '>': '>', '"': '"', "'": ''' }[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.tsnew file mode 100644index 00000000..942853b2Binary files /dev/null and b/dash/src/filter.ts differdiff --git a/dash/src/formula.ts b/dash/src/formula.tsindex 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 ** dpreturn 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 argumentsIF: (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.tsnew file mode 100644index 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.tsindex 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 = 52const OVERSCAN = 8export 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.elthis.store = opts.storethis.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 = idthis.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.sheetif (!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.sheetconst 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.valuesthis.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.sheetconst 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.sheetconst 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 chargetSelection()?.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 = truethis.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, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"')diff --git a/dash/src/main.ts b/dash/src/main.tsindex 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'): votitleEl.value = doc.titletitleEl.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) returnbinding.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 = nullbinding = 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'): vodocument.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() })+// --- actionsapp.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') returnconst text = e.clipboardData?.getData('text/plain')- if (!text || !/[,;\t]/.test(text.split('\n')[0] ?? '')) return+ if (!text) returne.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, '&').replace(/</g, '<').replace(/>/g, '>')+// 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, '&').replace(/</g, '<').replace(/>/g, '>')+}// 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.tsindex 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?: numbercolumns: 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: numbery: numberw: 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' | nulloption?: 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: stringname: 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: numberh: numbertiles: Tile[]@@ -312,6 +422,8 @@ export interface DashDoc {meta?: DocMetasheets: Sheet[]measures?: Record<string, Measure>+ /** the data story — see the Story block at the foot of this file */+ story?: Storynames?: 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: stringbecame: 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 DashDocreturn 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.cssnew file mode 100644index 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.tsnew file mode 100644index 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.cssnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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, '&').replace(/</g, '<').replace(/>/g, '>')+ .replace(/"/g, '"').replace(/'/g, ''')++/**+ * 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.tsnew file mode 100644index 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.cssnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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 = () => voidexport 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: Tp.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.cellsreturn {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: Tcase '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: Tcase '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 dataconst 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.titledoc.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) returnthis.endRun()- const list = Array.isArray(patches) ? patches : [patches]+ const list = this.runBefore(Array.isArray(patches) ? patches : [patches])+ if (!list.length) returnconst inverse: Patch[] = []const touched: Touched = {}let bytes = 0@@ -440,6 +731,7 @@ export class Store {this.touch()this.lastTouched = touchedthis.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) returnif (this.runCell !== cellKey) {this.endRun()this.runCell = cellKeythis.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.touchedthis.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 = touchedthis.emit('doc')+ this.runAfter()return { inverse, touched, bytes }}diff --git a/dash/src/story.css b/dash/src/story.cssnew file mode 100644index 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.tsnew file mode 100644index 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, '&').replace(/</g, '<').replace(/>/g, '>')++/**+ * 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.cssindex 353034c5..c0e98134 100644--- a/dash/src/styles.css+++ b/dash/src/styles.css@@ -2,16 +2,182 @@Copyright (c) 2026 The Bento authorsbento/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 inflow 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.cssnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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, '&').replace(/</g, '<').replace(/>/g, '>')++/** 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.tsnew file mode 100644index 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 * 1024diff --git a/dash/src/viz3d.ts b/dash/src/viz3d.tsnew file mode 100644index 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 === '&' ? '&' : c === '<' ? '<' : c === '>' ? '>' : '"'))++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.tsnew file mode 100644index 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 === '&' ? '&' : ch === '<' ? '<' : ch === '>' ? '>'+ : ch === '"' ? '"' : 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.mjsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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('<'), '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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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) !== beforeconst 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 tripsroundTrip('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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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('<script>'), '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.tsnew file mode 100644index 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 & b <c> "d" 'e'') === `a & b <c> "d" 'e'`,+ 'the five named entities decode')+ ok(unescapeXml('AB') === '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 & b <c>', '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: ['"£"#,##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.tsnew file mode 100644index 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)