bottleship 0.1.0-prototype.1 → 0.1.0-prototype.2

package/review-app/src/kit/live.ts

@@ -0,0 +1,91 @@
+// The review server's live side: events from review hooks and step scripts, step runs, and where instances are reachable.
+import { useEffect, useState, useSyncExternalStore } from "react";
+import type { ReviewComment } from "./comments";
+
+export type Status = "ok" | "fail" | "neutral";
+
+export interface ReviewEvent {
+  seq: number;
+  instance: string;
+  kind: "request" | "hook" | "ok" | "fail";
+  text: string;
+  at?: string;
+  // set by the server: the step running when the event arrived
+  step?: string;
+  flow?: { id: string; edge?: [string, string]; node?: string; status?: Status; label?: string };
+  overlay?: { title: string; body?: string; status: Status };
+}
+
+export interface StepState { id: string; status: "running" | "done" | "failed"; output?: string }
+
+export interface Verdict { event?: "COMMENT" | "APPROVE" | "REQUEST_CHANGES"; body?: string }
+// local reviews: whether the developer's agent is waiting for comments (bottleship agent review next)
+export interface AgentState { local: boolean; listening: boolean }
+// the change was updated after comments; refreshed once the tour shows it
+export interface Update { n: number; at: string; note: string; refreshed?: string }
+interface Live { events: ReviewEvent[]; steps: Record<string, StepState>; connected: boolean; comments: ReviewComment[]; verdict: Verdict; agent: AgentState; updates: Update[] }
+
+let live: Live = { events: [], steps: {}, connected: false, comments: [], verdict: {}, agent: { local: false, listening: false }, updates: [] };
+const listeners = new Set<() => void>();
+const set = (next: Partial<Live>) => {
+  live = { ...live, ...next };
+  listeners.forEach((l) => l());
+};
+
+let source: EventSource | undefined;
+function connect() {
+  if (source) return;
+  source = new EventSource("api/events");
+  const on = (name: string, fn: (d: any) => void) => source!.addEventListener(name, (e) => fn(JSON.parse((e as MessageEvent).data)));
+  on("state", (d) => set({ steps: d.steps, events: [] }));
+  on("event", (e: ReviewEvent) => set({ events: [...live.events, e] }));
+  on("ready", () => set({ connected: true }));
+  on("step", (s: StepState) => set({ steps: { ...live.steps, [s.id]: s } }));
+  on("reset", () => set({ events: [], steps: {} }));
+  on("comments", (d: { comments: ReviewComment[] }) => set({ comments: d.comments }));
+  on("verdict", (v: Verdict) => set({ verdict: v }));
+  on("agent", (a: AgentState) => set({ agent: a }));
+  on("updates", (d: { updates: Update[] }) => set({ updates: d.updates }));
+  source.onerror = () => set({ connected: false });
+}
+
+// the comments change through these; the server streams the new list back to every open tab
+export const setComments = (comments: ReviewComment[]) => set({ comments });
+export const liveComments = () => live.comments;
+// the verdict as it is now, for saves that land after the reviewer has changed it
+export const liveVerdict = () => live.verdict;
+
+// how the reviewer means to finish, sent with the review when they submit it
+export async function saveVerdict(v: Verdict) {
+  set({ verdict: v });
+  await fetch("api/verdict", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(v) }).catch(() => {});
+}
+
+export function useLive(): Live {
+  connect();
+  return useSyncExternalStore(
+    (l) => (listeners.add(l), () => listeners.delete(l)),
+    () => live,
+  );
+}
+
+const post = (path: string) => fetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+
+// runs ~/review/steps/<id>.sh in the box; events that arrive meanwhile are tagged with the step
+export const runStep = (id: string) => post(`api/steps/${encodeURIComponent(id)}/run`);
+export const resetEvents = () => post("api/reset");
+
+// where the reviewer's browser reaches each port the box publishes
+let urls: Promise<Record<string, string>> | undefined;
+export function useUrl(port: number, path = "/"): string | undefined {
+  const [url, setUrl] = useState<string>();
+  useEffect(() => {
+    urls ??= fetch("api/urls").then((r) => (r.ok ? r.json() : {}), () => ({}));
+    // the path goes under the instance's address, which may itself have a path
+    urls.then((m) => setUrl(new URL(path.replace(/^\/+/, ""), (m[port] ?? `http://localhost:${port}`).replace(/\/?$/, "/")).href));
+  }, [port, path]);
+  return url;
+}
+
+// a file under ~/review in the box, e.g. a screenshot taken with scripts/shot.cjs
+export const file = (path: string) => `files/${path.replace(/^\/+/, "")}`;

package/review-app/src/kit/media.tsx

@@ -0,0 +1,348 @@
+// What a reviewer looks at: the running instances, screenshots, and two screenshots compared.
+import { useEffect, useLayoutEffect, useRef, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { file, useUrl } from "./live";
+import { useChapter, useNav, type Instance } from "./review";
+import { Icon } from "./ui";
+import { referToChat } from "./comments";
+
+// whether anything answers at url; retries every few seconds until it does, e.g. while the app starts
+function useReachable(url?: string): boolean | undefined {
+  const [ok, setOk] = useState<boolean>();
+  useEffect(() => {
+    if (!url) return;
+    let stop = false, timer: ReturnType<typeof setTimeout>;
+    const probe = () =>
+      fetch(url, { mode: "no-cors", cache: "no-store" }).then(
+        () => !stop && setOk(true),
+        () => { if (!stop) { setOk(false); timer = setTimeout(probe, 3000); } },
+      );
+    probe();
+    return () => { stop = true; clearTimeout(timer); };
+  }, [url]);
+  return ok;
+}
+
+// one instance's app, with nothing around it; the bar above names it
+function Frame({ inst, hidden }: { inst: Instance; hidden?: boolean }) {
+  const url = useUrl(inst.port, inst.path);
+  const reachable = useReachable(url);
+  return (
+    <div className="frame" hidden={hidden}>
+      <div className="fview">
+        {url && reachable && <iframe src={url} title={inst.label} />}
+        {reachable === false && (
+          <div className="down">
+            <b>{inst.label} is not answering</b>
+            <span>Nothing responds on port {inst.port} in the box yet. It may still be starting; this retries every few seconds.</span>
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
+
+// the status the instance's latest overlay reported, for its dot
+function useStatus(id: string) {
+  const { events } = useChapter();
+  return [...events].reverse().find((e) => e.instance === id && e.overlay)?.overlay?.status;
+}
+
+function Open({ inst }: { inst: Instance }) {
+  const url = useUrl(inst.port, inst.path);
+  return url ? <a className="icon-btn" href={url} target="_blank" rel="noreferrer" title={`Open ${url.replace(/^https?:\/\/[^/]+/, "") || "/"} in a new tab`} aria-label={`Open ${inst.label} in a new tab`}>{Icon.external}</a> : null;
+}
+
+// side by side: a label over each app
+function InstanceLabel({ inst, lead }: { inst: Instance; lead?: ReactNode }) {
+  const status = useStatus(inst.id);
+  return (
+    <div className="live-label">
+      {lead}
+      <span className={`lamp${status ? " " + status : ""}`} />
+      <b>{inst.label}</b>
+      <Open inst={inst} />
+    </div>
+  );
+}
+
+// below this width per app, the apps show one at a time
+const MIN_WIDTH = 700;
+
+// the guide column folds away to give the apps the width; it stays folded across chapters
+// with live apps, and shows again on a chapter without them, which has no toggle
+let guideOff = false;
+function GuideToggle() {
+  const [off, setOff] = useState(guideOff);
+  useEffect(() => {
+    guideOff = off;
+    document.documentElement.toggleAttribute("data-guide-off", off);
+    return () => document.documentElement.removeAttribute("data-guide-off");
+  }, [off]);
+  const label = off ? "Show the guide" : "Hide the guide";
+  return <button className="icon-btn" onClick={() => setOff(!off)} title={label} aria-label={label} aria-pressed={off}>{Icon.panel}</button>;
+}
+
+// base / head as a sliding switch, each with the status its overlay reported
+function InstanceSwitch({ list, current, onChange }: { list: Instance[]; current: string; onChange: (id: string) => void }) {
+  const group = useRef<HTMLDivElement>(null);
+  const [pill, setPill] = useState<{ x: number; w: number; moved: boolean }>();
+  useLayoutEffect(() => {
+    const b = group.current?.querySelector<HTMLElement>(`[data-id="${current}"]`);
+    if (b) setPill((p) => ({ x: b.offsetLeft, w: b.offsetWidth, moved: !!p }));
+  }, [current]);
+  return (
+    <div className="modes" role="group" aria-label="Instance" ref={group}>
+      {pill && <span className={`pill${pill.moved ? " moved" : ""}`} style={{ width: pill.w, transform: `translateX(${pill.x}px)` }} />}
+      {list.map((i) => <SwitchItem key={i.id} inst={i} active={i.id === current} onClick={() => onChange(i.id)} />)}
+    </div>
+  );
+}
+
+function SwitchItem({ inst, active, onClick }: { inst: Instance; active: boolean; onClick: () => void }) {
+  const status = useStatus(inst.id);
+  return <button data-id={inst.id} aria-pressed={active} onClick={onClick}><span className={`lamp${status ? " " + status : ""}`} />{inst.label}</button>;
+}
+
+// the running instances: side by side when each gets MIN_WIDTH, otherwise one at a time with a switch (or S).
+// Both stay loaded either way, so switching keeps their state. Each name carries the status its events reported.
+export function Live({ ids }: { ids?: string[] }) {
+  const { instances } = useChapter();
+  const { chapter } = useNav();
+  const list = instances.filter((i) => !ids || ids.includes(i.id));
+  const [current, setCurrent] = useState(list[list.length - 1]?.id ?? "");
+  const body = useRef<HTMLDivElement>(null);
+  const [wide, setWide] = useState(true);
+  useLayoutEffect(() => {
+    if (!body.current) return;
+    const ro = new ResizeObserver(([e]) => setWide(list.length < 2 || e.contentRect.width / list.length >= MIN_WIDTH));
+    ro.observe(body.current);
+    return () => ro.disconnect();
+  }, [list.length]);
+  useEffect(() => {
+    if (wide) return;
+    const key = (e: KeyboardEvent) => {
+      if ((e.key !== "s" && e.key !== "S") || e.metaKey || e.ctrlKey || e.altKey || /input|textarea|select/i.test((e.target as HTMLElement).tagName)) return;
+      setCurrent((c) => list[(list.findIndex((i) => i.id === c) + 1) % list.length].id);
+    };
+    addEventListener("keydown", key);
+    return () => removeEventListener("keydown", key);
+  }, [wide, list]);
+  const shown = list.find((i) => i.id === current);
+  return (
+    <div className="live">
+      {wide ? (
+        <div className="live-labels" style={{ gridTemplateColumns: `repeat(${list.length}, minmax(0, 1fr))` }}>
+          {list.map((i, n) => <InstanceLabel key={i.id} inst={i} lead={n === 0 && chapter ? <GuideToggle /> : undefined} />)}
+        </div>
+      ) : (
+        <div className="live-bar">
+          {chapter && <GuideToggle />}
+          <div className="live-right">
+            <kbd title="Press S to switch">S</kbd>
+            <InstanceSwitch list={list} current={current} onChange={setCurrent} />
+            {shown && <Open inst={shown} />}
+          </div>
+        </div>
+      )}
+      <div className={`live-body${wide ? " wide" : ""}`} ref={body} style={wide ? { gridTemplateColumns: `repeat(${list.length}, minmax(0, 1fr))` } : undefined}>
+        {list.map((i) => <Frame key={i.id} inst={i} hidden={!wide && i.id !== current} />)}
+      </div>
+    </div>
+  );
+}
+
+// a screenshot opened full size over the page; Escape or a click closes it
+function Zoom({ src, alt, onClose }: { src: string; alt: string; onClose: () => void }) {
+  useEffect(() => {
+    const key = (e: KeyboardEvent) => e.key === "Escape" && onClose();
+    addEventListener("keydown", key);
+    return () => removeEventListener("keydown", key);
+  }, [onClose]);
+  return createPortal(<div className="zoom" onClick={onClose} role="dialog" aria-label={alt}><img src={src} alt={alt} /></div>, document.body);
+}
+
+function Img({ src, alt }: { src: string; alt: string }) {
+  const [open, setOpen] = useState(false);
+  return (
+    <>
+      <button className="media" onClick={() => setOpen(true)} title="Open full size"><img src={src} alt={alt} loading="lazy" /></button>
+      {open && <Zoom src={src} alt={alt} onClose={() => setOpen(false)} />}
+    </>
+  );
+}
+
+function FigHead({ title, children }: { title?: ReactNode; children?: ReactNode }) {
+  if (!title && !children) return null;
+  return <div className="fig-head"><div className="fig-title">{title}</div><div className="fig-actions">{children}</div></div>;
+}
+
+// brings a picture into the chat with the agent, by its title or file
+function AddToChat({ figure, title }: { figure: string; title?: ReactNode }) {
+  const name = typeof title === "string" && title ? title : figure.split("/").pop()!;
+  return <button className="icon-btn fig-remark" onClick={() => referToChat({ kind: "selection", text: figure, where: `the picture "${name}"` })} title="Add to the chat with the agent" aria-label="Add this picture to the chat with the agent">{Icon.cursorPlus}</button>;
+}
+
+// a screenshot taken in the box with scripts/shot.cjs, under ~/review/shots
+export function Shot({ src, alt = "", title, caption }: { src: string; alt?: string; title?: ReactNode; caption?: ReactNode }) {
+  return (
+    <figure className="fig">
+      <FigHead title={title}><AddToChat figure={src} title={title} /></FigHead>
+      <Img src={file(src)} alt={alt || (typeof title === "string" ? title : "")} />
+      {caption && <figcaption>{caption}</figcaption>}
+    </figure>
+  );
+}
+
+// a recording from scripts/clip.cjs: "shots/<name>.webm#t=<s>", where #t is where the page was ready
+const clipSrc = (src: string) => {
+  const [path, t] = src.split("#t=");
+  return { url: file(path), start: Number(t) || 0 };
+};
+
+// a short recording of a flow, looping from where the page was ready; with base and head, both side by side and in
+// step, so the same moment shows on each. Click to pause. With reduced motion it waits to be played.
+export function Clip({ src, base, head, labels = ["Base", "Head"], title, caption }: { src?: string; base?: string; head?: string; labels?: [string, string]; title?: ReactNode; caption?: ReactNode }) {
+  const sources = (src ? [src] : [base, head]).filter((x): x is string => !!x).map(clipSrc);
+  const videos = useRef<(HTMLVideoElement | null)[]>([]);
+  const still = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+  const [playing, setPlaying] = useState(!still);
+  const each = (fn: (v: HTMLVideoElement, i: number) => void) => videos.current.forEach((v, i) => v && fn(v, i));
+  // every video starts over when the longest one ends, so a pair stays in step
+  const restart = () => each((v, i) => { v.currentTime = sources[i].start; if (playing) void v.play().catch(() => {}); });
+  useEffect(() => {
+    each((v) => (playing ? void v.play().catch(() => {}) : v.pause()));
+  }, [playing]);
+  const ended = () => videos.current.every((v) => !v || v.ended) && restart();
+  const toggle = () => setPlaying((p) => !p);
+  return (
+    <figure className="fig clip">
+      <FigHead title={title}>
+        <AddToChat figure={src ?? base ?? ""} title={title} />
+        <button className="icon-btn" onClick={toggle} title={playing ? "Pause" : "Play"} aria-label={playing ? "Pause" : "Play"}>{playing ? Icon.pause : Icon.play}</button>
+      </FigHead>
+      <div className={sources.length > 1 ? "cmp-side" : undefined}>
+        {sources.map((s, i) => (
+          <div className="tagged" key={s.url}>
+            <video
+              ref={(el) => { videos.current[i] = el; }}
+              className="media still"
+              src={`${s.url}#t=${s.start}`}
+              muted playsInline preload="auto"
+              autoPlay={!still}
+              onEnded={ended}
+              onClick={toggle}
+            />
+            {sources.length > 1 && <Tag>{labels[i]}</Tag>}
+          </div>
+        ))}
+      </div>
+      {caption && <figcaption>{caption}</figcaption>}
+    </figure>
+  );
+}
+
+// marks every pixel that differs between two same-size screenshots
+function DiffCanvas({ a, b }: { a: string; b: string }) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const [note, setNote] = useState("");
+  useEffect(() => {
+    const load = (s: string) => new Promise<HTMLImageElement>((ok, fail) => { const i = new Image(); i.onload = () => ok(i); i.onerror = fail; i.src = s; });
+    Promise.all([load(a), load(b)]).then(([x, y]) => {
+      const w = Math.max(x.width, y.width), h = Math.max(x.height, y.height);
+      const c = canvas.current!;
+      c.width = w;
+      c.height = h;
+      const ctx = c.getContext("2d")!;
+      const px = (img: HTMLImageElement) => { ctx.clearRect(0, 0, w, h); ctx.drawImage(img, 0, 0); return ctx.getImageData(0, 0, w, h); };
+      const da = px(x), db = px(y), out = ctx.createImageData(w, h);
+      let changed = 0;
+      for (let i = 0; i < da.data.length; i += 4) {
+        const d = Math.abs(da.data[i] - db.data[i]) + Math.abs(da.data[i + 1] - db.data[i + 1]) + Math.abs(da.data[i + 2] - db.data[i + 2]);
+        const g = 255 - (255 - (db.data[i] + db.data[i + 1] + db.data[i + 2]) / 3) * 0.25;
+        if (d > 24) {
+          changed++;
+          out.data.set([235, 87, 87, 255], i);
+        } else out.data.set([g, g, g, 255], i);
+      }
+      ctx.putImageData(out, 0, 0);
+      const pct = (changed / (w * h)) * 100;
+      setNote(changed === 0 ? "No pixels differ" : `${pct < 0.1 ? "<0.1" : pct.toFixed(1)}% of pixels differ, marked red`);
+    }, () => setNote("Could not load both screenshots"));
+  }, [a, b]);
+  return <div className="cmp-diff"><div className="media still"><canvas ref={canvas} /></div><div className="cmp-note">{note}</div></div>;
+}
+
+const MODES = [["side", "Side by side"], ["slider", "Slider"], ["diff", "Difference"]] as const;
+type Mode = (typeof MODES)[number][0];
+
+// the compare modes; a background slides to the selected one
+function Modes({ value, onChange }: { value: Mode; onChange: (m: Mode) => void }) {
+  const group = useRef<HTMLDivElement>(null);
+  const [pill, setPill] = useState<{ x: number; w: number; moved: boolean }>();
+  useLayoutEffect(() => {
+    const place = () => {
+      const b = group.current?.querySelector<HTMLElement>(`[data-mode="${value}"]`);
+      if (b) setPill((p) => ({ x: b.offsetLeft, w: b.offsetWidth, moved: !!p }));
+    };
+    place();
+    addEventListener("resize", place);
+    return () => removeEventListener("resize", place);
+  }, [value]);
+  return (
+    <div className="modes" role="group" aria-label="Compare as" ref={group}>
+      {pill && <span className={`pill${pill.moved ? " moved" : ""}`} style={{ width: pill.w, transform: `translateX(${pill.x}px)` }} />}
+      {MODES.map(([m, name]) => (
+        <button key={m} data-mode={m} aria-pressed={value === m} onClick={() => onChange(m)}>{name}</button>
+      ))}
+    </div>
+  );
+}
+
+const Tag = ({ children, side }: { children: ReactNode; side?: "l" | "r" }) => <span className={`tag${side ? " " + side : ""}`}>{children}</span>;
+
+// two screenshots of the same thing, e.g. base and head: side by side, a slider, or the pixels that differ
+export function Compare({ base, head, labels = ["Base", "Head"], title, caption, mode: start = "side" }: { base: string; head: string; labels?: [string, string]; title?: ReactNode; caption?: ReactNode; mode?: "side" | "slider" | "diff" }) {
+  const [mode, setMode] = useState(start);
+  const [x, setX] = useState(50);
+  const [dragging, setDragging] = useState(false);
+  const move = (e: React.PointerEvent<HTMLDivElement>) => setX(Math.min(100, Math.max(0, ((e.clientX - e.currentTarget.getBoundingClientRect().left) / e.currentTarget.clientWidth) * 100)));
+  // arrows step the slider while it has focus, instead of turning the page
+  const key = (e: React.KeyboardEvent) => {
+    if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
+    e.preventDefault();
+    e.stopPropagation();
+    setX((v) => Math.min(100, Math.max(0, v + (e.key === "ArrowLeft" ? -5 : 5))));
+  };
+  return (
+    <figure className="fig compare">
+      <FigHead title={title}>
+        <AddToChat figure={base} title={title} />
+        <Modes value={mode} onChange={setMode} />
+      </FigHead>
+      {mode === "side" && (
+        <div className="cmp-side">
+          <div className="tagged"><Img src={file(base)} alt={labels[0]} /><Tag>{labels[0]}</Tag></div>
+          <div className="tagged"><Img src={file(head)} alt={labels[1]} /><Tag>{labels[1]}</Tag></div>
+        </div>
+      )}
+      {mode === "slider" && (
+        <div
+          className={`media still cmp-slider${dragging ? " dragging" : ""}`}
+          tabIndex={0} role="slider" aria-label={`${labels[0]} and ${labels[1]}`} aria-valuenow={Math.round(x)} aria-valuemin={0} aria-valuemax={100}
+          onKeyDown={key}
+          onPointerDown={(e) => { e.currentTarget.setPointerCapture(e.pointerId); setDragging(true); move(e); }}
+          onPointerMove={(e) => e.buttons && move(e)}
+          onPointerUp={() => setDragging(false)}
+        >
+          <img src={file(head)} alt={labels[1]} draggable={false} />
+          <img src={file(base)} alt={labels[0]} className="top" draggable={false} style={{ clipPath: `inset(0 ${100 - x}% 0 0)` }} />
+          <div className="handle" style={{ left: `${x}%` }}><span className="grip"><svg viewBox="0 0 16 16"><path d="M6 4.5 2.5 8 6 11.5M10 4.5 13.5 8 10 11.5" /></svg></span></div>
+          <Tag side="l">{labels[0]}</Tag><Tag side="r">{labels[1]}</Tag>
+        </div>
+      )}
+      {mode === "diff" && <DiffCanvas a={file(base)} b={file(head)} />}
+      {caption && <figcaption>{caption}</figcaption>}
+    </figure>
+  );
+}

package/review-app/src/kit/overview.tsx

@@ -0,0 +1,161 @@
+// The overview page: what the PR does, before and after, where it happens, what to look at and which claims hold.
+import { useState, type ReactNode } from "react";
+import { diffs, pr, shortTitle } from "./pr";
+import { useNav, type Target } from "./review";
+import { FileLine, Icon, Refs, Row, Rows, Section } from "./ui";
+
+// the page frame: title and PR line on top, the files and the way into the tour at the bottom
+export function Overview({ children }: { children: ReactNode }) {
+  const { review, go } = useNav();
+  return (
+    <section className="view orient">
+      <div>
+        <h1 className="title">{shortTitle}</h1>
+        <div className="meta">
+          <span className="who"><span className="avatar">{pr.author[0]?.toUpperCase()}</span>{pr.author}</span>
+          <span>{pr.repo} {pr.ref}</span>
+          <Refs from={pr.headRef} to={pr.baseRef} label={`${pr.headRef} into ${pr.baseRef}`} />
+        </div>
+      </div>
+      {children}
+      <Files />
+      <div className="cta">
+        {review.chapters.length > 0 && (
+          <button className="btn primary" onClick={() => go({ chapter: review.chapters[0].id })}>{Icon.play} Start the tour</button>
+        )}
+        <button className="btn ghost" onClick={() => go("changes")}>Skip to changes</button>
+      </div>
+    </section>
+  );
+}
+
+// the most changed files first, each a link to its diff; a long list shows the first few until asked
+function Files() {
+  const { review, go } = useNav();
+  const [all, setAll] = useState(false);
+  const files = [...pr.files].sort((a, b) => b.add + b.del - (a.add + a.del));
+  const shown = all || files.length <= 10 ? files : files.slice(0, 8);
+  const target = (path: string): Target | undefined => {
+    const g = review.groups.find((x) => x.file === path);
+    return g ? { group: g.id } : diffs[path] ? { group: `file-${path}` } : undefined;
+  };
+  return (
+    <Section label="Files" count={files.length}>
+      <div className="file-list">
+        {shown.map((f) => {
+          const to = target(f.path);
+          const line = <FileLine path={f.path} add={f.add} del={f.del} />;
+          return to
+            ? <button key={f.path} className="li file-li" onClick={() => go(to)}>{line}</button>
+            : <div key={f.path} className="li file-li">{line}</div>;
+        })}
+        {shown.length < files.length && (
+          <button className="li file-li files-more" onClick={() => setAll(true)}>Show all {files.length} files</button>
+        )}
+      </div>
+    </Section>
+  );
+}
+
+export const Lead = ({ children }: { children: ReactNode }) => <p className="lead">{children}</p>;
+
+// before above after, each a full line; the label sits in a narrow gutter
+export function BeforeAfter({ before, after }: { before: ReactNode; after: ReactNode }) {
+  return (
+    <dl className="ba">
+      <dt>Before</dt><dd>{before}</dd>
+      <dt className="after">After</dt><dd className="after">{after}</dd>
+    </dl>
+  );
+}
+
+// "Chapter 2" or "Code" for a link target
+export function useTargetLabel() {
+  const { review } = useNav();
+  return (t: Target) =>
+    t === "overview" ? "Overview" : t === "changes" ? "Code" : t === "finish" ? "Finish" : t === "pr" ? "Pull request" : "chapter" in t ? `Chapter ${review.chapters.findIndex((c) => c.id === t.chapter) + 1}` : "Code";
+}
+
+// a finding, or a claim someone made (a person, a bot, the description) that checking it in the box did not confirm
+export interface AttentionItem { text?: ReactNode; detail?: ReactNode; to?: Target; claim?: { source: string; quote: string; status: "fail" | "neutral"; label?: string } }
+// a claim that checking it in the box confirmed
+export interface HeldClaim { source: string; quote: string; to?: Target }
+
+// why there were no claims to check
+function noClaimsText() {
+  if (!pr.number) return pr.body.trim() ? "The author's note makes no claims about the code." : "No claims to check: there is no note from the author.";
+  const talk = pr.comments.length + pr.reviews.length + pr.reviewComments.length > 0;
+  if (!pr.body.trim() && !talk) return "No claims to check: the PR has no description or review comments.";
+  return "Nothing in the description or comments makes a claim about the code.";
+}
+
+const VERDICT = { fail: "Not true", neutral: "Partly true" };
+
+// titles only, open one to read why it matters; claims that held are one quiet line below
+export function Attention({ items, held = [] }: { items: AttentionItem[]; held?: HeldClaim[] }) {
+  const { go } = useNav();
+  const label = useTargetLabel();
+  const [open, setOpen] = useState<number | null>(null);
+  const [heldOpen, setHeldOpen] = useState(false);
+  const n = held.length;
+  const noClaims = !n && !items.some((a) => a.claim);
+  return (
+    <Section label="Worth a close look">
+      {items.length > 0 && (
+        <div className="acc-list">
+          {items.map((a, i) => {
+            const on = open === i;
+            const title = a.claim
+              ? <><span className="acc-title"><q className="claim-q">{a.claim.quote}</q> <span className="claim-by">{a.claim.source}</span></span><span className={`chip ${a.claim.status}`}>{a.claim.label ?? VERDICT[a.claim.status]}</span></>
+              : <span className="acc-title">{a.text}</span>;
+            if (!a.detail && !a.to) return <div key={i} className="acc"><div className="acc-head"><span className="acc-chev" />{title}</div></div>;
+            return (
+              <div key={i} className="acc" data-open={on || undefined}>
+                <button className="acc-head" aria-expanded={on} onClick={() => setOpen(on ? null : i)}>
+                  <span className="acc-chev">{Icon.chevron}</span>
+                  {title}
+                </button>
+                <div className="acc-body" inert={!on}>
+                  <div>
+                    <div className="acc-inner">
+                      {a.detail && <p className="prose">{a.detail}</p>}
+                      {a.to && <button className="btn sm" onClick={() => go(a.to!)}>{Icon.play} {label(a.to)}</button>}
+                    </div>
+                  </div>
+                </div>
+              </div>
+            );
+          })}
+        </div>
+      )}
+      {noClaims && <p className="held-none">{noClaimsText()}</p>}
+      {n > 0 && (
+        <div className="held" data-open={heldOpen || undefined}>
+          <button className="held-btn" aria-expanded={heldOpen} onClick={() => setHeldOpen(!heldOpen)}>
+            <span className="held-ok">{Icon.check}</span>
+            {items.some((a) => a.claim) ? "Also checked" : "Checked"} {n} {n === 1 ? "claim" : "claims"}. {n === 1 ? "It holds." : n === 2 ? "Both hold." : "All hold."}
+            <span className="acc-chev">{Icon.chevron}</span>
+          </button>
+          <div className="acc-body" inert={!heldOpen}>
+            <div>
+              <ul className="held-list">
+                {held.map((c, i) => (
+                  <li key={i}>
+                    <span className="held-ok">{Icon.check}</span>
+                    <span className="held-text"><span className="claim-by">{c.source}</span> <q>{c.quote}</q></span>
+                    {c.to && <button className="link" onClick={() => go(c.to!)}>{label(c.to)}</button>}
+                  </li>
+                ))}
+              </ul>
+            </div>
+          </div>
+        </div>
+      )}
+    </Section>
+  );
+}
+
+// any content in a quiet card, e.g. a flow or a screenshot
+export const Card = ({ children, caption }: { children: ReactNode; caption?: ReactNode }) => (
+  <div className="card pad">{children}{caption && <div className="cap">{caption}</div>}</div>
+);