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

package/review-app/playground/fixtures/rply-16/events.json

@@ -0,0 +1,156 @@
+{
+ "mapped-loopback": {
+  "status": {
+   "id": "mapped-loopback",
+   "status": "done"
+  },
+  "ms": 4000,
+  "events": [
+   {
+    "instance": "base",
+    "kind": "request",
+    "text": "GET /v1/unfurl?url=http://[::ffff:7f00:1]:9199/",
+    "flow": {
+     "id": "ssrf",
+     "edge": [
+      "route",
+      "guard"
+     ]
+    }
+   },
+   {
+    "instance": "head",
+    "kind": "request",
+    "text": "GET /v1/unfurl?url=http://[::ffff:7f00:1]:9199/",
+    "flow": {
+     "id": "ssrf",
+     "edge": [
+      "route",
+      "guard"
+     ]
+    }
+   },
+   {
+    "instance": "base",
+    "kind": "hook",
+    "text": "unfurl.ts:76  ::ffff:7f00:1 is public",
+    "flow": {
+     "id": "ssrf",
+     "node": "guard",
+     "status": "fail",
+     "label": "public"
+    }
+   },
+   {
+    "instance": "head",
+    "kind": "hook",
+    "text": "unfurl.ts:76  ::ffff:7f00:1 is private",
+    "flow": {
+     "id": "ssrf",
+     "node": "guard",
+     "status": "ok",
+     "label": "blocked"
+    }
+   },
+   {
+    "instance": "base",
+    "kind": "hook",
+    "text": "fetch http://127.0.0.1:9199/  200",
+    "flow": {
+     "id": "ssrf",
+     "edge": [
+      "guard",
+      "internal"
+     ],
+     "node": "internal",
+     "status": "fail",
+     "label": "fetched"
+    }
+   },
+   {
+    "instance": "base",
+    "kind": "fail",
+    "text": "Leaked the internal page",
+    "overlay": {
+     "title": "Leaked “internal”",
+     "body": "The loopback page came back as a preview.",
+     "status": "fail"
+    }
+   },
+   {
+    "instance": "head",
+    "kind": "ok",
+    "text": "Blocked before any fetch",
+    "overlay": {
+     "title": "Blocked, nothing fetched",
+     "body": "The preview is empty.",
+     "status": "ok"
+    }
+   }
+  ]
+ },
+ "other-forms": {
+  "status": {
+   "id": "other-forms",
+   "status": "done"
+  },
+  "ms": 3000,
+  "events": [
+   {
+    "instance": "base",
+    "kind": "hook",
+    "text": "::ffff:a9fe:a9fe is public",
+    "flow": {
+     "id": "ssrf",
+     "node": "guard",
+     "status": "fail",
+     "label": "4 of 6 pass"
+    }
+   },
+   {
+    "instance": "head",
+    "kind": "hook",
+    "text": "::ffff:a9fe:a9fe is private",
+    "flow": {
+     "id": "ssrf",
+     "node": "guard",
+     "status": "ok",
+     "label": "6 of 6 blocked"
+    }
+   },
+   {
+    "instance": "base",
+    "kind": "fail",
+    "text": "4 of 6 spellings pass the guard",
+    "overlay": {
+     "title": "4 of 6 spellings pass",
+     "status": "fail"
+    }
+   },
+   {
+    "instance": "head",
+    "kind": "ok",
+    "text": "All 6 blocked",
+    "overlay": {
+     "title": "All 6 blocked",
+     "status": "ok"
+    }
+   }
+  ]
+ },
+ "unit-tests": {
+  "status": {
+   "id": "unit-tests",
+   "status": "failed",
+   "output": "not ok 4 - unfurl refuses an IPv4-mapped loopback host\n  Error: connect ECONNREFUSED 127.0.0.1:5432"
+  },
+  "ms": 2500,
+  "events": [
+   {
+    "instance": "head",
+    "kind": "request",
+    "text": "node --test test/unfurl.test.ts"
+   }
+  ]
+ }
+}

package/review-app/playground/fixtures/rply-16/instances.json

@@ -0,0 +1 @@
+{}

package/review-app/playground/fixtures/rply-16/review.tsx

@@ -0,0 +1,98 @@
+// A complete review, for joshuaKnauber/rply#16: a backend fix with no visible UI, so the evidence is flows and overlays.
+// To try it with the sample data in src/data, copy it over src/review.tsx and change the imports to "./kit".
+import { Attention, BeforeAfter, Card, Chapter, defineReview, Flow, Lead, Outcome, Overview, type FlowDef } from "../../../src/kit";
+
+const UNFURL = "packages/server/src/routes/unfurl.ts";
+
+const ssrf: FlowDef = {
+  id: "ssrf",
+  title: "Link preview request path",
+  nodes: [
+    { id: "route", title: "GET /v1/unfurl", sub: "authenticated member", col: 0, row: 0 },
+    { id: "guard", title: "assertPublic", sub: "isPrivate(address)", col: 1, row: 0 },
+    { id: "internal", title: "Loopback / metadata", sub: "127.0.0.1:9199", col: 2, row: 0 },
+  ],
+  edges: [["route", "guard"], ["guard", "internal"]],
+  changed: ["guard"],
+};
+
+export default defineReview({
+  instances: [
+    { id: "base", label: "Base", detail: "main", port: 7781 },
+    { id: "head", label: "Head", detail: "this PR", port: 8080 },
+  ],
+
+  overview: () => (
+    <Overview>
+      <Lead>Link previews can no longer reach the server's own network through IPv6 spellings of private addresses.</Lead>
+      <BeforeAfter
+        before={<>The guard only stripped a dotted <code>::ffff:</code> prefix. URL parsing turns <code>[::ffff:127.0.0.1]</code> into <code>[::ffff:7f00:1]</code>, which looked public, so the server fetched its own loopback and returned the page.</>}
+        after="The guard reads every address as eight 16-bit groups, judges IPv6 that embeds IPv4 as that IPv4, and blocks private ranges before any fetch. Addresses it cannot parse are blocked too."
+      />
+      <Card caption="Dashed: changed in this PR. The tour lights it up on base and head.">
+        <Flow def={ssrf} />
+      </Card>
+      <Attention
+        items={[
+          { text: "Addresses the parser cannot read now count as private", detail: "Failing closed is right for a guard, but any odd resolver output now blocks a preview.", to: { group: "core" } },
+          { claim: { source: "PR description", quote: "The guard now parses each address and rejects the full loopback, link-local, unique-local, multicast, mapped, and NAT64 ranges before it fetches.", status: "neutral", label: "Mostly true" }, detail: "True for those ranges, but 6to4 (2002::/16), SIIT and 2001:db8::/32 are still treated as public, so \u201creserved\u201d in the title is broader than what is checked. None reach loopback on a normal host.", to: { chapter: "other-forms" } },
+          { text: "DNS rebinding still bypasses the guard", detail: "assertPublic and fetch resolve the host separately. The PR says so and leaves it for later." },
+        ]}
+        held={[
+          { source: "PR description", quote: "A URL whose host is an IPv4-mapped IPv6 address such as ::ffff:7f00:1 passed the private-address check, so the server connected to loopback.", to: { chapter: "mapped-loopback" } },
+          { source: "PR description", quote: "Parsing the address into groups and checking the full ranges classifies all 15 private test addresses as private and keeps the 5 public ones public.", to: { chapter: "unit-tests" } },
+        ]}
+      />
+    </Overview>
+  ),
+
+  chapters: [
+    {
+      id: "mapped-loopback",
+      title: "A loopback page through ::ffff:7f00:1",
+      page: () => (
+        <Chapter
+          title="A loopback page through ::ffff:7f00:1"
+          step="mapped-loopback"
+          expect={{ base: "Returns the internal page, titled “internal”.", head: "Returns no title. The guard blocks before any fetch." }}
+          flow={ssrf}
+          here="guard"
+          group="core"
+        >
+          Signs in as the demo user on each instance and asks for a preview of <code>http://[::ffff:7f00:1]:9199/</code>, a page only reachable on the server's loopback.
+        </Chapter>
+      ),
+    },
+    {
+      id: "other-forms",
+      title: "Other spellings of private addresses",
+      page: () => (
+        <Chapter
+          title="Other spellings of private addresses"
+          step="other-forms"
+          expect={{ base: "The mapped and NAT64 spellings pass the guard.", head: "Every spelling is blocked." }}
+          flow={ssrf}
+          here="guard"
+          group="parse"
+        >
+          Tries the metadata address in mapped hex form, dotted-mapped, the long zero form, <code>fe90::</code>, multicast <code>ff02::</code> and NAT64.
+        </Chapter>
+      ),
+    },
+    {
+      id: "unit-tests",
+      title: "The PR's own tests",
+      page: () => (
+        <Chapter title="The PR's own tests" step="unit-tests" expect={{ head: "15 private and 5 public addresses classified right, and the mapped-loopback test passes." }} group="tests" evidence={<Outcome empty="Press Run: the PR's test file runs against head." />}>
+          Runs the PR's test file against head: the address table and an end-to-end test against a real server on loopback.
+        </Chapter>
+      ),
+    },
+  ],
+
+  groups: [
+    { id: "core", title: "Embedded IPv4 is judged as IPv4", why: "The fix itself. isPrivate first asks for the IPv4 inside an IPv6 address, then checks the IPv6 ranges.", chapter: "mapped-loopback", file: UNFURL, lines: [[79, 107]] },
+    { id: "parse", title: "Addresses become numbers", why: "Prefix string checks are replaced by parsing into eight groups, so every spelling of one address is the same address.", chapter: "other-forms", file: UNFURL, lines: [[109, 128]] },
+    { id: "tests", title: "Tests", why: "An address table, and an end-to-end test against a real server on loopback.", chapter: "unit-tests", file: "packages/server/test/unfurl.test.ts", lines: [[1, 8], [49, 76]] },
+  ],
+});

package/review-app/playground/gallery.tsx

@@ -0,0 +1,127 @@
+// Every kit component in its states, on one page, to work on the look. Uses the fixture's review for navigation.
+import type { ReactNode } from "react";
+import { NavContext, type Review } from "../src/kit/review";
+import { FlowCompare } from "../src/kit/flow";
+import { Attention, BeforeAfter, Card, Compare, Diff, FileLine, Flow, Icon, Label, Lead, Live, Outcome, Row, Rows, Shot, Stat, pr, type FlowDef, type ReviewEvent } from "../src/kit";
+import { ChapterContext } from "../src/kit/review";
+
+const flow: FlowDef = {
+  id: "demo",
+  title: "Link preview request path",
+  nodes: [
+    { id: "route", title: "GET /v1/unfurl", sub: "authenticated member", col: 0, row: 0 },
+    { id: "guard", title: "assertPublic", sub: "isPrivate(address)", col: 1, row: 0 },
+    { id: "internal", title: "Loopback / metadata", sub: "127.0.0.1:9199", col: 2, row: 0 },
+    { id: "cache", title: "Preview cache", sub: "kv", col: 1, row: 1 },
+  ],
+  edges: [["route", "guard"], ["guard", "internal"], ["guard", "cache"]],
+  changed: ["guard"],
+};
+let seq = 0;
+const ev = (instance: string, kind: ReviewEvent["kind"], text: string, f?: ReviewEvent["flow"], overlay?: ReviewEvent["overlay"]): ReviewEvent => ({ seq: ++seq, instance, kind, text, flow: f, overlay });
+const failing = [ev("base", "hook", "x", { id: "demo", edge: ["route", "guard"] }), ev("base", "hook", "x", { id: "demo", node: "guard", status: "fail", label: "public" }), ev("base", "hook", "x", { id: "demo", edge: ["guard", "internal"], node: "internal", status: "fail", label: "fetched" })];
+const passing = [ev("head", "hook", "x", { id: "demo", edge: ["route", "guard"] }), ev("head", "hook", "x", { id: "demo", node: "guard", status: "ok", label: "blocked" })];
+const overlays = [ev("base", "fail", "Order is reversed", undefined, { title: "Leaked “internal”", body: "The loopback page came back as a preview.", status: "fail" }), ev("head", "ok", "Order is − 100% +", undefined, { title: "Blocked, nothing fetched", body: "The preview is empty.", status: "ok" })];
+
+const email = [ev("base", "ok", "No email", undefined, { title: "No email", status: "neutral" }), ev("head", "ok", "You have 2 unread messages in rply", undefined, { title: "You have 2 unread messages in rply", body: "To: quiet-agent@example.com\nSubject: You have 2 unread messages in rply\n\nYour agents are waiting on you:\n\n- Cron job: 2 unread\n  http://localhost:8080/c/rx2v49azvt1fs2vd\n\nTurn on notifications in rply to get these as push notifications instead of emails.", status: "ok" })];
+
+const SECTIONS = ["Foundations", "Buttons", "Rows", "Overview", "Flow", "Screenshots", "Live instances", "Code"];
+
+function Sec({ title, children, note }: { title: string; children: ReactNode; note?: ReactNode }) {
+  return (
+    <section className="g-sec" id={`g-${title}`}>
+      <div className="g-head"><h2>{title}</h2>{note && <p>{note}</p>}</div>
+      <div className="g-body">{children}</div>
+    </section>
+  );
+}
+const Spec = ({ name, children }: { name: string; children: ReactNode }) => <div className="g-spec"><div className="g-name">{name}</div><div>{children}</div></div>;
+
+const TOKENS = ["--bg", "--panel", "--card", "--raised", "--line", "--line-2", "--text", "--text-2", "--text-3", "--green", "--red", "--amber", "--green-bg", "--red-bg", "--amber-bg", "--add", "--del"];
+
+export function Gallery({ review }: { review: Review }) {
+  const first = pr.files[0]?.path;
+  const visual = pr.repo === "excalidraw";
+  return (
+    <NavContext.Provider value={{ review, go: (t) => (location.hash = typeof t === "string" ? (t === "overview" ? "#/" : "#/changes") : "chapter" in t ? `#/chapter/${t.chapter}` : `#/changes/${t.group}`) }}>
+      <nav className="rail">
+        <div className="pr"><span className="r">{Icon.pr} Review kit</span><b>Gallery</b></div>
+        {SECTIONS.map((s) => <a key={s} className="g-link" href={`#/gallery`} onClick={(e) => { e.preventDefault(); document.getElementById(`g-${s}`)?.scrollIntoView({ behavior: "smooth" }); }}>{s}</a>)}
+        <div className="gap" />
+        <a className="g-link" href="#/">Open the review</a>
+      </nav>
+      <main className="gallery-main">
+        <Sec title="Foundations" note="Tokens follow the system theme. Color is only for status.">
+          <div className="g-swatches">{TOKENS.map((t) => <div key={t}><i style={{ background: `var(${t})` }} /><code>{t}</code></div>)}</div>
+          <Spec name="title"><h1 className="title">Preserve zoom controls order in RTL locales</h1></Spec>
+          <Spec name="lead"><Lead>In right-to-left languages the zoom controls keep their − 100% + order.</Lead></Spec>
+          <Spec name="prose"><p className="prose">Opens each instance in Hebrew and Arabic and sorts the three zoom buttons by their position on screen.</p></Spec>
+          <Spec name="label"><Label count={3}>Worth a close look</Label></Spec>
+          <Spec name="stat"><Stat add={46} del={7} /></Spec>
+        </Sec>
+
+        <Sec title="Buttons">
+          <div className="g-row">
+            <button className="btn primary">{Icon.play} Run</button>
+            <button className="btn">{Icon.code} Show the code</button>
+            <button className="btn ghost">{Icon.back} Overview</button>
+            <button className="btn sm">{Icon.play} Chapter 1</button>
+            <button className="btn primary" disabled>{Icon.play} Running</button>
+          </div>
+        </Sec>
+
+        <Sec title="Rows">
+          <Spec name="file">{first && <Rows><Row><FileLine path={first} add={pr.files[0].add} del={pr.files[0].del} /></Row><Row to="changes" toLabel="Code"><FileLine path="packages/excalidraw/components/a/very/deeply/nested/folder/structure/ZoomActions.module.scss" add={12} del={0} /></Row></Rows>}</Spec>
+          <Spec name="attention">
+            <Attention items={[{ text: "Direction is set twice", detail: "Both the .zoom-actions rule and an inline style set direction: ltr; one is redundant.", to: { group: review.groups[0]?.id ?? "x" } }, { text: "A finding with no link", detail: "Some findings have nothing to point at." }]} />
+          </Spec>
+          <Spec name="claims">
+            <Attention
+              items={[
+                { claim: { source: "coderabbitai[bot]", quote: "Zen mode is unaffected by this change.", status: "fail" }, detail: "The zoom percentage still sits on the wrong side in zen mode.", to: { chapter: review.chapters[0]?.id ?? "x" } },
+                { claim: { source: "PR description", quote: "That separate weakness is recorded and is not addressed here.", status: "neutral", label: "Known, out of scope" }, detail: "assertPublic and fetch still resolve the host separately." },
+              ]}
+              held={[{ source: "PR description", quote: "A URL whose host is an IPv4-mapped IPv6 address passed the private-address check.", to: { chapter: review.chapters[0]?.id ?? "x" } }]}
+            />
+          </Spec>
+        </Sec>
+
+        <Sec title="Overview">
+          <BeforeAfter before={<>The row followed the page direction, so in RTL it read <code>+ 100% −</code>.</>} after={<>The row is forced to <code>direction: ltr</code>, so it reads <code>− 100% +</code> everywhere.</>} />
+          <Card caption="Dashed: changed in this PR. The tour lights it up on base and head."><Flow def={flow} /></Card>
+        </Sec>
+
+        <Sec title="Flow" note="The diagram with a failing run, and the comparison a chapter shows beside its text.">
+          <Spec name="default, failing"><Card><Flow def={flow} here="guard" events={failing} /></Card></Spec>
+          <Spec name="beside a chapter, base failing and head passing"><div style={{ maxWidth: 336 }}><FlowCompare def={flow} here="guard" instances={review.instances} events={[...failing.map((e) => ({ ...e, instance: "base" })), ...passing.map((e) => ({ ...e, instance: "head" }))]} /></div></Spec>
+        </Sec>
+
+        <Sec title="Screenshots" note={visual ? undefined : "Run the playground with the excalidraw fixture to see real screenshots."}>
+          {visual && <>
+            <Spec name="shot"><Shot src="shots/head-he-hover.png" title="Head, Hebrew, hovering +" caption="The tooltip sits on the right side of the button." /></Spec>
+            <Spec name="compare, side by side"><Compare title="The zoom controls in Hebrew" base="shots/base-he-IL-zoom.png" head="shots/head-he-IL-zoom.png" caption="Base mirrors the controls; head keeps − 100% +." /></Spec>
+            <Spec name="compare, slider"><Compare base="shots/base-he-dark.png" head="shots/head-he-dark.png" mode="slider" /></Spec>
+            <Spec name="compare, difference"><Compare base="shots/base-en-US-zoom.png" head="shots/head-en-US-zoom.png" mode="diff" caption="English: no pixel changes." /></Spec>
+            <Spec name="compare, whole page"><Compare base="shots/base-he-page.png" head="shots/head-he-page.png" /></Spec>
+          </>}
+        </Sec>
+
+        <Sec title="Live instances" note="Frames with an outcome overlay, as a step leaves them.">
+          <ChapterContext.Provider value={{ events: overlays, instances: review.instances }}>
+            <div className="g-frames"><Live /></div>
+            <Spec name="outcome"><Outcome /></Spec>
+          </ChapterContext.Provider>
+          <ChapterContext.Provider value={{ events: email, instances: review.instances }}>
+            <Spec name="outcome, a long result and none"><Outcome /></Spec>
+          </ChapterContext.Provider>
+          <Spec name="outcome, not run"><Outcome /></Spec>
+        </Sec>
+
+        <Sec title="Code">
+          {review.groups[0] && <Spec name="a group's lines, the rest folded"><div className="file"><div className="fh"><FileLine path={review.groups[0].file} /></div><Diff file={review.groups[0].file} lines={review.groups[0].lines} /></div></Spec>}
+          {first && <Spec name="a whole file"><div className="file"><div className="fh"><FileLine path={first} /></div><Diff file={first} /></div></Spec>}
+        </Sec>
+      </main>
+    </NavContext.Provider>
+  );
+}

package/review-app/playground/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Review playground</title>
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=Geist+Mono:wght@400;500&display=swap" rel="stylesheet">
+</head>
+<body>
+<div id="root"></div>
+<script type="module" src="./main.tsx"></script>
+</body>
+</html>

package/review-app/playground/main.tsx

@@ -0,0 +1,26 @@
+// The playground: the fixture's review in the real frame, or the gallery at #/gallery.
+// ?still turns off animation, for screenshots.
+import { useEffect, useState } from "react";
+import { createRoot } from "react-dom/client";
+import review from "@review";
+import { App } from "../src/App";
+import { Gallery } from "./gallery";
+import "../src/kit/kit.css";
+import "./playground.css";
+
+const params = new URLSearchParams(location.search);
+if (params.has("still")) document.documentElement.classList.add("still");
+// ?run presses Run once the chapter is up, for screenshots of results
+if (params.has("run")) { const t = setInterval(() => { const b = document.getElementById("run"); if (b) { clearInterval(t); setTimeout(() => b.click(), 300); } }, 100); }
+
+function Root() {
+  const [gallery, setGallery] = useState(location.hash.startsWith("#/gallery"));
+  useEffect(() => {
+    const on = () => setGallery(location.hash.startsWith("#/gallery"));
+    addEventListener("hashchange", on);
+    return () => removeEventListener("hashchange", on);
+  }, []);
+  return gallery ? <Gallery review={review} /> : <App review={review} />;
+}
+
+createRoot(document.getElementById("root")!).render(<Root />);

package/review-app/playground/mock.ts

@@ -0,0 +1,215 @@
+// The review server's API, played from a fixture: recorded events replay when a step runs, files and instance
+// stand-ins come from the fixture directory. Lets the kit run without a box.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, resolve, sep } from "node:path";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { Plugin } from "vite";
+import { validateAnswer, validateComment, validateVerdict, type CommentInput, type ReviewComment, type Verdict } from "../../src/review/contract";
+
+interface Recorded { status: { id: string; status: "done" | "failed"; output?: string }; ms: number; events: Record<string, unknown>[] }
+
+const TYPES: Record<string, string> = { ".png": "image/png", ".jpg": "image/jpeg", ".webp": "image/webp", ".webm": "video/webm", ".svg": "image/svg+xml" };
+
+// local: the review is of local changes, so comments go to the developer's agent, played here too
+export function mockReviewServer(fixture: string, local = false): Plugin {
+  const recorded: Record<string, Recorded> = existsSync(join(fixture, "events.json")) ? JSON.parse(readFileSync(join(fixture, "events.json"), "utf8")) : {};
+  // box port -> a screenshot standing in for the live app
+  const instances: Record<string, string> = existsSync(join(fixture, "instances.json")) ? JSON.parse(readFileSync(join(fixture, "instances.json"), "utf8")) : {};
+  let events: Record<string, unknown>[] = [];
+  let steps: Record<string, unknown> = {};
+  let running: string | undefined;
+  // comments live as long as the playground runs; GitHub and the agents only pretend
+  let comments: ReviewComment[] = [];
+  let nextComment = 1;
+  let verdict: Verdict = {};
+  const updates: { n: number; at: string; note: string; refreshed?: string }[] = [];
+  // the PR as GitHub would report it, for the pull request page
+  const checkRun = (name: string, status: string, workflow: string, secs: number) => ({ name, status, workflow, url: "https://github.com/excalidraw/excalidraw/actions", started: "2026-11-15T09:00:00Z", ...(status !== "pending" && { finished: new Date(Date.parse("2026-11-15T09:00:00Z") + secs * 1000).toISOString() }) });
+  let prStatus: Record<string, unknown> = {
+    number: 12602, title: "fix: preserve zoom controls order in RTL locales (#12375)", url: "https://github.com/excalidraw/excalidraw/pull/12602", body: "Fixes #12375.\n\nIn RTL locales the zoom row reversed, so **+** and **−** swapped sides. This pins the row to `direction: ltr`:\n\n- `Actions.tsx`: inline style on the row\n- `Actions.scss`: the same on `.zoom-actions`\n- a test for both locales\n\nZen mode keeps its RTL mirroring.", state: "OPEN", draft: false, author: "yashash1111",
+    head: { ref: "fix/zoom-buttons-rtl", oid: "abc123" }, base: "master", additions: 20, deletions: 13, files: 4,
+    mergeable: "MERGEABLE", mergeState: "UNSTABLE", reviewDecision: "REVIEW_REQUIRED",
+    reviews: [{ by: "dwelle", state: "COMMENTED", at: "2026-11-12T10:00:00Z" }, { by: "mtolmacs", state: "APPROVED", at: "2026-11-14T16:20:00Z" }],
+    requested: ["dwelle"],
+    checks: [checkRun("test", "pass", "Tests", 214), checkRun("lint", "pass", "Lint", 48), checkRun("size-limit", "fail", "Size", 95), checkRun("e2e (chromium)", "pending", "E2E", 0), { name: "Vercel – excalidraw-package-example", status: "pass", url: "https://vercel.com", started: "2026-11-15T09:01:00Z", finished: "2026-11-15T09:02:30Z" }],
+    canMerge: true, methods: ["SQUASH", "MERGE"], defaultMethod: "SQUASH",
+  };
+  const clients = new Set<ServerResponse>();
+  const send = (res: ServerResponse, ev: string, data: unknown) => res.write(`event: ${ev}\ndata: ${JSON.stringify(data)}\n\n`);
+  const broadcast = (ev: string, data: unknown) => clients.forEach((c) => send(c, ev, data));
+  const json = (res: ServerResponse, code: number, body: unknown) => res.writeHead(code, { "content-type": "application/json" }).end(JSON.stringify(body));
+
+  function run(id: string) {
+    const rec = recorded[id];
+    running = id;
+    steps[id] = { id, status: "running" };
+    broadcast("step", steps[id]);
+    const gap = Math.max(250, Math.min(900, rec.ms / Math.max(1, rec.events.length + 1)));
+    rec.events.forEach((e, i) =>
+      setTimeout(() => {
+        const ev = { ...e, step: id, seq: events.length + 1 };
+        events.push(ev);
+        broadcast("event", ev);
+      }, gap * (i + 1)),
+    );
+    setTimeout(() => {
+      running = undefined;
+      steps[id] = rec.status;
+      broadcast("step", rec.status);
+    }, gap * (rec.events.length + 1));
+  }
+
+  const read = (req: IncomingMessage) => new Promise<string>((ok) => { let b = ""; req.on("data", (c) => (b += c)); req.on("end", () => ok(b)); });
+
+  async function handle(req: IncomingMessage, res: ServerResponse, next: () => void) {
+    const u = new URL(req.url ?? "/", "http://playground");
+    const p = u.pathname;
+    if (p === "/api/status") return json(res, 200, { app: true });
+    if (p === "/api/urls") {
+      const host = `http://${req.headers.host}`;
+      return json(res, 200, Object.fromEntries(Object.keys(instances).map((port) => [port, `${host}/__instance/${port}/`])));
+    }
+    if (p === "/api/events" && req.method === "GET") {
+      res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
+      send(res, "state", { steps });
+      send(res, "comments", { comments });
+      send(res, "verdict", verdict);
+      send(res, "agent", { local, listening: local });
+      send(res, "updates", { updates });
+      events.forEach((e) => send(res, "event", e));
+      send(res, "ready", {});
+      clients.add(res);
+      req.on("close", () => clients.delete(res));
+      return;
+    }
+    const step = req.method === "POST" && p.match(/^\/api\/steps\/([^/]+)\/run$/);
+    if (step) {
+      const id = decodeURIComponent(step[1]);
+      if (!recorded[id]) return json(res, 404, { errors: [`no recorded step "${id}"`] });
+      if (running) return json(res, 409, { errors: [`step "${running}" is still running`] });
+      run(id);
+      return json(res, 202, { id, status: "running" });
+    }
+    if (p === "/api/reset" && req.method === "POST") {
+      events = [];
+      steps = {};
+      broadcast("reset", {});
+      return res.writeHead(204).end();
+    }
+    if (p === "/api/comments" && req.method === "GET") return json(res, 200, { comments });
+    if (p === "/api/verdict" && req.method === "GET") return json(res, 200, verdict);
+    // a moment's wait, as GitHub takes, so the page shows its skeleton first
+    if (p === "/api/pr" && req.method === "GET") return local ? json(res, 409, { errors: ["these are local changes with no PR"] }) : setTimeout(() => json(res, 200, prStatus), 900);
+    if (req.method !== "POST" && req.method !== "PATCH" && req.method !== "DELETE") return handleRest();
+    const body = JSON.parse((await read(req)) || "{}");
+    const changed = () => broadcast("comments", { comments });
+    if (p === "/api/verdict") {
+      const errors = validateVerdict(body);
+      if (errors.length) return json(res, 400, { errors });
+      verdict = body;
+      broadcast("verdict", verdict);
+      return json(res, 200, verdict);
+    }
+    if (p === "/api/comments" && req.method === "POST") {
+      const errors = validateComment(body);
+      if (errors.length) return json(res, 400, { errors });
+      const { mode, ...input } = body as CommentInput;
+      if (input.to === "github") {
+        if (local) return json(res, 409, { errors: ["these are local changes with no PR: comments go to your agent"] });
+        if (mode === "single" && comments.some((c) => c.github?.state === "pending")) return json(res, 502, { errors: ["you have a review in progress on GitHub: add the comment to it"] });
+      }
+      const id = nextComment++;
+      const c: ReviewComment = {
+        ...input,
+        id: `c${id}`,
+        at: new Date().toISOString(),
+        by: "reviewer",
+        ...(input.to === "github" ? { github: { state: mode === "single" ? "posted" : "pending", node: `C_${id}`, id: 90000 + id, url: `https://github.com/excalidraw/excalidraw/pull/12602#discussion_r${90000 + id}` } } : { status: "sent" }),
+      } as ReviewComment;
+      comments.push(c);
+      changed();
+      if (c.to === "agent") agentWorks([c]);
+      return setTimeout(() => json(res, 201, c), 250);
+    }
+    const one = p.match(/^\/api\/comments\/(c\d+)(\/answer)?$/);
+    if (one?.[2]) {
+      const errors = validateAnswer(body);
+      if (errors.length) return json(res, 400, { errors });
+      return json(res, 201, answer(one[1], body.body, body.commit));
+    }
+    if (one) {
+      const c = comments.find((x) => x.id === one[1]);
+      if (!c) return json(res, 404, { errors: [`no comment ${one[1]} of yours`] });
+      if (c.to === "agent" && c.status !== "sent") return json(res, 409, { errors: ["the agent is already working on it"] });
+      if (req.method === "DELETE") comments = comments.filter((x) => x !== c);
+      else c.body = body.body;
+      changed();
+      return req.method === "DELETE" ? res.writeHead(204).end() : json(res, 200, c);
+    }
+    if (p === "/api/finish") return res.writeHead(204).end();
+    if (p === "/api/pr/merge") {
+      if (!["MERGE", "SQUASH", "REBASE"].includes(body.method)) return json(res, 400, { errors: ["method: expected one of MERGE, SQUASH, REBASE"] });
+      prStatus = { ...prStatus, state: "MERGED", merged: { at: new Date().toISOString(), by: "you" } };
+      return setTimeout(() => json(res, 200, prStatus), 700);
+    }
+    if (p === "/api/submit") {
+      if (!verdict.event) return json(res, 400, { errors: ["choose a verdict before submitting"] });
+      comments.forEach((c) => c.github?.state === "pending" && (c.github.state = "posted"));
+      verdict = {};
+      changed();
+      broadcast("verdict", verdict);
+      return setTimeout(() => json(res, 200, { url: "https://github.com/excalidraw/excalidraw/pull/12602#pullrequestreview-1" }), 600);
+    }
+    return handleRest();
+
+    function handleRest() {
+      return rest(req, res, p, next);
+    }
+  }
+
+  function answer(id: string, body: string, commit?: string) {
+    const c = comments.find((x) => x.id === id)!;
+    c.status = "done";
+    const a: ReviewComment = { id: `c${nextComment++}`, at: new Date().toISOString(), by: "agent", to: "agent", replyTo: id, body, ...(commit && { commit }) };
+    comments.push(a);
+    broadcast("comments", { comments });
+    return a;
+  }
+
+  // the agent picks up what was sent, works a while, answers each, and the tour notes the update
+  function agentWorks(sent: ReviewComment[]) {
+    if (!sent.length) return;
+    setTimeout(() => {
+      sent.forEach((c) => (c.status = "working"));
+      broadcast("comments", { comments });
+    }, 900);
+    setTimeout(() => {
+      sent.forEach((c) => answer(c.id, `On ${c.topic!.label}, checked in the box:\n\n- Base renders the zoom buttons in DOM order, so in RTL the flex row **reverses** them.\n- Head pins the row to \`direction: ltr\`, which is why chapter 1 shows *− 100% +* in both locales.\n\n| Locale | Base | Head |\n| --- | --- | --- |\n| he-IL | + 100% − | − 100% + |\n| en-US | − 100% + | − 100% + |\n\n> The class on the wrapper is redundant with the inline style.\n\nNothing was changed.`));
+    }, 3500);
+  }
+
+  function rest(req: IncomingMessage, res: ServerResponse, p: string, next: () => void) {
+    if (p.startsWith("/files/")) {
+      const root = resolve(fixture, "files");
+      const file = resolve(root, "." + sep + decodeURIComponent(p.slice(7)));
+      if (!file.startsWith(root + sep) || !existsSync(file) || !statSync(file).isFile()) return res.writeHead(404).end();
+      return res.writeHead(200, { "content-type": TYPES[extname(file)] ?? "application/octet-stream" }).end(readFileSync(file));
+    }
+    const inst = p.match(/^\/__instance\/(\d+)\/?$/);
+    if (inst) {
+      const shot = instances[inst[1]];
+      const body = shot
+        ? `<img src="/files/${shot}" style="display:block;width:100%;height:100vh;object-fit:cover;object-position:top">`
+        : `<div style="height:100vh;display:grid;place-items:center;font:14px -apple-system,sans-serif;color:#888">Live app on port ${inst[1]}</div>`;
+      return res.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(`<!doctype html><body style="margin:0;background:#fff">${body}</body>`);
+    }
+    next();
+  }
+
+  return {
+    name: "mock-review-server",
+    configureServer(server) {
+      server.middlewares.use((req, res, next) => void handle(req, res, next));
+    },
+  };
+}