@shiyuphan/follow-me 0.1.0 → 0.2.0

package/dist/ui/app.js

@@ -1,18 +1,62 @@
 import {
+  allConcerns,
+  anchorLine,
+  blockersToHold,
+  bodyIndexes,
+  concernsInChunk,
+  dwellExtra,
+  pickConcern,
+  SEVERITIES,
+  severityOf,
+  toDecide,
+  topSeverity,
+  undecided,
+  undecidedPrompt,
+} from "/concerns.js";
+import { componentsForAll, highlightBody, languageFor } from "/highlight.js";
+import { applyEvent, backoffMs, bannerText, decisionsById, keepCommit, nextSince } from "/live.js";
+import {
+  beatAt,
+  beatStart,
   buildScript,
-  commitAt,
-  commitStart,
+  chunkOf,
+  commitOf,
+  describeLines,
+  diagramAt,
+  duration,
+  hasDiagrams,
+  hasNarration,
+  introOf,
   lineKey,
+  lineNumbers,
   lineStates,
   parseSpeed,
   pickVoice,
+  progress,
+  rowsOf,
   SPEEDS,
+  schedule,
+  scopeOf,
+  speechRate,
   speechTimeout,
-  stepDelay,
 } from "/playback.js";
+import {
+  answerCards,
+  answeredCount,
+  askAgain,
+  cardsAt,
+  holdAt,
+  inferKind,
+  kindCounts,
+  statusLine,
+} from "/questions.js";
+import { endSummary, reportPath } from "/summary.js";
 
 const $ = (id) => document.getElementById(id);
 
+/** "/s/<id>": this page's session on the shared server. Every session API sits under it. */
+const sessionPrefix = /^\/s\/[^/]+/.exec(location.pathname)?.[0] ?? "";
+
 /** Builds an element. Text always goes through textContent, never innerHTML. */
 function el(tag, props = {}, ...children) {
   const node = document.createElement(tag);
@@ -30,28 +74,125 @@ function el(tag, props = {}, ...children) {
 let state = null;
 let selected = 0;
 let unitsById = new Map();
+/** unit id -> per hunk line, its { old, new } file line numbers */
+let numbers = new Map();
 /** unit id -> (change index -> index of the commit that owns the line) */
 let owners = new Map();
-/** "commit:unit" -> change indices the reader clicked, to anchor a comment to them */
-const picks = new Map();
+/**
+ * The lines picked for a comment: a contiguous run of one commit's own lines in one unit, as hunk
+ * body indices. from is where a shift-click range starts.
+ */
+let selection = null;
+/** The comment box to focus after the next render. */
+let focusKey = null;
 /** Unsent textarea contents survive re-renders, keyed like the boxes. */
 const drafts = new Map();
 const openBoxes = new Set();
 const editing = new Set();
+/** key -> the kind picked for the box, and whether the reviewer chose it or the text implied it. */
+const kindDrafts = new Map();
+/** Answers shown or paused on, so a replay does not stop again. */
+const seenAnswers = new Set();
+/** Blockers playback already stopped on. */
+const seenBlockers = new Set();
+/** The previous version's questions with where they now sit, refreshed on every render. */
+let cards = [];
+
+/** Component scripts already requested, so a language shared by two files loads once. */
+const scripts = new Map();
+
+function loadScript(name) {
+  if (!scripts.has(name)) {
+    scripts.set(
+      name,
+      new Promise((resolve, reject) => {
+        const node = el("script", { src: `/vendor/prism/${name}.js` });
+        node.addEventListener("load", resolve);
+        node.addEventListener("error", () => reject(new Error(`Prism ${name} did not load`)));
+        document.head.append(node);
+      }),
+    );
+  }
+  return scripts.get(name);
+}
+
+/**
+ * Loads Prism and the grammars for the plan's files, and only those. Without a known language
+ * nothing is fetched. A failed load leaves the code plain, which is still a complete review.
+ */
+async function loadHighlighting(units) {
+  const languages = new Set(
+    units.flatMap((u) => (u.kind === "hunk" ? [languageFor(u.path)] : [])).filter(Boolean),
+  );
+  const names = componentsForAll(languages);
+  if (names.length === 0) return;
+  try {
+    // Prism reads this before it runs, and then waits to be called instead of scanning the page.
+    window.Prism ??= { manual: true };
+    await loadScript("core");
+    for (const name of names) await loadScript(name);
+  } catch {
+    // Plain code is the fallback.
+  }
+}
 
-async function api(method, path, body) {
-  const res = await fetch(path, {
+/** unit id -> its lines as coloured spans, or null when the file stays plain. */
+const highlighted = new Map();
+
+function spansOf(unit) {
+  if (!highlighted.has(unit.id)) {
+    const grammar = window.Prism?.languages?.[languageFor(unit.path)];
+    highlighted.set(
+      unit.id,
+      grammar ? highlightBody(unit.body, (text) => window.Prism.tokenize(text, grammar)) : null,
+    );
+  }
+  return highlighted.get(unit.id);
+}
+
+const RETRY_MS = 400;
+
+/** A write during a plan swap or an end answers 409; it is safe to repeat once a moment later. */
+async function api(method, path, body, retried = false) {
+  const res = await fetch(`${sessionPrefix}${path}`, {
     method,
     headers: { "content-type": "application/json" },
     body: body === undefined ? undefined : JSON.stringify(body),
   });
   const payload = await res.json().catch(() => ({}));
+  if (res.status === 409 && method !== "GET" && !retried) {
+    await new Promise((resolve) => setTimeout(resolve, RETRY_MS));
+    return api(method, path, body, true);
+  }
   if (!res.ok) throw new Error(payload.error ?? `${method} ${path} failed with ${res.status}`);
   return payload;
 }
 
+/** Links to every session the server hosts, so one tab can move between workstreams. */
+async function renderSwitcher() {
+  const res = await fetch("/api/sessions").catch(() => null);
+  if (!res?.ok) return;
+  const sessions = await res.json();
+  const here = `${sessionPrefix}/`;
+  const nav = $("sessions");
+  nav.hidden = sessions.length < 2;
+  nav.replaceChildren(
+    ...sessions.map((s) =>
+      el("a", {
+        href: s.url,
+        title: s.repo,
+        "aria-current": s.url === here ? "page" : undefined,
+        text: s.mode === "walk" ? `${s.branch} (walk)` : `${s.branch} v${s.version}`,
+      }),
+    ),
+    el("a", { href: "/", text: "All sessions" }),
+  );
+}
+
 function report(error) {
-  $("status").textContent = error ? error.message : "";
+  const status = $("status");
+  status.textContent = error ? error.message : "";
+  status.classList.toggle("error", Boolean(error));
 }
 
 async function guarded(action) {
@@ -65,6 +206,7 @@ async function guarded(action) {
 
 function indexOwnership() {
   unitsById = new Map(state.units.map((unit) => [unit.id, unit]));
+  numbers = lineNumbers(state.units);
   owners = new Map();
   for (const commit of state.commits) {
     for (const ref of commit.refs) {
@@ -97,61 +239,236 @@ function firstLine(message) {
   return message.split("\n")[0] ?? "";
 }
 
-function describeChanges(changes) {
-  return changes === null ? "whole hunk" : `lines ${changes.join(", ")}`;
+/** Where a hunk comment points, by file line numbers; the stored anchor keeps change indices. */
+function describeAnchor(anchor) {
+  const unit = unitsById.get(anchor.unit);
+  if (anchor.changes === null || unit?.kind !== "hunk") return "whole hunk";
+  return describeLines(unit.body, numbers.get(unit.id) ?? [], anchor.changes);
+}
+
+/**
+ * A comment textarea with its buttons. Cmd or Ctrl+Enter saves and Escape cancels; neither
+ * resumes playback.
+ */
+function commentForm({
+  key,
+  placeholder,
+  action = "Comment",
+  initial = "",
+  submit,
+  close,
+  kinds = false,
+}) {
+  const choice = kindDrafts.get(key) ?? {
+    kind: inferKind(drafts.get(key) ?? ""),
+    touched: false,
+    severity: "",
+  };
+  if (kinds) kindDrafts.set(key, choice);
+  const toggles = new Map();
+  const paint = () => {
+    for (const [kind, button] of toggles) {
+      button.setAttribute("aria-pressed", String(choice.kind === kind));
+    }
+  };
+  const area = el("textarea", {
+    placeholder,
+    "aria-label": placeholder,
+    oninput: () => {
+      drafts.set(key, area.value);
+      if (kinds && !choice.touched) {
+        choice.kind = inferKind(area.value);
+        paint();
+      }
+    },
+  });
+  area.value = drafts.get(key) ?? initial;
+  const done = () => {
+    drafts.delete(key);
+    kindDrafts.delete(key);
+  };
+  const cancel = () => {
+    done();
+    close();
+    render();
+  };
+  const save = () =>
+    guarded(async () => {
+      const body = area.value.trim();
+      if (!body) return;
+      await submit(body, choice.kind, choice.severity);
+      done();
+      close();
+      if (player.view === "play") notice = "Comment saved. Space to continue.";
+      await reloadComments();
+    });
+  area.addEventListener("keydown", (event) => {
+    if (event.key === "Enter" && (event.metaKey || event.ctrlKey)) {
+      event.preventDefault();
+      save();
+    } else if (event.key === "Escape") {
+      event.preventDefault();
+      cancel();
+    }
+  });
+  const toggle = el("div", { class: "kind", role: "group", "aria-label": "Kind of comment" });
+  for (const [kind, text] of [
+    ["question", "Ask a question"],
+    ["change", isWalk() ? "Code comment" : "Request a change"],
+  ]) {
+    const button = el("button", {
+      type: "button",
+      text,
+      onclick: () => {
+        choice.kind = kind;
+        choice.touched = true;
+        paint();
+        area.focus();
+      },
+    });
+    toggles.set(kind, button);
+    toggle.append(button);
+  }
+  paint();
+  const severity = el("select", {
+    "aria-label": "Severity, optional",
+    onchange: () => {
+      choice.severity = severity.value;
+    },
+  });
+  severity.append(el("option", { value: "", text: "No severity" }));
+  for (const level of [...SEVERITIES].reverse()) {
+    severity.append(el("option", { value: level, text: level }));
+  }
+  severity.value = choice.severity;
+  if (kinds) toggle.append(severity);
+  return el(
+    "div",
+    { class: "box", "data-box": key },
+    kinds ? toggle : null,
+    area,
+    el(
+      "div",
+      { class: "row" },
+      el("button", { class: "primary", text: action, onclick: save }),
+      el("button", { text: "Cancel", onclick: cancel }),
+      el("span", { class: "hint", text: "⌘/Ctrl+Enter to save, Esc to cancel" }),
+    ),
+  );
+}
+
+/** Mermaid sources a reply carried, drawn once each, so a re-render only copies the picture. */
+const replyDiagrams = new Map();
+
+function fillDiagram(node, drawn) {
+  if (drawn.svg !== undefined) {
+    // Mermaid sanitizes its own output under securityLevel "strict".
+    node.innerHTML = drawn.svg;
+  } else {
+    node.replaceChildren(el("pre", { class: "diagram-error", text: drawn.error }));
+  }
+}
+
+async function drawReplyDiagram(source) {
+  if (replyDiagrams.has(source)) return;
+  replyDiagrams.set(source, null);
+  drawing += 1;
+  let drawn;
+  try {
+    const { svg } = await (await loadMermaid()).render(`reply-diagram-${drawing}`, source);
+    drawn = { svg };
+  } catch (error) {
+    drawn = { error: `Mermaid could not draw this diagram: ${error?.message ?? String(error)}` };
+  }
+  replyDiagrams.set(source, drawn);
+  for (const node of document.querySelectorAll(".reply-diagram")) {
+    if (node.getAttribute("data-source") === source) fillDiagram(node, drawn);
+  }
+}
+
+function diagramSlot(source) {
+  const node = el("div", { class: "reply-diagram", "data-source": source });
+  const drawn = replyDiagrams.get(source);
+  if (drawn) fillDiagram(node, drawn);
+  else drawReplyDiagram(source);
+  return node;
+}
+
+function replyView(reply) {
+  return el(
+    "div",
+    { class: `reply ${reply.author}` },
+    el("div", { class: "meta", text: reply.author === "agent" ? "Agent" : "You" }),
+    el("div", { class: "said", text: reply.body }),
+    reply.diagram ? diagramSlot(reply.diagram) : null,
+  );
+}
+
+function commentLabel(comment) {
+  if (comment.kind === "question") return "Question";
+  return isWalk() ? "Code comment" : "Change request";
 }
 
 function commentView(comment) {
-  const key = `edit:${comment.id}`;
   if (editing.has(comment.id)) {
-    const area = el("textarea", {
-      oninput: () => drafts.set(key, area.value),
-    });
-    area.value = drafts.get(key) ?? comment.body;
     return el(
       "div",
       { class: "comment" },
-      area,
-      el(
-        "div",
-        { class: "row box" },
-        el("button", {
-          class: "primary",
-          text: "Save",
-          onclick: () =>
-            guarded(async () => {
-              await api("PUT", `/api/comments/${comment.id}`, { ...comment, body: area.value });
-              editing.delete(comment.id);
-              drafts.delete(key);
-              await reloadComments();
-            }),
-        }),
-        el("button", {
-          text: "Cancel",
-          onclick: () => {
-            editing.delete(comment.id);
-            drafts.delete(key);
-            render();
-          },
-        }),
-      ),
+      commentForm({
+        key: `edit:${comment.id}`,
+        placeholder: "Edit your comment",
+        action: "Save",
+        initial: comment.body,
+        submit: (body) => api("PUT", `/api/comments/${comment.id}`, { ...comment, body }),
+        close: () => editing.delete(comment.id),
+      }),
     );
   }
-  const where =
-    comment.anchor.kind === "hunk" ? ` · ${describeChanges(comment.anchor.changes)}` : "";
+  const question = comment.kind === "question";
+  const where = comment.anchor.kind === "hunk" ? ` · ${describeAnchor(comment.anchor)}` : "";
+  const again = comment.follows ? " · asked again" : "";
+  const rating = comment.severity ? ` · ${comment.severity}` : "";
+  const replyKey = `reply:${comment.id}`;
   return el(
     "div",
-    { class: "comment" },
-    el("div", { class: "meta" }, `${comment.id}${where}`),
+    { class: question ? "comment question" : "comment" },
+    el(
+      "div",
+      { class: "meta" },
+      `${commentLabel(comment)} · ${comment.id}${where}${again}${rating}`,
+    ),
     el("div", { class: "text", text: comment.body }),
+    ...(comment.replies ?? []).map(replyView),
+    openBoxes.has(replyKey)
+      ? commentForm({
+          key: replyKey,
+          placeholder: "Reply",
+          action: "Reply",
+          submit: (body) =>
+            api("POST", `/api/comments/${comment.id}/replies`, { author: "reviewer", body }),
+          close: () => openBoxes.delete(replyKey),
+        })
+      : null,
     el(
       "div",
       { class: "meta" },
+      question || comment.replies?.length
+        ? el("button", {
+            class: "link",
+            text: "reply",
+            onclick: () => {
+              openBoxes.add(replyKey);
+              focusKey = replyKey;
+              render();
+            },
+          })
+        : null,
       el("button", {
         class: "link",
         text: "edit",
         onclick: () => {
           editing.add(comment.id);
+          focusKey = `edit:${comment.id}`;
           render();
         },
       }),
@@ -168,55 +485,299 @@ function commentView(comment) {
   );
 }
 
+/** Marks a previous question resolved or reopens it; the server's event repeats it harmlessly. */
+function setResolved(card, resolved) {
+  return guarded(async () => {
+    await api("POST", "/api/resolved", { comment: card.id, resolved });
+    const others = state.resolved.filter((id) => id !== card.id);
+    state.resolved = resolved ? [...others, card.id] : others;
+    render();
+  });
+}
+
+function explainedIn(card) {
+  const { place } = card;
+  if (place === null) return null;
+  const path = place.unit === null ? null : unitsById.get(place.unit)?.path;
+  return `${path ? `${path} in ` : ""}commit ${place.commit + 1}`;
+}
+
+/** The previous version's question with the agent's answer, where it now lives. */
+function answerView(card) {
+  const { comment, response, place } = card;
+  if (card.resolved) {
+    return el(
+      "div",
+      { class: "answer resolved", "data-answer": card.id },
+      el("span", { text: `✓ Resolved · ${firstLine(comment.body)}` }),
+      el("button", { class: "link", text: "Reopen", onclick: () => setResolved(card, false) }),
+    );
+  }
+  const againKey = `again:${card.id}`;
+  const lines = comment.context.lines ?? [];
+  const followUps = state.comments.filter((c) => c.follows === card.id);
+  return el(
+    "section",
+    { class: "answer", "data-answer": card.id, "aria-label": "Answer to your question" },
+    el("div", {
+      class: "meta",
+      text: `You asked (v${state.previous.version}) · ${statusLine(card)}`,
+    }),
+    el("div", { class: "said", text: comment.body }),
+    lines.length > 0 ? el("pre", { class: "quote", text: lines.join("\n") }) : null,
+    response ? el("div", { class: "meta", text: "Answer" }) : null,
+    response ? el("div", { class: "said", text: response.note }) : null,
+    place === null && comment.anchor.kind === "hunk"
+      ? el("div", { class: "meta", text: "The code you asked about has changed since." })
+      : null,
+    place === null ? null : el("div", { class: "meta", text: `Explained in ${explainedIn(card)}` }),
+    ...(place?.continues ?? []).map((commit) =>
+      el("button", {
+        class: "link",
+        text: `continues in commit ${commit + 1}`,
+        onclick: () => select(commit, { focus: true }),
+      }),
+    ),
+    ...followUps.map(commentView),
+    openBoxes.has(againKey)
+      ? commentForm({
+          key: againKey,
+          placeholder: "What is still unclear?",
+          action: "Ask again",
+          submit: (body) => api("POST", "/api/comments", askAgain(card, body)),
+          close: () => openBoxes.delete(againKey),
+        })
+      : el(
+          "div",
+          { class: "answer-actions" },
+          el("button", {
+            class: "primary",
+            text: "Resolved",
+            onclick: () => setResolved(card, true),
+          }),
+          el("button", {
+            text: "Ask again",
+            onclick: () => {
+              openBoxes.add(againKey);
+              focusKey = againKey;
+              render();
+            },
+          }),
+        ),
+  );
+}
+
+/** While playing, an answer waits for its moment; browsing shows every one. */
+function visibleCards(list) {
+  return player.view === "play" ? list.filter((c) => seenAnswers.has(c.id) || c.resolved) : list;
+}
+
+function showAnswer(card) {
+  seenAnswers.add(card.id);
+  if (card.place !== null) select(card.place.commit);
+  else render();
+  document.querySelector(`[data-answer="${card.id}"]`)?.scrollIntoView({ block: "center" });
+}
+
+/** The sidebar list of the previous version's questions. Answers with no place show in full. */
+function renderAnswers() {
+  const panel = $("answers");
+  panel.hidden = cards.length === 0;
+  if (cards.length === 0) return;
+  const open = cards.filter((c) => !c.resolved).length;
+  panel.replaceChildren(
+    el("strong", { text: `Answers · ${open} to read` }),
+    ...cards.map((card) =>
+      el(
+        "div",
+        { class: "answer-entry" },
+        el("button", {
+          type: "button",
+          class: card.resolved ? "answer-row done" : "answer-row",
+          text: `${statusLine(card)} · ${firstLine(card.comment.body)}`,
+          onclick: () => showAnswer(card),
+        }),
+        card.place === null && !card.resolved ? answerView(card) : null,
+      ),
+    ),
+  );
+}
+
+/** Severity picked for an undecided concern, applied when it is kept. */
+const pickedSeverity = new Map();
+
+/** Records a decision on a concern; the server's event repeats it harmlessly. */
+function decide(concern, decision, extra = {}) {
+  return guarded(async () => {
+    const severity = extra.severity ?? pickedSeverity.get(concern.id);
+    const body = {
+      decision,
+      ...(severity && severity !== concern.severity ? { severity } : {}),
+      ...(extra.note === undefined ? {} : { note: extra.note }),
+    };
+    await api("POST", `/api/concerns/${concern.id}`, body);
+    state.decisions = { ...state.decisions, [concern.id]: { concern: concern.id, ...body } };
+    pickedSeverity.delete(concern.id);
+    if (player.view === "play") notice = null;
+    render();
+  });
+}
+
+function severitySelect(current, onchange) {
+  const select = el("select", { "aria-label": "Severity" });
+  for (const level of SEVERITIES) {
+    select.append(el("option", { value: level, text: level }));
+  }
+  select.value = current;
+  select.addEventListener("change", () => onchange(select.value));
+  return select;
+}
+
 /**
- * A collapsed button that opens into a textarea. `makeAnchor` runs at save time so a
- * hunk comment picks up whichever lines are selected then.
+ * The agent's concern as a card in its own voice. It is never spoken. Undecided it offers keep and
+ * dismiss; kept it takes the reviewer's own words; dismissed it folds to one row.
  */
-function commentBox({ key, label, placeholder, makeAnchor, context, onSaved }) {
+function concernView(concern, { after } = {}) {
+  const decision = state.decisions[concern.id];
+  const verdict = decision?.decision ?? "undecided";
+  const level = severityOf(concern, state.decisions);
+  const attrs = { "data-concern": concern.id, "data-after": after };
+  if (verdict === "dismissed") {
+    return el(
+      "div",
+      { class: "concern dismissed", ...attrs },
+      el("span", { text: `Dismissed · ${concern.text}` }),
+      el("button", {
+        class: "link",
+        text: "Undo",
+        onclick: () => decide(concern, "kept"),
+      }),
+    );
+  }
+  const noteKey = `note:${concern.id}`;
+  return el(
+    "section",
+    {
+      class: `concern sev-${level} ${verdict}`,
+      "aria-label": `Agent concern, ${level}`,
+      ...attrs,
+    },
+    el(
+      "div",
+      { class: "concern-head" },
+      el("span", { class: "who", text: "Agent" }),
+      el("span", { class: "chip", text: level }),
+      el("span", { class: "kind-tag", text: concern.kind }),
+      verdict === "kept" ? el("span", { class: "verdict", text: "Kept" }) : null,
+    ),
+    el("div", { class: "said", text: concern.text }),
+    verdict === "kept" && decision.note
+      ? el("div", { class: "said mine", text: `You: ${decision.note}` })
+      : null,
+    verdict === "kept"
+      ? commentForm({
+          key: noteKey,
+          placeholder: "Your words (optional)",
+          action: "Save note",
+          initial: decision.note ?? "",
+          submit: (note) => decide(concern, "kept", { note, severity: level }),
+          close: () => {},
+        })
+      : null,
+    el(
+      "div",
+      { class: "concern-actions" },
+      verdict === "undecided"
+        ? el("button", {
+            class: "primary",
+            text: "Keep",
+            title: "Keep this concern in the report (y)",
+            onclick: () => decide(concern, "kept"),
+          })
+        : null,
+      el("button", {
+        text: "Dismiss",
+        title: "Drop this concern (x)",
+        onclick: () => decide(concern, "dismissed"),
+      }),
+      el(
+        "label",
+        { class: "sev-pick" },
+        "Severity ",
+        severitySelect(level, (next) => {
+          if (verdict === "kept") decide(concern, "kept", { severity: next, note: decision.note });
+          else {
+            pickedSeverity.set(concern.id, next);
+            render();
+          }
+        }),
+      ),
+    ),
+  );
+}
+
+/** The commit's concerns with no unit, shown under its message. */
+function commitConcerns(commit) {
+  return (commit.concerns ?? []).filter((c) => c.unit === undefined);
+}
+
+/** Concerns on the commit that are still undecided, for the list dot and the stage reminder. */
+function openConcerns() {
+  return undecided(allConcerns(state.commits), state.decisions);
+}
+
+/** The concern y and x act on: the chunk on screen, else the commit being read. */
+function actionableConcern() {
+  const commit = state.commits[selected];
+  if (!commit) return null;
+  const at = player.view === "play" ? currentBeat() : -1;
+  const unit = beats[at]?.kind === "chunk" ? unitsById.get(beats[at].unit) : undefined;
+  const chunk =
+    unit?.kind === "hunk" ? concernsInChunk(commit.concerns ?? [], beats, at, unit.body) : [];
+  return pickConcern(commit.concerns ?? [], chunk, state.decisions);
+}
+
+function decideCurrent(decision) {
+  const concern = actionableConcern();
+  if (concern) decide(concern, decision);
+}
+
+/** Only a question is written with a kind; absent means a change request. */
+function kindField(kind) {
+  return kind === "question" ? { kind } : {};
+}
+
+/** A reviewer's own severity rating, when they gave one. */
+function rated(severity) {
+  return severity ? { severity } : {};
+}
+
+/** A button that opens into a comment form, focused. */
+function commentBox({ key, label, placeholder, anchor, context }) {
   if (!openBoxes.has(key)) {
     return el("button", {
-      text: typeof label === "function" ? label() : label,
+      text: label,
       onclick: () => {
         openBoxes.add(key);
+        focusKey = key;
         render();
       },
     });
   }
-  const area = el("textarea", { placeholder, oninput: () => drafts.set(key, area.value) });
-  area.value = drafts.get(key) ?? "";
-  const close = () => {
-    openBoxes.delete(key);
-    drafts.delete(key);
-  };
-  return el(
-    "div",
-    { class: "box" },
-    area,
-    el(
-      "div",
-      { class: "row" },
-      el("button", {
-        class: "primary",
-        text: "Comment",
-        onclick: () =>
-          guarded(async () => {
-            const body = area.value.trim();
-            if (!body) return;
-            await api("POST", "/api/comments", { anchor: makeAnchor(), context, body });
-            close();
-            onSaved?.();
-            await reloadComments();
-          }),
-      }),
-      el("button", {
-        text: "Cancel",
-        onclick: () => {
-          close();
-          render();
-        },
+  return commentForm({
+    key,
+    placeholder,
+    kinds: true,
+    submit: (body, kind, severity) =>
+      api("POST", "/api/comments", {
+        anchor,
+        context,
+        body,
+        ...kindField(kind),
+        ...rated(severity),
       }),
-    ),
-  );
+    close: () => openBoxes.delete(key),
+  });
 }
 
 function describeFileUnit(unit) {
@@ -224,124 +785,352 @@ function describeFileUnit(unit) {
   return `${unit.reason} file ${change}`;
 }
 
-function diffLine(unit, commit, line, index, pickKey) {
-  const base = el("span", { class: "op", text: line.op });
-  const text = el("span", { text: line.text.replace(/\n$/, "") });
+/** Body indices of a commit's own change lines in a unit, in hunk order. */
+function ownLines(unit, commitIndex) {
+  return rowsOf(unit.body, ownersOf(unit), commitIndex).flatMap((r) =>
+    r.kind === "line" && r.mine ? [r.line] : [],
+  );
+}
+
+/** Picks a line for a comment; shift extends the pick to a range. Pauses playback. */
+function pickLine(unit, commitIndex, line, extend) {
+  const own = ownLines(unit, commitIndex);
+  const same = extend && selection?.unit === unit.id && selection.commit === commitIndex;
+  const from = same ? selection.from : line;
+  const [a, b] = [own.indexOf(from), own.indexOf(line)].sort((x, y) => x - y);
+  selection = { commit: commitIndex, unit: unit.id, from, lines: own.slice(a, b + 1) };
+  focusKey = `line:${commitIndex}:${unit.id}`;
+  if (player.playing) pause();
+  render();
+}
+
+function lineBox(unit, commit) {
+  const changes = selection.lines.map((i) => unit.body[i].change);
+  return commentForm({
+    key: `line:${commit.index}:${unit.id}`,
+    placeholder: `Comment on ${describeLines(unit.body, numbers.get(unit.id) ?? [], changes)}`,
+    kinds: true,
+    submit: (body, kind, severity) =>
+      api("POST", "/api/comments", {
+        anchor: { kind: "hunk", unit: unit.id, commit: commit.index, changes },
+        context: {
+          commitMessage: commit.message,
+          path: unit.path,
+          lines: selection.lines.map((i) => unit.body[i].text.replace(/\n$/, "")),
+        },
+        body,
+        ...kindField(kind),
+        ...rated(severity),
+      }),
+    close: () => {
+      selection = null;
+    },
+  });
+}
+
+/** One line of a hunk. Only the commit's own change lines can be picked for a comment. */
+function diffLine(unit, commit, index, mine) {
+  const line = unit.body[index];
   const key = lineKey(unit.id, index);
-  if (line.op === " ")
+  const spans = spansOf(unit)?.[index];
+  const text = spans
+    ? el(
+        "span",
+        { class: "text" },
+        ...spans.map((s) =>
+          el("span", { class: s.tone ? `tok-${s.tone}` : undefined, text: s.text }),
+        ),
+      )
+    : el("span", { class: "text", text: line.text.replace(/\n$/, "") });
+  const at = numbers.get(unit.id)?.[index];
+  const gutter = el(
+    "span",
+    { class: "gutter" },
+    el("span", { class: "ln", text: at?.old == null ? "" : String(at.old) }),
+    el("span", { class: "ln", text: at?.new == null ? "" : String(at.new) }),
+  );
+  if (!mine) {
     return el(
       "div",
       { class: "dl", "data-line": key },
-      el("span", { class: "gutter" }),
-      base,
+      gutter,
+      el("span", { class: "op", text: " " }),
       text,
     );
-
-  const owner = owners.get(unit.id)?.get(line.change);
-  const mine = owner === commit.index;
-  const picked = picks.get(pickKey)?.has(line.change) ?? false;
-  const classes = ["dl", line.op === "+" ? "add" : "del", mine ? "mine pickable" : "other"];
+  }
+  gutter.prepend(
+    el("button", {
+      type: "button",
+      class: "add-comment",
+      tabindex: "-1",
+      "aria-label": "Comment on this line",
+      text: "+",
+    }),
+  );
+  const picked =
+    selection?.commit === commit.index &&
+    selection.unit === unit.id &&
+    selection.lines.includes(index);
+  const classes = ["dl", line.op === "+" ? "add" : "del", "mine"];
   if (picked) classes.push("picked");
-  const node = el(
+  return el(
     "div",
     {
       class: classes.join(" "),
       "data-line": key,
-      title: mine ? "Click to select this line for a comment" : undefined,
-      onclick: mine
-        ? () => {
-            const set = picks.get(pickKey) ?? new Set();
-            if (!set.delete(line.change)) set.add(line.change);
-            picks.set(pickKey, set);
-            render();
-          }
-        : undefined,
+      onmousedown: (event) => {
+        // Shift-click extends the pick; without this it also selects page text.
+        if (event.shiftKey) event.preventDefault();
+      },
+      onclick: (event) => pickLine(unit, commit.index, index, event.shiftKey),
+      onkeydown: (event) => lineKeys(event, unit, commit.index, index),
+      tabindex: "-1",
+      "aria-label": `${line.op === "+" ? "Added" : "Removed"}: ${line.text.trim() || "blank line"}`,
     },
-    el("span", { class: "gutter", text: String(line.change) }),
-    base,
+    gutter,
+    el("span", { class: "op", text: line.op }),
     text,
   );
-  if (!mine && owner !== undefined)
-    node.append(el("span", { class: "label", text: `→ commit ${owner + 1}` }));
-  return node;
+}
+
+/**
+ * Inside a hunk the commit's own lines are one tab stop: arrows move between them, Space or
+ * Enter picks one for a comment and Shift extends the pick.
+ */
+function lineKeys(event, unit, commitIndex, index) {
+  const lines = [...event.currentTarget.parentElement.querySelectorAll(".dl.mine:not(.pending)")];
+  const at = lines.indexOf(event.currentTarget);
+  const move = { ArrowDown: 1, ArrowUp: -1 }[event.key];
+  if (move !== undefined) {
+    const to = lines[at + move];
+    if (to) {
+      event.currentTarget.tabIndex = -1;
+      to.tabIndex = 0;
+      to.focus();
+    }
+  } else if (event.key === " " || event.key === "Enter") {
+    pickLine(unit, commitIndex, index, event.shiftKey);
+  } else return;
+  event.preventDefault();
+  event.stopPropagation();
+}
+
+/** Gives each hunk one tab stop, on its first own line. */
+function rovingLines() {
+  for (const diff of $("main").querySelectorAll(".diff")) {
+    const first = diff.querySelector(".dl.mine:not(.pending)");
+    if (first) first.tabIndex = 0;
+  }
+}
+
+/** Lines a later commit adds, folded into one row that leads to that commit. */
+function foldRow(lines, owner) {
+  const n = lines.length;
+  return el("button", {
+    type: "button",
+    class: "fold",
+    text: `${n} line${n === 1 ? "" : "s"} arrive${n === 1 ? "s" : ""} in commit ${owner + 1}`,
+    onclick: () => select(owner),
+  });
+}
+
+function ownersOf(unit) {
+  const byChange = owners.get(unit.id);
+  return Array.from({ length: unit.changeCount }, (_, c) => byChange?.get(c));
 }
 
 function unitComments(unit, commit) {
   const anchor = { kind: "hunk", unit: unit.id, commit: commit.index, changes: null };
-  const pickKey = `${commit.index}:${unit.id}`;
-  const existing = commentsAt(anchor);
-  const picked = () => [...(picks.get(pickKey) ?? [])].sort((a, b) => a - b);
   return el(
     "div",
     { class: "comments" },
-    ...existing.map(commentView),
+    ...commentsAt(anchor).map(commentView),
     el(
       "div",
       { class: "controls" },
       commentBox({
-        key: `box:${pickKey}`,
-        label: () => {
-          const n = picked().length;
-          return n > 0 ? `Comment on ${n} selected line${n === 1 ? "" : "s"}` : "Comment";
-        },
+        key: `box:${commit.index}:${unit.id}`,
+        label: unit.kind === "hunk" ? "Comment on this hunk" : "Comment",
         placeholder: "What about this change?",
-        makeAnchor: () => ({ ...anchor, changes: picked().length > 0 ? picked() : null }),
+        anchor,
         context: { commitMessage: commit.message, path: unit.path },
-        onSaved: () => picks.delete(pickKey),
       }),
     ),
   );
 }
 
+/** Narration shown in place while browsing; playback moves its own card instead. */
+function staticNarration(text) {
+  if (!text || player.view === "play") return null;
+  return el("blockquote", { class: "narration" }, text);
+}
+
 function unitView(unit, commit) {
-  const pickKey = `${commit.index}:${unit.id}`;
-  const head = el("div", { class: "unit-head" }, el("span", { text: unit.id }));
+  const ref = commit.refs.find((r) => r.unit === unit.id);
+  const head = el("div", { class: "unit-head", title: unit.id });
   let content;
   if (unit.kind === "hunk") {
-    const mineCount = [...(owners.get(unit.id) ?? [])].filter(([, o]) => o === commit.index).length;
+    const rows = rowsOf(unit.body, ownersOf(unit), commit.index);
+    const first = rows.find((r) => r.kind === "line" && r.mine);
+    const scope = first === undefined ? null : scopeOf(unit.body, first.line);
+    const mineCount = rows.filter((r) => r.kind === "line" && r.mine).length;
     head.append(
+      el("span", { class: "scope", text: scope === null ? "" : `in ${scope}` }),
       el("span", { class: "spacer" }),
-      el("span", { text: `takes ${mineCount} of ${unit.changeCount} changes` }),
+      el("span", {
+        text: `${mineCount} of ${unit.changeCount} changed lines in this commit`,
+      }),
+    );
+    const picking = selection?.commit === commit.index && selection.unit === unit.id;
+    const boxAfter = picking ? Math.max(...selection.lines) : -1;
+    const own = ownLines(unit, commit.index);
+    const raised = (commit.concerns ?? []).filter((c) => c.unit === unit.id);
+    const under = new Map();
+    for (const concern of raised) {
+      const at = anchorLine(concern, unit.body, own);
+      if (at !== null) under.set(at, [...(under.get(at) ?? []), concern]);
+    }
+    const flagged = new Map(
+      raised.flatMap((c) =>
+        bodyIndexes(unit.body, c.lines ?? []).map((i) => [i, severityOf(c, state.decisions)]),
+      ),
     );
     content = el(
       "div",
       { class: "diff" },
-      ...unit.body.map((line, index) => diffLine(unit, commit, line, index, pickKey)),
+      ...rows.flatMap((row) => {
+        if (row.kind === "fold") return [foldRow(row.lines, row.commit)];
+        const line = diffLine(unit, commit, row.line, row.mine);
+        const level = flagged.get(row.line);
+        if (level) line.classList.add("flagged", `flag-${level}`);
+        const cardsUnder = (under.get(row.line) ?? []).map((c) =>
+          concernView(c, { after: lineKey(unit.id, row.line) }),
+        );
+        return [line, ...cardsUnder, ...(row.line === boxAfter ? [lineBox(unit, commit)] : [])];
+      }),
     );
   } else {
     const summary =
       unit.kind === "file" ? describeFileUnit(unit) : `mode change ${unit.from} → ${unit.to}`;
+    head.append(el("span", { text: summary }));
     content = el("div", { class: "card", text: `${summary}: ${unit.path}` });
   }
   return el(
     "div",
     { class: "unit", "data-unit": unit.id },
     head,
+    ...visibleCards(
+      cardsAt(
+        cards,
+        commit.index,
+        unit.id,
+        commit.refs.map((r) => r.unit),
+      ),
+    ).map(answerView),
+    staticNarration(ref?.narration?.trim()),
     content,
     unitComments(unit, commit),
   );
 }
 
+/** A dot in the commit list while the commit holds concerns nobody has decided. */
+function concernDot(commit) {
+  const open = undecided(commit.concerns ?? [], state.decisions);
+  const level = topSeverity(open, state.decisions);
+  if (level === null) return null;
+  return el("span", {
+    class: `dot sev-${level}`,
+    role: "img",
+    "aria-label": `${open.length} undecided ${level} concern${open.length === 1 ? "" : "s"}`,
+    title: `${open.length} agent concern${open.length === 1 ? "" : "s"} to decide`,
+  });
+}
+
 function renderList() {
   const list = $("commits");
+  const hadFocus = list.contains(document.activeElement);
   list.replaceChildren(
     ...state.commits.map((commit, i) => {
-      const count = state.comments.filter(
-        (c) => c.anchor.kind !== "plan" && c.anchor.commit === commit.index,
-      ).length;
+      const { questions, changes } = kindCounts(state.comments, commit.index);
+      const playing = player.view === "play" && i === selected;
       return el(
         "li",
-        {
-          class: i === selected ? "selected" : undefined,
-          onclick: () => select(i),
-        },
-        el("span", { class: "index", text: String(i + 1) }),
-        el("span", { class: "title", text: firstLine(commit.message) }),
-        count > 0 ? el("span", { class: "badge", text: String(count) }) : null,
+        { class: i === selected ? "selected" : undefined },
+        el(
+          "button",
+          {
+            type: "button",
+            class: "commit-row",
+            "aria-current": i === selected ? "step" : undefined,
+            onclick: () => {
+              setListOpen(false);
+              select(i, { focus: true });
+            },
+          },
+          el("span", { class: "index", text: String(i + 1) }),
+          el("span", { class: "title", text: firstLine(commit.message) }),
+          concernDot(commit),
+          playing
+            ? el("span", { class: "mark", title: "Playing", text: "▶" })
+            : watched.has(i)
+              ? el("span", { class: "mark", title: "Watched", text: "✓" })
+              : null,
+          questions > 0
+            ? el("span", {
+                class: "badge question",
+                title: `${questions} question${questions === 1 ? "" : "s"}`,
+                text: `${questions} ?`,
+              })
+            : null,
+          changes > 0
+            ? el("span", {
+                class: "badge",
+                title: `${changes} comment${changes === 1 ? "" : "s"}`,
+                text: String(changes),
+              })
+            : null,
+        ),
       );
     }),
   );
   list.children[selected]?.scrollIntoView({ block: "nearest" });
+  if (hadFocus) list.children[selected]?.querySelector("button")?.focus({ preventScroll: true });
+  markClamped();
+}
+
+/** Only a clamped title needs its full text on hover and focus. */
+function markClamped() {
+  for (const row of $("commits").querySelectorAll(".commit-row")) {
+    const title = row.querySelector(".title");
+    if (title.scrollHeight > title.clientHeight) row.title = title.textContent;
+    else row.removeAttribute("title");
+  }
+}
+
+const rail = window.matchMedia("(max-width: 899px)");
+
+/** In the rail, hovering or focusing a row shows its title beside it. */
+function showRailTip(event) {
+  const row = event.target.closest?.(".commit-row");
+  const tip = $("rail-tip");
+  if (!rail.matches || $("sidebar").classList.contains("open") || !row) return;
+  const box = row.getBoundingClientRect();
+  tip.textContent = row.querySelector(".title").textContent;
+  tip.style.left = `${box.right + 6}px`;
+  tip.style.top = `${box.top + 4}px`;
+  tip.hidden = false;
+  row.setAttribute("aria-describedby", "rail-tip");
+}
+
+function hideRailTip(event) {
+  $("rail-tip").hidden = true;
+  event.target.closest?.(".commit-row")?.removeAttribute("aria-describedby");
+}
+
+function setListOpen(open) {
+  $("sidebar").classList.toggle("open", open);
+  $("commits-toggle").setAttribute("aria-expanded", String(open));
+  $("rail-tip").hidden = true;
 }
 
 function renderPlanNote() {
@@ -356,7 +1145,7 @@ function renderPlanNote() {
       placeholder: walk
         ? "Anything about the change as a whole"
         : "Anything about the plan as a whole",
-      makeAnchor: () => anchor,
+      anchor,
       context: { commitMessage: "", path: null },
     }),
   );
@@ -382,12 +1171,22 @@ function renderMain() {
   }
 
   main.replaceChildren(
+    stage,
     el(
       "div",
       { class: "commit-head" },
-      el("h2", { text: `Commit ${selected + 1} of ${state.commits.length}` }),
       el("div", { class: "message", text: commit.message }),
+      staticNarration(commit.narration?.trim()),
       ...commentsAt(messageAnchor).map(commentView),
+      ...visibleCards(
+        cardsAt(
+          cards,
+          commit.index,
+          null,
+          commit.refs.map((r) => r.unit),
+        ),
+      ).map(answerView),
+      ...commitConcerns(commit).map((c) => concernView(c)),
       // A walk plan's messages and order are the planner's, not the author's, so only code is
       // up for comment there.
       isWalk()
@@ -399,14 +1198,14 @@ function renderMain() {
               key: `box:message:${commit.index}`,
               label: "Comment on the message",
               placeholder: "What should this message say?",
-              makeAnchor: () => messageAnchor,
+              anchor: messageAnchor,
               context,
             }),
             commentBox({
               key: `box:position:${commit.index}`,
               label: "This belongs elsewhere",
               placeholder: "Where should this go, and why?",
-              makeAnchor: () => positionAnchor,
+              anchor: positionAnchor,
               context,
             }),
           ),
@@ -423,23 +1222,50 @@ function renderMain() {
   );
   main.scrollTop = scroll;
   applyPlayback();
+  rovingLines();
+}
+
+/** The textarea being typed in, so a re-render caused by someone else's event keeps the caret. */
+function typingPlace() {
+  const area = document.activeElement;
+  if (!(area instanceof HTMLTextAreaElement)) return null;
+  const key = area.closest("[data-box]")?.getAttribute("data-box");
+  return key ? { key, start: area.selectionStart, end: area.selectionEnd } : null;
 }
 
 function render() {
+  const typing = typingPlace();
+  cards = answerCards(state.previous, state.resolved, state.commits);
   renderList();
+  renderAnswers();
   renderPlanNote();
   renderMain();
+  if (focusKey !== null) {
+    document.querySelector(`[data-box="${focusKey}"] textarea`)?.focus();
+    focusKey = null;
+  } else if (typing !== null) {
+    const area = document.querySelector(`[data-box="${typing.key}"] textarea`);
+    if (area instanceof HTMLTextAreaElement) {
+      area.focus();
+      area.setSelectionRange(typing.start, typing.end);
+    }
+  }
 }
 
-function select(index) {
+/** Moves to a commit. A move the reviewer asked for takes focus to the commit heading. */
+function select(index, { focus = false } = {}) {
   const next = Math.max(0, Math.min(state.commits.length - 1, index));
-  if (player.view === "play") {
-    seek(commitStart(script, next));
-    return;
+  if (player.view === "play") seek(beatStart(steps, introOf(beats, next)));
+  else {
+    selected = next;
+    render();
+    $("main").scrollTop = 0;
   }
-  selected = next;
-  render();
-  $("main").scrollTop = 0;
+  if (focus) focusHeading();
+}
+
+function focusHeading() {
+  stage.querySelector("h2")?.focus({ preventScroll: true });
 }
 
 function isWalk() {
@@ -447,9 +1273,10 @@ function isWalk() {
 }
 
 const synth = "speechSynthesis" in window ? window.speechSynthesis : null;
+const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
 /**
- * view "play" hides lines the playback has not written yet; "browse" shows every line.
- * position counts performed steps of the script. generation retires a loop on every seek.
+ * view "play" shows the plan beat by beat; "browse" shows every line. position indexes the step
+ * on screen, steps.length being the end. generation retires a running loop on every move.
  */
 const player = {
   view: "browse",
@@ -460,8 +1287,22 @@ const player = {
   muted: false,
   voice: null,
 };
-let script = [];
+let beats = [];
+/** Commits whose outro playback reached. */
+const watched = new Set();
+/** When p last restarted a commit, so a second press soon after goes one further back. */
+let restartedAt = 0;
+/** Shown in the narration card until the next move, such as after a comment is saved. */
+let notice = null;
+/** Whether playback has run at all, so the ready card shows only before the first Play. */
+let started = false;
+let steps = [];
+let narrated = true;
 let voices = [];
+/** The one narration card. It moves to whatever the reviewer is looking at. */
+const card = el("blockquote", { class: "narration", "aria-live": "polite" });
+/** Sticky header of the code pane: where the reviewer is. */
+const stage = el("div", { class: "stage" });
 
 function stored(key) {
   try {
@@ -480,10 +1321,10 @@ function store(key, value) {
 }
 
 function silent() {
-  return player.muted || synth === null;
+  return player.muted || synth === null || !narrated;
 }
 
-/** Resolves true after `ms` of playing time, or false once a seek retires this loop. */
+/** Resolves true after `ms` of playing time, or false once a move retires this loop. */
 function sleep(ms, generation) {
   return new Promise((resolve) => {
     let left = ms;
@@ -500,132 +1341,359 @@ function sleep(ms, generation) {
   });
 }
 
-function speak(text) {
-  if (silent() || !text) return null;
+/**
+ * Speaks one utterance, cancelling whatever was speaking, so voice and picture never drift.
+ * Resolves when it ends, or after a bound for engines that never report the end.
+ */
+function speak(text, generation) {
+  synth.cancel();
   const utterance = new SpeechSynthesisUtterance(text);
-  utterance.rate = player.speed;
+  utterance.rate = speechRate(player.speed);
   const voice = voices.find((v) => v.name === player.voice);
   if (voice) {
     utterance.voice = voice;
     utterance.lang = voice.lang;
   }
-  synth.speak(utterance);
-  return utterance;
-}
-
-/** Some engines never fire "end", so a pause-aware timeout bounds the wait. */
-function speakAndWait(text, generation) {
-  const utterance = speak(text);
-  if (!utterance) return Promise.resolve(true);
   const ended = new Promise((resolve) => {
     utterance.addEventListener("end", () => resolve(true));
     utterance.addEventListener("error", () => resolve(true));
   });
+  synth.speak(utterance);
   return Promise.race([ended, sleep(speechTimeout(text, player.speed), generation)]);
 }
 
-function setCaption(text) {
-  $("caption").textContent = text;
+function scrollMain(top) {
+  $("main").scrollTo({
+    top: Math.max(0, top),
+    behavior: reducedMotion.matches ? "auto" : "smooth",
+  });
 }
 
-function applyPlayback() {
-  const { states, current } =
-    player.view === "play"
-      ? lineStates(script, player.position, selected)
-      : { states: new Map(), current: null };
-  for (const node of $("main").querySelectorAll("[data-line]")) {
-    const key = node.dataset.line;
-    const lineState = states.get(key);
-    node.classList.toggle("pending", lineState === "hidden");
-    node.classList.toggle("gone", lineState === "gone");
-    node.classList.toggle("current", key === current);
+/** Brings a node to 30% from the top of the code pane. */
+function scrollToChunk(node) {
+  const main = $("main");
+  const offset = node.getBoundingClientRect().top - main.getBoundingClientRect().top;
+  scrollMain(main.scrollTop + offset - main.clientHeight * 0.3);
+}
+
+/** What watching costs, shown before the first Play. */
+function readyText() {
+  const paths = new Set(state.units.map((u) => u.path));
+  const minutes = Math.max(1, Math.round(duration(steps) / 60_000));
+  const what = `${state.commits.length} commits · ${paths.size} files · about ${minutes} min at ${player.speed}x`;
+  return `${what}. Press Play or Space to watch the branch being written.`;
+}
+
+function setCard(text, kind) {
+  card.textContent = text;
+  card.className = `narration ${kind}`;
+}
+
+/** Where the card and the reader's eye go for a beat: its first line, else its unit. */
+function anchorOf(beat) {
+  const main = $("main");
+  if (beat.kind !== "chunk") return main.querySelector(".commit-head");
+  const first = beat.lines[0];
+  const line =
+    first === undefined
+      ? null
+      : (main.querySelector(`[data-ph="${lineKey(beat.unit, first)}"]`) ??
+        main.querySelector(`[data-line="${lineKey(beat.unit, first)}"]`));
+  return line ?? main.querySelector(`[data-unit="${beat.unit}"] .card`);
+}
+
+function chunkText(beat) {
+  return beat.narration ?? beat.label;
+}
+
+/** Renders the position: which lines exist yet, the placeholders, the card and the countdown. */
+function renderStage() {
+  const commit = state.commits[selected];
+  if (!commit) return;
+  const beat = beatAt(steps, player.position);
+  const here = player.view === "play" ? beats[beat] : undefined;
+  const chunk = here === undefined ? null : chunkOf(beats, beat);
+  const path = here?.kind === "chunk" ? unitsById.get(here.unit)?.path : undefined;
+  const parts = [
+    firstLine(commit.message),
+    chunk === null ? null : `chunk ${chunk.index} of ${chunk.count}`,
+    path ?? null,
+  ].filter((p) => p !== null);
+  stage.replaceChildren(
+    el(
+      "h2",
+      { tabindex: "-1" },
+      el("span", { text: `Commit ${selected + 1} of ${state.commits.length}` }),
+      ...parts.map((p) => el("span", { class: "part", text: ` · ${p}` })),
+      toDecide(openConcerns().length) === null
+        ? null
+        : el("span", { class: "part to-decide", text: ` · ${toDecide(openConcerns().length)}` }),
+    ),
+  );
+  const strip = $("strip");
+  strip.replaceChildren(
+    ...progress(beats, player.view === "play" ? beat : 0).map((seg) =>
+      el(
+        "button",
+        {
+          type: "button",
+          class: seg.commit === selected ? "seg here" : "seg",
+          style: `flex-grow: ${seg.weight}`,
+          title: `Commit ${seg.commit + 1}: ${firstLine(state.commits[seg.commit]?.message ?? "")}`,
+          "aria-label": `Go to commit ${seg.commit + 1}`,
+          onclick: () => seek(beatStart(steps, introOf(beats, seg.commit))),
+        },
+        el("span", { class: "fill", style: `width: ${Math.round(seg.filled * 100)}%` }),
+      ),
+    ),
+  );
+}
+
+/** Mermaid, imported on first use, so a plan without diagrams never downloads it. */
+let mermaid = null;
+let drawn = null;
+let drawing = 0;
+
+async function loadMermaid() {
+  if (mermaid === null) {
+    const { default: loaded } = await import("/vendor/mermaid.mjs");
+    loaded.initialize({
+      startOnLoad: false,
+      securityLevel: "strict",
+      suppressErrorRendering: true,
+      theme: window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "default",
+    });
+    mermaid = loaded;
   }
+  return mermaid;
 }
 
-async function perform(step, generation) {
-  player.position += 1;
-  if (step.kind === "commit") {
-    if (selected === step.commit) applyPlayback();
-    else {
-      selected = step.commit;
-      render();
-      $("main").scrollTop = 0;
+/** Draws the diagram for what is on screen into the side panel, or hides the panel. */
+async function renderDiagram() {
+  const panel = $("diagram");
+  const beat = player.view === "play" ? beats[beatAt(steps, player.position)] : undefined;
+  const shown = diagramAt(state.commits[selected], beat);
+  panel.hidden = shown === null;
+  if (shown === null || shown.source === drawn) return;
+  drawn = shown.source;
+  const unit = shown.unit === null ? null : unitsById.get(shown.unit);
+  $("diagram-from").textContent = unit ? unit.path : "this commit";
+  const body = $("diagram-body");
+  drawing += 1;
+  const id = `diagram-${drawing}`;
+  try {
+    const { svg } = await (await loadMermaid()).render(id, shown.source);
+    if (drawn !== shown.source) return;
+    // Mermaid sanitizes its own output under securityLevel "strict".
+    body.innerHTML = svg;
+  } catch (error) {
+    if (drawn !== shown.source) return;
+    body.replaceChildren(
+      el("p", { class: "diagram-error", text: "Mermaid could not draw this diagram:" }),
+      el("pre", { class: "diagram-error", text: error?.message ?? String(error) }),
+    );
+  }
+}
+
+function applyPlayback() {
+  const main = $("main");
+  if (hasDiagrams(state.commits)) renderDiagram();
+  for (const node of main.querySelectorAll(".ph, .countdown")) node.remove();
+  card.remove();
+  renderStage();
+  if (player.view !== "play") {
+    for (const node of main.querySelectorAll("[data-line], .unit")) {
+      node.classList.remove("pending", "struck", "in-chunk");
     }
-    setCaption(step.say);
-    speak(step.say);
-  } else if (step.kind === "unit") {
-    applyPlayback();
-    $("main")
-      .querySelector(`[data-unit="${step.unit}"]`)
-      ?.scrollIntoView({ block: "start", behavior: "smooth" });
-    if (step.say) {
-      setCaption(step.say);
-      await speakAndWait(step.say, generation);
+    for (const node of main.querySelectorAll(".concern")) node.classList.remove("pending");
+    return;
+  }
+  const { states, upcoming, current } = lineStates(beats, steps, player.position, selected);
+  const chunk = current === null ? null : beats[current];
+  const inChunk = new Set(chunk?.lines.map((line) => lineKey(chunk.unit, line)) ?? []);
+  for (const node of main.querySelectorAll("[data-line]")) {
+    const key = node.dataset.line;
+    const look = states.get(key);
+    node.classList.toggle("pending", look === "hidden");
+    node.classList.toggle("struck", look === "struck");
+    node.classList.toggle("in-chunk", inChunk.has(key) && look !== "hidden");
+  }
+  for (const node of main.querySelectorAll(".concern[data-after]")) {
+    node.classList.toggle("pending", states.get(node.dataset.after) === "hidden");
+  }
+  for (const node of main.querySelectorAll(".unit")) {
+    node.classList.toggle(
+      "in-chunk",
+      chunk?.unit === node.dataset.unit && chunk.lines.length === 0,
+    );
+  }
+  for (const [key, n] of upcoming) {
+    const line = main.querySelector(`[data-line="${key}"]`);
+    const ph = el("div", {
+      class: inChunk.has(key) ? "ph in-chunk" : "ph",
+      "data-ph": key,
+      text: `${n} line${n === 1 ? "" : "s"} coming${inChunk.has(key) ? "" : " next"}`,
+    });
+    line?.before(ph);
+  }
+
+  const step = steps[player.position];
+  const beat = beats[beatAt(steps, player.position)];
+  if (notice !== null) {
+    setCard(notice, "notice");
+    (beat?.kind === "chunk" ? anchorOf(beat) : null)?.before(card);
+    if (!card.isConnected) main.querySelector(".commit-head .message")?.after(card);
+    return;
+  }
+  if (step === undefined || beat === undefined) {
+    setCard(
+      isWalk()
+        ? "That is the whole branch. Leave any last comments, then finish the code review."
+        : "That is the whole plan.",
+      "end",
+    );
+    main.querySelector(".commit-head")?.append(card);
+    return;
+  }
+  if (beat.kind === "intro" && player.position === 0 && !player.playing && !started) {
+    setCard(readyText(), "label");
+    main.querySelector(".commit-head .message")?.after(card);
+    return;
+  }
+  if (beat.kind === "intro") {
+    const note = narrated ? null : "This plan has no narration. Showing commit messages.";
+    if (beat.narration !== null || (note !== null && beat.commit === 0)) {
+      setCard(beat.narration ?? note, "say");
+      main.querySelector(".commit-head .message")?.after(card);
     }
+  } else if (beat.kind === "chunk") {
+    setCard(chunkText(beat), beat.narration === null ? "label" : "say");
+    anchorOf(beat)?.before(card);
+  } else {
+    const countdown = el(
+      "div",
+      { class: "countdown" },
+      el("span", { text: beat.next === null ? "Last commit" : `Next: ${beat.next}` }),
+      el("span", { class: "bar", style: `animation-duration: ${step.ms}ms` }),
+    );
+    countdown.classList.toggle("paused", !player.playing);
+    stage.append(countdown);
+    watched.add(beat.commit);
+  }
+}
+
+/** Shows the step at the current position: its commit, its lines, and where the eye goes. */
+function present() {
+  const commit = commitOf(beats, beatAt(steps, player.position));
+  const beat = beats[beatAt(steps, player.position)];
+  if (commit !== selected) {
+    selected = commit;
+    render();
+    $("main").scrollTop = 0;
   } else {
     applyPlayback();
-    $("main")
-      .querySelector(".dl.current")
-      ?.scrollIntoView({ block: "nearest", behavior: "smooth" });
+    renderList();
   }
-  return sleep(stepDelay(step, player.speed), generation);
+  if (beat?.kind === "chunk") {
+    const anchor = card.isConnected ? card : anchorOf(beat);
+    if (anchor) scrollToChunk(anchor);
+  } else if (beat?.kind === "intro") scrollMain(0);
+  updatePlayer();
+}
+
+/** Waits out one step. A say step lasts its reading time or until speech ends, whichever is later. */
+async function perform(step, generation) {
+  if (step.kind === "show") {
+    const extra = dwellExtra(chunkConcerns(step.beat), state.decisions, player.speed);
+    return sleep(step.ms + extra, generation);
+  }
+  if (step.kind !== "say" || silent()) return sleep(step.ms, generation);
+  const [read, heard] = await Promise.all([
+    sleep(step.ms, generation),
+    speak(step.text, generation).then((ok) => ok && sleep(step.tail, generation)),
+  ]);
+  return read && heard && generation === player.generation;
+}
+
+/** The concerns that belong to a chunk beat. */
+function chunkConcerns(beat) {
+  const unit = unitsById.get(beats[beat]?.unit);
+  const commit = state.commits[beats[beat]?.commit];
+  if (unit?.kind !== "hunk" || !commit) return [];
+  return concernsInChunk(commit.concerns ?? [], beats, beat, unit.body);
+}
+
+/** A blocker stops playback as soon as the lines it is about are on screen. */
+function holdForConcern() {
+  const step = steps[player.position];
+  if (step === undefined) return;
+  const held = blockersToHold(chunkConcerns(step.beat), step, state.decisions, seenBlockers);
+  if (held.length === 0) return;
+  for (const concern of held) seenBlockers.add(concern.id);
+  notice = "The agent flagged a blocker here. Keep or dismiss it, then Space to continue.";
+  pause();
+  render();
+}
+
+/** Stops on an answer to the reviewer's own question, once the narration has been heard. */
+function holdForAnswer() {
+  const held = holdAt(beats, steps, player.position, cards, seenAnswers);
+  if (held.length === 0) return;
+  for (const card of held) seenAnswers.add(card.id);
+  notice =
+    held.length === 1
+      ? "Your question is answered here. Space to continue."
+      : `${held.length} of your questions are answered here. Space to continue.`;
+  pause();
+  render();
 }
 
 async function playLoop(generation) {
-  while (player.position < script.length) {
+  while (player.position < steps.length) {
     if (!(await sleep(0, generation))) return;
-    if (!(await perform(script[player.position], generation))) return;
+    if (!(await perform(steps[player.position], generation))) return;
+    player.position += 1;
+    present();
+    holdForAnswer();
+    holdForConcern();
   }
   player.playing = false;
-  setCaption(
-    isWalk()
-      ? "That is the whole branch. Leave any last comments, then finish the code review."
-      : "That is the whole plan.",
-  );
+  renderList();
   updatePlayer();
 }
 
-/** Moves playback to a step and starts a fresh loop, which waits while paused. */
+/** Moves to a step and starts a fresh loop, which waits while paused. */
 function seek(position) {
   synth?.cancel();
-  player.position = position;
+  notice = null;
+  player.position = Math.max(0, Math.min(steps.length, position));
   player.generation += 1;
-  selected = script[position]?.commit ?? commitAt(script, position);
-  render();
-  $("main").scrollTop = 0;
-  setCaption("");
+  present();
   playLoop(player.generation);
 }
 
 function play() {
   if (player.view !== "play") enterPlay();
-  if (player.position >= script.length) seek(0);
+  if (player.position >= steps.length) seek(0);
+  notice = null;
+  started = true;
   player.playing = true;
+  applyPlayback();
   synth?.resume();
   updatePlayer();
 }
 
-/** Pausing preselects the line just written, so the comment button is ready for it. */
 function pause() {
   player.playing = false;
   synth?.pause();
   updatePlayer();
-  const key = $("main").querySelector(".dl.current")?.dataset.line;
-  if (key === undefined) return;
-  const at = key.lastIndexOf(":");
-  const unitId = key.slice(0, at);
-  const change = unitsById.get(unitId)?.body?.[Number(key.slice(at + 1))]?.change;
-  const pickKey = `${selected}:${unitId}`;
-  if (change === undefined || (picks.get(pickKey)?.size ?? 0) > 0) return;
-  picks.set(pickKey, new Set([change]));
-  render();
 }
 
 function enterPlay() {
   player.view = "play";
   $("player").hidden = false;
-  seek(commitStart(script, selected));
-  updatePlayer();
+  render();
+  seek(beatStart(steps, introOf(beats, selected)));
 }
 
 function enterBrowse() {
@@ -638,8 +1706,79 @@ function enterBrowse() {
   updatePlayer();
 }
 
+function currentBeat() {
+  return beatAt(steps, player.position);
+}
+
+/** Seeks to a beat; the beat starts over, so its narration replays. */
+function toBeat(beat) {
+  seek(beatStart(steps, Math.max(0, Math.min(beats.length, beat))));
+}
+
+function stepBeat(delta) {
+  if (player.view !== "play") enterPlay();
+  toBeat(currentBeat() + delta);
+}
+
+function nextCommit() {
+  if (player.view !== "play") return select(selected + 1, { focus: true });
+  toBeat(introOf(beats, selected + 1));
+  focusHeading();
+}
+
+/** Restarts the commit; a second press within 1.5s goes to the previous one. */
+function previousCommit() {
+  if (player.view !== "play") return select(selected - 1, { focus: true });
+  focusHeading();
+  const now = performance.now();
+  const intro = introOf(beats, selected);
+  const again = now - restartedAt < 1500 || currentBeat() === intro;
+  restartedAt = now;
+  toBeat(again ? introOf(beats, selected - 1) : intro);
+}
+
+/** Pauses and opens a comment of a kind on the chunk on screen, its lines preselected. */
+function commentOnChunk(kind) {
+  if (player.view !== "play") return;
+  const at = currentBeat();
+  const beat = beats[at];
+  if (beat?.kind !== "chunk") {
+    report(new Error("Step to a chunk to comment on it."));
+    return;
+  }
+  pause();
+  const show = steps.findIndex((s) => s.kind === "show" && s.beat === at);
+  if (player.position < show) seek(show);
+  if (beat.lines.length === 0) {
+    const key = `box:${beat.commit}:${beat.unit}`;
+    openBoxes.add(key);
+    focusKey = key;
+  } else {
+    selection = { commit: beat.commit, unit: beat.unit, from: beat.lines[0], lines: beat.lines };
+    focusKey = `line:${beat.commit}:${beat.unit}`;
+  }
+  kindDrafts.set(focusKey, { kind, touched: true, severity: "" });
+  render();
+}
+
+function toggleKeys() {
+  const sheet = $("keys");
+  if (sheet.open) sheet.close();
+  else sheet.showModal();
+}
+
+function setSpeed(speed) {
+  player.speed = speed;
+  steps = schedule(beats, speed);
+  store("speed", String(speed));
+}
+
 function updatePlayer() {
-  $("play").textContent = player.playing ? "Pause" : "Play";
+  $("main").querySelector(".countdown")?.classList.toggle("paused", !player.playing);
+  const play = $("play");
+  play.querySelector(".icon").textContent = player.playing ? "❚❚" : "▶";
+  play.querySelector(".label").textContent = player.playing ? "Pause" : "Play";
+  play.setAttribute("aria-pressed", String(player.playing));
   $("view-toggle").textContent = player.view === "play" ? "Show all" : "Play";
   const mute = $("mute");
   mute.disabled = synth === null;
@@ -647,6 +1786,19 @@ function updatePlayer() {
   mute.setAttribute("aria-pressed", String(player.muted));
 }
 
+function setDiagramOpen(open) {
+  $("diagram-toggle").setAttribute("aria-expanded", String(open));
+  $("diagram").classList.toggle("collapsed", !open);
+}
+
+function toggleMute() {
+  if (!narrated || synth === null) return;
+  player.muted = !player.muted;
+  store("muted", String(player.muted));
+  if (player.muted) synth.cancel();
+  updatePlayer();
+}
+
 function loadVoices() {
   if (synth === null) return;
   voices = synth.getVoices();
@@ -661,16 +1813,22 @@ function loadVoices() {
   picker.value = player.voice ?? "";
 }
 
+/** The beats and steps of the plan on screen; again whenever a new plan version replaces it. */
+function buildPlayback() {
+  beats = buildScript(state.commits, state.units);
+  narrated = hasNarration(state.commits);
+  steps = schedule(beats, player.speed);
+  for (const id of ["voice-label", "mute"]) $(id).hidden = !narrated;
+}
+
 function setUpPlayer() {
   player.speed = parseSpeed(stored("speed"));
+  buildPlayback();
   player.muted = stored("muted") === "true";
   const speed = $("speed");
   speed.replaceChildren(...SPEEDS.map((s) => el("option", { value: String(s), text: `${s}x` })));
   speed.value = String(player.speed);
-  speed.addEventListener("change", () => {
-    player.speed = parseSpeed(speed.value);
-    store("speed", String(player.speed));
-  });
+  speed.addEventListener("change", () => setSpeed(parseSpeed(speed.value)));
   const picker = $("voice");
   picker.disabled = synth === null;
   picker.addEventListener("change", () => {
@@ -680,17 +1838,24 @@ function setUpPlayer() {
   synth?.addEventListener("voiceschanged", loadVoices);
   loadVoices();
   $("play").addEventListener("click", () => (player.playing ? pause() : play()));
-  $("prev").addEventListener("click", () => select(selected - 1));
-  $("next").addEventListener("click", () => select(selected + 1));
-  $("mute").addEventListener("click", () => {
-    player.muted = !player.muted;
-    store("muted", String(player.muted));
-    if (player.muted) synth?.cancel();
-    updatePlayer();
+  $("prev-commit").addEventListener("click", previousCommit);
+  $("next-commit").addEventListener("click", nextCommit);
+  $("prev-beat").addEventListener("click", () => stepBeat(-1));
+  $("next-beat").addEventListener("click", () => stepBeat(1));
+  $("keys-button").addEventListener("click", toggleKeys);
+  $("mute").addEventListener("click", toggleMute);
+  $("diagram-toggle").addEventListener("click", () => {
+    const open = $("diagram-toggle").getAttribute("aria-expanded") !== "true";
+    setDiagramOpen(open);
+    store("diagram", String(open));
+  });
+  setDiagramOpen(stored("diagram") !== "false");
+  $("view-toggle").addEventListener("click", () => {
+    if (player.view === "play") enterBrowse();
+    else play();
+    // Space should now drive playback, not this button.
+    focusHeading();
   });
-  $("view-toggle").addEventListener("click", () =>
-    player.view === "play" ? enterBrowse() : play(),
-  );
   updatePlayer();
 }
 
@@ -698,44 +1863,145 @@ function hasUnsentText() {
   return [...drafts.values()].some((text) => text.trim() !== "");
 }
 
+/** What the review holds, in words: comments, questions, kept concerns, unread answers. */
+function commentSummary() {
+  const kept = allConcerns(state.commits).filter(
+    (c) => state.decisions[c.id]?.decision === "kept",
+  ).length;
+  const unresolved = cards.filter((c) => c.status === "answered" && !c.resolved).length;
+  return endSummary({ comments: state.comments, kept, unresolved, walk: isWalk() });
+}
+
+/** The consolidated report as markdown, or null from a server that has none. */
+async function fetchReport() {
+  const res = await fetch(`${sessionPrefix}/api/report`).catch(() => null);
+  return res?.ok ? res.text() : null;
+}
+
+function copyButton(label, text) {
+  const button = el("button", {
+    type: "button",
+    text: label,
+    onclick: async () => {
+      await navigator.clipboard?.writeText(text).catch(() => {});
+      button.textContent = "Copied";
+    },
+  });
+  return button;
+}
+
+/**
+ * Asks before ending, with what the review holds. Resolves "end", or with agent concerns still
+ * undecided "keep-all", "dismiss-all" or "back".
+ */
+function confirmEnd() {
+  const sheet = $("confirm-end");
+  const unsent = hasUnsentText() ? " Some comment boxes have text you have not sent." : "";
+  const open = openConcerns().length;
+  const text = `${commentSummary()}.${unsent}`;
+  $("confirm-text").textContent = open === 0 ? text : `${undecidedPrompt(open)} ${text}`;
+  $("confirm-ok").textContent = $("end").textContent;
+  $("confirm-ok").hidden = open > 0;
+  $("confirm-keep-all").hidden = open === 0;
+  $("confirm-dismiss-all").hidden = open === 0;
+  $("confirm-back").textContent = open === 0 ? "Keep reviewing" : "Go back";
+  sheet.returnValue = "";
+  sheet.showModal();
+  return new Promise((resolve) => {
+    sheet.addEventListener("close", () => resolve(sheet.returnValue || "back"), { once: true });
+  });
+}
+
 async function endReview() {
-  if (
-    hasUnsentText() &&
-    !window.confirm("Some comment boxes have text you have not sent. End anyway?")
-  ) {
-    return;
+  if (player.playing) pause();
+  const answer = await confirmEnd();
+  if (answer === "back" || answer === "keep") return;
+  if (answer === "keep-all" || answer === "dismiss-all") {
+    const decision = answer === "keep-all" ? "kept" : "dismissed";
+    for (const concern of openConcerns()) {
+      await api("POST", `/api/concerns/${concern.id}`, { decision });
+      state.decisions = { ...state.decisions, [concern.id]: { concern: concern.id, decision } };
+    }
   }
-  await api("POST", "/api/end");
+  // The session is gone once it ends, so the report is read first. Nothing changes in between.
+  const markdown = await fetchReport();
+  const summary = commentSummary();
+  ending = true;
+  const { saved } = await api("POST", "/api/end").catch((error) => {
+    ending = false;
+    throw error;
+  });
   player.generation += 1;
   synth?.cancel();
-  const done = $("done");
-  const saved = `reviews/v${state.version}.json`;
-  done.replaceChildren(
-    isWalk()
-      ? el(
-          "p",
-          {},
-          `Code review saved to ${saved}. The author can run `,
-          el("code", { text: "follow-me feedback" }),
-          " to read it.",
-        )
-      : el(
-          "p",
-          {},
-          `Review saved to ${saved}. Run `,
-          el("code", { text: "follow-me feedback" }),
-          " or hand the session to your agent.",
-        ),
+  const at = saved.indexOf(".follow-me/");
+  const shortPath = (path) => (at === -1 ? path : path.slice(at));
+  const command = "follow-me feedback";
+  $("done").replaceChildren(
+    el(
+      "section",
+      {
+        class: markdown === null ? "done-card" : "done-card wide",
+        "aria-labelledby": "done-title",
+      },
+      el("h1", { id: "done-title", text: isWalk() ? "Code review saved" : "Review saved" }),
+      el("p", { class: "muted", text: `${summary}.` }),
+      el("p", {}, el("code", { class: "path", text: at === -1 ? saved : saved.slice(at) })),
+      markdown === null
+        ? null
+        : el(
+            "section",
+            { class: "report-box", "aria-label": "Report" },
+            el(
+              "div",
+              { class: "report-head" },
+              el("strong", { text: "Report" }),
+              el("code", { text: shortPath(reportPath(saved)) }),
+              copyButton("Copy markdown", markdown),
+            ),
+            el("pre", { class: "report", tabindex: "0", text: markdown }),
+          ),
+      el(
+        "p",
+        { class: "next" },
+        isWalk() ? "The author reads it with " : "Next, run ",
+        el("code", { text: command }),
+        copyButton("Copy", command),
+      ),
+      isWalk() ? null : el("p", { class: "muted", text: "or hand the session to your agent." }),
+      el("p", {}, el("a", { href: "/", text: "All sessions" })),
+    ),
   );
-  done.hidden = false;
+  $("done").hidden = false;
+  $("done-title").setAttribute("tabindex", "-1");
+  $("done-title").focus();
 }
 
+/** Playback keys. Shift+arrows move by commit, plain arrows by chunk. */
+const KEYS = {
+  ArrowRight: (shift) => (shift ? nextCommit() : stepBeat(1)),
+  ArrowLeft: (shift) => (shift ? previousCommit() : stepBeat(-1)),
+  l: () => stepBeat(1),
+  h: () => stepBeat(-1),
+  n: nextCommit,
+  j: nextCommit,
+  p: previousCommit,
+  k: previousCommit,
+  r: () => player.view === "play" && toBeat(currentBeat()),
+  c: () => commentOnChunk("change"),
+  q: () => commentOnChunk("question"),
+  y: () => decideCurrent("kept"),
+  x: () => decideCurrent("dismissed"),
+  m: toggleMute,
+  "?": toggleKeys,
+};
+
 document.addEventListener("keydown", (event) => {
   const target = event.target;
   if (
     target instanceof HTMLTextAreaElement ||
     target instanceof HTMLInputElement ||
-    target instanceof HTMLSelectElement
+    target instanceof HTMLSelectElement ||
+    $("keys").open
   ) {
     return;
   }
@@ -745,26 +2011,191 @@ document.addEventListener("keydown", (event) => {
     event.preventDefault();
     if (player.playing) pause();
     else play();
+    return;
   }
-  if (event.key === "j" || event.key === "n") select(selected + 1);
-  if (event.key === "k" || event.key === "p") select(selected - 1);
+  const action = Object.hasOwn(KEYS, event.key) ? KEYS[event.key] : undefined;
+  if (action === undefined) return;
+  event.preventDefault();
+  action(event.shiftKey);
 });
 
 $("end").addEventListener("click", () => guarded(endReview));
+$("commits-toggle").addEventListener("click", () =>
+  setListOpen(!$("sidebar").classList.contains("open")),
+);
+$("sidebar").addEventListener("keydown", (event) => {
+  if (event.key === "Escape" && $("sidebar").classList.contains("open")) {
+    setListOpen(false);
+    $("commits-toggle").focus();
+  }
+});
+window.addEventListener("resize", markClamped);
+for (const type of ["mouseover", "focusin"]) $("commits").addEventListener(type, showRailTip);
+for (const type of ["mouseout", "focusout"]) $("commits").addEventListener(type, hideRailTip);
+window.addEventListener("focus", () => renderSwitcher());
+renderSwitcher();
 
-guarded(async () => {
-  state = await api("GET", "/api/state");
-  indexOwnership();
-  script = buildScript(state.commits, state.units);
+function renderHeader() {
   const walk = isWalk();
   document.title = walk ? "follow-me code review" : "follow-me review";
   $("summary").textContent = walk
     ? `${state.anchor.branch} · Code review`
     : `${state.anchor.branch} · Review of plan v${state.version}`;
   $("end").textContent = walk ? "Finish code review" : "End review";
+}
+
+/** Makes a fetched state the page's own: indexes, highlighting and header. */
+async function adopt(fresh) {
+  state = {
+    ...fresh,
+    decisions: decisionsById(fresh.concerns ?? []),
+    resolved: fresh.resolved ?? [],
+    previous: fresh.previous ?? null,
+  };
+  indexOwnership();
+  highlighted.clear();
+  await loadHighlighting(state.units);
+  renderHeader();
+}
+
+/** Says a plan arrived, and offers the answers it brings when it has any. */
+function announceVersion() {
+  const answered = answeredCount(state.previous);
+  $("banner-text").textContent = bannerText(state.version, answered);
+  $("banner-show").hidden = answered === 0;
+  $("banner").hidden = false;
+}
+
+/** A newer plan arrived: swap it in place and stay on the commit being read when it survives. */
+async function swapVersion() {
+  const fresh = await api("GET", "/api/state");
+  if (fresh.version <= state.version) return;
+  const title = state.commits[selected] ? firstLine(state.commits[selected].message) : null;
+  const was = selected;
+  await adopt(fresh);
+  buildPlayback();
+  selected = keepCommit(title, was, state.commits);
+  watched.clear();
+  announceVersion();
+  if (player.view === "play") seek(beatStart(steps, introOf(beats, selected)));
+  else render();
+}
+
+let ending = false;
+
+function showEnded() {
+  if (ending || !$("done").hidden) return;
+  player.generation += 1;
+  synth?.cancel();
+  $("done").replaceChildren(
+    el(
+      "section",
+      { class: "done-card", "aria-labelledby": "done-title" },
+      el("h1", { id: "done-title", text: "Review ended" }),
+      el("p", { class: "muted", text: "This review was ended in another window. It is saved." }),
+      el("p", {}, el("a", { href: "/", text: "All sessions" })),
+    ),
+  );
+  $("done").hidden = false;
+}
+
+async function receive(event) {
+  const { state: next, effect } = applyEvent(state, event);
+  state = next;
+  if (effect === "refetch") await swapVersion();
+  else if (effect === "ended") showEnded();
+  else render();
+}
+
+const sleep_ = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The page's whole state again, after the server's log no longer matches what we followed. */
+async function resync() {
+  const fresh = await api("GET", "/api/state");
+  const title = state.commits[selected] ? firstLine(state.commits[selected].message) : null;
+  const was = selected;
+  await adopt(fresh);
+  buildPlayback();
+  selected = keepCommit(title, was, state.commits);
+  render();
+  return fresh.seq ?? 0;
+}
+
+/** Reads the push stream until it fails twice in a row, resolving with the last seq seen. */
+function followStream(since, onEvent) {
+  return new Promise((resolve) => {
+    let last = since;
+    let failures = 0;
+    const source = new EventSource(`${sessionPrefix}/api/events/stream?since=${since}`);
+    const stop = () => {
+      source.close();
+      resolve(last);
+    };
+    source.addEventListener("message", async (message) => {
+      failures = 0;
+      try {
+        const event = JSON.parse(message.data);
+        last = Math.max(last, event.seq ?? 0);
+        await onEvent(event);
+      } catch {
+        // A malformed event is skipped; the next one still applies.
+      }
+      if (!$("done").hidden) stop();
+    });
+    source.addEventListener("error", () => {
+      failures += 1;
+      if (failures >= 2 || source.readyState === EventSource.CLOSED) stop();
+    });
+  });
+}
+
+/** Long-polls for what others changed, reconnecting with backoff after an error. */
+async function pollEvents(from) {
+  let since = from;
+  let failures = 0;
+  while ($("done").hidden) {
+    try {
+      const res = await fetch(`${sessionPrefix}/api/events?since=${since}&timeout=25000`);
+      // A server without live updates answers 404; the page then works as it always did.
+      if (res.status === 404) return;
+      if (res.status === 409) {
+        since = await resync();
+        continue;
+      }
+      if (!res.ok) throw new Error(`events failed with ${res.status}`);
+      const reply = await res.json();
+      failures = 0;
+      since = nextSince(since, reply);
+      for (const event of reply.events ?? []) await receive(event);
+    } catch {
+      failures += 1;
+      await sleep_(backoffMs(failures));
+    }
+  }
+}
+
+/** Follows the server from the seq of the state we hold, so nothing between is missed. */
+async function followEvents() {
+  let since = state.seq ?? 0;
+  if ("EventSource" in window) since = await followStream(since, receive);
+  if ($("done").hidden) await pollEvents(since);
+}
+
+$("banner-show").addEventListener("click", () => {
+  setListOpen(true);
+  $("answers").scrollIntoView({ block: "nearest" });
+  $("answers").querySelector("button")?.focus();
+});
+
+$("banner-close").addEventListener("click", () => {
+  $("banner").hidden = true;
+});
+
+guarded(async () => {
+  await adopt(await api("GET", "/api/state"));
   setUpPlayer();
-  if (walk) {
-    enterPlay();
-    setCaption("Press Play or space to watch this branch being written.");
-  } else render();
+  if (isWalk()) enterPlay();
+  else render();
+  if (answeredCount(state.previous) > 0) announceVersion();
+  followEvents();
 });