Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

50.3 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// Comments — margin notes on a RANGE of text, with replies and resolution.
//
// The thing every reviewed document needs, and the last review surface this app
// was missing: redline.ts answers "what changed", comments answer "why, and
// what do you think". A redline is a diff between two revisions; a comment is a
// conversation about text that has not changed at all, which is most of the
// text a reviewer has something to say about.
//
// ─────────────────────────────────────────────────────────── the four choices
//
// 1. A COMMENT IS A DOC-LEVEL RECORD, KEYED BY ID — `doc.comments`, exactly the
//    shape `doc.footnotes` already uses. Not nested into the block it points
//    at. The document is FLAT (model.ts explains why: the redline aligns on
//    block ids, the caret is (blockId, offset), pagination walks line boxes),
//    and a thread hanging off a block would put a second kind of nesting under
//    all three. It also has to outlive its block — see orphans below — which a
//    field on the block cannot do by construction.
//
// 2. THE ANCHOR IS A CHARACTER RANGE INTO PLAIN TEXT, and it moves with the
//    text using inline.ts `shift` — the SAME function marks use and the same
//    rule footnote anchors follow. Not a copy of it. A comment whose range
//    drifts onto the wrong words is worse than no comment, and the way that
//    happens is a second implementation of offset arithmetic that is 95%
//    identical to the first. There is one implementation; this module wraps a
//    range in a carrier mark and asks `shift` to move it. Everything an author
//    can anchor into a block's text — a mark, a footnote, a comment — therefore
//    moves identically, and there is one place to get it right.
//
// 3. A COMMENT WHOSE TEXT IS DELETED IS ORPHANED, NEVER DROPPED. See below.
//
// 4. NOTHING IS DRAWN INSIDE THE EDITABLE. Highlights are rectangles painted
//    into an OVERLAY layer, computed from `Range.getClientRects()` — the same
//    technique paginate.ts uses to place its sidenotes, and for the same
//    reason: decorations inserted into the flow enter the undo stack, confuse
//    the caret's offset walk, and get destroyed on the next re-render anyway.
//
// ─────────────────────────────────────────────── how comments stay out of print
//
// STRUCTURALLY, not by a flag. print.ts builds its flow in `bodyHtml`, which
// emits `blockHtml(b)` per block; `blockHtml` reads exactly `b.text`, `b.marks`
// and `b.notes`. It never reads `doc.comments`, and this module never writes a
// mark, a note, or a character into a block — the highlight is an absolutely
// positioned <div> in a sibling overlay of `.t-paper`, and the margin cards are
// in that same overlay. There is no code path from a comment to the printed
// string, so no print-time exclusion is needed and none can be forgotten. (The
// tempting shortcut — a `t:'comment'` mark — is exactly what would have printed
// a yellow highlight onto every executed copy of a contract.) Verified in the
// rig: `buildPrintDocument` output of a commented document contains no comment
// text and is byte-identical to the same document with `comments` removed.
//
// ───────────────────────────────────────────────────────── NEEDS FROM THE CORE
//
// This module is complete and testable WITHOUT the following. Each one is a
// call site the core owns; until they land, a comment's anchor survives every
// edit that goes through `commentsOnEdit` (which nothing calls yet) and is
// repaired defensively on every read by `reconcileThreads` — so nothing is ever
// wrong, only coarse: after an unhooked edit a range is clamped to the block
// and orphaned if it no longer fits, rather than tracked character by character.
//
// (A) type/src/model.ts — declare the field, and repair it at parse time.
//
//     After `NoteRef`, add:
//
//         /** comment id → thread. Doc-level and keyed by id, like footnotes:
//          *  a thread must be able to outlive the block it points at. */
//         export interface CommentMsg { id: string; author: string; at: string; text: string }
//         export interface CommentThread {
//           id: string; block: string; from: number; to: number;
//           quote: string; messages: CommentMsg[];
//           resolved?: boolean; orphan?: boolean;
//         }
//
//     and on `TypeDoc`, beside `footnotes`:
//
//         comments?: Record<string, CommentThread>;
//
//     WHY: format additivity means an unknown `comments` key already rides
//     through `parseDoc` untouched (the `...json` spread), so old files open in
//     a new build and NEW FILES OPEN IN AN OLD BUILD with the comments intact
//     but invisible — which is the additivity requirement, already met. The
//     field is wanted for two other reasons: so `tsc` types it instead of this
//     module casting through the index signature, and so `parseDoc` can repair
//     a hand-edited or generator-produced file (drop a thread with no messages,
//     clamp `from`/`to` into the block, detach a thread whose block is missing
//     or whose range is degenerate) deterministically, the way it already
//     repairs dangling footnote refs. That repair is already written here, pure
//     and in two halves, so `parseDoc` can call it directly:
//
//         const list = reconcileThreads(readThreadsRaw(json), body);
//         if (list.length) doc.comments = Object.fromEntries(list.map(t => [t.id, t]));
//
//     Note the ORDER, which matters: `readThreadsRaw` is the total parse and
//     `reconcileThreads` is the repair, and the edit hooks in (B) deliberately
//     use only the first — repairing before moving an anchor clamps it against
//     a body that has already changed.
//
// (B) type/src/editor.ts — three one-line calls, so an anchor tracks an edit
//     exactly rather than being repaired approximately.
//
//     import { commentsOnEdit, commentsOnSplit, commentsOnMerge } from './comments.ts';
//
//     · in `#input`, inside the existing `this.store.commit(d => { … })`
//       callback, after `d.body[i] = next`:
//               commentsOnEdit(d, c.id, prev.text, next.text);
//       WHY inside the commit: it must land in the same undo snapshot as the
//       text, or ⌘Z restores the words and leaves the anchor where the edit
//       put it. The snapshot scope is `{ block }` today, which does not cover
//       `doc.comments` — so this call also needs the scope widened to 'doc'
//       for the commits that move a comment, OR (cheaper, and what I would do)
//       `commentsOnEdit` returning false when it changed nothing, which it
//       does: a block carrying no comments never widens anybody's undo.
//     · in `#splitBlock`, inside its commit, after the splice:
//               commentsOnSplit(d, src.id, c.at, src.text.length, tail.id);
//     · in `#mergeBack`, inside its commit, after the splice:
//               commentsOnMerge(d, prev.id, cur.id, at);
//
// (C) type/src/print.ts — NOTHING. Deliberately. See above.
//
// (D) type/src/icons.ts — optional. `COMMENT_ICON` below follows the house
//     recipe exactly (24×24 box, rendered 16px, stroke currentColor, width 2,
//     round caps and joins) and lives here only because this module owns its
//     own file. Moving it to `ICONS.comment` is a pure lift.
//
// (E) type/src/main.ts — optional. `PanelSpec.update` is declared in
//     features.ts and never called; this module therefore drives its own
//     repaints from `store.on` and a MutationObserver on the paper, which is
//     self-contained and needs no change. If main.ts ever starts calling
//     `spec.update`, this panel is already idempotent.

import { shift, type Mark } from './inline.ts';
import { isNoteAtom } from './render.ts';
import { uid, type Block, type TypeDoc } from './model.ts';
import { registerTool, registerPanel, registerKey, registerMenuItem, registerReady, type FeatureContext } from './features.ts';
import { t } from './i18n.ts';
// NOT `import './comments.css'` here: model.ts imports this module's pure
// functions (readThreadsRaw, reconcileThreads) for parsing, and model.ts is
// imported by nearly every test rig under plain Node, which cannot load a
// bare `.css` specifier the way Vite does. about.ts is always loaded by
// main.ts (never lazily) and no rig imports it, so it is the safe place that
// pulls comments.css into the bundle — see about.ts.

// ───────────────────────────────────────────────────────────────── the shape

/** One message in a thread. The first is the comment; the rest are replies. */
export interface CommentMsg {
  id: string;
  /** self-asserted, from localStorage 'bento-author'. A claim, not an identity —
   *  signatures (canon.ts) are the only thing in this document that proves who. */
  author: string;
  /** ISO wall clock, display only */
  at: string;
  /** CONTENT, not UI: never passed through t() */
  text: string;
}

export interface CommentThread {
  id: string;
  /** the block this points into */
  block: string;
  /** character offsets into that block's PLAIN text — same coordinates as a
   *  mark and a footnote anchor, moved by the same function */
  from: number;
  to: number;
  /**
   * The anchored text, captured when the comment was made.
   *
   * Not a cache: it is the thread's only self-description once the text it
   * pointed at is gone. "Is this enforceable?" with no idea what "this" was is
   * not a comment, it is a riddle.
   */
  quote: string;
  messages: CommentMsg[];
  resolved?: boolean;
  /**
   * The anchor no longer exists: its block was deleted, or its words were.
   *
   * ORPHANS ARE KEPT, and this is the whole policy. Three options were on the
   * table and two of them are wrong:
   *
   *   · DROP the thread — silently destroys review conversation, and it does it
   *     precisely when somebody deletes the clause that was being argued about,
   *     which is the moment the argument matters most.
   *   · KEEP THE OFFSETS LIVE — the comment then points at whatever text has
   *     since flowed into those offsets, so "this indemnity is uncapped" ends
   *     up attached to the notices clause. Worse than no comment, because it
   *     is confidently wrong.
   *   · ORPHAN — the thread stays in the file with its conversation and its
   *     `quote` intact, `block`/`from`/`to` frozen as a record of where it USED
   *     to be, and this flag set. It is not highlighted (there is nothing to
   *     highlight), it is not clickable-to-scroll, and the panel lists it in a
   *     "detached" group saying which words it was about. A human decides
   *     whether it is finished; the app never decides for them.
   *
   * ONCE SET BY AN EDIT, THIS PERSISTS. The first version of this file derived
   * the flag on every read instead — "never trust the file" — and it was wrong
   * in a way the rig caught: a thread whose words were deleted keeps its old
   * `from`/`to` as the record of where it was, and those numbers are usually
   * still inside the (now shorter) block, so re-deriving cheerfully un-orphaned
   * it and pointed it at whatever had flowed into those offsets. That is the
   * exact failure the orphan policy exists to prevent.
   *
   * Undo still resurrects a thread, and does it properly: the store snapshots
   * the whole document, so undoing the deletion restores the comment map as it
   * was before it — flag and offsets together — rather than reconstructing a
   * guess. `reconcileThreads` therefore only ever ADDS this flag, never clears
   * it. What it adds is transient (a read does not write back), which is what
   * lets a thread whose BLOCK is missing come back by itself if the block
   * returns — a redline rejection re-inserting a deleted paragraph does exactly
   * that.
   */
  orphan?: boolean;
}

/** Where a thread's anchor is, as bare offsets. */
export interface Anchor { from: number; to: number }

const AUTHOR_KEY = 'bento-author';   // shared with bento/slides, on purpose

// ─────────────────────────────────────────────────── reading and writing them
//
// `doc.comments` is reached through TypeDoc's `[extra: string]: unknown` index
// signature until (A) above lands. Centralised in these two functions so that
// when it does, this is the only edit.

type Commented = { comments?: Record<string, CommentThread> };
const asCommented = (doc: TypeDoc): Commented => doc as unknown as Commented;

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

/**
 * Every thread in the document, EXACTLY as stored — no repair.
 *
 * Total: a `comments` field of any shape at all yields a valid list, because
 * this runs on files a generator or a hand edit produced. A thread with no
 * messages is not a thread and is the one thing dropped — there is no
 * conversation in it to preserve.
 *
 * The edit hooks below read through THIS, not `readThreads`. They are told the
 * exact edit and know how to move an anchor through it; running the defensive
 * repair first would clamp anchors against the already-mutated body and destroy
 * the very offsets the hook was about to move. That ordering bug is real and
 * the rig caught it: a comment in the tail of a split paragraph was clamped
 * against the truncated head, orphaned, and then skipped by the split.
 */
export function readThreadsRaw(doc: TypeDoc): CommentThread[] {
  const raw = asCommented(doc).comments;
  if (!isObj(raw)) return [];
  const out: CommentThread[] = [];
  for (const [key, v] of Object.entries(raw)) {
    if (!isObj(v)) continue;
    const messages = Array.isArray(v.messages)
      ? (v.messages as unknown[]).filter(isObj).map((m, i) => ({
          id: typeof m.id === 'string' && m.id ? m.id : `${key}-m${i}`,
          author: typeof m.author === 'string' ? m.author : '',
          at: typeof m.at === 'string' ? m.at : '',
          text: typeof m.text === 'string' ? m.text : '',
        }))
      : [];
    if (!messages.length) continue;
    // NOT sorted into order and not clamped here: a stored range of (9e9, -3)
    // is garbage, and quietly repairing it into "the whole paragraph" would
    // attach somebody's comment to text they never selected. Left as read, so
    // reconcileThreads sees a degenerate range and orphans it — which says
    // "this pointed somewhere that no longer makes sense", which is the truth.
    const num = (v: unknown) => typeof v === 'number' && Number.isFinite(v) ? Math.floor(v) : 0;
    const from = num(v.from), to = num(v.to);
    out.push({
      id: typeof v.id === 'string' && v.id ? v.id : key,
      block: typeof v.block === 'string' ? v.block : '',
      from, to,
      quote: typeof v.quote === 'string' ? v.quote : '',
      messages,
      ...(v.resolved === true ? { resolved: true as const } : {}),
      ...(v.orphan === true ? { orphan: true as const } : {}),
    });
  }
  return out;
}

/** Every thread, repaired against the current body — what every reader wants. */
export const readThreads = (doc: TypeDoc): CommentThread[] =>
  reconcileThreads(readThreadsRaw(doc), doc.body);

/** Put a thread list back, as the id-keyed map the format stores. */
export function writeThreads(doc: TypeDoc, threads: CommentThread[]): void {
  const d = asCommented(doc);
  if (!threads.length) { delete d.comments; return; }
  const map: Record<string, CommentThread> = {};
  for (const th of threads) map[th.id] = th;
  d.comments = map;
}

// ───────────────────────────────────────────────────────── anchor maintenance
//
// All pure. This is the part that must not be wrong.

/**
 * A range wrapped as a MARK, so inline.ts `shift` can move it.
 *
 * The carrier's type is arbitrary and never rendered or stored — `shift` only
 * ever reads `from`/`to`, and `normalize` (which it ends with) only cares that
 * a mark of zero width is dropped, which is exactly the signal this module
 * wants for "the anchored text is gone".
 *
 * This indirection is the point of the whole file. Marks, footnote anchors and
 * comment anchors are three names for one problem, and the moment any of them
 * gets its own arithmetic they start disagreeing under an edit that straddles a
 * boundary — the failure mode being a comment sitting one word to the left of
 * the sentence it is about, which nobody notices until a contract is signed.
 */
const CARRIER: Mark['t'] = 'b';

/**
 * Move a range to follow an edit that replaced [at, at+removed) with `added`
 * characters, against a text of final length `len`.
 *
 * Returns null when the range no longer covers anything — the anchored text was
 * deleted outright. The caller decides what that means; here it means orphan.
 *
 * The behaviour at the two edges is inherited, deliberately, rather than chosen:
 * an insertion exactly AT `from` joins the range and one exactly AT `to` does
 * not, because that is what `shift` does to a mark, and a comment highlight
 * that grew differently from the bold underneath it would look like a bug in
 * one of them.
 */
export function shiftAnchor(a: Anchor, at: number, removed: number, added: number, len: number): Anchor | null {
  const moved = shift([{ t: CARRIER, from: a.from, to: a.to }], at, removed, added, len);
  if (!moved.length) return null;
  return { from: moved[0].from, to: moved[0].to };
}

/**
 * The minimal edit between two versions of one block's text, as
 * (at, removed, added) — a common-prefix / common-suffix trim.
 *
 * The editor rebuilds a whole block from the DOM on every `input` (render.ts
 * readBlock) rather than reporting a splice, so the splice has to be recovered
 * here. Minimal matters: treating a keystroke as "replaced the entire
 * paragraph" would orphan every comment in it on the first character typed.
 *
 * Returns null when the text did not change.
 */
export function textEdit(prev: string, next: string): { at: number; removed: number; added: string } | null {
  if (prev === next) return null;
  const max = Math.min(prev.length, next.length);
  let p = 0;
  while (p < max && prev[p] === next[p]) p++;
  let s = 0;
  while (s < max - p && prev[prev.length - 1 - s] === next[next.length - 1 - s]) s++;
  return { at: p, removed: prev.length - p - s, added: next.slice(p, next.length - s) };
}

/** Move one thread through an edit in ITS block. Pure; returns a new thread. */
export function shiftThread(th: CommentThread, at: number, removed: number, added: number, len: number): CommentThread {
  const moved = shiftAnchor({ from: th.from, to: th.to }, at, removed, added, len);
  // The frozen from/to are kept as the record of where it was — see `orphan`.
  if (!moved) return { ...th, orphan: true };
  const out: CommentThread = { ...th, from: moved.from, to: moved.to };
  delete out.orphan;
  return out;
}

/** Move every thread anchored in `blockId` through one edit. Pure. */
export function shiftThreads(threads: CommentThread[], blockId: string,
                             at: number, removed: number, added: number, len: number): CommentThread[] {
  return threads.map(th =>
    th.block === blockId && !th.orphan ? shiftThread(th, at, removed, added, len) : th);
}

/**
 * Follow a paragraph SPLIT: `srcId` was cut at `at`, the head keeping `srcId`
 * and the tail becoming `tailId`.
 *
 * A thread that straddles the cut cannot be in two places, and the two obvious
 * answers are both bad: dropping it destroys a live conversation over an edit
 * that changed no words at all, and duplicating it makes one comment that two
 * people must now resolve twice. It goes to the side holding MORE of the text
 * it was about, clipped — which is the side a reader would point at.
 */
export function splitThreads(threads: CommentThread[], srcId: string, at: number,
                             srcLen: number, tailId: string): CommentThread[] {
  const tailLen = srcLen - at;
  return threads.map(th => {
    if (th.block !== srcId || th.orphan) return th;
    if (th.to <= at) return th;                                   // wholly in the head
    if (th.from >= at) {                                          // wholly in the tail
      return { ...th, block: tailId, from: th.from - at, to: Math.min(th.to - at, tailLen) };
    }
    const inHead = at - th.from, inTail = th.to - at;
    if (inTail > inHead) return { ...th, block: tailId, from: 0, to: Math.min(inTail, tailLen) };
    return { ...th, to: at };
  });
}

/**
 * Follow a paragraph MERGE: `curId` was appended to `prevId` at offset `at`.
 * Nothing is lost — a merge only concatenates — so every anchor survives.
 */
export function mergeThreads(threads: CommentThread[], prevId: string, curId: string, at: number): CommentThread[] {
  return threads.map(th =>
    th.block === curId && !th.orphan
      ? { ...th, block: prevId, from: th.from + at, to: th.to + at }
      : th);
}

/**
 * Repair every thread against the body, and set or CLEAR `orphan`.
 *
 * A NET, NOT A DERIVATION. It only ever ADDS the flag — see `orphan` for the
 * bug that taught the difference. Its job is to make this module safe before
 * the editor hooks in (B) exist, and safe against files nothing in this app
 * wrote: the worst an untracked edit or a bad generator can do is clamp a range
 * or detach a thread, never point one somewhere false.
 *
 * Runs on every read and writes nothing back, so what it adds is transient —
 * which is what lets a thread whose block is missing come back by itself when
 * the block returns.
 */
export function reconcileThreads(threads: CommentThread[], body: readonly Block[]): CommentThread[] {
  const byId = new Map(body.map(b => [b.id, b]));
  return threads.map(th => {
    if (th.orphan) return th;                      // already detached; leave the record alone
    const blk = byId.get(th.block);
    if (!blk) return { ...th, orphan: true };
    const from = Math.max(0, Math.min(th.from, blk.text.length));
    const to = Math.max(0, Math.min(th.to, blk.text.length));
    if (to <= from) return { ...th, orphan: true };
    return { ...th, from, to };
  });
}

// ───────────────────────────────────────────────────────────── thread logic

const now = () => new Date().toISOString();

/** Start a thread on [from,to) of a block. `quote` is captured here, once. */
export function newThread(block: Block, from: number, to: number, author: string, text: string,
                          id = uid('cm'), at = now()): CommentThread {
  return {
    id, block: block.id, from, to,
    quote: block.text.slice(from, to),
    messages: [{ id: uid('cmm'), author, at, text }],
  };
}

/** Append a reply. Pure. An empty body is not a reply and is refused. */
export function addReply(th: CommentThread, author: string, text: string, at = now()): CommentThread {
  if (!text.trim()) return th;
  return { ...th, messages: [...th.messages, { id: uid('cmm'), author, at, text }] };
}

/**
 * Edit a message's text in place. Pure; touches nothing else on the thread —
 * `block`/`from`/`to`/`quote` are the ANCHOR and an edit to what somebody
 * SAID about the text is not an edit to what they said it ABOUT, so the
 * anchor a caller reads before and after this call is byte-identical.
 *
 * An empty result is not an edit (that is what delete is for) and is refused:
 * this returns the thread unchanged rather than leaving a blank message
 * behind for a hasty save-of-empty-textarea to commit.
 */
export function editMessage(th: CommentThread, msgId: string, text: string): CommentThread {
  const trimmed = text.trim();
  if (!trimmed || !th.messages.some(m => m.id === msgId)) return th;
  return { ...th, messages: th.messages.map(m => m.id === msgId ? { ...m, text: trimmed } : m) };
}

/**
 * Remove one message. Returns the thread with it gone, or `null` when it was
 * the LAST message — a thread with no messages is not a thread (the same
 * rule `readThreadsRaw` applies on parse), so the caller deletes the whole
 * thread rather than keep an empty shell with a frozen anchor and no
 * conversation to show for it.
 */
export function deleteMessage(th: CommentThread, msgId: string): CommentThread | null {
  const messages = th.messages.filter(m => m.id !== msgId);
  return messages.length ? { ...th, messages } : null;
}

/**
 * Resolve or unresolve. Both directions, because "resolved" is a reviewer's
 * judgement and reviewers change their minds — a one-way resolve is a delete
 * with extra steps.
 */
export function setResolved(th: CommentThread, resolved: boolean): CommentThread {
  const out = { ...th };
  if (resolved) out.resolved = true; else delete out.resolved;
  return out;
}

/** How many threads still want a human. Orphans count: they are not resolved. */
export const unresolvedCount = (threads: readonly CommentThread[]): number =>
  threads.filter(th => !th.resolved).length;

/**
 * The order the panel shows.
 *
 * UNRESOLVED FIRST, because the panel's job is a to-do list and a document with
 * forty settled comments must not bury the three that are open. Then attached
 * before detached — a comment you can still click through to outranks one whose
 * text is gone. Then DOCUMENT ORDER, so reading the panel top to bottom is
 * reading the document top to bottom. Orphans have no position left, so they
 * fall back to when they were written. Fully deterministic: two readers of one
 * file see the same list, which matters because people say "the third comment".
 */
export function orderThreads(threads: readonly CommentThread[], body: readonly Block[]): CommentThread[] {
  const pos = new Map(body.map((b, i) => [b.id, i]));
  const rank = (th: CommentThread) => [
    th.resolved ? 1 : 0,
    th.orphan ? 1 : 0,
    th.orphan ? Number.MAX_SAFE_INTEGER : (pos.get(th.block) ?? Number.MAX_SAFE_INTEGER),
    th.orphan ? 0 : th.from,
  ];
  return [...threads].sort((a, b) => {
    const ra = rank(a), rb = rank(b);
    for (let i = 0; i < ra.length; i++) if (ra[i] !== rb[i]) return ra[i] - rb[i];
    const ta = a.messages[0]?.at ?? '', tb = b.messages[0]?.at ?? '';
    return ta < tb ? -1 : ta > tb ? 1 : (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
  });
}

// ────────────────────────────────────── the hooks the core calls (see (B))
//
// Thin, mutating wrappers over the pure functions above. Each returns whether
// it changed anything, so a commit whose block carries no comments costs
// nothing and does not have to widen its undo scope.

export function commentsOnEdit(doc: TypeDoc, blockId: string, prevText: string, nextText: string): boolean {
  const d = asCommented(doc);
  if (!d.comments) return false;
  const e = textEdit(prevText, nextText);
  if (!e) return false;
  const before = readThreadsRaw(doc);
  if (!before.some(th => th.block === blockId)) return false;
  writeThreads(doc, shiftThreads(before, blockId, e.at, e.removed, e.added.length, nextText.length));
  return true;
}

export function commentsOnSplit(doc: TypeDoc, srcId: string, at: number, srcLen: number, tailId: string): boolean {
  const d = asCommented(doc);
  if (!d.comments) return false;
  const before = readThreadsRaw(doc);
  if (!before.some(th => th.block === srcId)) return false;
  writeThreads(doc, splitThreads(before, srcId, at, srcLen, tailId));
  return true;
}

export function commentsOnMerge(doc: TypeDoc, prevId: string, curId: string, at: number): boolean {
  const d = asCommented(doc);
  if (!d.comments) return false;
  const before = readThreadsRaw(doc);
  if (!before.some(th => th.block === curId)) return false;
  writeThreads(doc, mergeThreads(before, prevId, curId, at));
  return true;
}

// ═══════════════════════════════════════════════════════════════════════ UI
//
// Everything below touches the DOM. The logic above does not, which is what
// lets the rig run under plain node.

/**
 * The bubble, to the house recipe in icons.ts: 24×24 box, rendered at 16px,
 * stroke currentColor at width 2, round caps and joins. It lives here rather
 * than in ICONS because this feature is one file — see (D).
 */
const COMMENT_ICON =
  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" width="16" height="16" fill="none" ' +
  'stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
  '<path d="M21 12a8 8 0 0 1-8 8H8l-5 3 1.4-4.2A8 8 0 0 1 13 4a8 8 0 0 1 8 8z"/>' +
  '<line x1="8.5" y1="11" x2="15.5" y2="11"/><line x1="8.5" y1="14.5" x2="13" y2="14.5"/></svg>';

/**
 * Who you are IF you have already said — never asks.
 *
 * authorName() below prompts when it does not know, which is right when you
 * have just chosen to leave a comment and wrong on a keystroke: tracked changes
 * attribute every edit, and a modal in the middle of a sentence would be
 * unusable. Tracking asks once, when it is switched on.
 */
export function knownAuthor(): string {
  try { return localStorage.getItem(AUTHOR_KEY) || ''; } catch { return ''; }
}

/** Ask for a name if there isn't one, without the caller needing a comment. */
export const ensureAuthor = (): string => authorName();

/**
 * Set the name directly — the primary path, from the About dialog's "You"
 * section. `authorName()`'s prompt stays as the FALLBACK for someone who
 * comments or turns on tracking before ever opening About; both write the
 * same key, so whichever ran first is what the other reads.
 *
 * Trimmed and stored empty-as-cleared: an empty saved name is not a name, and
 * `authorName()` must still see nothing there so it prompts (or falls back to
 * 'Anonymous') the next time it is needed, rather than silently attributing
 * as ''.
 */
export function setAuthorName(name: string): void {
  const who = name.trim();
  try { who ? localStorage.setItem(AUTHOR_KEY, who) : localStorage.removeItem(AUTHOR_KEY); }
  catch { /* private mode — the name just won't persist across reloads */ }
}

/** Who you are, as bento/slides records it — one suite, one answer. */
function authorName(): string {
  let who = '';
  try { who = localStorage.getItem(AUTHOR_KEY) ?? ''; } catch { /* private mode */ }
  if (who) return who;
  const asked = typeof prompt === 'function'
    ? prompt(t('Your name, so your comments are attributed'), '') : '';
  who = (asked ?? '').trim();
  if (who) { try { localStorage.setItem(AUTHOR_KEY, who); } catch { /* ignore */ } }
  // NOT t(): this becomes CONTENT in the file, and content does not change
  // language when somebody else opens it.
  return who || 'Anonymous';
}

const when = (iso: string) => {
  const d = new Date(iso);
  return isNaN(d.getTime()) ? '' : d.toLocaleString(undefined,
    { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });
};

/** The selected thread — VIEW state, never in the document. */
let selected: string | null = null;
/** The one message currently being edited in place — VIEW state too. */
let editingMsg: string | null = null;
let layer: HTMLElement | null = null;
let repaint: (() => void) | null = null;
let refreshPanel: (() => void) | null = null;

/**
 * The DOM point `at` characters into a rendered block — footnote atoms skipped,
 * exactly as editor.ts counts them. A comment's offsets are model offsets, and
 * the model does not know the marker is there.
 */
function pointAt(block: HTMLElement, at: number): { node: Node; offset: number } | null {
  let count = 0;
  let last: { node: Node; offset: number } | null = null;
  const walk = (n: Node): { node: Node; offset: number } | null => {
    if (n.nodeType === 3) {
      const len = n.nodeValue!.length;
      if (count + len >= at) return { node: n, offset: at - count };
      count += len;
      last = { node: n, offset: len };
      return null;
    }
    if (n.nodeType === 1 && isNoteAtom(n as Element)) return null;
    for (const c of Array.from(n.childNodes)) { const r = walk(c); if (r) return r; }
    return null;
  };
  for (const c of Array.from(block.childNodes)) { const r = walk(c); if (r) return r; }
  return last;
}

/** Characters before (container, offset) in this block — the inverse of above. */
function offsetIn(block: HTMLElement, container: Node, offset: number): number {
  let count = 0, done = false;
  const walk = (n: Node): void => {
    if (done) return;
    if (n === container && n.nodeType !== 3) {
      for (let i = 0; i < offset && i < n.childNodes.length; i++) walk(n.childNodes[i]);
      done = true; return;
    }
    if (n.nodeType === 3) {
      if (n === container) { count += Math.min(offset, n.nodeValue!.length); done = true; return; }
      count += n.nodeValue!.length; return;
    }
    if (n.nodeType === 1 && isNoteAtom(n as Element)) return;
    for (const c of Array.from(n.childNodes)) { walk(c); if (done) return; }
  };
  for (const c of Array.from(block.childNodes)) { walk(c); if (done) break; }
  return count;
}

const blockEl = (paper: HTMLElement, id: string) =>
  paper.querySelector<HTMLElement>(`[data-id="${CSS.escape(id)}"]`);

function rangeFor(paper: HTMLElement, th: CommentThread): Range | null {
  const el = blockEl(paper, th.block);
  if (!el) return null;
  const a = pointAt(el, th.from), b = pointAt(el, th.to);
  if (!a || !b) return null;
  const r = document.createRange();
  try { r.setStart(a.node, a.offset); r.setEnd(b.node, b.offset); } catch { return null; }
  return r;
}

/**
 * Paint highlights and margin cards into the overlay.
 *
 * Its own layer, a sibling of `.t-deco` — because `drawPages` calls
 * `deco.replaceChildren()` on every repagination and would wipe anything this
 * module put there. The layer is `pointer-events:none` with only the cards
 * interactive, so a highlight can never swallow a click meant for the text.
 */
function paintLayer(ctx: FeatureContext): void {
  const paper = ctx.editor.host;
  const wrap = paper.parentElement;
  if (!wrap) return;
  if (!layer || layer.parentElement !== wrap) {
    layer = document.createElement('div');
    layer.className = 't-cmt-layer';
    // never captured by a save: the file carries doc.comments, not their pixels
    layer.setAttribute('data-bento-transient', '');
    wrap.appendChild(layer);
  }
  layer.replaceChildren();

  const threads = orderThreads(readThreads(ctx.store.doc), ctx.store.doc.body)
    .filter(th => !th.orphan);
  if (!threads.length) return;

  const top0 = paper.getBoundingClientRect().top;
  const left0 = paper.getBoundingClientRect().left;
  const frag = document.createDocumentFragment();

  // The gutter is shared with footnote sidenotes, which paginate.ts has already
  // stacked. Start below whatever is there and keep stacking, so a note and a
  // comment beside the same line never land on top of each other.
  const occupied: Array<[number, number]> = [];
  const deco = wrap.querySelector('.t-deco');
  if (deco) for (const n of Array.from(deco.querySelectorAll<HTMLElement>('.sidenote'))) {
    const y = parseFloat(n.style.top || '0');
    occupied.push([y, y + n.getBoundingClientRect().height]);
  }
  let lastBottom = -1e9;

  for (const th of threads) {
    const r = rangeFor(paper, th);
    if (!r) continue;
    const rects = Array.from(r.getClientRects()).filter(x => x.width > 0 && x.height > 0);
    if (!rects.length) continue;

    for (const rect of rects) {
      const hl = document.createElement('div');
      hl.className = 't-cmt-hl' + (th.resolved ? ' done' : '') + (th.id === selected ? ' on' : '');
      hl.style.top = `${rect.top - top0}px`;
      hl.style.left = `${rect.left - left0}px`;
      hl.style.width = `${rect.width}px`;
      hl.style.height = `${rect.height}px`;
      frag.appendChild(hl);
    }

    const card = buildCard(ctx, th);
    frag.appendChild(card);
    layer.appendChild(card);                       // measured after insertion
    let y = rects[0].top - top0 - 2;
    for (const [a, b] of occupied) if (y < b && y + 10 > a) y = b + 8;
    y = Math.max(y, lastBottom + 8);
    card.style.top = `${y}px`;
    lastBottom = y + card.getBoundingClientRect().height;
  }
  layer.prepend(frag);
}

/**
 * One message, in the shape both the margin card and the panel use.
 *
 * Edit/delete are gated by NAME, not identity — this document has no notion
 * of who is typing beyond the self-asserted `bento-author` value, so "is this
 * yours" is "does the byline match what's in localStorage right now", the
 * same honour-system comparison editor.ts already trusts for attributing a
 * tracked change. Anyone can rename themselves to someone else's name and
 * edit their comments; that is true of `authorName()` everywhere else in this
 * file too, and is not something a margin-card button could fix.
 */
function buildMessage(ctx: FeatureContext, th: CommentThread, m: CommentMsg, cls: string, suffix = ''): HTMLElement {
  const wrap = document.createElement('div');
  wrap.className = cls;
  const editing = editingMsg === m.id;

  const who = document.createElement('div');
  who.className = 'who';
  who.textContent = `${m.author} · ${when(m.at)}${suffix}`;

  const me = knownAuthor();
  if (me && m.author === me && !editing) {
    const tools = document.createElement('span');
    tools.className = 't-cmt-msgtools';
    const editBtn = document.createElement('button');
    editBtn.type = 'button';
    editBtn.className = 't-cmt-msgbtn';
    editBtn.textContent = t('Edit');
    editBtn.title = t('Edit your comment');
    editBtn.addEventListener('click', () => { editingMsg = m.id; repaint?.(); refreshPanel?.(); });
    const delBtn = document.createElement('button');
    delBtn.type = 'button';
    delBtn.className = 't-cmt-msgbtn';
    delBtn.textContent = t('Delete');
    delBtn.title = th.messages.length > 1 ? t('Delete your comment') : t('Delete this thread');
    delBtn.addEventListener('click', () => {
      const question = th.messages.length > 1
        ? t('Delete this comment?') : t('Delete this whole thread?');
      if (!confirm(question)) return;
      mutateThread(ctx, th.id, cur => deleteMessage(cur, m.id));
    });
    tools.append(editBtn, delBtn);
    who.appendChild(tools);
  }
  wrap.appendChild(who);

  if (editing) {
    const ta = document.createElement('textarea');
    ta.className = 't-cmt-edit';
    ta.rows = 2;
    ta.value = m.text;
    const row = document.createElement('div');
    row.className = 'btns';
    const save = document.createElement('button');
    save.type = 'button';
    save.textContent = t('Save');
    save.addEventListener('click', () => {
      const text = ta.value.trim();
      if (!text) return;
      editingMsg = null;
      mutateThread(ctx, th.id, cur => editMessage(cur, m.id, text));
    });
    const cancel = document.createElement('button');
    cancel.type = 'button';
    cancel.textContent = t('Cancel');
    cancel.addEventListener('click', () => { editingMsg = null; repaint?.(); refreshPanel?.(); });
    row.append(save, cancel);
    wrap.append(ta, row);
    return wrap;
  }

  const what = document.createElement('div');
  what.className = 'what';
  what.textContent = m.text;
  wrap.appendChild(what);
  return wrap;
}

/** One margin card. Expanded — replies, a reply box, resolve — when selected. */
function buildCard(ctx: FeatureContext, th: CommentThread): HTMLElement {
  const card = document.createElement('div');
  card.className = 't-cmt-card' + (th.resolved ? ' done' : '') + (th.id === selected ? ' on' : '');
  card.dataset.thread = th.id;
  const open = th.id === selected;
  const msgs = open ? th.messages : th.messages.slice(0, 1);
  const more = th.messages.length - msgs.length;
  for (const m of msgs) card.appendChild(buildMessage(ctx, th, m, 'msg'));
  if (more > 0) {
    const rest = document.createElement('div');
    rest.className = 'who';
    rest.textContent = t('{n} more', { n: String(more) });
    card.appendChild(rest);
  }
  card.addEventListener('mousedown', e => {
    // not `click`: mousedown beats the selection change, so opening a card
    // cannot be mistaken for the author clicking into the paper
    if ((e.target as HTMLElement).closest('button, textarea')) return;
    e.preventDefault();
    select(ctx, th.id === selected ? null : th.id);
  });
  if (open) card.appendChild(threadActions(ctx, th));
  return card;
}

/** Reply box + resolve toggle, shared by the margin card and the panel. */
function threadActions(ctx: FeatureContext, th: CommentThread): HTMLElement {
  const box = document.createElement('div');
  box.className = 'acts';
  const input = document.createElement('textarea');
  input.rows = 2;
  input.placeholder = t('Reply…');
  const row = document.createElement('div');
  row.className = 'btns';
  const send = document.createElement('button');
  send.type = 'button';
  send.textContent = t('Reply');
  send.addEventListener('click', () => {
    const text = input.value.trim();
    if (!text) return;
    mutateThread(ctx, th.id, cur => addReply(cur, authorName(), text));
    input.value = '';
  });
  const res = document.createElement('button');
  res.type = 'button';
  res.textContent = th.resolved ? t('Reopen') : t('Resolve');
  res.addEventListener('click', () => mutateThread(ctx, th.id, cur => setResolved(cur, !cur.resolved)));
  row.append(send, res);
  box.append(input, row);
  return box;
}

/**
 * Change one thread and commit it, or DELETE it when `fn` returns null —
 * deleting the last message in it. Whole-doc scope: comments are doc-level.
 *
 * A deleted thread leaves nothing behind to clean up: `paintLayer` and the
 * panel both rebuild their contents from `readThreads(ctx.store.doc)` on
 * every commit (via the `store.on` subscription below), so a thread that is
 * no longer in the map is simply not painted — there is no separate
 * highlight or marker element to remember to remove.
 */
function mutateThread(ctx: FeatureContext, id: string, fn: (th: CommentThread) => CommentThread | null): void {
  ctx.store.commit(d => {
    // raw: a reply/edit/delete must not silently write back the read-time repair
    const threads = readThreadsRaw(d);
    const i = threads.findIndex(x => x.id === id);
    if (i < 0) return;
    const next = fn(threads[i]);
    if (next === null) {
      threads.splice(i, 1);
      if (selected === id) selected = null;
    } else {
      threads[i] = next;
    }
    writeThreads(d, threads);
  });
}

function select(ctx: FeatureContext, id: string | null): void {
  selected = id;
  repaint?.();
  refreshPanel?.();
  if (!id) return;
  const th = readThreads(ctx.store.doc).find(x => x.id === id);
  if (!th || th.orphan) return;
  const el = blockEl(ctx.editor.host, th.block);
  el?.scrollIntoView({ block: 'center', behavior: 'smooth' });
}

// ─────────────────────────────────────────────────────────────── the feature

/** Comment on the current selection. */
function addComment(ctx: FeatureContext): void {
  const c = ctx.editor.caret();
  if (!c || c.to === undefined || c.to === c.at) {
    ctx.toast(t('Select some text first, then comment on it'));
    return;
  }
  const from = Math.min(c.at, c.to), to = Math.max(c.at, c.to);
  const blk = ctx.store.block(c.id);
  if (!blk) return;
  const who = authorName();
  const text = typeof prompt === 'function'
    ? (prompt(t('Comment on “{quote}”', { quote: blk.text.slice(from, to).slice(0, 60) })) ?? '').trim()
    : '';
  if (!text) return;
  const th = newThread(blk, from, to, who, text);
  ctx.store.commit(d => { writeThreads(d, [...readThreadsRaw(d), th]); });
  selected = th.id;
  ctx.refresh();
}

registerTool({
  id: 'comment',
  icon: COMMENT_ICON,
  get title() { return t('Comment on the selected text (⌘⇧M)'); },
  group: 'review',
  order: 10,
  run: addComment,
});

registerKey({ key: 'm', mod: true, shift: true, run: addComment });

registerPanel({
  id: 'comments',
  get label() { return t('Comments'); },
  // a SECTION of the Review tab: comments are one of the things people did to
  // this document, alongside tracked changes and signatures
  host: 'commentsHost',
  order: 20,
  mount(host, ctx) {
    const render = () => {
      const threads = orderThreads(readThreads(ctx.store.doc), ctx.store.doc.body);
      const open = unresolvedCount(threads);

      // The count lives HERE and not on the tab. Putting it on the tab was the
      // first version and it wrapped "Comments 1" onto two lines — four tabs
      // share a 250px sidebar — which made the whole tab row grow taller the
      // moment a document had a comment, jogging the panel below it. A count
      // that reflows the chrome it lives in is not worth the glance it saves.

      host.replaceChildren();
      if (!threads.length) {
        const hint = document.createElement('div');
        hint.className = 't-hint';
        hint.textContent = t('Select some text and press ⌘⇧M to comment on it.');
        host.appendChild(hint);
        return;
      }
      const count = document.createElement('div');
      count.className = 't-hint';
      count.textContent = open
        ? t('{open} open of {all}', { open: String(open), all: String(threads.length) })
        : t('All {all} resolved', { all: String(threads.length) });
      host.appendChild(count);

      for (const th of threads) {
        const card = document.createElement('div');
        card.className = 't-card t-cmt-item' + (th.resolved ? ' done' : '')
                       + (th.id === selected ? ' on' : '');
        const first = th.messages[0];
        const repliesSuffix = th.messages.length > 1
          ? ` · ${t('{n} replies', { n: String(th.messages.length - 1) })}` : '';
        const firstEl = buildMessage(ctx, th, first, 'msg', repliesSuffix);
        // splice the quote between the byline and the body — the reading order
        // is "who said it, about what, saying what" — by inserting it right
        // after the who-line buildMessage always puts first.
        const quote = document.createElement('div');
        quote.className = 'quote' + (th.orphan ? ' gone' : '');
        quote.textContent = th.quote;
        firstEl.insertBefore(quote, firstEl.firstElementChild!.nextSibling);
        card.appendChild(firstEl);
        if (th.orphan) {
          const gone = document.createElement('div');
          gone.className = 'who';
          gone.textContent = t('the text this was about is gone');
          card.appendChild(gone);
        }
        card.addEventListener('click', e => {
          if ((e.target as HTMLElement).closest('.acts, button, textarea')) return;
          select(ctx, th.id === selected ? null : th.id);
        });
        if (th.id === selected) {
          for (const m of th.messages.slice(1)) card.appendChild(buildMessage(ctx, th, m, 'reply'));
          card.appendChild(threadActions(ctx, th));
        }
        host.appendChild(card);
      }
    };

    refreshPanel = render;
    repaint = () => paintLayer(ctx);
    render();

    // Own repaints, because main.ts never calls PanelSpec.update — see (E).
    // The store fires on every commit; the observer catches the editor's
    // re-renders and pagination's reflows, which move the geometry without
    // changing the document.
    let beat: number | undefined;
    const soon = () => {
      clearTimeout(beat);
      beat = setTimeout(() => { render(); paintLayer(ctx); }, 60) as unknown as number;
    };
    ctx.store.on(soon);
    new MutationObserver(soon).observe(ctx.editor.host, { childList: true, subtree: true, characterData: true });
    window.addEventListener('resize', soon);

    // Clicking a commented range focuses its comment — the other half of
    // "clicking a comment scrolls to the range". Capture-phase and read-only:
    // it never touches the selection the author is making.
    ctx.editor.host.addEventListener('click', () => {
      const sel = getSelection();
      if (!sel || !sel.rangeCount) return;
      const r = sel.getRangeAt(0);
      if (!sel.isCollapsed || !ctx.editor.host.contains(r.startContainer)) return;
      let n: Node | null = r.startContainer;
      while (n && n !== ctx.editor.host && !(n.nodeType === 1 && (n as HTMLElement).dataset?.id)) n = n.parentNode;
      if (!n || n === ctx.editor.host) return;
      const el = n as HTMLElement;
      const at = offsetIn(el, r.startContainer, r.startOffset);
      const hit = orderThreads(readThreads(ctx.store.doc), ctx.store.doc.body)
        .find(th => !th.orphan && th.block === el.dataset.id && at >= th.from && at <= th.to);
      if (hit) select(ctx, hit.id);
    });

    setTimeout(() => paintLayer(ctx), 120);
  },
  update(_host, ctx) { refreshPanel?.(); paintLayer(ctx); },
});

// ─────────────────────────────────────────────────────── showing and hiding
//
// A VIEWER preference, kept beside the theme rather than in the document: it is
// about reading this file today, not about the file. Two people opening the
// same document disagree about whether they want the margin full of review,
// and neither answer belongs in bytes they both sign.
//
// It hides the APPARATUS — highlights and cards — and never the text, and it
// changes nothing in `doc.comments`, so a hidden thread is still saved, still
// exported, and still there when it is turned back on.

const HIDE_KEY = 'bento-type-hide-comments';

export const commentsHidden = (): boolean => {
  try { return localStorage.getItem(HIDE_KEY) === '1'; } catch { return false; }
};

export function setCommentsHidden(on: boolean): void {
  try { on ? localStorage.setItem(HIDE_KEY, '1') : localStorage.removeItem(HIDE_KEY); }
  catch { /* storage blocked — the class below still applies for this session */ }
  document.documentElement.classList.toggle('t-hide-comments', on);
}

/** Apply the remembered choice at boot. */
export const applyCommentVisibility = (): void => {
  document.documentElement.classList.toggle('t-hide-comments', commentsHidden());
};

registerMenuItem({
  id: 'comments-visibility',
  get label() { return commentsHidden() ? t('Show comments') : t('Hide comments'); },
  order: 15,
  run(ctx) {
    setCommentsHidden(!commentsHidden());
    ctx.refresh();
    ctx.toast(commentsHidden() ? t('Comments hidden') : t('Comments shown'));
  },
});

// the remembered choice, applied once the app exists
registerReady(() => applyCommentVisibility());