bottleship 0.1.0-prototype.0 → 0.1.0-prototype.2

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

@@ -0,0 +1,100 @@
+// The PR as bottleship fetched it, written into src/data (@data) when the box was set up.
+import raw from "@data/pr.json";
+import box from "@data/box.json";
+import diffText from "@data/pr.diff?raw";
+import reviewComments from "@data/review-comments.json";
+
+
+export interface Person { login: string; is_bot?: boolean }
+export interface PrFile { path: string; additions: number; deletions: number }
+export interface GhComment {
+  id: number;
+  path: string;
+  // null when the lines it was on have changed since
+  line: number | null;
+  original_line?: number | null;
+  side?: "LEFT" | "RIGHT";
+  start_line?: number | null;
+  start_side?: "LEFT" | "RIGHT" | null;
+  in_reply_to_id?: number;
+  body: string;
+  user: { login: string; type?: string };
+  created_at: string;
+  html_url?: string;
+  resolved?: boolean;
+}
+
+export const pr = {
+  number: raw.number as number,
+  title: raw.title as string,
+  url: raw.url as string,
+  body: (raw.body as string) ?? "",
+  author: (raw.author as Person).login.replace(/^app\//, ""),
+  // local changes have a repo name but no PR
+  repo: ((raw as { repo?: string }).repo ?? (raw.url as string).replace(/^https?:\/\/[^/]+\/([^/]+\/[^/]+)\/pull\/.*$/, "$1")).split("/").pop()!,
+  ref: raw.number ? `#${raw.number}` : "local changes",
+  baseRef: raw.baseRefName as string,
+  headRef: raw.headRefName as string,
+  // the commits the instances run: base is where the PR branched off
+  base: box.base.slice(0, 7),
+  head: /^[0-9a-f]{40}$/.test(box.head) ? box.head.slice(0, 7) : box.head,
+  files: (raw.files as PrFile[]).map((f) => ({ path: f.path, add: f.additions, del: f.deletions })),
+  comments: raw.comments as unknown[],
+  reviews: raw.reviews as unknown[],
+  // inline comments already on GitHub, as its REST API returns them, with resolved added by bottleship
+  reviewComments: reviewComments as GhComment[],
+};
+
+// the title without a conventional-commit prefix, capitalised
+export const shortTitle = pr.title.replace(/^\w+(\([^)]*\))?!?:\s*/, "").replace(/^./, (c) => c.toUpperCase());
+
+export const total = pr.files.reduce((t, f) => ({ add: t.add + f.add, del: t.del + f.del }), { add: 0, del: 0 });
+
+// n is the line in the new file, o in the old one; a removed row sits at the next new line (at)
+export interface Row { t: "a" | "d" | "c"; n?: number; o?: number; at?: number; s: string }
+
+// a unified diff split per file
+function splitDiff(text: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const part of text.split(/^diff --git /m).slice(1)) {
+    const file = part.match(/^\+\+\+ b\/(.+)$/m)?.[1] ?? part.match(/^a\/(\S+)/)?.[1];
+    if (file) out[file] = "diff --git " + part;
+  }
+  return out;
+}
+
+export const diffs = splitDiff(diffText);
+// what the PR did to a file, read from its diff header
+export type FileStatus = "added" | "deleted" | "renamed" | "modified";
+export function fileStatus(path: string): FileStatus {
+  const d = diffs[path] ?? "";
+  const at = d.indexOf("\n@@");
+  const head = at < 0 ? d : d.slice(0, at);
+  return /^new file mode/m.test(head) ? "added" : /^deleted file mode/m.test(head) ? "deleted" : /^rename from/m.test(head) ? "renamed" : "modified";
+}
+
+// a file's diff as rows with new-file line numbers; removed rows sit at the next new line
+export function rows(diff: string): Row[] {
+  const out: Row[] = [];
+  let n = 0;
+  let o = 0;
+  let inHunk = false;
+  for (const line of diff.split("\n")) {
+    const m = line.match(/^@@ -(\d+)(?:,\d+)? \+(\d+)/);
+    if (m) {
+      o = Number(m[1]);
+      n = Number(m[2]);
+      inHunk = true;
+      continue;
+    }
+    if (!inHunk || line.startsWith("\\")) continue;
+    if (line.startsWith("diff --git ")) {
+      inHunk = false;
+      continue;
+    }
+    if (line.startsWith("+")) out.push({ t: "a", n: n++, s: line.slice(1) });
+    else if (line.startsWith("-")) out.push({ t: "d", o: o++, at: n, s: line.slice(1) });
+    else out.push({ t: "c", n: n++, o: o++, s: line.slice(1) });
+  }
+  return out;
+}

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

@@ -0,0 +1,298 @@
+// The pull request itself, as it stands on GitHub: its state, what stands between it and a merge, the checks and
+// action runs on its head, who reviewed it, and merging it when the reviewer's account may. Read through the review
+// server (the box's gh), which merges only at the head the tour was built from.
+import { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { Body } from "./comments";
+import { pr } from "./pr";
+import { Icon, Section, Stat } from "./ui";
+
+type Method = "MERGE" | "SQUASH" | "REBASE";
+interface Check { name: string; workflow?: string; status: "pass" | "fail" | "pending" | "skipped" | "neutral"; url?: string; started?: string; finished?: string }
+interface Status {
+  number: number;
+  title: string;
+  url: string;
+  body: string;
+  state: "OPEN" | "CLOSED" | "MERGED";
+  draft: boolean;
+  author?: string;
+  head: { ref: string; oid: string };
+  base: string;
+  additions: number;
+  deletions: number;
+  files: number;
+  merged?: { at?: string; by?: string };
+  mergeable: string;
+  mergeState: string;
+  reviewDecision?: string;
+  reviews: { by: string; state: string; at?: string }[];
+  requested: string[];
+  checks: Check[];
+  canMerge: boolean;
+  methods: Method[];
+  defaultMethod?: Method;
+}
+
+// how often the page asks again while it is open; the server answers from a short cache
+const POLL = 15_000;
+
+async function call(path: string, body?: unknown): Promise<{ ok: true; data: Status } | { ok: false; error: string }> {
+  try {
+    const r = await fetch(path, body ? { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) } : undefined);
+    const data = await r.json().catch(() => ({}));
+    return r.ok ? { ok: true, data } : { ok: false, error: (data as { errors?: string[] }).errors?.join(", ") ?? `The review server answered ${r.status}.` };
+  } catch {
+    return { ok: false, error: "The review server is not answering." };
+  }
+}
+
+const ago = new Intl.RelativeTimeFormat("en", { numeric: "auto" });
+function when(at?: string) {
+  if (!at) return "";
+  const s = (Date.parse(at) - Date.now()) / 1000;
+  for (const [unit, n] of [["year", 31536000], ["month", 2592000], ["day", 86400], ["hour", 3600], ["minute", 60]] as const)
+    if (Math.abs(s) >= n) return ago.format(Math.round(s / n), unit);
+  return "just now";
+}
+function took(c: Check) {
+  if (!c.started || !c.finished) return "";
+  const s = Math.round((Date.parse(c.finished) - Date.parse(c.started)) / 1000);
+  return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${s % 60}s`;
+}
+
+const METHOD = { SQUASH: ["Squash", "Squash and merge"], MERGE: ["Merge", "Create a merge commit"], REBASE: ["Rebase", "Rebase and merge"] } as const;
+
+type Tone = "pass" | "fail" | "pending" | "warn" | "merged" | "skipped" | "neutral";
+const ICON: Record<Tone, React.ReactNode> = { pass: Icon.check, fail: Icon.cross, warn: Icon.minus, skipped: Icon.minus, neutral: Icon.minus, merged: Icon.check, pending: null };
+const St = ({ tone }: { tone: Tone }) => <span className={`prp-st ${tone}`}>{ICON[tone]}</span>;
+
+// what a merge needs, each with its state and why, as GitHub reports them
+function gatesOf(s: Status): { tone: Tone; title: string; why: string }[] {
+  const failing = s.checks.filter((c) => c.status === "fail");
+  const running = s.checks.filter((c) => c.status === "pending");
+  const passing = s.checks.filter((c) => c.status === "pass");
+  const out: { tone: Tone; title: string; why: string }[] = [];
+  if (s.draft) out.push({ tone: "fail", title: "A draft", why: "It cannot be merged until it is marked ready for review" });
+  out.push(
+    failing.length
+      ? { tone: "fail", title: `${failing.length} ${failing.length === 1 ? "check" : "checks"} failing`, why: `${failing.map((c) => c.name + (c.workflow ? ` in ${c.workflow}` : "")).join(", ")}.${s.mergeState === "UNSTABLE" ? " Not required, so it does not block." : ""}` }
+      : running.length
+        ? { tone: "pending", title: "Checks running", why: running.map((c) => c.name).join(", ") }
+        : s.checks.length
+          ? { tone: "pass", title: "Checks passed", why: `${passing.length} passed` }
+          : { tone: "neutral", title: "No checks", why: "Nothing ran on this commit" },
+  );
+  const approvers = s.reviews.filter((r) => r.state === "APPROVED").map((r) => r.by);
+  const blockers = s.reviews.filter((r) => r.state === "CHANGES_REQUESTED").map((r) => r.by);
+  out.push(
+    s.reviewDecision === "CHANGES_REQUESTED"
+      ? { tone: "fail", title: "Changes requested", why: `By ${blockers.join(", ") || "a reviewer"}` }
+      : s.reviewDecision === "REVIEW_REQUIRED"
+        ? { tone: "fail", title: "Review required", why: s.requested.length ? `Waiting on ${s.requested.join(", ")}` : "An approving review is needed" }
+        : approvers.length
+          ? { tone: "pass", title: "Approved", why: `By ${approvers.join(", ")}` }
+          : { tone: "neutral", title: "No review needed", why: "The branch does not require one" },
+  );
+  out.push(
+    s.mergeable === "CONFLICTING" || s.mergeState === "DIRTY"
+      ? { tone: "fail", title: "Conflicts", why: `With ${s.base}; resolve them first` }
+      : s.mergeable === "UNKNOWN"
+        ? { tone: "pending", title: "Checking for conflicts", why: "GitHub is still working it out" }
+        : { tone: "pass", title: "No conflicts", why: `Merges cleanly into ${s.base}` },
+  );
+  out.push(s.mergeState === "BEHIND" ? { tone: "warn", title: "Behind", why: `${s.base} has moved on; update the branch first` } : { tone: "pass", title: "Up to date", why: `Nothing on ${s.base} it needs first` });
+  return out;
+}
+
+// the description, cut to a few lines with More when it runs longer
+function Description({ text }: { text: string }) {
+  const ref = useRef<HTMLDivElement>(null);
+  const [long, setLong] = useState(false);
+  const [open, setOpen] = useState(false);
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (el && !open) setLong(el.scrollHeight > el.clientHeight + 1);
+  }, [text, open]);
+  if (!text.trim()) return <p className="prose prp-dim">No description.</p>;
+  return (
+    <div className="card pad prp-desc">
+      <div ref={ref} className={open ? undefined : "prp-clamp"}><Body text={text} /></div>
+      {long && <button className="show-more" onClick={() => setOpen(!open)}>{open ? "Less" : "More"}</button>}
+    </div>
+  );
+}
+
+export function PullRequest() {
+  const [status, setStatus] = useState<Status>();
+  const [error, setError] = useState<string>();
+  const [loading, setLoading] = useState(false);
+  const [open, setOpen] = useState<Set<string>>();
+  const load = async () => {
+    setLoading(true);
+    const r = await call("api/pr");
+    setLoading(false);
+    if (r.ok) (setStatus(r.data), setError(undefined));
+    else setError(r.error);
+  };
+  useEffect(() => {
+    void load();
+    const t = setInterval(() => document.visibilityState === "visible" && void load(), POLL);
+    return () => clearInterval(t);
+  }, []);
+  if (!status)
+    return error ? (
+      <section className="view orient prp">
+        <h1 className="title">{pr.title}</h1>
+        <p className="prose post-error" role="alert">{error}</p>
+      </section>
+    ) : <Skeleton />;
+  const s = status;
+  // checks by workflow; statuses from outside a workflow, like deploys, go together
+  const groups = [...new Set(s.checks.map((c) => c.workflow ?? "Other"))].map((name) => ({ name, checks: s.checks.filter((c) => (c.workflow ?? "Other") === name) }));
+  const toneOf = (cs: Check[]): Tone => (cs.some((c) => c.status === "fail") ? "fail" : cs.some((c) => c.status === "pending") ? "pending" : cs.every((c) => c.status === "skipped") ? "skipped" : "pass");
+  // groups with a failure start open
+  const expanded = open ?? new Set(groups.filter((g) => toneOf(g.checks) === "fail").map((g) => g.name));
+  const toggle = (n: string) => {
+    const next = new Set(expanded);
+    next.has(n) ? next.delete(n) : next.add(n);
+    setOpen(next);
+  };
+  const count = (st: Check["status"]) => s.checks.filter((c) => c.status === st).length;
+  const sum = [count("fail") && `${count("fail")} failing`, count("pending") && `${count("pending")} running`, count("pass") && `${count("pass")} passing`, count("skipped") && `${count("skipped")} skipped`].filter(Boolean).join(", ");
+  return (
+    <section className="view prp-gates">
+      <div className="prp-main">
+        <div>
+          <h1 className="title">{s.title}</h1>
+          <div className="meta">
+            <span className={`chip ${s.state === "MERGED" ? "merged" : s.state === "CLOSED" ? "fail" : s.draft ? "" : "done"}`}>{s.state === "MERGED" ? "Merged" : s.state === "CLOSED" ? "Closed" : s.draft ? "Draft" : "Open"}</span>
+            <span>#{s.number}{s.author ? ` by ${s.author}` : ""}</span>
+            <span className="refs">{s.head.ref} {Icon.arrow} {s.base}</span>
+            <Stat add={s.additions} del={s.deletions} />
+            <span>{s.files} {s.files === 1 ? "file" : "files"}</span>
+            <a className="link" href={s.url} target="_blank" rel="noreferrer">On GitHub</a>
+          </div>
+        </div>
+        <Description text={s.body} />
+        <section>
+          <div className="label prp-label">Checks <span className="c">{sum}</span><button className="btn ghost sm" onClick={() => void load()} disabled={loading}>{Icon.reset} {loading ? "Checking" : "Refresh"}</button></div>
+          {groups.length ? groups.map((g) => (
+            <div className="prp-wf" key={g.name}>
+              <button className="prp-wf-h" aria-expanded={expanded.has(g.name)} onClick={() => toggle(g.name)}>
+                <span className="chev">{Icon.chevron}</span>
+                <St tone={toneOf(g.checks)} />
+                <span className="grow"><b>{g.name}</b> <span className="prp-dim">{g.checks.length} {g.checks.length === 1 ? "job" : "jobs"}</span></span>
+              </button>
+              {expanded.has(g.name) && (
+                <div className="prp-jobs">
+                  {g.checks.map((c, i) => (
+                    <div className="prp-job" key={i}>
+                      <St tone={c.status} />
+                      <span className="grow">{c.name}</span>
+                      <span className="prp-dim">{c.status === "pending" ? "running" : c.status === "skipped" ? "skipped" : took(c)}</span>
+                      {c.url && <a className="link" href={c.url} target="_blank" rel="noreferrer">Details</a>}
+                    </div>
+                  ))}
+                </div>
+              )}
+            </div>
+          )) : <p className="prose">No checks or action runs on this commit.</p>}
+        </section>
+        <Section label="Reviews" count={s.reviews.length || undefined}>
+          {s.reviews.length || s.requested.length ? (
+            <div className="rows">
+              {s.reviews.map((r) => {
+                const [name, tone] = REVIEW[r.state as keyof typeof REVIEW] ?? [r.state.toLowerCase(), ""];
+                return (
+                  <div key={r.by} className="row">
+                    <span className="avatar">{r.by[0]?.toUpperCase()}</span>
+                    <span className="grow"><b>{r.by}</b></span>
+                    <span className={`chip ${tone}`}>{name}</span>
+                    <span className="prp-dim">{when(r.at)}</span>
+                  </div>
+                );
+              })}
+              {s.requested.length > 0 && <div className="row"><span className="grow prp-dim">Waiting on {s.requested.join(", ")}</span></div>}
+            </div>
+          ) : <p className="prose">Nobody has reviewed it yet.</p>}
+        </Section>
+      </div>
+      <Gates s={s} onDone={setStatus} />
+    </section>
+  );
+}
+
+const REVIEW = { APPROVED: ["Approved", "ok"], CHANGES_REQUESTED: ["Changes requested", "fail"], COMMENTED: ["Commented", ""], DISMISSED: ["Dismissed", ""] } as const;
+
+// the page's shape while GitHub answers
+function Skeleton() {
+  const bar = (w: string, h = 12) => <span className="skel" style={{ width: w, height: h }} />;
+  return (
+    <section className="view prp-gates" aria-busy="true" aria-label="Loading the pull request">
+      <div className="prp-main">
+        <div className="skel-stack">{bar("70%", 26)}{bar("55%")}</div>
+        <div className="card pad prp-desc skel-stack">{bar("92%")}{bar("84%")}{bar("60%")}</div>
+        <div>
+          <div className="skel-stack" style={{ marginBottom: 12 }}>{bar("28%")}</div>
+          {[0, 1, 2].map((i) => <div className="prp-wf skel-row" key={i}><span className="skel skel-dot" />{bar(`${[30, 22, 26][i]}%`)}</div>)}
+        </div>
+      </div>
+      <aside className="prp-panel">
+        {bar("60%", 18)}
+        {[0, 1, 2, 3].map((i) => <div className="prp-gate" key={i}><span className="skel skel-dot" /><span className="skel-stack" style={{ flex: 1 }}>{bar(`${[45, 35, 40, 30][i]}%`)}{bar(`${[75, 60, 70, 55][i]}%`, 9)}</span></div>)}
+        <hr />
+        {bar("100%", 32)}
+      </aside>
+    </section>
+  );
+}
+
+// what a merge needs, then merging; that takes a second click, as it changes the base branch for everyone
+function Gates({ s, onDone }: { s: Status; onDone: (s: Status) => void }) {
+  const [method, setMethod] = useState<Method | undefined>(s.defaultMethod ?? s.methods[0]);
+  const [confirm, setConfirm] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string>();
+  const blocked = s.draft || s.mergeable === "CONFLICTING" || s.mergeState === "DIRTY";
+  const merge = async () => {
+    if (!method) return;
+    setBusy(true);
+    setError(undefined);
+    const r = await call("api/pr/merge", { method });
+    setBusy(false);
+    setConfirm(false);
+    if (r.ok) onDone(r.data);
+    else setError(r.error);
+  };
+  return (
+    <aside className="prp-panel">
+      <h2>{s.state === "MERGED" ? "Merged" : s.state === "CLOSED" ? "Closed" : `Merging into ${s.base}`}</h2>
+      {s.state === "OPEN" && gatesOf(s).map((g) => (
+        <div className="prp-gate" key={g.title}><St tone={g.tone} /><span><b>{g.title}</b><span>{g.why}</span></span></div>
+      ))}
+      {s.state === "OPEN" && <hr />}
+      {s.state === "MERGED" ? (
+        <div className="prp-gate"><St tone="merged" /><span><b>Merged{s.merged?.by ? ` by ${s.merged.by}` : ""}</b><span>{when(s.merged?.at)}</span></span></div>
+      ) : s.state === "CLOSED" ? (
+        <p className="prose prp-dim">Closed without merging.</p>
+      ) : s.canMerge ? (
+        <div className="prp-acts">
+          {s.methods.length > 1 && (
+            <div className="vswitch prp-methods" role="radiogroup" aria-label="How to merge">
+              {s.methods.map((m) => <button key={m} role="radio" aria-checked={method === m} onClick={() => (setMethod(m), setConfirm(false))}>{METHOD[m][0]}</button>)}
+            </div>
+          )}
+          {error && <p className="prose post-error" role="alert">{error}</p>}
+          {confirm ? (
+            <div className="prp-confirm">
+              <button className="btn" disabled={busy} onClick={() => setConfirm(false)}>Cancel</button>
+              <button className="btn primary" disabled={busy} onClick={() => void merge()}>{busy ? "Merging" : "Confirm"}</button>
+            </div>
+          ) : (
+            <button className="btn primary" disabled={blocked || !method} onClick={() => setConfirm(true)}>{method ? METHOD[method][1] : "Merge"}</button>
+          )}
+        </div>
+      ) : <p className="prose prp-dim">Your GitHub account cannot merge in this repository.</p>}
+    </aside>
+  );
+}

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

@@ -0,0 +1,74 @@
+// What a review is: instances, an overview, chapters in tour order, and the code grouped the same way.
+import { createContext, useContext, type ReactNode } from "react";
+import type { ReviewEvent } from "./live";
+
+export interface Instance {
+  id: string;
+  // short: Base, Head
+  label: string;
+  // what sets it apart, e.g. "master, Hebrew"
+  detail?: string;
+  // a port inside the box: the app's own for head, 7781 to 7784 for base and others
+  port: number;
+  path?: string;
+}
+
+export interface ChapterDef {
+  id: string;
+  title: string;
+  page: () => ReactNode;
+}
+
+// a part of the diff with its reason; lines are new-file line ranges
+export interface Group {
+  id: string;
+  title: string;
+  why: string;
+  chapter?: string;
+  file: string;
+  lines?: [number, number][];
+}
+
+export interface Review {
+  instances: Instance[];
+  overview: () => ReactNode;
+  chapters: ChapterDef[];
+  groups: Group[];
+}
+
+export const defineReview = (r: Review) => r;
+
+// the chapters the reviewer has opened this visit; the rail ticks them, Finish counts them
+export const seenChapters = new Set<string>();
+
+export type Target = "overview" | "changes" | "pr" | "finish" | { chapter: string } | { group: string };
+
+export interface Nav {
+  review: Review;
+  go: (t: Target) => void;
+  // the chapter being shown, if any
+  chapter?: { def: ChapterDef; index: number };
+}
+
+export const NavContext = createContext<Nav | null>(null);
+
+export function useNav(): Nav {
+  const nav = useContext(NavContext);
+  if (!nav) throw new Error("useNav outside the review shell");
+  return nav;
+}
+
+export const hash = (t: Target) =>
+  t === "overview" ? "#/" : t === "changes" ? "#/changes" : t === "finish" ? "#/finish" : t === "pr" ? "#/pr" : "chapter" in t ? `#/chapter/${t.chapter}` : `#/changes/${t.group}`;
+
+interface ChapterState { step?: string; events: ReviewEvent[]; instances: Instance[] }
+export const ChapterContext = createContext<ChapterState | null>(null);
+
+// inside a chapter: its step's events since the last Run, and the instances it is about
+export function useChapter(): ChapterState {
+  const nav = useContext(NavContext);
+  return useContext(ChapterContext) ?? { events: [], instances: nav?.review.instances ?? [] };
+}
+
+// the latest outcome (an ok or fail event) an instance reported
+export const outcomeOf = (events: ReviewEvent[], id: string) => [...events].reverse().find((e) => e.instance === id && (e.kind === "ok" || e.kind === "fail"));

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

@@ -0,0 +1,30 @@
+// Light or dark: follows the system until the reviewer picks one, then remembers it.
+import { useState } from "react";
+
+type Theme = "light" | "dark";
+const KEY = "review-theme";
+const system = matchMedia("(prefers-color-scheme: dark)");
+
+function chosen(): Theme | null {
+  try {
+    const v = localStorage.getItem(KEY);
+    return v === "light" || v === "dark" ? v : null;
+  } catch {
+    return null;
+  }
+}
+
+const apply = (t: Theme) => { document.documentElement.dataset.theme = t; };
+apply(chosen() ?? (system.matches ? "dark" : "light"));
+system.addEventListener("change", (e) => { if (!chosen()) apply(e.matches ? "dark" : "light"); });
+
+export function useTheme() {
+  const [theme, setTheme] = useState(document.documentElement.dataset.theme as Theme);
+  const toggle = () => {
+    const next: Theme = document.documentElement.dataset.theme === "dark" ? "light" : "dark";
+    apply(next);
+    try { localStorage.setItem(KEY, next); } catch { /* private mode: still switches for this visit */ }
+    setTheme(next);
+  };
+  return { theme, toggle };
+}

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

@@ -0,0 +1,127 @@
+// Small pieces every page uses: icons, buttons, rows, labels, file rows and stats.
+import type { ReactNode } from "react";
+import { useNav, type Instance, type Target } from "./review";
+import { useTheme } from "./theme";
+import { fileStatus, pr, type FileStatus } from "./pr";
+
+const svg = (d: ReactNode, fill = false) => (
+  <svg className="i" viewBox="0 0 16 16" style={fill ? { fill: "currentColor", stroke: "none" } : undefined}>{d}</svg>
+);
+export const Icon = {
+  pr: svg(<><circle cx="4" cy="3.5" r="1.5" /><circle cx="4" cy="12.5" r="1.5" /><circle cx="12" cy="12.5" r="1.5" /><path d="M4 5v6M12 11V6.5A2 2 0 0 0 10 4.5H7.5M9 3l-1.5 1.5L9 6" /></>),
+  arrow: svg(<path d="M3.5 8h9M9 4.5 12.5 8 9 11.5" />),
+  back: svg(<path d="M12.5 8h-9M7 4.5 3.5 8 7 11.5" />),
+  dock: svg(<><rect x="2" y="3" width="12" height="10" rx="2" /><path d="M9.5 3v10" /></>),
+  float: svg(<><rect x="2" y="3" width="12" height="10" rx="2" /><rect x="8" y="8" width="4" height="3" rx=".5" /></>),
+  panel: svg(<><rect x="2" y="3" width="12" height="10" rx="2" /><path d="M6.5 3v10" /></>),
+  sun: svg(<><circle cx="8" cy="8" r="2.75" /><path d="M8 1.5v1.5M8 13v1.5M1.5 8H3M13 8h1.5M3.4 3.4l1.06 1.06M11.54 11.54l1.06 1.06M3.4 12.6l1.06-1.06M11.54 4.46l1.06-1.06" /></>),
+  moon: svg(<path d="M13.5 9.6A5.5 5.5 0 0 1 6.4 2.5a5.5 5.5 0 1 0 7.1 7.1Z" />),
+  eye: svg(<><path d="M1.5 8s2.4-4.5 6.5-4.5S14.5 8 14.5 8s-2.4 4.5-6.5 4.5S1.5 8 1.5 8Z" /><circle cx="8" cy="8" r="1.8" /></>),
+  play: svg(<path d="M5 3.3v9.4a.5.5 0 0 0 .76.43l7.5-4.7a.5.5 0 0 0 0-.86l-7.5-4.7A.5.5 0 0 0 5 3.3Z" />, true),
+  code: svg(<path d="M5.5 4.5 2 8l3.5 3.5M10.5 4.5 14 8l-3.5 3.5" />),
+  expand: svg(<path d="M8 2.5v11M5 5.5l3-3 3 3M5 10.5l3 3 3-3" />),
+  check: svg(<path d="M3.5 8.5 6.5 11.5 12.5 4.5" />),
+  reset: svg(<path d="M3 8a5 5 0 1 0 1.5-3.5M3 3v2.5h2.5" />),
+  external: svg(<path d="M6.5 3.5h-3v9h9v-3M9 3.5h3.5V7M12.5 3.5 7 9" />),
+  chevron: svg(<path d="M6 4l4 4-4 4" />),
+  cross: svg(<path d="M4.5 4.5l7 7M11.5 4.5l-7 7" />),
+  minus: svg(<path d="M4 8h8" />),
+  plus: svg(<path d="M8 3.5v9M3.5 8h9" />),
+  pause: svg(<path d="M5.5 3.5v9M10.5 3.5v9" />),
+  cursorPlus: svg(<><path d="M2.5 2 9.5 5.5 6.25 6.5 5.25 9.75Z" /><path d="M12 9v5M9.5 11.5h5" /></>),
+  cursor: svg(<path d="M3.5 2.5 12.5 7 8.25 8.25 7 12.5Z" />),
+  page: svg(<><path d="M4 2.5h5.5L12 5v8.5H4Z" /><path d="M6.5 8h3M6.5 10.5h3" /></>),
+  quote: svg(<path d="M6 3h4M6 13h4M8 3v10" />),
+  send: svg(<path d="M8 12.5v-9M4.5 7 8 3.5 11.5 7" />),
+  suggest: svg(<path d="M8 2.5v6M5 5.5h6M5 12.5h6" />),
+  comment: svg(<path d="M4.5 3h7A1.5 1.5 0 0 1 13 4.5v5a1.5 1.5 0 0 1-1.5 1.5H7.5l-3 2.5V11A1.5 1.5 0 0 1 3 9.5v-5A1.5 1.5 0 0 1 4.5 3Z" />),
+};
+
+
+export function Stat({ add, del }: { add: number; del: number }) {
+  return (
+    <span className="stat">
+      {add > 0 && <span className="plus">+{add}</span>}
+      {del > 0 && <span className="minus">{"−"}{del}</span>}
+    </span>
+  );
+}
+
+const STATUS: Record<FileStatus, [ReactNode, string]> = {
+  added: [svg(<path d="M8 4v8M4 8h8" />), "Added"],
+  deleted: [svg(<path d="M4 8h8" />), "Deleted"],
+  renamed: [svg(<path d="M3.5 8h9M9 4.5 12.5 8 9 11.5" />), "Renamed"],
+  modified: [svg(<circle cx="8" cy="8" r="2.25" />, true), "Changed"],
+};
+
+// added, deleted, renamed or changed
+export function FileMark({ path }: { path: string }) {
+  const status = fileStatus(path);
+  const [icon, label] = STATUS[status];
+  return <span className={`fmark ${status}`} title={label} aria-label={label}>{icon}</span>;
+}
+
+// five blocks: how many fill is the file's size against the PR's largest file, split green and red by added and deleted
+const largest = Math.max(1, ...pr.files.map((f) => f.add + f.del));
+export function SizeBar({ add, del }: { add: number; del: number }) {
+  const filled = add + del ? Math.max(1, Math.round((5 * (add + del)) / largest)) : 0;
+  const green = Math.round((filled * add) / (add + del || 1));
+  return (
+    <span className="sbar" title={`+${add} −${del}`}>
+      {[0, 1, 2, 3, 4].map((i) => <i key={i} className={i < green ? "a" : i < filled ? "d" : ""} />)}
+    </span>
+  );
+}
+
+export function FileLine({ path, add, del }: { path: string; add?: number; del?: number }) {
+  const name = path.split("/").pop()!;
+  return (
+    <>
+      {add !== undefined ? <SizeBar add={add} del={del ?? 0} /> : <FileMark path={path} />}
+      <span className="fname">{name}</span>
+      <span className="fpath grow">{path.slice(0, -name.length)}</span>
+      {add !== undefined && <Stat add={add} del={del ?? 0} />}
+    </>
+  );
+}
+
+export function Label({ children, count }: { children: ReactNode; count?: number }) {
+  return <div className="label">{children}{count !== undefined && <span className="c">{count}</span>}</div>;
+}
+
+export function Section({ label, count, children }: { label: string; count?: number; children: ReactNode }) {
+  return <div><Label count={count}>{label}</Label>{children}</div>;
+}
+
+// a card row, a link when it has a target
+export function Row({ to, toLabel, tall, children }: { to?: Target; toLabel?: string; tall?: boolean; children: ReactNode }) {
+  const { go } = useNav();
+  return (
+    <div className={`row${tall ? " tall" : ""}`}>
+      {children}
+      {to && <button className="link" onClick={() => go(to)}>{toLabel ?? "Open"}</button>}
+    </div>
+  );
+}
+
+export const Rows = ({ children }: { children: ReactNode }) => <div className="rows">{children}</div>;
+
+// an instance's short name, and what sets it apart
+export function InstanceName({ inst }: { inst: Instance }) {
+  return <span className="iname"><b>{inst.label}</b>{inst.detail && <span>{inst.detail}</span>}</span>;
+}
+
+const arrow = <svg className="refs-arrow" viewBox="0 0 16 8" aria-hidden="true"><path d="M1 4h13M11 1l3 3-3 3" /></svg>;
+
+// two refs with a thin arrow between them: a branch into the branch it merges into, or base and head commits
+export function Refs({ from, to, label }: { from: ReactNode; to: ReactNode; label?: string }) {
+  return <span className="refs" aria-label={label}><span>{from}</span>{arrow}<span>{to}</span></span>;
+}
+
+// switches between light and dark, shown as the theme it switches to
+export function ThemeToggle() {
+  const { theme, toggle } = useTheme();
+  const dark = theme === "dark";
+  const label = dark ? "Light theme" : "Dark theme";
+  return <button className="icon-btn theme" onClick={toggle} title={label} aria-label={label}>{dark ? Icon.sun : Icon.moon}</button>;
+}

package/review-app/src/main.tsx

@@ -0,0 +1,6 @@
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+import review from "./review";
+import "./kit/kit.css";
+
+createRoot(document.getElementById("root")!).render(<App review={review} />);

package/review-app/src/review.tsx

@@ -0,0 +1,22 @@
+// The review of this PR. Replace this starter with the tour: read KIT.md, and see examples/rply-16.tsx for a complete one.
+import { Chapter, defineReview, Lead, Overview, pr } from "./kit";
+
+export default defineReview({
+  instances: [
+    { id: "base", label: "Base", detail: pr.baseRef, port: 7781 },
+    { id: "head", label: "Head", detail: "this PR", port: 7782 },
+  ],
+  overview: () => (
+    <Overview>
+      <Lead>{pr.body.split("\n\n")[0] || pr.title}</Lead>
+    </Overview>
+  ),
+  chapters: [
+    {
+      id: "side-by-side",
+      title: "Base and head side by side",
+      page: () => <Chapter title="Base and head side by side">The app before and after this PR.</Chapter>,
+    },
+  ],
+  groups: [],
+});