@shiyuphan/follow-me 0.1.1 → 0.2.0

package/dist/ui/concerns.js

@@ -0,0 +1,165 @@
+// @ts-check
+// Pure logic for the agent's concerns: which are still undecided, where each one sits among the
+// lines, when playback stops for one and how long a chunk lingers for it. No DOM, no fetch.
+
+import { readMs } from "./playback.js";
+
+/**
+ * @typedef {"blocker" | "major" | "minor"} Severity
+ * @typedef {{ id: string, severity: Severity, kind: string, text: string, lines?: number[],
+ *   unit?: string }} Concern
+ * @typedef {{ concern: string, decision: "kept" | "dismissed", severity?: Severity,
+ *   note?: string }} Decision
+ * @typedef {{ index: number, concerns?: Concern[] }} CommitConcerns
+ * @typedef {{ op: string, change?: number }} BodyLine
+ * @typedef {{ kind: string, commit: number, unit?: string, lines?: number[] }} Beat
+ */
+
+export const SEVERITIES = /** @type {const} */ (["blocker", "major", "minor"]);
+
+/**
+ * The severity in force: the reviewer's override when they kept it with one, else the agent's.
+ * @param {Concern} concern
+ * @param {Readonly<Record<string, Decision>>} decisions
+ * @returns {Severity}
+ */
+export function severityOf(concern, decisions) {
+  return decisions[concern.id]?.severity ?? concern.severity;
+}
+
+/**
+ * @param {Concern} concern
+ * @param {Readonly<Record<string, Decision>>} decisions
+ * @returns {"undecided" | "kept" | "dismissed"}
+ */
+export function stateOf(concern, decisions) {
+  return decisions[concern.id]?.decision ?? "undecided";
+}
+
+/**
+ * Every concern of the plan in commit order.
+ * @param {readonly CommitConcerns[]} commits
+ * @returns {Concern[]}
+ */
+export function allConcerns(commits) {
+  return commits.flatMap((c) => c.concerns ?? []);
+}
+
+/**
+ * Concerns the reviewer has not decided.
+ * @param {readonly Concern[]} concerns
+ * @param {Readonly<Record<string, Decision>>} decisions
+ */
+export function undecided(concerns, decisions) {
+  return concerns.filter((c) => stateOf(c, decisions) === "undecided");
+}
+
+/**
+ * The most severe of some concerns, or null for none.
+ * @param {readonly Concern[]} concerns
+ * @param {Readonly<Record<string, Decision>>} decisions
+ * @returns {Severity | null}
+ */
+export function topSeverity(concerns, decisions) {
+  const found = new Set(concerns.map((c) => severityOf(c, decisions)));
+  return SEVERITIES.find((s) => found.has(s)) ?? null;
+}
+
+/**
+ * Body index of each change line asked for, skipping any the unit does not have.
+ * @param {readonly BodyLine[]} body
+ * @param {readonly number[]} changes
+ */
+export function bodyIndexes(body, changes) {
+  const wanted = new Set(changes);
+  return body.flatMap((line, i) =>
+    line.op !== " " && line.change !== undefined && wanted.has(line.change) ? [i] : [],
+  );
+}
+
+/**
+ * The body line a concern's card sits under: below its last pinned line, else below the last
+ * line the commit changes in the unit. null when the commit shows none.
+ * @param {Concern} concern
+ * @param {readonly BodyLine[]} body
+ * @param {readonly number[]} own body indexes of the commit's own lines in the unit
+ */
+export function anchorLine(concern, body, own) {
+  const pinned = bodyIndexes(body, concern.lines ?? []).filter((i) => own.includes(i));
+  return pinned.at(-1) ?? own.at(-1) ?? null;
+}
+
+/**
+ * The concerns that belong to a chunk: those whose pinned lines it holds, and unpinned ones on
+ * the first chunk of their unit.
+ * @param {readonly Concern[]} concerns the commit's
+ * @param {readonly Beat[]} beats
+ * @param {number} index the chunk's beat
+ * @param {readonly BodyLine[]} body of the chunk's unit
+ */
+export function concernsInChunk(concerns, beats, index, body) {
+  const beat = beats[index];
+  if (beat?.kind !== "chunk") return [];
+  const first = beats.findIndex(
+    (b) => b.kind === "chunk" && b.commit === beat.commit && b.unit === beat.unit,
+  );
+  const held = new Set(beat.lines ?? []);
+  return concerns.filter((c) => {
+    if (c.unit !== beat.unit) return false;
+    if (c.lines === undefined || c.lines.length === 0) return first === index;
+    return bodyIndexes(body, c.lines).some((i) => held.has(i));
+  });
+}
+
+/**
+ * The concern y and x act on: the first undecided one of the chunk on screen, else of the commit.
+ * @param {readonly Concern[]} commitConcerns
+ * @param {readonly Concern[]} chunkConcerns
+ * @param {Readonly<Record<string, Decision>>} decisions
+ */
+export function pickConcern(commitConcerns, chunkConcerns, decisions) {
+  return undecided(chunkConcerns, decisions)[0] ?? undecided(commitConcerns, decisions)[0] ?? null;
+}
+
+/**
+ * Undecided blockers to stop on, at the step that reveals their chunk, once each.
+ * @param {readonly Concern[]} inChunk
+ * @param {{ kind: string } | undefined} step
+ * @param {Readonly<Record<string, Decision>>} decisions
+ * @param {ReadonlySet<string>} seen
+ */
+export function blockersToHold(inChunk, step, decisions, seen) {
+  if (step?.kind !== "show") return [];
+  return undecided(inChunk, decisions).filter(
+    (c) => severityOf(c, decisions) === "blocker" && !seen.has(c.id),
+  );
+}
+
+/**
+ * Extra milliseconds a chunk lingers so its undecided major and minor concerns can be read.
+ * Blockers pause playback instead.
+ * @param {readonly Concern[]} inChunk
+ * @param {Readonly<Record<string, Decision>>} decisions
+ * @param {number} speed
+ */
+export function dwellExtra(inChunk, decisions, speed) {
+  return undecided(inChunk, decisions)
+    .filter((c) => severityOf(c, decisions) !== "blocker")
+    .reduce((sum, c) => sum + Math.round(readMs(c.text) / speed), 0);
+}
+
+/**
+ * The question asked when the review ends with concerns undecided.
+ * @param {number} count
+ */
+export function undecidedPrompt(count) {
+  return `${count} agent concern${count === 1 ? "" : "s"} undecided. Undecided concerns are left out of the report.`;
+}
+
+/**
+ * The stage header's reminder, or null when nothing waits.
+ * @param {number} count
+ */
+export function toDecide(count) {
+  return count === 0 ? null : `${count} agent concern${count === 1 ? "" : "s"} to decide`;
+}

package/dist/ui/highlight.js

@@ -0,0 +1,221 @@
+// @ts-check
+// Pure syntax highlighting logic. The browser imports it from /highlight.js and the tests import
+// it directly, so nothing here may touch the DOM. Prism itself is injected as a tokenize function.
+
+/**
+ * @typedef {{ text: string, tone: string | null }} Span
+ * @typedef {{ type: string, content: unknown, alias?: string | string[] }} PrismToken
+ * @typedef {{ op: " " | "+" | "-", text: string }} BodyLine
+ */
+
+/** Prism language per file extension. Anything else is shown plain. */
+const BY_EXTENSION = new Map([
+  ["js", "javascript"],
+  ["mjs", "javascript"],
+  ["cjs", "javascript"],
+  ["jsx", "jsx"],
+  ["ts", "typescript"],
+  ["tsx", "tsx"],
+  ["json", "json"],
+  ["md", "markdown"],
+  ["css", "css"],
+  ["html", "markup"],
+  ["sh", "bash"],
+  ["bash", "bash"],
+  ["py", "python"],
+  ["go", "go"],
+  ["rs", "rust"],
+  ["rb", "ruby"],
+  ["java", "java"],
+  ["kt", "kotlin"],
+  ["c", "c"],
+  ["cpp", "cpp"],
+  ["h", "c"],
+  ["yaml", "yaml"],
+  ["yml", "yaml"],
+  ["toml", "toml"],
+  ["sql", "sql"],
+  ["swift", "swift"],
+  ["php", "php"],
+]);
+
+/**
+ * Prism components to load for a language, dependencies first. html also takes the script and
+ * style grammars so inline code in a page is coloured.
+ */
+const COMPONENTS = new Map([
+  ["javascript", ["clike", "javascript"]],
+  ["jsx", ["markup", "clike", "javascript", "jsx"]],
+  ["typescript", ["clike", "javascript", "typescript"]],
+  ["tsx", ["markup", "clike", "javascript", "jsx", "typescript", "tsx"]],
+  ["json", ["json"]],
+  ["markdown", ["markup", "markdown"]],
+  ["css", ["css"]],
+  ["markup", ["markup", "clike", "javascript", "css"]],
+  ["bash", ["bash"]],
+  ["python", ["python"]],
+  ["go", ["clike", "go"]],
+  ["rust", ["rust"]],
+  ["ruby", ["clike", "ruby"]],
+  ["java", ["clike", "java"]],
+  ["kotlin", ["clike", "kotlin"]],
+  ["c", ["clike", "c"]],
+  ["cpp", ["clike", "c", "cpp"]],
+  ["yaml", ["yaml"]],
+  ["toml", ["toml"]],
+  ["sql", ["sql"]],
+  ["swift", ["swift"]],
+  ["php", ["markup", "markup-templating", "php"]],
+]);
+
+/**
+ * The Prism language for a repo path, or null when it should stay plain.
+ * @param {string} path
+ * @returns {string | null}
+ */
+export function languageFor(path) {
+  const name = path.slice(path.lastIndexOf("/") + 1);
+  const dot = name.lastIndexOf(".");
+  if (dot <= 0) return null;
+  return BY_EXTENSION.get(name.slice(dot + 1).toLowerCase()) ?? null;
+}
+
+/**
+ * Prism component names to load, in order, to highlight a language. Empty for an unknown one.
+ * @param {string} language
+ * @returns {readonly string[]}
+ */
+export function componentsFor(language) {
+  return COMPONENTS.get(language) ?? [];
+}
+
+/**
+ * Every component needed for a set of languages, each once, in an order that keeps dependencies
+ * first.
+ * @param {Iterable<string>} languages
+ */
+export function componentsForAll(languages) {
+  const seen = new Set();
+  for (const language of languages) for (const name of componentsFor(language)) seen.add(name);
+  // Each list is dependency ordered, and a Set keeps first insertion, so dependencies stay first.
+  return [...seen];
+}
+
+/** Prism token types, and aliases, grouped under the few tones the page colours. */
+const TONES = new Map([
+  ["comment", "comment"],
+  ["prolog", "comment"],
+  ["doctype", "comment"],
+  ["cdata", "comment"],
+  ["keyword", "keyword"],
+  ["atrule", "keyword"],
+  ["important", "keyword"],
+  ["string", "string"],
+  ["char", "string"],
+  ["attr-value", "string"],
+  ["template-string", "string"],
+  ["url", "string"],
+  ["regex", "string"],
+  ["number", "number"],
+  ["boolean", "number"],
+  ["constant", "number"],
+  ["symbol", "number"],
+  ["unit", "number"],
+  ["function", "function"],
+  ["class-name", "type"],
+  ["builtin", "type"],
+  ["namespace", "type"],
+  ["property", "property"],
+  ["attr-name", "property"],
+  ["variable", "property"],
+  ["parameter", "property"],
+  ["tag", "tag"],
+  ["selector", "tag"],
+  ["entity", "tag"],
+]);
+
+/**
+ * The tone a run of text takes from its token types, innermost first. null leaves it plain.
+ * @param {readonly string[]} types
+ * @returns {string | null}
+ */
+export function toneOf(types) {
+  for (const type of types) {
+    const tone = TONES.get(type);
+    if (tone !== undefined) return tone;
+  }
+  return null;
+}
+
+/** @param {unknown} value @returns {value is PrismToken} */
+function isToken(value) {
+  return typeof value === "object" && value !== null && "type" in value && "content" in value;
+}
+
+/**
+ * @param {readonly unknown[]} stream
+ * @param {readonly string[]} inherited
+ * @param {{ text: string, types: readonly string[] }[]} out
+ */
+function walk(stream, inherited, out) {
+  for (const item of stream) {
+    if (typeof item === "string") out.push({ text: item, types: inherited });
+    else if (isToken(item)) {
+      const alias = item.alias === undefined ? [] : [item.alias].flat();
+      const types = [item.type, ...alias, ...inherited];
+      walk(Array.isArray(item.content) ? item.content : [item.content], types, out);
+    }
+  }
+}
+
+/**
+ * Splits a Prism token stream into lines of spans. Multi-line tokens, such as block comments,
+ * are cut at each newline so every line carries its own spans. Line ends are dropped.
+ * @param {readonly unknown[]} stream
+ * @returns {Span[][]}
+ */
+export function spansByLine(stream) {
+  /** @type {{ text: string, types: readonly string[] }[]} */
+  const pieces = [];
+  walk(stream, [], pieces);
+  /** @type {Span[][]} */
+  const lines = [[]];
+  for (const piece of pieces) {
+    const tone = toneOf(piece.types);
+    piece.text.split("\n").forEach((part, i) => {
+      if (i > 0) lines.push([]);
+      const line = lines[lines.length - 1];
+      if (line === undefined || part === "") return;
+      const last = line.at(-1);
+      if (last?.tone === tone) last.text += part;
+      else line.push({ text: part, tone });
+    });
+  }
+  return lines;
+}
+
+/**
+ * Highlights every line of a hunk body, or returns null when the tokens do not add up to the
+ * text, in which case the caller shows plain lines. The old side (context and removed lines) and
+ * the new side (context and added lines) are tokenized apart, so a removed line never changes
+ * how an added one reads. Context takes its colours from the new side.
+ * @param {readonly BodyLine[]} body
+ * @param {(text: string) => readonly unknown[]} tokenize
+ * @returns {Span[][] | null}
+ */
+export function highlightBody(body, tokenize) {
+  /** @param {(line: BodyLine) => boolean} keep */
+  const side = (keep) => {
+    const indexes = body.flatMap((line, i) => (keep(line) ? [i] : []));
+    const texts = indexes.map((i) => (body[i]?.text ?? "").replace(/\n$/, ""));
+    if (texts.length === 0) return new Map();
+    const lines = spansByLine(tokenize(texts.join("\n")));
+    if (lines.length !== texts.length) return null;
+    const ok = lines.every((spans, k) => spans.map((s) => s.text).join("") === texts[k]);
+    return ok ? new Map(indexes.map((i, k) => [i, lines[k] ?? []])) : null;
+  };
+  const before = side((line) => line.op !== "+");
+  const after = side((line) => line.op !== "-");
+  if (before === null || after === null) return null;
+  return body.map((line, i) => (line.op === "-" ? before.get(i) : after.get(i)) ?? []);
+}

package/dist/ui/index.html

@@ -18,23 +18,77 @@
       </button>
       <button id="end" type="button" class="primary">End review</button>
     </header>
+    <div id="banner" class="banner" role="status" hidden>
+      <span id="banner-text"></span>
+      <button id="banner-show" type="button" hidden>Show answers</button>
+      <button id="banner-close" type="button">Dismiss</button>
+    </div>
     <section id="player" class="player" aria-label="Playback" hidden>
-      <button id="play" type="button" class="primary" title="Play or pause (space)">Play</button>
-      <button id="prev" type="button" title="Previous commit (p)">Previous</button>
-      <button id="next" type="button" title="Next commit (n)">Next</button>
+      <button id="play" type="button" class="primary play" title="Play or pause (space)">
+        <span class="icon" aria-hidden="true"></span><span class="label"></span>
+      </button>
+      <fieldset class="steps" aria-label="Step">
+        <button id="prev-commit" type="button" title="Restart this commit, press again for the previous one (p)">⏮ Commit</button>
+        <button id="prev-beat" type="button" title="Previous chunk (left arrow)">◀ Chunk</button>
+        <button id="next-beat" type="button" title="Next chunk (right arrow)">Chunk ▶</button>
+        <button id="next-commit" type="button" title="Next commit (n)">Commit ⏭</button>
+      </fieldset>
       <label>Speed <select id="speed"></select></label>
-      <label>Voice <select id="voice"></select></label>
-      <button id="mute" type="button" aria-pressed="false">Mute</button>
-      <p id="caption" class="caption" aria-live="polite"></p>
+      <label id="voice-label">Voice <select id="voice"></select></label>
+      <button id="mute" type="button" aria-pressed="false" title="Mute (m)">Mute</button>
+      <button id="keys-button" type="button" title="Keyboard shortcuts (?)" aria-label="Keyboard shortcuts">?</button>
+      <fieldset id="strip" class="strip" aria-label="Progress"></fieldset>
     </section>
     <div id="app" class="layout">
-      <nav class="sidebar" aria-label="Commits">
+      <nav id="sidebar" class="sidebar" aria-label="Commits">
+        <button id="commits-toggle" type="button" class="commits-toggle" aria-expanded="false" aria-controls="commits">
+          Commits
+        </button>
         <ol id="commits" class="commit-list"></ol>
+        <section id="answers" class="answers" aria-label="Answers" hidden></section>
         <section id="plan-note" class="plan-note"></section>
       </nav>
       <main id="main" class="main"></main>
+      <aside id="diagram" class="diagram-panel" aria-label="Diagram" hidden>
+        <div class="diagram-head">
+          <button id="diagram-toggle" type="button" aria-expanded="true" aria-controls="diagram-body">
+            Diagram
+          </button>
+          <span id="diagram-from" class="muted"></span>
+        </div>
+        <div id="diagram-body" class="diagram-body"></div>
+      </aside>
     </div>
+    <div id="rail-tip" class="rail-tip" role="tooltip" hidden></div>
     <div id="done" class="done" hidden></div>
+    <dialog id="confirm-end" class="keys" aria-labelledby="confirm-title">
+      <h2 id="confirm-title">End this review?</h2>
+      <p id="confirm-text"></p>
+      <form method="dialog" class="row">
+        <button id="confirm-ok" type="submit" value="end" class="primary">End review</button>
+        <button id="confirm-keep-all" type="submit" value="keep-all" hidden>Keep all</button>
+        <button id="confirm-dismiss-all" type="submit" value="dismiss-all" hidden>Dismiss all</button>
+        <button id="confirm-back" type="submit" value="back">Keep reviewing</button>
+      </form>
+    </dialog>
+    <dialog id="keys" class="keys" aria-labelledby="keys-title">
+      <h2 id="keys-title">Keyboard shortcuts</h2>
+      <dl>
+        <dt><kbd>Space</kbd></dt><dd>Play or pause</dd>
+        <dt><kbd>→</kbd> <kbd>l</kbd></dt><dd>Next chunk</dd>
+        <dt><kbd>←</kbd> <kbd>h</kbd></dt><dd>Previous chunk</dd>
+        <dt><kbd>n</kbd> <kbd>j</kbd> <kbd>Shift →</kbd></dt><dd>Next commit</dd>
+        <dt><kbd>p</kbd> <kbd>k</kbd> <kbd>Shift ←</kbd></dt><dd>Restart this commit, twice for the previous one</dd>
+        <dt><kbd>r</kbd></dt><dd>Replay the narration</dd>
+        <dt><kbd>c</kbd></dt><dd>Request a change on the current chunk</dd>
+        <dt><kbd>q</kbd></dt><dd>Ask a question about the current chunk</dd>
+        <dt><kbd>y</kbd></dt><dd>Keep the agent's concern on this chunk</dd>
+        <dt><kbd>x</kbd></dt><dd>Dismiss it</dd>
+        <dt><kbd>m</kbd></dt><dd>Mute</dd>
+        <dt><kbd>⌘ Enter</kbd></dt><dd>Save a comment, <kbd>Esc</kbd> cancels</dd>
+      </dl>
+      <form method="dialog"><button type="submit">Close</button></form>
+    </dialog>
     <script src="/app.js" type="module"></script>
   </body>
 </html>

package/dist/ui/live.js

@@ -0,0 +1,184 @@
+// @ts-check
+// Pure logic for live updates: folding server events into the page state, deciding which commit
+// to stay on across a plan swap, and the reconnect delay. No DOM, no fetch.
+
+/**
+ * @typedef {{ id: string, author: string, body: string, diagram?: string, createdAt: string }} Reply
+ * @typedef {{ id: string, replies?: Reply[], kind?: string, body?: string }} LiveComment
+ * @typedef {{ concern: string, decision: "kept" | "dismissed", severity?: string, note?: string }} Decision
+ * @typedef {{ comments: LiveComment[], decisions?: Record<string, Decision>, resolved?: string[],
+ *   version: number, [key: string]: unknown }} LiveState
+ * @typedef {{ type: string, seq?: number, data?: unknown, [key: string]: unknown }} LiveEvent
+ * @typedef {null | "refetch" | "ended"} Effect
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is Reply} */
+function isReply(value) {
+  return isRecord(value) && typeof value["id"] === "string";
+}
+
+/** @param {unknown} value @returns {value is LiveComment} */
+function isComment(value) {
+  return (
+    isRecord(value) &&
+    typeof value["id"] === "string" &&
+    (value["replies"] === undefined || Array.isArray(value["replies"]))
+  );
+}
+
+/**
+ * The decisions the server stores as a list, keyed by concern id.
+ * @param {readonly Decision[]} list
+ * @returns {Record<string, Decision>}
+ */
+export function decisionsById(list) {
+  return Object.fromEntries(list.map((d) => [d.concern, d]));
+}
+
+/**
+ * An event's fields. The server may nest them under data or flatten them beside type.
+ * @param {LiveEvent} event
+ * @returns {Record<string, unknown>}
+ */
+function payload(event) {
+  return isRecord(event.data) ? event.data : event;
+}
+
+/**
+ * Inserts or replaces by id, keeping the position of an existing item. Replaying an event is
+ * therefore harmless, which matters because the first poll asks for everything.
+ * @template {{ id: string }} T
+ * @param {readonly T[]} list
+ * @param {T} item
+ * @returns {T[]}
+ */
+function upsert(list, item) {
+  const at = list.findIndex((x) => x.id === item.id);
+  if (at === -1) return [...list, item];
+  return list.map((x, i) => (i === at ? item : x));
+}
+
+/**
+ * Folds one server event into the page state. Returns a new state, and an effect the caller must
+ * carry out: "refetch" when a newer plan version arrived, "ended" when the review is over.
+ * @param {LiveState} state
+ * @param {LiveEvent} event
+ * @returns {{ state: LiveState, effect: Effect }}
+ */
+export function applyEvent(state, event) {
+  const body = payload(event);
+  switch (event.type) {
+    case "comment":
+    case "comment-updated": {
+      const comment = body["comment"] ?? body;
+      if (!isComment(comment)) return { state, effect: null };
+      const existing = state.comments.find((c) => c.id === comment.id);
+      // An update that omits the thread must not erase replies the page already holds.
+      const replies = comment.replies ?? existing?.replies;
+      const next = replies === undefined ? comment : { ...comment, replies };
+      return { state: { ...state, comments: upsert(state.comments, next) }, effect: null };
+    }
+    case "comment-deleted": {
+      const id = body["id"] ?? body["commentId"];
+      return {
+        state: { ...state, comments: state.comments.filter((c) => c.id !== id) },
+        effect: null,
+      };
+    }
+    case "reply": {
+      const reply = body["reply"];
+      const target = body["commentId"];
+      if (!isReply(reply)) return { state, effect: null };
+      const comments = state.comments.map((c) =>
+        c.id === target ? { ...c, replies: upsert(c.replies ?? [], reply) } : c,
+      );
+      return { state: { ...state, comments }, effect: null };
+    }
+    case "concern": {
+      const id = body["concernId"];
+      const verdict = body["decision"];
+      if (typeof id !== "string" || (verdict !== "kept" && verdict !== "dismissed")) {
+        return { state, effect: null };
+      }
+      /** @type {Decision} */
+      const decision = { concern: id, decision: verdict };
+      if (typeof body["severity"] === "string") decision.severity = body["severity"];
+      if (typeof body["note"] === "string") decision.note = body["note"];
+      return {
+        state: { ...state, decisions: { ...state.decisions, [id]: decision } },
+        effect: null,
+      };
+    }
+    case "resolved": {
+      const id = body["commentId"];
+      if (typeof id !== "string" || typeof body["resolved"] !== "boolean") {
+        return { state, effect: null };
+      }
+      const others = (state.resolved ?? []).filter((x) => x !== id);
+      return {
+        state: { ...state, resolved: body["resolved"] ? [...others, id] : others },
+        effect: null,
+      };
+    }
+    case "version": {
+      const version = body["version"];
+      const newer = typeof version === "number" && version > state.version;
+      return { state, effect: newer ? "refetch" : null };
+    }
+    case "ended":
+      return { state, effect: "ended" };
+    default:
+      return { state, effect: null };
+  }
+}
+
+/**
+ * The seq to ask for next: the highest the server reported, never going backwards.
+ * @param {number} since
+ * @param {{ seq?: unknown, events?: readonly LiveEvent[] }} reply
+ */
+export function nextSince(since, reply) {
+  const seqs = (reply.events ?? []).map((e) => e.seq).filter((n) => typeof n === "number");
+  const reported = typeof reply.seq === "number" ? reply.seq : 0;
+  return Math.max(since, reported, ...seqs);
+}
+
+const BACKOFF_FIRST_MS = 500;
+const BACKOFF_MAX_MS = 15_000;
+
+/**
+ * How long to wait before reconnecting after the given number of failures in a row.
+ * @param {number} failures at least 1
+ */
+export function backoffMs(failures) {
+  return Math.min(BACKOFF_MAX_MS, BACKOFF_FIRST_MS * 2 ** Math.max(0, failures - 1));
+}
+
+/**
+ * The commit to stay on after a plan swap: the one with the same title, nearest the old index
+ * when titles repeat. Falls back to the first commit when it no longer exists.
+ * @param {string | null} title first line of the commit on screen
+ * @param {number} index its old position
+ * @param {readonly { message: string }[]} commits
+ */
+export function keepCommit(title, index, commits) {
+  if (title === null) return 0;
+  const same = commits.flatMap((c, i) => (c.message.split("\n")[0] === title ? [i] : []));
+  if (same.length === 0) return 0;
+  return same.reduce((best, i) => (Math.abs(i - index) < Math.abs(best - index) ? i : best));
+}
+
+/**
+ * The banner for a new plan version: "Plan v6 arrived, 3 questions answered".
+ * @param {number} version
+ * @param {number} answered
+ */
+export function bannerText(version, answered) {
+  const tail = answered === 0 ? "" : `, ${answered} question${answered === 1 ? "" : "s"} answered`;
+  return `Plan v${version} arrived${tail}`;
+}