Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

45.1 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// Comments — the half of a workbook that is an argument rather than data.
//
// A spreadsheet a team uses is a spreadsheet a team disagrees about. "Is this
// the right basis?", "this row is double-counted", "agreed with finance, leave
// it" — none of that is a number, none of it belongs in a cell, and all of it
// has to travel in the file, because the file is the product (PLATFORM §1).
//
// WHERE THEY LIVE. `Sheet.comments`, an ADDITIVE array (PLATFORM §3): a build
// that has never heard of comments round-trips them untouched, which is the
// only reason this can ship before every surface understands it.
//
// They are emphatically NOT in `sheet.cells`. That map is read by the formula
// engine, the cell-formula evaluator, the chart bindings, the totals row and
// the static preview — every one of them through `'v' in over`. A comment
// stored there would be a remark that can change a number, and the whole point
// of a comment is that it cannot. `CellOverride.note` already exists and is
// deliberately NOT reused: it is one string per cell with no author, no time,
// no thread and no resolve, and `deleteRowsAt`/`deleteColumn` take it with the
// row or column it sat on. That is the correct policy for a correction and
// exactly the wrong one for somebody's unanswered objection.
//
// WHAT A COMMENT ANCHORS TO, and why these three:
//
//   cell    `{col, rid}` — never a row POSITION and never an A1 reference.
//           Sorting and filtering are VIEW state (store.ts `view()`), so a
//           positional anchor would point at a different number the moment
//           somebody clicked a column header, with the re-sorted grid hiding
//           the evidence — the same failure `Grid.canonicalRow` exists to
//           prevent, where £22,750 was selected and £12,400 destroyed. A rid is
//           row identity and a colId is column identity; that is what they are
//           for. The marker therefore survives a sort, a filter, an insert
//           above, a delete elsewhere, a column move and a column RENAME with
//           nothing rewritten and no migration step.
//   column  `{col}` — "this column is the wrong basis" is a remark about the
//           column, not about any one of its cells.
//   sheet   `{}` — the catch-all, and where a thread about the whole sheet
//           goes. It is also what the interface offers when a cell cannot be
//           named, which is what keeps the entry point single.
//
// NO RANGE ANCHOR, and that is a refusal rather than an omission. A range has
// two honest spellings here and both drift:
//
//   * CORNERS (`{col,rid}` × 2). After a sort the two corners name rows that
//     are no longer adjacent, so "rows 4-9" silently becomes an arbitrary set
//     of rows — and it changes again on the next sort. A highlight that means
//     something different to each reader is worse than no highlight.
//   * A MEMBERSHIP LIST (every rid). Survives sorting honestly, and then fails
//     on structure: a row inserted in the middle of the span is not in the
//     list, so the range quietly stops covering what it visibly covers. The
//     comment narrows and nobody is told.
//
// So a remark about several cells is a column comment, a sheet comment, or
// several cell comments — each of which means exactly one thing forever. When
// dash grows a stable range identity (a named range is the obvious candidate,
// because it is a document object with an id) a fourth anchor kind can be
// added additively; `CommentAnchor` is an OPEN union so a file written by that
// build already parses here.
//
// WHEN THE ROW OR THE COLUMN GOES AWAY. Nothing is rewritten and nothing is
// deleted. An anchor is RESOLVED at read time, never migrated, so a comment
// whose rid or colId no longer exists becomes an ORPHAN: kept in the file,
// listed with a badge naming what it used to point at, and never drawn on any
// cell. This is the policy `CellOverride.againstHash` already states for a
// suspended override — "kept, not applied, flagged" — and it is chosen over
// the two alternatives for reasons that are not aesthetic:
//
//   * DELETING with the row would destroy a human utterance as a side effect
//     of a structural edit. `deleteRowsAt` may take a correction with it; it
//     may not take somebody's unanswered question.
//   * RE-TARGETING to the sheet on delete would need a patch minted in the
//     SAME commit as the delete, and its inverse would have to re-target back.
//     Rows are also deleted by paths this module cannot decorate —
//     `window.bento.commit`, a remote op, an older build — so the retarget
//     would sometimes not run, and the file would carry two conventions. Doing
//     nothing is the only rule every writer already obeys.
//
// The reward is that UNDO IS FREE: undoing the delete brings the row back and
// the comment re-attaches byte-identically, because it never moved.
//
// THE ONE RESIDUAL HAZARD, stated plainly. Rids are never reused (the
// `nextRid` watermark, store.ts), so a cell comment cannot land on a different
// row — EXCEPT that `nextRidFloor` (rowcol.ts) derives its floor from live
// rows, `cells` keys and the watermark, and does not read comments. A file
// whose rows were deleted by a build that had no watermark can therefore mint
// a rid a comment still names. Column ids are worse and by design: import
// slugs them from the header (import.ts), so re-importing the same CSV
// re-creates a deleted column's id and an orphaned comment ATTACHES AGAIN.
// That is tolerable here and is not tolerable for an override, and the
// asymmetry is the whole argument: an override silently rewrites a number,
// while a comment is a sentence a person reads and evaluates. A remark
// reappearing on a re-imported column of the same name is usually right and is
// always visible. `was` (below) records what the anchor named at the time so
// the reader can check rather than guess.
//
// NEVER IN THE PREVIEW, NEVER IN A STORY. preview.ts draws columns and cell
// VALUES and cannot reach this field; story.ts renders bindings. Nothing in
// this module is imported by either, and the rig proves the preview markup of
// a commented workbook contains none of its text. Comments are for the people
// editing — a thumbnail is seen by everyone with the folder open.

import './comments.css'
import { t } from './i18n.ts'
import { lsGet, lsSet } from '../../kernel/src/storage.ts'
import { colToLetters } from './a1.ts'
import { formatValue } from './format.ts'
import { hiddenSet } from './rowcol.ts'
import { readCell, type Patch, type Store } from './store.ts'
import type { Column, DashDoc, Sheet, TableSheet, Comment, CommentAnchor, CommentReply } from './model.ts'
import type { Grid } from './grid.ts'

// --- the model ---------------------------------------------------------------
//
// Declared here so it can be reviewed in one place; it belongs in model.ts
// beside `CellOverride`, which is where the report asks for it to be moved.


/** `was.value` is a caption, not a payload. Long text is a paste, not a number. */
const WAS_CHARS = 48

// --- reading -----------------------------------------------------------------

const isObj = (v: unknown): v is Record<string, unknown> =>
  typeof v === 'object' && v !== null && !Array.isArray(v)

/**
 * The comments on a sheet, read DEFENSIVELY.
 *
 * This is an additive field, so an older build, a hand edit, an agent or a
 * newer build can put anything here and every surface still has to draw.
 * Anything unreadable is skipped rather than repaired: repairing would write to
 * the document on OPEN, and a file that changes because somebody looked at it
 * is a file whose dirty flag lies.
 */
export function sheetComments(sheet: Sheet | null | undefined): Comment[] {
  const raw = (sheet as { comments?: unknown } | null | undefined)?.comments
  if (!Array.isArray(raw)) return []
  return raw.filter((c): c is Comment =>
    isObj(c) && typeof c.id === 'string' && typeof c.text === 'string' && isObj(c.anchor)
      && typeof (c.anchor as { kind?: unknown }).kind === 'string')
}

export const unresolvedCount = (sheet: Sheet | null | undefined): number =>
  sheetComments(sheet).reduce((n, c) => n + (c.resolved ? 0 : 1), 0)

/** Canonical row index → rid. Walks the run-length runs; -1 past the end. */
export function ridOfRow(sheet: TableSheet, row: number): number {
  let i = 0
  for (const [start, count] of sheet.rids) {
    if (row < i + count) return start + (row - i)
    i += count
  }
  return -1
}

/** rid → canonical row index, or -1 when the row is gone. */
export function rowOfRid(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
}

export interface ResolvedAnchor {
  /** `orphan` = the row or column it names is gone; `unknown` = a newer build's kind */
  state: 'live' | 'orphan' | 'unknown'
  kind: string
  col?: Column
  rid?: number
  /** CANONICAL data row, 0-based — never a visible one */
  row?: number
  /** live, but the author has hidden the column it sits on */
  hidden?: boolean
  /** what went missing, for the badge */
  why?: 'row' | 'column'
}

/**
 * Where a comment points RIGHT NOW.
 *
 * Called on every paint and every list build, so it walks the rid runs rather
 * than expanding them. Nothing here writes: resolution is a read, which is the
 * entire orphan policy in one sentence.
 */
export function resolveAnchor(sheet: TableSheet, a: CommentAnchor): ResolvedAnchor {
  const kind = a.kind
  if (kind === 'sheet') return { state: 'live', kind }

  if (kind === 'column' || kind === 'cell') {
    const colId = (a as { col?: unknown }).col
    const col = typeof colId === 'string'
      ? sheet.columns.find((c) => c.id === colId)
      : undefined
    // The column goes first: when both halves are gone, the column is the
    // bigger loss and is the one the badge should name.
    if (!col) return { state: 'orphan', kind, why: 'column' }
    const hidden = hiddenSet(sheet).has(col.id)
    if (kind === 'column') return { state: 'live', kind, col, hidden }

    const rid = (a as { rid?: unknown }).rid
    if (typeof rid !== 'number' || !Number.isFinite(rid)) {
      return { state: 'orphan', kind, col, why: 'row' }
    }
    const row = rowOfRid(sheet, rid)
    return row < 0
      ? { state: 'orphan', kind, col, rid, why: 'row' }
      : { state: 'live', kind, col, rid, row, hidden }
  }

  return { state: 'unknown', kind }
}

/**
 * The A1-style handle for a live anchor.
 *
 * A1 counts `sheet.columns` — every column, hidden included — and the sheet's
 * OWN row order, exactly as cellformula.ts does. Two people looking at one file
 * through different sorts have to be able to say "C13" and mean the same cell.
 */
export function anchorRef(sheet: TableSheet, r: ResolvedAnchor): string {
  if (!r.col) return ''
  const ci = sheet.columns.findIndex((c) => c.id === r.col!.id)
  if (ci < 0) return ''
  const letter = colToLetters(ci)
  if (r.kind === 'column') return `${letter}:${letter}`
  return typeof r.row === 'number' ? `${letter}${r.row + 1}` : ''
}

/** The cell a comment names, as the grid would show it. Blank for anything else. */
export function anchorValue(
  sheet: TableSheet, r: ResolvedAnchor, computed?: Map<string, unknown[]>,
): string {
  if (r.state !== 'live' || r.kind !== 'cell' || !r.col || typeof r.row !== 'number') return ''
  const over = sheet.cells?.[`${r.col.id}:${r.rid}`]
  const comp = computed?.get(r.col.id)
  // The same precedence the grid paints with, minus the per-cell formula —
  // which needs the whole evaluator, and a caption is not worth recalculating a
  // sheet for. A commented formula cell shows its stored value or nothing,
  // never a number this module invented.
  const v = comp ? comp[r.row]
    : over && 'v' in over ? over.v
      : readCell(sheet.data[r.col.id], r.row)
  return v == null ? '' : formatValue(v, r.col)
}

/** One line naming what a thread is about, for the popover head and the list. */
export function anchorLabel(sheet: TableSheet, r: ResolvedAnchor, was?: Comment['was']): string {
  if (r.state === 'unknown') return t('an anchor this build does not know ({kind})').replace('{kind}', r.kind)
  if (r.state === 'orphan') {
    const name = was?.col ?? (r.col?.name ?? '')
    return r.why === 'column'
      ? name
        ? t('a deleted column ({name})').replace('{name}', name)
        : t('a deleted column')
      : name
        ? t('a deleted row of {name}').replace('{name}', name)
        : t('a deleted row')
  }
  if (r.kind === 'sheet') return sheet.name || t('this sheet')
  if (r.kind === 'column') return `${r.col?.name ?? ''} · ${anchorRef(sheet, r)}`
  return `${r.col?.name ?? ''} · ${t('row {n}').replace('{n}', String((r.row ?? 0) + 1))} · ${anchorRef(sheet, r)}`
}

// --- the flat list: window.bento.comments() ----------------------------------

/**
 * One comment, flattened for an agent.
 *
 * The point of this shape is that a model can act on it WITHOUT opening the
 * document: `sheet` + `ref` locate the cell in words a spreadsheet user uses,
 * `value` says what it currently reads, and `live` says whether the thing being
 * argued about still exists. Slides' `window.bento.comments()` is the same
 * idea; this one carries dash's identities as well as its coordinates, because
 * `ref` moves when a column is inserted and `anchor` does not.
 */
export interface FlatComment {
  id: string
  sheet: string
  sheetName: string
  anchor: CommentAnchor
  /** 'cell' | 'column' | 'sheet' | whatever a newer build wrote */
  kind: string
  /** false when the row or the column it names has been deleted */
  live: boolean
  /** "C13", "C:C", or '' for a sheet-level or orphaned thread */
  ref: string
  column?: string
  /** 1-based, in the sheet's own order — never the reader's sorted view */
  row?: number
  /** what the cell reads now, formatted as the grid shows it */
  value?: string
  /** what the anchor named when the comment was written */
  was?: Comment['was']
  author: string
  at: string
  text: string
  resolved: boolean
  replies: Array<{ author: string; at: string; text: string }>
}

/**
 * Every comment in the workbook, resolved. THE entry point for an agent
 * processing flagged issues — the same role slides gives its own.
 *
 * Sheets that are not table sheets are walked too: a pivot or a canvas sheet
 * can carry the field even though this build's writer cannot yet put one there
 * (see the report), and a reader that skipped them would make those threads
 * invisible rather than merely uneditable.
 */
export function flatComments(doc: DashDoc): FlatComment[] {
  const out: FlatComment[] = []
  for (const sheet of doc.sheets) {
    for (const c of sheetComments(sheet)) {
      const table = sheet.kind === 'table' ? sheet as TableSheet : null
      const r = table ? resolveAnchor(table, c.anchor) : null
      out.push({
        id: c.id,
        sheet: sheet.id,
        sheetName: sheet.name,
        anchor: c.anchor,
        kind: c.anchor.kind,
        live: r ? r.state === 'live' : true,
        ref: table && r ? anchorRef(table, r) : '',
        ...(r?.col ? { column: r.col.name } : {}),
        ...(typeof r?.row === 'number' ? { row: r.row + 1 } : {}),
        ...(table && r ? { value: anchorValue(table, r) } : {}),
        ...(c.was ? { was: c.was } : {}),
        author: c.author,
        at: c.at,
        text: c.text,
        resolved: c.resolved === true,
        replies: (c.replies ?? []).map((x) => ({ author: x.author, at: x.at, text: x.text })),
      })
    }
  }
  return out
}

// --- writing: patch factories ------------------------------------------------
//
// EVERY WRITE IS A PATCH AND NOTHING HERE MUTATES — rowcol.ts's rule, for
// rowcol.ts's reason: the same Patch objects are the undo entries, the CRDT ops
// and the agent API, so a comment written by assignment would be an edit with
// no inverse and no op.
//
// They all ride on `setSheetProps`, which writes the WHOLE array as one value.
// That has a real cost and it is stated rather than hidden: the inverse carries
// the previous array (so a workbook of 500 threads makes ~75KB undo entries,
// against a 24MB cap), and under collaboration the array is ONE last-writer-
// wins register — two people adding a thread at the same instant keep one. That
// is the same documented compromise slides' table `rows` makes. The fix is a
// per-comment op keyed by id, exactly as `setView` is keyed by view id; it is
// named in the report and is a drop-in replacement for `writeComments` below.

/**
 * THE FACTORIES BELOW REWRITE THE WHOLE ARRAY, so they must start from the RAW
 * one and not from `sheetComments`.
 *
 * `sheetComments` skips anything it cannot read — an entry from a newer build
 * with a shape this one does not recognise, or a hand edit. Mapping the READ
 * list back over the field would then delete every one of those as a side
 * effect of somebody clicking Reply: silent loss of another build's data, which
 * is precisely the additivity invariant (PLATFORM §3), failing in the one place
 * nobody would look for it. So entries are matched by id and passed through
 * untouched otherwise.
 */
const rawComments = (sheet: TableSheet): unknown[] => {
  const raw = (sheet as { comments?: unknown }).comments
  return Array.isArray(raw) ? raw : []
}

const idOf = (c: unknown): string | undefined =>
  isObj(c) && typeof c.id === 'string' ? c.id : undefined

/** Set the array, or DROP the key when it empties — an additive field that
 *  means "no comments" must be ABSENT, or adding and deleting one leaves the
 *  workbook changed and every reader diffs it. `freezeAt` states the same rule. */
function writeComments(sheet: TableSheet, next: unknown[]): Patch {
  return next.length
    ? { op: 'setSheetProps', sheet: sheet.id, props: { comments: next } }
    : { op: 'setSheetProps', sheet: sheet.id, props: {}, drop: ['comments'] }
}

/** A fresh id. Random, never derived: two replicas must not mint the same one. */
export function commentId(): string {
  const rnd = typeof crypto !== 'undefined' && crypto.randomUUID
    ? crypto.randomUUID().slice(0, 8)
    : Math.random().toString(36).slice(2, 10)
  return `cmt-${rnd}`
}

/** Mint a comment, capturing what its anchor named at the time. */
export function newComment(
  sheet: TableSheet, anchor: CommentAnchor, author: string, text: string,
  computed?: Map<string, unknown[]>,
): Comment {
  const r = resolveAnchor(sheet, anchor)
  const was: NonNullable<Comment['was']> = {}
  if (r.col) was.col = r.col.name
  if (typeof r.row === 'number') was.row = r.row + 1
  const v = anchorValue(sheet, r, computed)
  if (v) was.value = v.length > WAS_CHARS ? `${v.slice(0, WAS_CHARS - 1)}…` : v
  return {
    id: commentId(), anchor, author, text,
    at: new Date().toISOString(),
    ...(Object.keys(was).length ? { was } : {}),
  }
}

export function addCommentPatch(sheet: TableSheet, c: Comment): Patch {
  return writeComments(sheet, [...rawComments(sheet), c])
}

/** Nothing to reply to returns NOTHING — `commit([])` still pushes an undo
 *  entry, and a ⌘Z that visibly does nothing is a bug report (rowcol.ts). */
export function replyPatch(
  sheet: TableSheet, id: string, author: string, text: string,
): Patch | null {
  if (!sheetComments(sheet).some((c) => c.id === id)) return null
  const reply: CommentReply = { id: commentId(), author, text, at: new Date().toISOString() }
  return writeComments(sheet, rawComments(sheet).map((c) => {
    if (idOf(c) !== id) return c
    const t2 = c as Comment
    return { ...t2, replies: [...(t2.replies ?? []), reply] }
  }))
}

/**
 * Resolve or reopen.
 *
 * Reopening DELETES the key rather than writing `false`. In memory the two are
 * the same; in the FILE they are not, and `resolved: false` would accumulate on
 * every thread anybody ever ticked, in every saved copy, forever — the argument
 * `setHidden` makes for `hidden`, with the wire hazard reversed: this key never
 * has to travel as a delete, because the whole array is rewritten anyway.
 */
export function setResolvedPatch(sheet: TableSheet, id: string, resolved: boolean): Patch | null {
  const cur = sheetComments(sheet).find((c) => c.id === id)
  if (!cur || (cur.resolved === true) === resolved) return null
  return writeComments(sheet, rawComments(sheet).map((c) => {
    if (idOf(c) !== id) return c
    if (resolved) return { ...(c as Comment), resolved: true }
    const { resolved: _drop, ...rest } = c as Comment
    return rest as Comment
  }))
}

export function deleteCommentPatch(sheet: TableSheet, id: string): Patch | null {
  if (!sheetComments(sheet).some((c) => c.id === id)) return null
  return writeComments(sheet, rawComments(sheet).filter((c) => idOf(c) !== id))
}

// --- who is commenting -------------------------------------------------------

const LS_AUTHOR = 'bento-author'

/**
 * The commenter's name, remembered per browser and never sent anywhere.
 *
 * The SAME key slides uses, deliberately: it is one person at one browser, and
 * being asked your name again because you switched Bento app would read as the
 * suite forgetting who you are. It is not in the document (a name is not
 * document data until it is attached to something somebody wrote) and it is not
 * synced.
 */
export const commentAuthor = (): string => lsGet(LS_AUTHOR)?.trim() ?? ''

export function setCommentAuthor(name: string): string {
  const n = name.trim()
  if (n) lsSet(LS_AUTHOR, n)
  return n
}

/** "just now" / "4m ago" / a date. Formatted for the VIEWER; the file has ISO. */
export function relTime(iso: string, now = Date.now()): string {
  const s = (now - new Date(iso).getTime()) / 1000
  if (!Number.isFinite(s) || s < 45) return t('just now')
  if (s < 3600) return t('{n}m ago').replace('{n}', String(Math.round(s / 60)))
  if (s < 86400) return t('{n}h ago').replace('{n}', String(Math.round(s / 3600)))
  if (s < 86400 * 30) return t('{n}d ago').replace('{n}', String(Math.round(s / 86400)))
  return new Date(iso).toLocaleDateString()
}

// --- the interface -----------------------------------------------------------
//
// Everything below touches the DOM. The half above does not, which is what lets
// `scripts/test-dash-comments.ts` hold the anchor rules to a sort, a filter, an
// insert, a delete and a JSON round trip with no browser in the room.

export interface CommentsHost {
  store: Store
  grid: Grid
  /** the grid's host element — main.ts's `.dx-grid`. Markers and the pill live in it. */
  el: HTMLElement
}

/** Grid geometry this module has to agree with, read from the grid rather than
 *  copied: `Grid` writes `--row-h` onto its host from its own ROW_H constant
 *  precisely so a second reader cannot drift from it. */
const rowHeight = (el: HTMLElement): number => {
  const v = parseFloat(getComputedStyle(el).getPropertyValue('--row-h'))
  return Number.isFinite(v) && v > 0 ? v : 20
}

export class CommentsUI {
  private store: Store
  private grid: Grid
  private el: HTMLElement
  private pill: HTMLElement
  private obs: MutationObserver | null = null
  private offs: Array<() => void> = []
  /** the thread just created, so its marker can announce itself once */
  private fresh: string | null = null

  constructor(host: CommentsHost) {
    this.store = host.store
    this.grid = host.grid
    this.el = host.el

    this.pill = document.createElement('button')
    this.pill.className = 'dxc-pill'
    this.pill.addEventListener('click', (e) => {
      e.stopPropagation()
      const r = this.pill.getBoundingClientRect()
      this.openList(r.left, r.top)
    })
    this.el.appendChild(this.pill)

    // THE MARKERS ARE RE-INJECTED AFTER EVERY PAINT, and this observer is how
    // this module learns a paint happened without editing grid.ts. `paint()`
    // replaces `.dg-sizer` and `.dg-head-row` wholesale — on a document change,
    // a view change, a scroll, a selection move and a resize — so a childList
    // observer on exactly those two nodes sees every one of them.
    //
    // NOT `subtree: true`, and that is the load-bearing half: markers are
    // injected into `.dg-row > .dg-cell` and into `.dg-h`, which are children
    // of children, so a non-subtree observer cannot see this module's own
    // writes and cannot feed itself. A one-line `onPaint` hook in Grid would
    // replace all of this; until there is one, this costs one microtask per
    // paint and reads no layout.
    const sizer = this.el.querySelector('.dg-sizer')
    const head = this.el.querySelector('.dg-head-row')
    if (sizer && head) {
      this.obs = new MutationObserver(() => this.paintMarkers())
      this.obs.observe(sizer, { childList: true })
      this.obs.observe(head, { childList: true })
    }

    this.offs.push(this.store.on('doc', () => this.refresh()))
    this.offs.push(this.store.on('view', () => this.refresh()))

    // SWITCHING SHEETS emits no store event — `Grid.setSheet` repaints and
    // nothing else — so the markers would follow (the observer sees the paint)
    // while the PILL kept the previous sheet's count. CHAIN the callback, never
    // replace it: panels.ts is already on it, and main.ts states the rule for
    // `onSelectionChange` in the same words. Mount this AFTER mountPanels or
    // the chain is built the wrong way round.
    const wasSheetChange = this.grid.onSheetChange
    this.grid.onSheetChange = (id: string): void => {
      wasSheetChange?.(id)
      this.refresh()
    }

    // ⌘⌥M / Ctrl+Alt+M — Sheets' shortcut for the same act. It cannot collide
    // with the grid's typing path, which main.ts gates on no modifier at all.
    this.onKey = (e: KeyboardEvent): void => {
      if (!(e.metaKey || e.ctrlKey) || !e.altKey) return
      if (e.key.toLowerCase() !== 'm') return
      e.preventDefault()
      this.commentOnSelection()
    }
    document.addEventListener('keydown', this.onKey)

    this.refresh()
  }

  private onKey: (e: KeyboardEvent) => void

  /** The sheet the grid is showing, or null mid-replaceDoc / on a pivot sheet. */
  private sheet(): TableSheet | null {
    try {
      return this.grid.sheet
    } catch {
      return null
    }
  }

  refresh(): void {
    this.paintMarkers()
    this.updatePill()
  }

  destroy(): void {
    this.obs?.disconnect()
    document.removeEventListener('keydown', this.onKey)
    for (const off of this.offs) off()
    this.pill.remove()
    for (const el of this.el.querySelectorAll('.dxc-mark, .dxc-hmark')) el.remove()
  }

  private updatePill(): void {
    const sheet = this.sheet()
    const open = unresolvedCount(sheet)
    const all = sheetComments(sheet).length
    // THE PILL IS A LIST NOW, not the way in: adding a comment is the toolbar's
    // Comment tool (⌘⌥M), as in slides and spaces. With nothing to list it
    // stands down instead of floating over the grid as a second entry point.
    this.pill.hidden = all === 0
    this.pill.classList.toggle('dxc-pill-on', open > 0)
    this.pill.textContent = open ? `💬 ${open}` : '💬'
    this.pill.title = all
      ? t('{open} open of {all} comment(s) — click to list them, ⌘⌥M to add one')
        .replace('{open}', String(open)).replace('{all}', String(all))
      : t('No comments yet — click to add one, or press ⌘⌥M')
  }

  // --- markers ---------------------------------------------------------------

  /**
   * Draw a marker on every commented cell and column that is CURRENTLY PAINTED.
   *
   * The grid is windowed, so a comment 40,000 rows down has no cell to sit on
   * and simply has no marker — the pill and the list are what make it findable.
   * The lookup is by `data-rid`, which is the identity the grid already stamps
   * on each row: that is why a marker follows a sort and a filter without this
   * module knowing either exists.
   */
  private paintMarkers(): void {
    for (const el of this.el.querySelectorAll('.dxc-mark, .dxc-hmark')) el.remove()
    const sheet = this.sheet()
    if (!sheet) return
    const list = sheetComments(sheet)
    if (!list.length) return
    // Keyed `colId SEP rid`. The separator is U+001F and it is written as an
    // ESCAPE, never as a literal — an invisible control character in source
    // does not survive being retyped (the lesson slides records in
    // markdown.ts). It is the CRDT's composite-key separator, chosen for the
    // same reason: a column id is author-derived — import slugs it from the
    // header — so it can hold any byte a header can, including the colon that
    // `cells` keys already use.
    const cells = new Map<string, Comment[]>()
    const columns = new Map<string, Comment[]>()
    for (const c of list) {
      const r = resolveAnchor(sheet, c.anchor)
      if (r.state !== 'live' || r.hidden || !r.col) continue
      const map = r.kind === 'cell' ? cells : r.kind === 'column' ? columns : null
      if (!map) continue
      const key = r.kind === 'cell' ? `${r.col.id}\u001F${r.rid}` : r.col.id
      const at = map.get(key) ?? []
      at.push(c)
      map.set(key, at)
    }

    for (const [key, threads] of cells) {
      const sep = key.indexOf('\u001F')
      const colId = key.slice(0, sep)
      const rid = Number(key.slice(sep + 1))
      // `data-rid` is a number this module produced from the sheet's own runs,
      // so it is safe to interpolate; the COLUMN id is author-derived (import
      // slugs the header) and is compared as a value rather than spliced into a
      // selector, where a quote would be a broken query or worse.
      const row = this.el.querySelector<HTMLElement>(`.dg-row[data-rid="${rid}"]`)
      if (!row) continue
      for (const cell of row.querySelectorAll<HTMLElement>('.dg-cell[data-col]')) {
        if (cell.dataset.col !== colId) continue
        cell.appendChild(this.marker(threads, 'dxc-mark'))
        break
      }
    }

    for (const [colId, threads] of columns) {
      for (const h of this.el.querySelectorAll<HTMLElement>('.dg-head-row .dg-h[data-col]')) {
        if (h.dataset.col !== colId) continue
        // Into the header's own flow row, before the filter caret, rather than
        // absolutely positioned over it: the header is two tight lines already
        // and the resize grip owns the right edge.
        const main = h.querySelector('.dg-hmain')
        const mark = this.marker(threads, 'dxc-hmark')
        if (main) main.insertBefore(mark, main.querySelector('.dg-filter'))
        else h.appendChild(mark)
        break
      }
    }
  }

  /** The corner triangle. Excel's placement, and it covers no digit at 7px. */
  private marker(threads: Comment[], cls: string): HTMLElement {
    const b = document.createElement('button')
    const open = threads.filter((c) => !c.resolved)
    const show = open[0] ?? threads[0]
    b.className = `${cls}${open.length ? '' : ' dxc-done'}`
    if (threads.some((c) => c.id === this.fresh)) {
      b.classList.add('dxc-fresh')
      setTimeout(() => { this.fresh = null }, 1400)
    }
    b.title = `${show.author}: ${show.text.slice(0, 120)}` +
      (threads.length > 1 ? `  (+${threads.length - 1})` : '')
    b.setAttribute('aria-label', t('Comment'))
    // A marker is a CLICK TARGET INSIDE A CELL, so it must not reach the cell's
    // own mousedown — which starts a selection drag. Selection is unchanged by
    // reading a comment, exactly as hovering a note in Excel does not move the
    // cursor.
    b.addEventListener('mousedown', (e) => { e.stopPropagation(); e.preventDefault() })
    b.addEventListener('click', (e) => {
      e.stopPropagation()
      const r = b.getBoundingClientRect()
      if (threads.length === 1) this.openThread(show.id, r.right, r.bottom)
      else this.openList(r.right, r.bottom, threads.map((c) => c.id))
    })
    return b
  }

  // --- composing -------------------------------------------------------------

  /**
   * Comment on what is selected. THE entry point, and it always has an answer:
   * a cell under the cursor anchors to the cell, and anything else — no
   * columns, a filtered-away row, a sheet with no rows — anchors to the SHEET
   * rather than refusing. Slides makes the same call for a click on the grey
   * surround.
   */
  commentOnSelection(): void {
    const sheet = this.sheet()
    if (!sheet || this.store.readOnly) return
    const anchor = this.selectionAnchor(sheet)
    const cell = this.el.querySelector<HTMLElement>('.dg-cell.dg-cursor')
    const r = cell?.getBoundingClientRect()
    const p = this.pill.getBoundingClientRect()
    this.openCompose(anchor, r ? r.right : p.left, r ? r.bottom : p.top)
  }

  /** Cell under the cursor → a cell anchor; nothing addressable → the sheet. */
  private selectionAnchor(sheet: TableSheet): CommentAnchor {
    const hidden = hiddenSet(sheet)
    const visible = sheet.columns.filter((c) => !hidden.has(c.id))
    const col = visible[this.grid.sel.cursor.col]
    if (!col) return { kind: 'sheet' }
    // The cursor counts VISIBLE rows; a comment names a rid. Going through
    // `canonicalRow` is what makes the anchor mean the same cell to a reader
    // whose sort is different — the conversion `Grid.canonicalRow` exists for.
    const row = this.grid.canonicalRow(this.grid.sel.cursor.row)
    if (row < 0) return { kind: 'sheet' }
    const rid = ridOfRow(sheet, row)
    return rid < 0 ? { kind: 'sheet' } : { kind: 'cell', col: col.id, rid }
  }

  private openCompose(anchor: CommentAnchor, x: number, y: number): void {
    const sheet = this.sheet()
    if (!sheet) return
    const r = resolveAnchor(sheet, anchor)
    const pop = this.pop(x, y)

    this.head(pop, t('Comment on {what}').replace('{what}', anchorLabel(sheet, r)))
    const v = anchorValue(sheet, r, this.computed())
    if (v) this.note(pop, t('reads {value}').replace('{value}', v))

    const who = this.authorRow(pop)
    const ta = document.createElement('textarea')
    ta.className = 'dxc-text'
    ta.rows = 3
    ta.placeholder = t('What is wrong with this number?')
    pop.appendChild(ta)

    const foot = document.createElement('div')
    foot.className = 'dxc-foot'
    const add = this.btn(t('Comment'), () => {
      const text = ta.value.trim()
      const author = setCommentAuthor(who.value) || t('Anonymous')
      if (!text) { ta.focus(); return }
      const live = this.sheet()
      if (!live) return
      const c = newComment(live, anchor, author, text, this.computed())
      this.fresh = c.id
      this.store.commit(addCommentPatch(live, c))
      pop.remove()
      this.refresh()
    }, 'dxc-primary')
    foot.append(add, this.btn(t('Cancel'), () => pop.remove()))
    pop.appendChild(foot)

    // ⌘Enter commits, because a textarea owns Enter and a comment is a
    // sentence, not a cell value.
    ta.addEventListener('keydown', (e) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') { e.preventDefault(); add.click() }
    })
    ;(who.value ? ta : who).focus()
  }

  // --- one thread ------------------------------------------------------------

  private openThread(id: string, x: number, y: number): void {
    const sheet = this.sheet()
    if (!sheet) return
    const c = sheetComments(sheet).find((x2) => x2.id === id)
    if (!c) return
    const r = resolveAnchor(sheet, c.anchor)
    const pop = this.pop(x, y)

    this.head(pop, anchorLabel(sheet, r, c.was), r.state !== 'live'
      ? r.state === 'orphan' ? t('orphaned') : t('unknown anchor') : undefined)

    if (r.state === 'orphan') {
      // WHY THE THREAD IS STILL HERE, said in the interface and not only in a
      // comment in the source. A reader who cannot find the row must be told
      // that the row went, not left to conclude the comment is broken.
      this.note(pop, c.was?.value
        ? t('The {what} this comment was on has been deleted. It read {value}.')
          .replace('{what}', r.why === 'column' ? t('column') : t('row'))
          .replace('{value}', c.was.value)
        : t('The {what} this comment was on has been deleted. The comment is kept.')
          .replace('{what}', r.why === 'column' ? t('column') : t('row')))
    } else if (r.state === 'live' && r.kind === 'cell') {
      const now = anchorValue(sheet, r, this.computed())
      const then = c.was?.value
      this.note(pop, then && then !== now
        ? t('now {now} — was {then} when this was written')
          .replace('{now}', now || '—').replace('{then}', then)
        : t('reads {value}').replace('{value}', now || '—'))
    }

    const entries = document.createElement('div')
    entries.className = 'dxc-entries'
    const entry = (author: string, at: string, text: string): void => {
      const e = document.createElement('div')
      e.className = 'dxc-entry'
      const b = document.createElement('b')
      b.textContent = author
      const when = document.createElement('span')
      when.className = 'dxc-when'
      when.textContent = relTime(at)
      when.title = at
      const p = document.createElement('p')
      // textContent, never innerHTML: a comment is user text and the popover is
      // in the editor's own document.
      p.textContent = text
      e.append(b, when, p)
      entries.appendChild(e)
    }
    entry(c.author, c.at, c.text)
    for (const rep of c.replies ?? []) entry(rep.author, rep.at, rep.text)
    pop.appendChild(entries)

    const who = this.authorRow(pop)
    const ta = document.createElement('textarea')
    ta.className = 'dxc-text'
    ta.rows = 2
    ta.placeholder = t('Reply…')
    pop.appendChild(ta)

    const foot = document.createElement('div')
    foot.className = 'dxc-foot'
    const commit = (p: Patch | null): void => {
      if (p) this.store.commit(p)
      pop.remove()
      this.refresh()
    }
    const reply = this.btn(t('Reply'), () => {
      const text = ta.value.trim()
      const author = setCommentAuthor(who.value) || t('Anonymous')
      const live = this.sheet()
      if (!text || !live) { ta.focus(); return }
      commit(replyPatch(live, id, author, text))
    }, 'dxc-primary')
    foot.append(
      reply,
      this.btn(c.resolved ? t('Reopen') : t('Resolve'), () => {
        const live = this.sheet()
        if (live) commit(setResolvedPatch(live, id, !c.resolved))
      }),
      this.btn(t('Delete'), () => {
        const live = this.sheet()
        if (live) commit(deleteCommentPatch(live, id))
      }, 'dxc-danger'),
    )
    if (r.state === 'live' && r.kind !== 'sheet') {
      foot.append(this.btn(t('Go to'), () => { pop.remove(); this.goTo(r) }))
    }
    pop.appendChild(foot)
    ta.addEventListener('keydown', (e) => {
      if ((e.metaKey || e.ctrlKey) && e.key === 'Enter') { e.preventDefault(); reply.click() }
    })
    ta.focus()
  }

  // --- the list --------------------------------------------------------------

  /** Every thread on this sheet: open first, then orphans, then resolved. */
  private openList(x: number, y: number, only?: string[]): void {
    const sheet = this.sheet()
    const pop = this.pop(x, y, 'dxc-list')
    if (!sheet) {
      this.note(pop, t('No table sheet is open.'))
      return
    }
    const pick = only ? new Set(only) : null
    const all = sheetComments(sheet).filter((c) => !pick || pick.has(c.id))
    const rank = (c: Comment): number => {
      if (c.resolved) return 2
      return resolveAnchor(sheet, c.anchor).state === 'live' ? 0 : 1
    }
    const sorted = [...all].sort((a, b) => rank(a) - rank(b) || (a.at < b.at ? -1 : 1))

    this.head(pop, t('Comments on {sheet}').replace('{sheet}', sheet.name))
    if (!sorted.length) this.note(pop, t('Nothing has been flagged on this sheet yet.'))

    let group = -1
    for (const c of sorted) {
      const g = rank(c)
      if (g !== group) {
        group = g
        const h = document.createElement('div')
        h.className = 'dxc-group'
        h.textContent = g === 0 ? t('Open') : g === 1 ? t('Orphaned') : t('Resolved')
        pop.appendChild(h)
      }
      const r = resolveAnchor(sheet, c.anchor)
      const item = document.createElement('button')
      item.className = `dxc-item${c.resolved ? ' dxc-done' : ''}`
      const where = document.createElement('span')
      where.className = 'dxc-where'
      where.textContent = anchorLabel(sheet, r, c.was)
      const line = document.createElement('span')
      line.className = 'dxc-line'
      line.textContent = `${c.author}: ${c.text}`
      item.append(where, line)
      item.addEventListener('click', (e) => {
        e.stopPropagation()
        pop.remove()
        const rect = item.getBoundingClientRect()
        this.openThread(c.id, rect.right, rect.top)
      })
      pop.appendChild(item)
    }

    if (!this.store.readOnly) {
      const foot = document.createElement('div')
      foot.className = 'dxc-foot'
      foot.append(this.btn(t('+ Comment on the selected cell'), () => {
        pop.remove()
        this.commentOnSelection()
      }, 'dxc-primary'))
      pop.appendChild(foot)
    }
  }

  /**
   * Scroll a live anchor into view and put the cursor on it.
   *
   * The row may be filtered AWAY, which is not an error and must not be
   * silently ignored — the reader asked to go somewhere and has to be told why
   * they did not arrive.
   *
   * KNOWN WART: the formula bar and the status bar are driven by the grid's own
   * private `announce()`, so they keep showing the previous cell until the next
   * click or keystroke. One word (`private announce` → `announce`) fixes it;
   * see the report.
   */
  private goTo(r: ResolvedAnchor): void {
    const sheet = this.sheet()
    if (!sheet || !r.col) return
    const hidden = hiddenSet(sheet)
    const vcol = sheet.columns.filter((c) => !hidden.has(c.id)).findIndex((c) => c.id === r.col!.id)
    if (vcol < 0) return
    if (r.kind === 'column' || typeof r.row !== 'number') {
      this.grid.sel.selectCol(vcol)
      this.grid.paint()
      return
    }
    const order = this.store.order[sheet.id]
    const vrow = order ? order.indexOf(r.row) : r.row
    if (vrow < 0) {
      window.alert(t('That row is hidden by the current filter.'))
      return
    }
    const scroll = this.el.querySelector<HTMLElement>('.dg-scroll')
    if (scroll) {
      const h = rowHeight(this.el)
      scroll.scrollTop = Math.max(0, vrow * h - scroll.clientHeight / 2)
    }
    this.grid.sel.moveTo(vrow, vcol)
    this.grid.paint()
  }

  // --- popover furniture -------------------------------------------------------
  //
  // `.dx-pop` IS REUSED RATHER THAN RE-STYLED. The filter menu, the retype
  // menu, the cell menu and the save menu are all one floating surface; a
  // comment popover that looked like a fifth thing would read as a different
  // application. comments.css only adds what a THREAD needs and nothing the
  // surface already provides.

  private pop(x: number, y: number, extra = ''): HTMLElement {
    document.querySelector('.dx-pop')?.remove()
    const el = document.createElement('div')
    el.className = `dx-pop dxc-pop ${extra}`.trim()
    el.style.left = `${Math.max(8, Math.min(x, window.innerWidth - 320))}px`
    el.style.top = `${Math.max(8, Math.min(y, window.innerHeight - 260))}px`
    document.body.appendChild(el)
    // Keystrokes inside the popover are the popover's. Without this, typing a
    // comment reaches main.ts's document handler, which hands any bare
    // printable key to `grid.typeInto` — every letter would also start editing
    // the selected cell.
    el.addEventListener('keydown', (e) => {
      e.stopPropagation()
      if (e.key === 'Escape') el.remove()
    })
    setTimeout(() => {
      const off = (e: MouseEvent): void => {
        if (!el.contains(e.target as Node)) {
          el.remove()
          document.removeEventListener('mousedown', off)
        }
      }
      document.addEventListener('mousedown', off)
    }, 0)
    return el
  }

  private head(pop: HTMLElement, label: string, badge?: string): void {
    const h = document.createElement('div')
    h.className = 'dxc-head'
    const s = document.createElement('span')
    s.textContent = label
    h.appendChild(s)
    if (badge) {
      const b = document.createElement('span')
      b.className = 'dxc-badge'
      b.textContent = badge
      h.appendChild(b)
    }
    pop.appendChild(h)
  }

  private note(pop: HTMLElement, text: string): void {
    const p = document.createElement('p')
    p.className = 'dxc-note'
    p.textContent = text
    pop.appendChild(p)
  }

  /** The name new entries will carry — editable in place, never a native prompt.
   *  dash already refused `window.prompt` for the type picker, for the same
   *  reason: a dialog that asks you to type an answer is not a control. */
  private authorRow(pop: HTMLElement): HTMLInputElement {
    const row = document.createElement('label')
    row.className = 'dxc-who'
    const span = document.createElement('span')
    span.textContent = t('as')
    const input = document.createElement('input')
    input.className = 'dx-pop-in'
    input.type = 'text'
    input.spellcheck = false
    input.value = commentAuthor()
    input.placeholder = t('your name')
    row.append(span, input)
    pop.appendChild(row)
    return input
  }

  private btn(label: string, onClick: () => void, cls = ''): HTMLElement {
    const b = document.createElement('button')
    b.className = `dxc-btn ${cls}`.trim()
    b.textContent = label
    b.addEventListener('click', (e) => { e.stopPropagation(); onClick() })
    return b
  }

  /** The grid's freshly computed formula columns, so a caption shows the number
   *  on screen rather than the empty column underneath it. */
  private computed(): Map<string, unknown[]> {
    return this.grid.computed as unknown as Map<string, unknown[]>
  }
}

export function mountComments(host: CommentsHost): CommentsUI {
  return new CommentsUI(host)
}