Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

59.1 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Document state, undo history, and the TYPING RUN.
//
// THE TYPING RUN and THE BYTE CAP are spaces' (spaces/src/store.ts:6-13, :20-23),
// taken deliberately and unchanged. Slides sidesteps commit granularity because
// canvas text commits on blur; a grid may never blur, so this one policy sets
// undo granularity, autosave churn, the dirty flag and later the collab op rate.
// A run is consecutive input in ONE cell with no structural op between: one
// checkpoint at its first input, later inputs mutate in place, closing on idle,
// on the caret leaving the cell, on any structural change, on save and on
// replaceDoc.
//
// THE ENTRY BODY IS WHERE DASH DIVERGES, and it is the sharpest divergence in
// the app. spaces snapshots `JSON.stringify(doc minus assets)` per checkpoint
// (store.ts:137-142) — the right instinct, since it forked slides' MAX_UNDO=100
// entry cap into a byte cap precisely because whole-document snapshots do not
// scale, but an incomplete fork: it still stringifies the whole document.
// Measured on a 12.2 MB workbook: 10 ms per checkpoint — most of a 16 ms frame,
// paid in the frame the user starts typing — and 1.19 GB of live strings for a
// full stack. Unusable at 50k-100k cells, OOM before 500k.
//
// So history here is a list of TYPED INVERSES, each carrying only what it
// touched, minted at the edit site. A 10,000-cell paste is one entry holding
// 10,000 values, not 100 copies of the workbook.
//
// The same Patch objects are the undo entries, the future CRDT ops and the
// agent API. That is why this lands at commit one: retrofitting op-minting
// means rewriting the store.

import { t } from './i18n.ts'
import { applySheetProps } from './rowcol.ts'
// The one definition of "what counts as a number" — import's. A second
// implementation here is how a value converts on import and refuses on a
// type change, or the other way round.
import { coerce, encodeColumn, inferColumn } from './import.ts'
import { PROVENANCE_OPS } from './steps.ts'
import type { CellOverride, Comment, View, Column, ColumnData, ColumnType, DashDoc, Measure, Sheet, Step, TableSheet, CanvasCell, CanvasSheet } from './model.ts'

type Listener = () => void
/**
 * 'unsaved' — the document changed in a way that is not an edit to its data
 * and goes through no patch (sharing switched on or off, keys rotated), but
 * the FILE must still be rewritten for it. See `markUnsaved`.
 */
export type StoreEvent = 'doc' | 'view' | 'selection' | 'unsaved'

/** Idle that closes a run. Autosave debounces longer, so no snapshot lands mid-run. */
const RUN_IDLE_MS = 600

/**
 * Undo is bounded by BYTES, not entries — spaces' correction to slides'
 * MAX_UNDO = 100, and the right one. What differs is what the bytes measure:
 * here it is the size of the patches themselves, not of document copies.
 */
const UNDO_BYTES = 24 * 1024 * 1024

// --- Patches ---------------------------------------------------------------

/**
 * One undoable change, carrying only what it touched.
 *
 * Every variant is INVERTIBLE: `applyPatch` returns the patch that undoes it,
 * built from the values it displaced. Nothing here reads the whole document.
 */
export type Patch =
  /** `dictLen` truncates a dictionary that this edit grew. Without it, undo
   *  restores the values and leaves the orphaned strings behind — the document
   *  is semantically right and no longer byte-identical, and the dictionary
   *  grows forever under editing. */
  | { op: 'setCells'; sheet: string; col: string; rids: number[]; v: unknown[]; dictLen?: number }
  /** `dropEmpty` removes the `cells` container the forward patch created. An
   *  apply-then-undo that leaves `"cells": {}` behind is not a round trip. */
  | {
      op: 'setOverrides'; sheet: string; keys: string[]
      /** `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
   * before this was fixed: deleting row 2 of [10,20,30,40] and undoing gave
   * [10,30,40,20].
   */
  | {
      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>;
      /** the pre-conversion bytes, set only on the INVERSE of a type change */
      data?: ColumnData }
  /** `at` is the position; omitted appends. `data` is omitted for a FORMULA
   *  column, which has no stored values — its numbers are derived from its
   *  expression, so storing them would let a file carry a number that
   *  disagrees with the formula that produced it. */
  | { op: 'addColumn'; sheet: string; column: Column; at?: number; data?: ColumnData }
  | { op: 'removeColumn'; sheet: string; col: string }
  | { 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 }
  /**
   * Sheet ORDER, as a permutation of the ids. The tab strip's drag, and
   * `Move left` / `Move right`.
   *
   * WHY THIS EXISTS RATHER THAN TWO `setSheet`s. A move used to be a remove
   * followed by a re-insert, which is correct — `setSheet` on a sheet already
   * in the document REPLACES it in place, so one patch could not express a
   * move — and its inverse was correct too, carrying the sheet and its original
   * index so one ⌘Z put the tab back where it was rather than at the end.
   *
   * What it was not is CHEAP. This history is bounded by BYTES (see the header
   * and `UNDO_BYTES`), and the accounting is `JSON.stringify` of the inverse —
   * so the inverse of a re-insert stringified the WHOLE SHEET. Dragging a tab
   * on a 12MB workbook spent 12MB of a 24MB budget and evicted every earlier
   * entry: two drags and the undo stack was two drags long. O(sheet) for an
   * operation that changes an ARRAY ORDER, which is O(number of sheets) —
   * twenty ids, about 200 bytes, whatever the workbook weighs.
   *
   * MUST BE A PERMUTATION. `reorderColumns` drops ids it cannot find, which is
   * survivable for a column list; here an id left out of `order` would DELETE
   * a sheet, and a delete arriving inside a reorder is the kind of data loss
   * nobody thinks to look for. It is refused loudly instead, and
   * `crdt.committable` refuses it BEFORE the commit when a collaborator has
   * changed the sheet list underneath it.
   */
  | { op: 'reorderSheets'; order: string[] }
  /**
   * One comment thread, by id. `comment: undefined` removes it.
   *
   * Per-thread rather than rewriting `Sheet.comments` through `setSheetProps`:
   * that carried the WHOLE array in the inverse — about 75KB per keystroke at
   * five hundred threads, against a 24MB history cap — and under collaboration
   * it is a single LWW register, so two people adding a thread in the same
   * moment keep one of them. Keyed by id, exactly as `setView` is.
   */
  | { op: 'setComment'; sheet: string; id: string; comment?: Comment; at?: number }
  /**
   * Cells on a SPREADSHEET sheet (`kind: 'canvas'` — the sparse A1 map that has
   * been in the format since commit one).
   *
   * Keyed by **A1 address** — `A1`, `B7` — which is the format's key for this
   * kind and not a choice made here. model.ts calls it "the classic sparse A1
   * map"; `validate.ts` raises `bad-canvas-key` for anything else; `preview.ts`
   * parses A1 to find the used range for a file-manager thumbnail. It is NOT
   * `cellformula.cellKey(row, col)` — that is an internal computation key for a
   * recalc map, and writing it into the document would have made every cell
   * this op wrote invisible to the validator, the thumbnail and any other build.
   *
   * One op carries MANY cells because a paste, a fill and a delete are each one
   * edit to a reader and must be one undo step.
   *
   * A `null` or `undefined` entry REMOVES the cell rather than storing an empty
   * object — a sparse sheet whose cleared cells linger as `{}` is neither sparse
   * nor equal to the same sheet reached another way. `null` is the spelling that
   * survives JSON, which is what a collaborator receives.
   */
  | { op: 'setCanvasCells'; sheet: string; cells: Record<string, CanvasCell | null> }
  /**
   * Column widths and row heights on a SPREADSHEET sheet.
   *
   * `cols` is keyed by column LETTER and `rows` by the 1-based row number — the
   * two halves of an A1 address, so `"C": 180` reads as the column a reader can
   * see. A `null` removes the key, for the reason `setCanvasCells` gives.
   *
   * A SEPARATE OP from `setCanvasCells` rather than two more fields on it,
   * because the containers differ in the one way an inverse cares about:
   * `cells` is required on the kind and always exists, while `cols`/`rows` are
   * optional — so this op creates a container on the first write and deletes it
   * with the last key, or an apply-then-undo leaves `"cols": {}` in the file
   * for every other reader to diff.
   */
  | {
      op: 'setCanvasSizes'; sheet: string
      cols?: Record<string, number | null>; rows?: Record<string, number | null>
    }
  /**
   * RESERVED. Both need the transform engine, which does not exist yet. They
   * are in the union now because the discriminant cannot be retrofitted once
   * patches are also CRDT ops. `applyPatch` refuses them loudly rather than
   * pretending — a silent no-op here would be an edit the user believes landed.
   */
  | { 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.
 *
 * If undo emitted a document-wide invalidation the patch log's entire win would
 * be thrown away at undo time — spaces' `restore` emits `doc`+`tree`+`page` and
 * the editor rebuilds the page, which is correct for a page of prose and wrong
 * for 100k rows. A patch knows which cells it touched; the invalidation carries
 * that.
 */
export interface Touched {
  sheet?: string
  cols?: string[]
  rids?: number[]
  /** structure changed (rows added/removed, columns reordered) — relayout, not repaint */
  structural?: boolean
  /** genuinely everything: replaceDoc, and nothing else */
  all?: boolean
}

interface Entry {
  /** the patches that undo this step, in reverse application order */
  inverse: Patch[]
  touched: Touched
  bytes: number
}

// --- Column encoding -------------------------------------------------------
// Reading and writing one cell has to understand the encoding, because the
// encoding is what makes the format fit (4.8 bytes/cell dictionary-columnar
// against 15.9 array-of-objects). `pack` is an author-chosen archive encoding
// and is READ-ONLY here: writing to it would mean inflating a whole column on
// a keystroke, so an edit promotes it to `raw` at the call site instead.

/**
 * Row ids are run-length encoded — `[[1, 4200]]` is 20 bytes for 4200 rows —
 * 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. So structural
 * ops expand, manipulate and re-compress; only reads walk the runs.
 */
const expandRids = (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
}

const compressRids = (flat: number[]): Array<[number, number]> => {
  const out: Array<[number, number]> = []
  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
}

const ridIndex = (sheet: TableSheet, rid: number): number => {
  let i = 0
  for (const [start, count] of sheet.rids) {
    if (rid >= start && rid < start + count) return i + (rid - start)
    i += count
  }
  return -1
}

/**
 * Change a column's type, and SAY SO when it will not go.
 *
 * The `setColumn` case throws when a value cannot be read as the new type,
 * which is the right thing — refusing beats zeroing. But a throw is only half
 * an answer, and the missing half was measured on screen: the reader picked
 * "Money", the commit threw into the console, and the dropdown went on
 * displaying **money** while the column header chip beside it displayed
 * **Text**. Two controls disagreeing, no message, nothing to act on.
 *
 * That is the same shape as the bug this whole change exists to fix — the app
 * knowing something and not saying it — and it is the second time this exact
 * pattern has appeared in this codebase, after the Offline switch that stayed
 * ticked over a preference that had not persisted.
 *
 * So both call sites go through here: it commits, and on refusal it reports the
 * reason and returns false so the caller can put its control back. A third call
 * site that forgets is the failure mode this function exists to remove.
 */
export function setColumnType(
  store: Store,
  sheetId: string,
  colId: string,
  next: ColumnType,
  report: (message: string) => void,
): boolean {
  try {
    store.commit({ op: 'setColumn', sheet: sheetId, col: colId, patch: { type: next } })
    return true
  } catch (e) {
    report(e instanceof Error ? e.message : String(e))
    return false
  }
}

export function readCell(data: ColumnData | undefined, row: number): unknown {
  if (!data || row < 0) return null
  if (data.enc === 'raw') return data.v[row] ?? null
  if (data.enc === 'dict') {
    const k = data.idx[row]
    return k == null ? null : (data.dict[k] ?? null)
  }
  return null // `pack` is opaque until inflated
}

function writeCell(data: ColumnData, row: number, v: unknown): void {
  if (data.enc === 'raw') {
    data.v[row] = v as never
    return
  }
  if (data.enc === 'dict') {
    if (v == null) { data.idx[row] = null; return }
    const s = String(v)
    let k = data.dict.indexOf(s)
    if (k < 0) { k = data.dict.length; data.dict.push(s) }
    data.idx[row] = k
    return
  }
  throw new Error('cannot write into a packed column; promote it to raw first')
}

const totalRows = (sheet: TableSheet): number =>
  sheet.rids.reduce((n, [, c]) => n + c, 0)

// --- Apply -----------------------------------------------------------------

const table = (doc: DashDoc, id: string): TableSheet => {
  const s = doc.sheets.find((x: Sheet) => x.id === id)
  if (!s || s.kind !== 'table') throw new Error(`no table sheet ${id}`)
  return s
}

/**
 * The sheet by id, WHATEVER ITS KIND — for the ops that are about a sheet
 * rather than about a dataset. `setSheetProps` is the one today (a name, and
 * later anything else every kind has); `setComment` says the same thing inline
 * because a remark on a pivot is a remark.
 *
 * Still throws when the id names nothing: an op that cannot find its target is
 * an edit the user believes landed, and applyPatch's rule is to refuse loudly.
 */
const anySheet = (doc: DashDoc, id: string): Sheet => {
  const s = doc.sheets.find((x: Sheet) => x.id === id)
  if (!s) throw new Error(`no sheet ${id}`)
  return s
}

const canvas = (doc: DashDoc, id: string): CanvasSheet => {
  const s = doc.sheets.find((x: Sheet) => x.id === id)
  if (!s || s.kind !== 'canvas') throw new Error(`no spreadsheet sheet ${id}`)
  return s
}

/**
 * Apply one patch, and return the patch that undoes it.
 *
 * The inverse is built from the values actually displaced, so it costs what the
 * edit costs — never what the document costs.
 */
export function applyPatch(doc: DashDoc, p: Patch): { inverse: Patch; touched: Touched } {
  switch (p.op) {
    case 'setCells': {
      const sheet = table(doc, p.sheet)
      const data = sheet.data[p.col]
      if (!data) throw new Error(`no column data ${p.col}`)
      const dictLen = data.enc === 'dict' ? data.dict.length : undefined
      const was: unknown[] = []
      p.rids.forEach((rid, i) => {
        const row = ridIndex(sheet, rid)
        if (row < 0) { was.push(null); return }
        was.push(readCell(data, row))
        writeCell(data, row, p.v[i])
      })
      if (p.dictLen !== undefined && data.enc === 'dict' && data.dict.length > p.dictLen) {
        data.dict.length = p.dictLen
      }
      return {
        inverse: { op: 'setCells', sheet: p.sheet, col: p.col, rids: p.rids, v: was, dictLen },
        touched: { sheet: p.sheet, cols: [p.col], rids: p.rids },
      }
    }

    case 'applySteps': {
      const sheet = table(doc, p.sheet)
      // The leading PROVENANCE ops are the attested head and are never re-run
      // (model.ts). `applySteps` owns the RE-EXECUTABLE tail and nothing above
      // it, so the inverse is bounded by the STEPS rather than by the data they
      // produce — a whole-sheet inverse would put document-sized snapshots into
      // a byte-capped history.
      let cut = sheet.steps.findIndex(
        (s) => !PROVENANCE_OPS.has((s as { op?: string }).op ?? ''),
      )
      if (cut < 0) cut = sheet.steps.length
      const was = sheet.steps.slice(cut)
      sheet.steps = [...sheet.steps.slice(0, cut), ...p.steps]
      return {
        inverse: { op: 'applySteps', sheet: p.sheet, steps: was },
        touched: { sheet: p.sheet, structural: true },
      }
    }
    case 'setCanvasCells': {
      const sheet = canvas(doc, p.sheet)
      // No `dropEmpty` twin of `setOverrides`: `cells` is REQUIRED on a
      // CanvasSheet and `parseDoc` always materialises it, so there is no
      // container to leave behind and no divergence to create.
      const was: Record<string, CanvasCell | null> = {}
      for (const [k, v] of Object.entries(p.cells)) {
        // the PREVIOUS value, or null for "there was nothing here" — so the
        // inverse of creating a cell REMOVES it rather than blanking it
        was[k] = sheet.cells[k] ?? null
        if (v === undefined || v === null) delete sheet.cells[k]
        else sheet.cells[k] = v
      }
      return {
        inverse: { op: 'setCanvasCells', sheet: p.sheet, cells: was },
        touched: { sheet: p.sheet },
      }
    }

    case 'setCanvasSizes': {
      const sheet = canvas(doc, p.sheet)
      const axis = (
        which: 'cols' | 'rows', want: Record<string, number | null> | undefined,
      ): Record<string, number | null> | undefined => {
        if (!want) return undefined
        const bag = (sheet[which] ??= {})
        const was: Record<string, number | null> = {}
        for (const [k, v] of Object.entries(want)) {
          was[k] = bag[k] ?? null
          if (v === undefined || v === null) delete bag[k]
          else bag[k] = v
        }
        // THE CONTAINER GOES WITH ITS LAST KEY, in both directions. `cols` and
        // `rows` are OPTIONAL on the kind, so absent and `{}` say the same
        // thing — and if only the forward patch dropped it, undoing the FIRST
        // width ever set would leave `"cols": {}` behind, which is a file that
        // differs from the one the edit started with and a diff every other
        // reader has to explain.
        if (!Object.keys(bag).length) delete sheet[which]
        return was
      }
      const cols = axis('cols', p.cols)
      const rows = axis('rows', p.rows)
      return {
        inverse: {
          op: 'setCanvasSizes', sheet: p.sheet,
          ...(cols ? { cols } : {}), ...(rows ? { rows } : {}),
        },
        touched: { sheet: p.sheet },
      }
    }
    case 'setOverrides': {
      const sheet = table(doc, p.sheet)
      const existed = sheet.cells !== undefined
      sheet.cells ??= {}
      const was: Array<CellOverride | undefined> = []
      p.keys.forEach((k, i) => {
        was.push(sheet.cells![k])
        const v = p.v[i]
        // `null` deletes as well as `undefined`, and it is the spelling that
        // SURVIVES: this is an array, and `JSON.stringify([undefined])` is
        // `[null]`, so a delete sent over collab arrives as a null. Checking
        // only for undefined would write that null in as an override — junk in
        // the file, `dropEmpty` never firing, and the two replicas disagreeing
        // about whether the cell has one.
        if (v === undefined || v === null) delete sheet.cells![k]
        else sheet.cells![k] = v
      })
      if (p.dropEmpty && Object.keys(sheet.cells).length === 0) delete sheet.cells
      return {
        inverse: {
          op: 'setOverrides', sheet: p.sheet, keys: p.keys, v: was,
          // `dropEmpty` 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,
          cols: [...new Set(p.keys.map((k) => k.slice(0, k.indexOf(':'))))],
          rids: p.keys.map((k) => Number(k.slice(k.indexOf(':') + 1))),
        },
      }
    }

    case 'insertRows': {
      const sheet = table(doc, p.sheet)
      const flat = expandRids(sheet)
      // 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)
        for (const [col, d] of Object.entries(sheet.data)) {
          const v = p.values?.[col]?.[i] ?? null
          if (d.enc === 'raw') d.v.splice(at, 0, null)
          else if (d.enc === 'dict') d.idx.splice(at, 0, null)
          // through writeCell, so a dict column re-interns rather than growing
          // a second encoding beside itself
          if (v !== null) writeCell(d, at, v)
        }
      }
      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 },
      }
    }

    case 'deleteRows': {
      const sheet = table(doc, p.sheet)
      // ON DELETE TOO — this is the half that matters. Raising the mark only on
      // insert leaves nothing remembering that a DELETED rid ever existed, so
      // the floor (derived from the current maximum) drops back and the next
      // insert mints it again. Measured before this line: rid 3 deleted, then
      // minted for a different row.
      raiseWatermark(sheet, p.rids)
      // capture position AND value before anything moves — the inverse has to
      // put each row back exactly where it was, because order is data
      const taken = p.rids
        .map((rid) => ({ rid, at: ridIndex(sheet, rid) }))
        .filter((r) => r.at >= 0)
        .sort((a, b) => a.at - b.at)
      const restore: Record<string, unknown[]> = {}
      for (const [col, d] of Object.entries(sheet.data)) {
        restore[col] = taken.map((r) => readCell(d, r.at))
      }
      // descending, so each splice leaves the remaining indices valid
      const flat = expandRids(sheet)
      for (let i = taken.length - 1; i >= 0; i--) {
        flat.splice(taken[i].at, 1)
        for (const d of Object.values(sheet.data)) {
          if (d.enc === 'raw') d.v.splice(taken[i].at, 1)
          else if (d.enc === 'dict') d.idx.splice(taken[i].at, 1)
        }
      }
      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 },
      }
    }

    case 'addColumn': {
      const sheet = table(doc, p.sheet)
      const at = p.at ?? sheet.columns.length
      sheet.columns.splice(at, 0, p.column)
      if (p.data) sheet.data[p.column.id] = p.data
      return {
        inverse: { op: 'removeColumn', sheet: p.sheet, col: p.column.id },
        touched: { sheet: p.sheet, cols: [p.column.id], structural: true },
      }
    }

    case 'removeColumn': {
      const sheet = table(doc, p.sheet)
      const at = sheet.columns.findIndex((c) => c.id === p.col)
      if (at < 0) throw new Error(`no column ${p.col}`)
      const [column] = sheet.columns.splice(at, 1)
      const data = sheet.data[p.col]
      delete sheet.data[p.col]
      // the inverse carries the column AND its data, or undoing a delete
      // returns an empty column — the same failure deleteRows had
      return {
        inverse: { op: 'addColumn', sheet: p.sheet, column, at, ...(data ? { data } : {}) },
        touched: { sheet: p.sheet, cols: [p.col], structural: true },
      }
    }

    case 'setColumn': {
      const sheet = table(doc, p.sheet)
      const col = sheet.columns.find((c) => c.id === p.col)
      if (!col) throw new Error(`no column ${p.col}`)
      const was: Record<string, unknown> = {}
      for (const k of Object.keys(p.patch)) was[k] = (col as Record<string, unknown>)[k]

      // A TYPE CHANGE MUST CONVERT THE STORAGE, or the column's declared type
      // and its bytes disagree and every reader downstream believes the
      // declaration.
      //
      // This shipped, and it produced a WRONG NUMBER at the end of a path dash
      // itself recommends. Import lands a mixed column as `text` and advises
      // "set the column type once you have decided what it is". Doing that used
      // to rewrite only `col.type`: the grid began right-aligning and
      // number-formatting the values, and `aggregate` (grid.ts) — which skips
      // anything not already `typeof v === 'number'` — totalled them as
      // **zero**. Measured on a real import: footer `SUM 0` against a true
      // total of 10,308.85, which dash returns correctly from `=SUM(D2:D10)`
      // on a spreadsheet copy of the same rows. A confident wrong total is
      // worse than a refusal and much worse than an error.
      //
      // The conversion reuses IMPORT's own coercion (`inferColumn`/`coerce`/
      // `encodeColumn`) rather than a second implementation, so "what counts as
      // a number" has one answer here, on import, and on paste.
      //
      // WHAT WILL NOT CONVERT IS REFUSED, NOT ZEROED. `coerce` answers null for
      // a value it cannot read, and writing those nulls would silently delete
      // data on a dropdown change. So the patch throws with a count and an
      // example, the commit is abandoned, and the column keeps both its old
      // type and its old bytes. That matches the house rule import already
      // follows: refuse where you cannot decide.
      let dataWas: ColumnData | undefined

      // AN INVERSE CARRYING BYTES RESTORES THEM. Undo of a type change has to
      // put back the storage as well as the declaration; restoring only the
      // declaration leaves exactly the disagreement this case exists to
      // prevent, pointing the other way.
      if (p.data !== undefined) {
        dataWas = sheet.data[p.col]
        sheet.data[p.col] = p.data
        Object.assign(col, p.patch)
        return {
          inverse: { op: 'setColumn', sheet: p.sheet, col: p.col, patch: was, data: dataWas },
          touched: { sheet: p.sheet, cols: [p.col], structural: true },
        }
      }

      const nextType = p.patch.type as ColumnType | undefined
      if (nextType !== undefined && nextType !== col.type) {
        const n = totalRows(sheet)
        const src = sheet.data[p.col]
        const rawText: string[] = []
        for (let i = 0; i < n; i++) {
          const v = readCell(src, i)
          rawText.push(v == null ? '' : String(v))
        }
        const inf = { ...inferColumn(rawText), type: nextType }
        const out: unknown[] = []
        let lost = 0
        let firstLost = ''
        for (let i = 0; i < n; i++) {
          const t = rawText[i]
          if (t.trim() === '') { out.push(null); continue }
          const c = coerce(t, inf)
          if (c === null) { lost++; if (!firstLost) firstLost = t }
          out.push(c)
        }
        if (lost) {
          throw new Error(
            `${lost} value${lost === 1 ? '' : 's'} in “${col.name}” cannot be read as ${nextType}` +
            `${firstLost ? ` (for example “${firstLost}”)` : ''}. The column was left as it was.`,
          )
        }
        dataWas = src
        sheet.data[p.col] = encodeColumn(out, nextType)
      }

      Object.assign(col, p.patch)
      return {
        inverse: {
          op: 'setColumn', sheet: p.sheet, col: p.col, patch: was,
          ...(dataWas !== undefined ? { data: dataWas } : {}),
        },
        touched: { sheet: p.sheet, cols: [p.col], ...(dataWas !== undefined ? { structural: true } : {}) },
      }
    }

    case 'reorderColumns': {
      const sheet = table(doc, p.sheet)
      const was = sheet.columns.map((c) => c.id)
      const by = new Map(sheet.columns.map((c) => [c.id, c]))
      sheet.columns = p.order.map((id) => by.get(id)!).filter(Boolean)
      return {
        inverse: { op: 'reorderColumns', sheet: p.sheet, order: was },
        touched: { sheet: p.sheet, structural: true },
      }
    }

    case 'setMeasure': {
      const existed = doc.measures !== undefined
      doc.measures ??= {}
      const was = doc.measures[p.name]
      if (p.measure === undefined) delete doc.measures[p.name]
      else doc.measures[p.name] = p.measure
      if (p.dropEmpty && Object.keys(doc.measures).length === 0) delete doc.measures
      return {
        inverse: { op: 'setMeasure', name: p.name, measure: was, dropEmpty: !existed },
        touched: {},
      }
    }

    case 'setComment': {
      // ANY sheet kind, not just a table: a remark on a pivot is a remark.
      const sheet = doc.sheets.find((sh) => sh.id === p.sheet) as
        (Sheet & { comments?: Comment[] }) | undefined
      if (!sheet) throw new Error(`no sheet "${p.sheet}"`)
      const existed = sheet.comments !== undefined
      sheet.comments ??= []
      const at = sheet.comments.findIndex((c) => c.id === p.id)
      const was = at < 0 ? undefined : sheet.comments[at]
      if (p.comment === undefined) { if (at >= 0) sheet.comments.splice(at, 1) }
      else if (at >= 0) sheet.comments[at] = p.comment
      else if (typeof p.at === 'number' && p.at >= 0 && p.at <= sheet.comments.length) {
        sheet.comments.splice(p.at, 0, p.comment)
      } else sheet.comments.push(p.comment)
      // add-then-remove must not leave `comments: []` behind — a round trip
      // that changes the file is a diff every other reader has to explain
      if (!existed && sheet.comments.length === 0) delete sheet.comments
      return {
        inverse: { op: 'setComment', sheet: p.sheet, id: p.id, comment: was, at: at < 0 ? undefined : at },
        touched: { sheet: p.sheet },
      }
    }

    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 'reorderSheets': {
      const was = doc.sheets.map((s) => s.id)
      const by = new Map(doc.sheets.map((s) => [s.id, s]))
      // A PERMUTATION, checked all three ways — same length, every id known,
      // no id twice. Anything else and the map below would silently drop or
      // duplicate a sheet, which is a delete (or a second tab sharing one
      // sheet's arrays) arriving inside an operation that only claims to
      // change an order.
      if (
        p.order.length !== was.length ||
        new Set(p.order).size !== p.order.length ||
        p.order.some((id) => !by.has(id))
      ) {
        throw new Error('reorderSheets must name every sheet in the workbook exactly once')
      }
      doc.sheets = p.order.map((id) => by.get(id)!)
      // `all`, as `setSheet` is: the tab strip, the grid and every panel read
      // the sheet list. The INVERSE is what this op exists for — a list of ids,
      // not a sheet.
      return { inverse: { op: 'reorderSheets', order: was }, 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.
      //
      // `anySheet`, NOT `table`. This narrowed to a dataset and threw on
      // everything else, which made the SHEET NAME — the one property every
      // kind has — writable on datasets alone: renaming a spreadsheet tab built
      // a valid patch and died here with `no table sheet`, and the tab strip
      // shipped a disabled Rename for the kinds it could not reach. The op's
      // own writer never looked at a column or a rid; the narrowing was the
      // whole of the restriction. (`applySheetProps` still refuses every
      // structural key, so widening the kind does not widen what can be
      // written.)
      return applySheetProps(anySheet(doc, p.sheet), p)

    case 'setTitle': {
      const was = doc.title
      doc.title = p.title
      return { inverse: { op: 'setTitle', title: was }, touched: {} }
    }

    default:
      // applySteps / refreshBinding, and anything a future build sends us.
      // Refusing loudly is the point: a silent no-op is an edit the user
      // believes landed.
      throw new Error(`patch op "${(p as { op: string }).op}" is not implemented yet`)
  }
}

const patchBytes = (p: Patch): number => JSON.stringify(p).length

// --- Store -----------------------------------------------------------------

export class Store {
  doc: DashDoc
  readOnly = false
  /** view state: never in the document, never synced, never undoable by default */
  order: Record<string, number[] | undefined> = {}
  private undoStack: Entry[] = []
  private redoStack: Entry[] = []
  private listeners = new Map<StoreEvent, Set<Listener>>()
  private runCell: string | null = null
  private runTimer: ReturnType<typeof setTimeout> | undefined
  private pending: { inverse: Patch[]; touched: Touched; bytes: number } | null = null
  /**
   * Set while a document change is being applied and broadcast.
   *
   * The grid re-derives its order vector from inside the `doc` listener
   * (grid.ts: a structural edit renumbers the rows the vector holds), so a
   * `view()` call arriving here is DERIVED — the consequence of an edit, not
   * something the reader did. `viewBarrier` exists to tell those two apart and
   * this counter is the only honest way to do it.
   */
  private inDocChange = 0
  /**
   * THE READER'S LAST ACTION WAS A VIEW ACTION — see `view()` and `undo()`.
   *
   * Null means the last thing they did was a document edit (or nothing).
   */
  private viewBarrier = false
  /**
   * How the store speaks to the reader, when refusing.
   *
   * A FIELD RATHER THAN AN IMPORT, and the same shape `setColumnType` takes its
   * `report` in: this module runs in the node rigs and must not reach the DOM.
   * Default swallows, so a build that never lends it a voice is quieter than it
   * should be but never wrong. panels.ts lends it `toast` today.
   */
  say: (message: string) => void = () => {}

  constructor(doc: DashDoc) {
    this.doc = doc
  }

  on(ev: StoreEvent, fn: Listener): () => void {
    const set = this.listeners.get(ev) ?? new Set()
    this.listeners.set(ev, set)
    set.add(fn)
    return () => set.delete(fn)
  }

  /**
   * Advances on EVERY document change — committed, mid-run, remote, and the
   * few writes that go straight onto the doc and call `touch()` (document
   * properties, sharing credentials). The save queue compares it at
   * acknowledgement time: a write may clear the unsaved dot only if this has
   * not moved since its snapshot. View changes do not count.
   */
  revision = 0

  private emit(ev: StoreEvent): void {
    if (ev === 'doc') this.revision++
    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
    // NOT a barrier reset: somebody else's edit is not the reader's last
    // action, exactly as it is not an entry in their undo history.
    this.inDocChange++
    try {
      this.emit('doc')
      this.emit('view')
    } finally { this.inDocChange-- }
  }

  /** The last invalidation, for a listener that wants to repaint precisely. */
  lastTouched: Touched = {}

  /**
   * One undoable step: apply patches, record their inverses as ONE entry.
   * Closes any open typing run first, so a run's text and a structural edit
   * never merge into one entry.
   */
  /**
   * Listeners that see every patch BEFORE it is applied, and may replace the
   * list — collaboration's entry point.
   *
   * WHY A HOOK RATHER THAN WRAPPING THE VERBS. The sync session used to
   * decorate `commit` and `runEdit` on the instance, which covers every edit
   * the UI makes and cannot see UNDO and REDO — those apply their inverses
   * through a private path. Undo therefore fell back to broadcasting a whole
   * state snapshot: correct, and enormously heavier than the two ops it
   * stands in for. `invert` calls this too, so an undo now ships as ops.
   *
   * The listener runs BEFORE the document changes because the CRDT reads what
   * a delete is about to displace; `afterPatch` is the other half.
   */
  beforePatch(fn: (patches: Patch[]) => Patch[] | void): () => void {
    this.patchHooks.push(fn)
    return () => { this.patchHooks = this.patchHooks.filter((f) => f !== fn) }
  }

  /** Listeners that run once the document HAS changed. */
  afterPatch(fn: () => void): () => void {
    this.appliedHooks.push(fn)
    return () => { this.appliedHooks = this.appliedHooks.filter((f) => f !== fn) }
  }

  private patchHooks: Array<(p: Patch[]) => Patch[] | void> = []
  private appliedHooks: Array<() => void> = []

  /**
   * Run the before-hooks. `substitute` is false for undo/redo: a hook may
   * REFUSE a patch it cannot express, and dropping one there would apply half
   * an inverse and leave the undo stack describing a document that no longer
   * exists. An undo must land whole or not at all.
   */
  private runBefore(list: Patch[], substitute = true): Patch[] {
    let out = list
    for (const fn of this.patchHooks) {
      const next = fn(out)
      if (substitute && Array.isArray(next)) out = next
    }
    return out
  }

  private runAfter(): void {
    for (const fn of this.appliedHooks) fn()
  }

  commit(patches: Patch | Patch[]): void {
    if (this.readOnly) return
    this.endRun()
    const list = this.runBefore(Array.isArray(patches) ? patches : [patches])
    if (!list.length) return
    const inverse: Patch[] = []
    const touched: Touched = {}
    let bytes = 0
    for (const p of list) {
      const r = applyPatch(this.doc, p)
      inverse.unshift(r.inverse) // undo in reverse application order
      bytes += patchBytes(r.inverse)
      merge(touched, r.touched)
    }
    this.push({ inverse, touched, bytes })
    this.touch()
    this.lastTouched = touched
    // The reader's last action is a document edit again, so undo has something
    // of theirs to reverse and no reason to hesitate.
    this.viewBarrier = false
    this.inDocChange++
    try {
      this.emit('doc')
      this.runAfter()
    } finally { this.inDocChange-- }
  }

  /**
   * An edit inside a typing run. The FIRST edit in a cell opens the entry;
   * 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 | Patch[]): void {
    if (this.readOnly) return
    if (this.runCell !== cellKey) {
      this.endRun()
      this.runCell = cellKey
      this.pending = { inverse: [], touched: {}, bytes: 0 }
    }
    // 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.viewBarrier = false
    this.inDocChange++
    try {
      this.emit('doc')
      this.runAfter()
    } finally { this.inDocChange-- }
    clearTimeout(this.runTimer)
    this.runTimer = setTimeout(() => this.endRun(), RUN_IDLE_MS)
  }

  /** Close the current run, if any. Idempotent. */
  endRun(): void {
    clearTimeout(this.runTimer)
    if (!this.runCell) return
    this.runCell = null
    if (this.pending && this.pending.inverse.length) this.push(this.pending)
    this.pending = null
  }

  /**
   * VIEW STATE — the third write verb, and the one nothing in spaces suggests.
   *
   * The grid reads through an order vector: sorting sorts the index, filtering
   * builds a mask. NEITHER touches the document, so neither takes a checkpoint,
   * sets the dirty flag, or produces an op. Writing the first sort as a
   * `commit` is the easy mistake, and nobody notices until a file saves itself
   * every time someone clicks a column header.
   *
   * A SORT IS STILL NOT UNDOABLE, AND UNDO NO LONGER PRETENDS OTHERWISE.
   *
   * The open question this comment used to hold was whether ⌘Z should reverse a
   * sort. Measured while it was open: sort a column, press ⌘Z, and the sort
   * stayed while the NUMBER FORMAT set two actions earlier came off. The reader
   * keeps the thing they asked to reverse and loses a thing they were not
   * thinking about, with nothing said either way. "Sort is not undoable" is
   * defensible; silently undoing something else is not.
   *
   * A real view history still belongs to the grid, not here — `docs/DECISIONS.md`
   * ("one view vector") puts the filters and sorts in grid.ts and the store owns
   * only the vector they produce, so a stack kept here would restore the row
   * order while the header arrow, the status line and the filter menu went on
   * describing the sort that had just been undone, and the next `applyView()`
   * would put it back. Half an undo that lies is worse than none.
   *
   * So the store does the one thing it CAN see and CAN promise: it notices that
   * the reader's last action changed the rows on screen without changing the
   * document, and makes the next undo REFUSE and say so, instead of reaching
   * past the sort for an edit nobody asked about. One press to be told; a
   * second press to undo the edit anyway.
   *
   * THE TEST FOR "THE READER DID THIS" is that the order map changed and no
   * document change was in flight. That is deliberately about the VECTOR rather
   * than about sorts and filters by name: the store cannot see grid.ts's
   * `filters`/`sorts` (nor should it), and filter.ts is free to widen what a
   * filter is without this having to hear about it. It errs towards arming —
   * switching to a sheet that still holds a stale vector clears it here, and
   * that arms the barrier too. Costing one keypress after a tab switch is the
   * right side to be wrong on, and undoing an edit on the sheet you just left
   * is the same surprise anyway.
   */
  view(mutate: () => void): void {
    if (this.inDocChange) { mutate(); this.emit('view'); return }
    const before = { ...this.order }
    mutate()
    if (orderChanged(before, this.order)) this.viewBarrier = true
    this.emit('view')
  }

  /**
   * The document changed OUTSIDE the patch vocabulary, and the file is now
   * behind it. Not undoable, not a repaint — just "this needs saving".
   *
   * Exists for sharing. Starting, stopping and rotating write `doc.collab`
   * directly (they are not edits to the workbook's data and must not sit in
   * its undo history), and nothing told the unsaved dot. So a key ROTATION —
   * which is revocation — could be closed without a warning and without the
   * automatic save, and the file kept the keys that were meant to be dead.
   */
  markUnsaved(): void {
    this.touch()
    this.emit('unsaved')
  }

  /** Model changed without a new undo entry (mid-run). */
  touch(): void {
    this.revision++
    this.doc.modified = new Date().toISOString()
  }

  private push(e: Entry): void {
    this.undoStack.push(e)
    this.redoStack.length = 0
    // Walk backwards dropping the OLDEST entries once the budget is exceeded —
    // spaces' splice, unchanged (store.ts:144-152).
    let bytes = 0
    for (let i = this.undoStack.length - 1; i >= 0; i--) {
      bytes += this.undoStack[i].bytes
      if (bytes > UNDO_BYTES) { this.undoStack.splice(0, i + 1); break }
    }
  }

  private invert(e: Entry): Entry {
    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)
      bytes += patchBytes(r.inverse)
      merge(touched, r.touched)
    }
    this.touch()
    this.lastTouched = touched
    this.inDocChange++
    try {
      this.emit('doc')
      this.runAfter()
    } finally { this.inDocChange-- }
    return { inverse, touched, bytes }
  }

  /**
   * The refusal, once. Returns true when this press was spent saying no.
   *
   * ONLY WHEN THERE IS SOMETHING TO REVERSE: with an empty stack the next press
   * would do nothing either, so "press it again" would be a lie and the barrier
   * is simply dropped. Redo is guarded on the same footing — after a sort,
   * ⇧⌘Z reaching past it for a document edit is the same surprise pointing the
   * other way.
   */
  private blocked(has: boolean): boolean {
    if (!this.viewBarrier) return false
    this.viewBarrier = false
    if (!has) return false
    // ONE LITERAL, not a concatenation: the i18n rig sweeps t() calls out of the
    // source and cannot see through a `+`, and an unswept string is one that
    // silently never gets translated.
    this.say(t('Sorting and filtering are not changes to the data, so undo cannot take them back — clear them from the column’s ▾ menu. Nothing was undone; press undo again to undo the last change to the data.'))
    this.emit('view')
    return true
  }

  undo(): boolean {
    if (this.readOnly) return false
    this.endRun()
    if (this.blocked(this.undoStack.length > 0)) return false
    const e = this.undoStack.pop()
    if (!e) return false
    this.redoStack.push(this.invert(e))
    return true
  }

  redo(): boolean {
    if (this.readOnly) return false
    this.endRun()
    if (this.blocked(this.redoStack.length > 0)) return false
    const e = this.redoStack.pop()
    if (!e) return false
    this.undoStack.push(this.invert(e))
    return true
  }

  get canUndo(): boolean { return this.undoStack.length > 0 }
  get canRedo(): boolean { return this.redoStack.length > 0 }
  /** live bytes held by history — the number the cap is enforced against */
  get historyBytes(): number { return this.undoStack.reduce((n, e) => n + e.bytes, 0) }

  /** Wholesale replacement (agent load, version restore). The one `all` case. */
  replaceDoc(next: DashDoc): void {
    this.endRun()
    this.doc = next
    this.undoStack.length = 0
    this.redoStack.length = 0
    this.order = {}
    this.viewBarrier = false
    this.lastTouched = { all: true }
    this.emit('doc')
    this.emit('view')
  }
}

/**
 * Did the rows on screen change?
 *
 * BY CONTENT, not by reference: `applyView` builds a fresh array every time it
 * runs, so reference equality would call re-applying an identical filter a
 * change. The walk costs a pass over a vector that was just built by a pass
 * over the same rows, and it only runs on a view change the reader made.
 */
function orderChanged(
  a: Record<string, number[] | undefined>, b: Record<string, number[] | undefined>,
): boolean {
  const keys = new Set([...Object.keys(a), ...Object.keys(b)])
  for (const k of keys) {
    const x = a[k]
    const y = b[k]
    if (x === y) continue
    if (!x || !y) return true          // one of them says "no filter, no sort"
    if (x.length !== y.length) return true
    for (let i = 0; i < x.length; i++) if (x[i] !== y[i]) return true
  }
  return false
}

function merge(into: Touched, from: Touched): void {
  if (from.all) { into.all = true; return }
  if (from.sheet) into.sheet = from.sheet
  if (from.structural) into.structural = true
  if (from.cols) into.cols = [...new Set([...(into.cols ?? []), ...from.cols])]
  if (from.rids) into.rids = [...new Set([...(into.rids ?? []), ...from.rids])]
}

export const _internals = { RUN_IDLE_MS, UNDO_BYTES, totalRows, ridIndex }