@myrtilleio/redline 0.1.0

package/src/mcp.js

@@ -0,0 +1,380 @@
+// Redline as an MCP server over stdio (newline-delimited JSON-RPC 2.0), without
+// dependencies. stdout carries protocol messages only; logs go to stderr.
+import { readFile } from 'node:fs/promises';
+import { extname, join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { formatMarkdown } from './format.js';
+import { createRedlineServer } from './server.js';
+import { Store } from './store.js';
+import { describeVerify, openVerifier, verifyApprovals } from './verify.js';
+
+const PROTOCOL_VERSIONS = ['2025-06-18', '2025-03-26', '2024-11-05'];
+
+const WAIT_DEFAULT = 240;
+const WAIT_MAX = 1800;
+const PROGRESS_EVERY = 15_000;
+
+const TOOLS = [
+  {
+    name: 'wait_for_round',
+    description:
+      'Wait until the reviewer presses Send in the Redline overlay, then get their round: the same brief as `feedback`, with screenshots. ' +
+      'Returns at once if a round is already waiting. Use it to work in a loop without the human prompting you: ' +
+      'wait_for_round → fix each item and `resolve` → `finish_round` → wait_for_round again. ' +
+      'If it says the reviewer has not sent anything yet, call it again to keep waiting.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        timeout_seconds: { type: 'number', description: `How long to wait before returning "still waiting" (default ${WAIT_DEFAULT}, max ${WAIT_MAX})` },
+      },
+    },
+  },
+  {
+    name: 'feedback',
+    description:
+      'Get the design feedback the reviewer left on the website with the Redline overlay: notes on components and pen marks, ' +
+      'each marked Good (keep), Fix (change) or Idea, with the element selector, text, styles, screen width and page state. ' +
+      'Call this before changing the site, then fix each item and call `resolve`.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        page: { type: 'string', description: 'Only items for this page path, e.g. "/pricing"' },
+        include_resolved: { type: 'boolean', description: 'Also include resolved items (default false)' },
+        format: { type: 'string', enum: ['markdown', 'json'], description: 'markdown (default) is an actionable brief; json is the raw data' },
+      },
+    },
+  },
+  {
+    name: 'propose_variants',
+    description:
+      'Offer the reviewer options instead of guessing, when a mark could reasonably be fixed several ways (or when they asked for options): give 2–5 alternatives. Each is {label, css, html?, note?}: in `css`, `&` ' +
+      'stands for the item\'s element (e.g. "& { font-size: 32px } & h3 { … }"); `html` replaces the element\'s contents. ' +
+      'The reviewer flips between them on the live page and picks one; the pick then shows up in `feedback` for you to build.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'string', description: 'Item id or pin number' },
+        variants: {
+          type: 'array',
+          minItems: 2,
+          maxItems: 5,
+          items: {
+            type: 'object',
+            properties: {
+              label: { type: 'string', description: 'Two or three words, e.g. "Bold serif"' },
+              css: { type: 'string' },
+              html: { type: 'string' },
+              note: { type: 'string', description: 'One line: the idea behind it' },
+            },
+            required: ['label'],
+          },
+        },
+      },
+      required: ['id', 'variants'],
+    },
+  },
+  {
+    name: 'reply',
+    description: 'Answer the reviewer in an item\'s conversation (they asked something, or you explain what you did or why). They see it on the page.',
+    inputSchema: { type: 'object', properties: { id: { type: 'string', description: 'Item id or pin number' }, text: { type: 'string' } }, required: ['id', 'text'] },
+  },
+  {
+    name: 'finish_round',
+    description:
+      'Close the round when you have handled what the reviewer sent: a one-paragraph summary of what you changed, how you read the page ' +
+      '(its purpose, in two sentences, so they can correct you), and at most 3 questions you need answered. They see it as one report.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        summary: { type: 'string' },
+        reading: { type: 'string', description: 'How you understand the page and what it is for' },
+        questions: { type: 'array', items: { type: 'string' }, maxItems: 3 },
+      },
+      required: ['summary'],
+    },
+  },
+  {
+    name: 'check_approvals',
+    description:
+      'Before finish_round: check that everything the reviewer approved (green marks, accepted fixes) still looks exactly as approved, ' +
+      'at every screen width it is guarded at, by photographing it now in headless Chrome. Records nothing: the reviewer only sees the check ' +
+      'Redline runs when you close the round, so fix anything this finds first. Returns what changed, in words, with the approved screenshots. ' +
+      'Uses the running review session; otherwise pass `dir` (static folder) or `url` (dev server).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: 'Static site directory, when no review session is running' },
+        url: { type: 'string', description: 'Dev server URL, when no review session is running' },
+      },
+    },
+  },
+  {
+    name: 'resolve',
+    description:
+      'Mark feedback items as done after changing the code. The reviewer sees a ✓ and your note on the pin in their browser. ' +
+      'Also resolve Good items, noting the pattern was kept.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ids: { type: 'array', items: { type: 'string' }, description: 'Item ids (a_1b2c3d4e) or pin numbers ("3")' },
+        note: { type: 'string', description: 'One line: what you changed' },
+        target: { type: 'string', description: 'Optional CSS selector for the "after" screenshot, when your fix moved or restructured the element (e.g. "#faq")' },
+      },
+      required: ['ids', 'note'],
+    },
+  },
+  {
+    name: 'reopen',
+    description: 'Mark feedback items as open again.',
+    inputSchema: {
+      type: 'object',
+      properties: { ids: { type: 'array', items: { type: 'string' }, description: 'Item ids or pin numbers' } },
+      required: ['ids'],
+    },
+  },
+  {
+    name: 'start_review',
+    description:
+      'Start a Redline review session and return the URL to give the reviewer. Pass `dir` to serve a static site folder ' +
+      '(with live reload), or `url` to put the overlay in front of a running dev server (e.g. http://localhost:5173).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        dir: { type: 'string', description: 'Static site directory to serve' },
+        url: { type: 'string', description: 'Dev server URL to proxy' },
+        port: { type: 'number', description: 'Port to listen on (default 4545)' },
+      },
+    },
+  },
+  {
+    name: 'stop_review',
+    description: 'Stop the review session started with start_review.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+];
+
+export function createMcpHandler({ storeDir, log = () => {}, notify = () => {}, progressEvery = PROGRESS_EVERY, account = null }) {
+  const store = new Store(storeDir);
+  let session = null; // { server, url }
+  const inflight = new Map(); // request id -> AbortController, so a client can cancel a long wait
+
+  async function findAll(refs) {
+    const all = await store.all();
+    return refs.map((ref) => {
+      const a = all.find((x) => x.id === ref) || all.find((x) => String(x.n) === String(ref).replace(/^#/, ''));
+      if (!a) throw new Error(`No feedback item "${ref}". Call \`feedback\` to see current items.`);
+      return a;
+    });
+  }
+
+  // Screenshots and reference images, as MCP image content the model can look at.
+  async function images(list) {
+    const out = [];
+    let budget = 12;
+    for (const a of list) {
+      const files = [
+        ...Object.entries(a.shots || {}).filter(([k]) => k !== 'plain').map(([k, p]) => [`#${a.n} ${k === 'before' ? 'as reviewed (with the mark)' : k === 'proposed' ? 'with the reviewer\'s proposed change' : k}`, p]),
+        ...(a.references || []).filter((r) => r.path).map((r) => [`#${a.n} reference image${r.name ? ` (${r.name})` : ''}`, r.path]),
+      ];
+      for (const [caption, rel] of files) {
+        if (budget-- <= 0) return out;
+        const data = await readFile(join(storeDir, rel)).catch(() => null);
+        if (!data || data.length > 1.5 * 1024 * 1024) continue;
+        const ext = extname(rel).slice(1);
+        out.push({ type: 'text', text: caption }, { type: 'image', data: data.toString('base64'), mimeType: `image/${ext === 'jpg' ? 'jpeg' : ext}` });
+      }
+    }
+    return out;
+  }
+
+  const tools = {
+    async wait_for_round({ timeout_seconds: secs = WAIT_DEFAULT } = {}, { signal, progress } = {}) {
+      const timeoutMs = Math.min(Math.max(Number(secs) || WAIT_DEFAULT, 1), WAIT_MAX) * 1000;
+      const started = Date.now();
+      let last = started;
+      const round = await store.waitForRound({
+        timeoutMs,
+        signal,
+        // Progress keeps clients that reset their timeout on progress from giving up on a long wait.
+        onTick: () => {
+          if (Date.now() - last < progressEvery) return;
+          last = Date.now();
+          progress?.(Math.round((last - started) / 1000), Math.round(timeoutMs / 1000), 'Waiting for the reviewer to press Send');
+        },
+      });
+      if (!round) {
+        if (signal?.aborted) return 'Stopped waiting.';
+        return `The reviewer has not sent a round yet (waited ${Math.round((Date.now() - started) / 1000)}s). Call wait_for_round again to keep waiting.`;
+      }
+      const brief = await tools.feedback();
+      return [{ type: 'text', text: `Round ${round.n} is here: ${round.count} item${round.count === 1 ? '' : 's'} sent at ${round.sentAt}. Fix them, resolve each, call finish_round, then wait_for_round again.` }, ...brief];
+    },
+    async feedback({ page, include_resolved: includeResolved = false, format = 'markdown' } = {}) {
+      let list = await store.list(page);
+      if (!includeResolved) list = list.filter((a) => a.status !== 'resolved');
+      if (format === 'json') return JSON.stringify(list, null, 2);
+      const md = formatMarkdown(list, { includeResolved, rounds: (await store.rounds()).rounds, taste: await store.taste() }).replace(
+        /\n## /,
+        '\n\n## ',
+      );
+      return [{ type: 'text', text: md }, ...(await images(list))];
+    },
+    async reply({ id, text }) {
+      const a = await store.agentSays(id, text);
+      return `Replied on #${a.n}.`;
+    },
+    async finish_round({ summary, reading = '', questions = [] }) {
+      const round = await store.finishRound({ summary, reading, questions });
+      return `Closed round ${round.n}. The reviewer will check your fixes and may answer your questions.`;
+    },
+    async propose_variants({ id, variants }) {
+      const a = await store.proposeVariants(id, variants);
+      return `Proposed ${a.variants.length} options for #${a.n}: ${a.variants.map((v) => `${v.key} “${v.label}”`).join(', ')}. The reviewer will preview them and pick one.`;
+    },
+    async resolve({ ids, note, target }) {
+      const items = await findAll(ids);
+      for (const a of items) await store.resolve(a.id, note, target);
+      return items.map((a) => `✓ resolved #${a.n} (${a.id})`).join('\n');
+    },
+    async reopen({ ids }) {
+      const items = await findAll(ids);
+      for (const a of items) await store.update(a.id, { status: 'open' });
+      return items.map((a) => `↺ reopened #${a.n} (${a.id})`).join('\n');
+    },
+    async start_review({ dir, url, port = 4545 } = {}) {
+      if (session) return `Already running at ${session.url}. Call stop_review first to change it.`;
+      if (!dir === !url) throw new Error('Pass exactly one of `dir` (static folder) or `url` (dev server).');
+      const target = url && new URL(/^https?:\/\//.test(url) ? url : `http://${url}`).origin;
+      const server = createRedlineServer(dir ? { root: resolve(dir), storeDir, log } : { target, storeDir, log });
+      await new Promise((ok, fail) => {
+        server.once('error', (err) => fail(err.code === 'EADDRINUSE' ? new Error(`Port ${port} is in use; pass another port.`) : err));
+        server.listen(port, '127.0.0.1', ok);
+      });
+      session = { server, url: `http://127.0.0.1:${server.address().port}/` };
+      return (
+        `Review session running at ${session.url} (${dir ? `serving ${resolve(dir)}` : `proxying ${target}`}).\n` +
+        'Give the reviewer this URL. In the page: P draws on anything (or click something to say why), Send hands you the round, ' +
+        'Review is where they accept or redo your fixes. Call `wait_for_round` to be handed the round as soon as they send.'
+      );
+    },
+    async check_approvals({ dir, url } = {}) {
+      let v = session && { store: session.server.store, shots: session.server.shots, close: async () => {} };
+      if (!v) {
+        if (!dir === !url) throw new Error('No review session is running: pass `dir` (static folder) or `url` (dev server) to check against.');
+        v = await openVerifier(dir ? { root: resolve(dir), storeDir } : { target: new URL(/^https?:\/\//.test(url) ? url : `http://${url}`).origin, storeDir });
+      }
+      try {
+        if (!v.shots.available) throw new Error('Checking approvals needs Chrome or Chromium (set CHROME_PATH) and Node 22+.');
+        const results = await verifyApprovals(v);
+        if (!results.length) return 'Nothing approved yet: no green marks or accepted fixes to check.';
+        const { lines, summary, bad } = describeVerify(results, { storeDir: '.redline' });
+        const text = `${summary}.\n${lines.join('\n')}\n\n${bad ? 'Restore what changed before you call finish_round.' : 'All approvals hold: safe to close the round.'}`;
+        // The approved look, as images, for what changed.
+        const pics = [];
+        for (const r of results.filter((x) => x.status !== 'held' && x.baseShot).slice(0, 4)) {
+          const data = await readFile(join(storeDir, r.baseShot)).catch(() => null);
+          if (data) pics.push({ type: 'text', text: `#${r.a.n} as approved:` }, { type: 'image', data: data.toString('base64'), mimeType: 'image/png' });
+        }
+        return [{ type: 'text', text }, ...pics];
+      } finally {
+        await v.close();
+      }
+    },
+    async stop_review() {
+      if (!session) return 'No review session is running.';
+      await new Promise((ok) => session.server.close(ok));
+      session = null;
+      return 'Review session stopped.';
+    },
+  };
+
+  /** Handle one JSON-RPC message; returns the response, or null for notifications. */
+  async function handle(msg) {
+    const { id, method, params = {} } = msg;
+    const reply = (result) => (id === undefined ? null : { jsonrpc: '2.0', id, result });
+    const error = (code, message) => (id === undefined ? null : { jsonrpc: '2.0', id, error: { code, message } });
+
+    switch (method) {
+      case 'initialize': {
+        const asked = params.protocolVersion;
+        return reply({
+          protocolVersion: PROTOCOL_VERSIONS.includes(asked) ? asked : PROTOCOL_VERSIONS[0],
+          capabilities: { tools: {} },
+          serverInfo: { name: 'redline', version: '0.1.0' },
+          instructions:
+            'Redline collects design feedback a human leaves directly on a website (pen marks and boxes), in rounds. ' +
+            'Use start_review to give them a URL, wait_for_round to be handed each round as soon as they press Send (feedback reads it on demand), ' +
+            'resolve after each fix, reply under a mark to ask, check_approvals before finish_round (fix anything it finds), ' +
+            'and finish_round when you are done; then wait_for_round again for the next round. ' +
+            'The brief starts with the reviewer\'s taste (all of it in .redline/TASTE.md): never repeat a rejected fix. ' +
+            'What they approved is checked after every round; an item marked "Changed since the reviewer approved it" must be restored.',
+        });
+      }
+      case 'ping':
+        return reply({});
+      case 'tools/list':
+        return reply({ tools: TOOLS });
+      case 'tools/call': {
+        const fn = tools[params.name];
+        if (!fn) return error(-32602, `Unknown tool: ${params.name}`);
+        // No valid Redline account: every tool says how to get one (the agent can relay it).
+        if (account) {
+          const acc = await account;
+          if (!acc.ok) return reply({ content: [{ type: 'text', text: acc.message }], isError: true });
+        }
+        const abort = new AbortController();
+        if (id !== undefined) inflight.set(id, abort);
+        const token = params._meta?.progressToken;
+        const progress =
+          token === undefined
+            ? undefined
+            : (done, total, message) => notify({ jsonrpc: '2.0', method: 'notifications/progress', params: { progressToken: token, progress: done, total, message } });
+        try {
+          const out = await fn(params.arguments || {}, { signal: abort.signal, progress });
+          // A cancelled request gets no response (the client has stopped listening for it).
+          if (abort.signal.aborted) return null;
+          return reply({ content: Array.isArray(out) ? out : [{ type: 'text', text: out }] });
+        } catch (err) {
+          // Tool failures are results the model can read and recover from, not protocol errors.
+          return reply({ content: [{ type: 'text', text: err.message }], isError: true });
+        } finally {
+          inflight.delete(id);
+        }
+      }
+      case 'notifications/cancelled':
+        inflight.get(params.requestId)?.abort();
+        return null;
+      default:
+        if (method && method.startsWith('notifications/')) return null;
+        return error(-32601, `Method not found: ${method}`);
+    }
+  }
+
+  return {
+    handle,
+    close: () => {
+      for (const a of inflight.values()) a.abort();
+      return tools.stop_review();
+    },
+  };
+}
+
+export function runMcpServer({ storeDir, account = null }) {
+  const log = (m) => process.stderr.write(`[redline] ${m}\n`);
+  const mcp = createMcpHandler({ storeDir, log, account, notify: (msg) => process.stdout.write(JSON.stringify(msg) + '\n') });
+  if (account) account.then((acc) => log(acc.ok ? (acc.user ? `signed in as ${acc.user.email}` : 'account check skipped') : 'not signed in: tools will explain how to get a key'));
+  const rl = createInterface({ input: process.stdin });
+  rl.on('line', async (line) => {
+    if (!line.trim()) return;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      return process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }) + '\n');
+    }
+    const res = await mcp.handle(msg);
+    if (res) process.stdout.write(JSON.stringify(res) + '\n');
+  });
+  rl.on('close', () => mcp.close().then(() => process.exit(0)));
+  log(`MCP server ready (feedback in ${storeDir})`);
+}

package/src/report.js

@@ -0,0 +1,199 @@
+// The round, as proof you can hand to someone who wasn't there: a PM, a client,
+// a PR reviewer. What was asked, what the agent did, before and after, what you
+// accepted or sent back, and what the guards caught. One self-contained HTML page
+// (images inlined, a drag slider per fix), or Markdown for a PR comment.
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const esc = (s) => String(s ?? '').replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+const plain = (s) => String(s ?? '').replace(/`/g, '');
+
+/** What happened to each item in round `n` (default: the last one that came back). */
+export function reportModel(list, rounds, n) {
+  const all = (rounds && rounds.rounds) || [];
+  const round = n ? all.find((r) => r.n === Number(n)) : [...all].reverse().find((r) => r.returnedAt) || all.at(-1);
+  if (!round) return null;
+  const since = round.returnedAt || round.sentAt;
+  const guardNews = (a) => a.guard && a.guard.now && a.guard.now.at >= since && a.guard.now.status !== 'held';
+  const items = [];
+  const held = [];
+  for (const a of list) {
+    const sentIn = a.rounds || (a.round ? [a.round] : []);
+    const inRound = sentIn.includes(round.n) || (a.draft && (a.history || []).length) || guardNews(a);
+    if (!inRound) continue;
+    const g = a.guard || {};
+    if (guardNews(a)) {
+      items.push({ a, kind: 'guard', status: g.sentBack || a.draft ? 'sent-back' : g.now.status === 'missing' ? 'gone' : 'changed',
+        diff: g.now.diff || [], before: g.now.baseShot || (g.base && g.base.shot), after: g.now.shot });
+      continue;
+    }
+    if (a.verdict === 'good' && !a.accepted && a.status !== 'resolved') {
+      if (g.now && g.now.status === 'held') held.push(a);
+      continue;
+    }
+    // Sent again in a later round: this round's fix was sent back.
+    const redo = (a.draft && (a.history || []).length) || a.round > round.n;
+    const status = a.accepted ? 'accepted' : redo ? 'redo' : a.status === 'resolved' ? 'to-check' : 'with-agent';
+    const reply = redo ? [...(a.thread || [])].reverse().find((m) => m.by === 'you') : null;
+    items.push({ a, kind: 'fix', status, asked: a.comment, did: a.resolution || (a.history || []).at(-1), why: reply && reply.text,
+      before: (a.shots || {}).before, after: (a.shots || {}).after });
+  }
+  const order = { changed: 0, gone: 0, 'to-check': 1, redo: 2, 'sent-back': 3, 'with-agent': 4, accepted: 5 };
+  items.sort((x, y) => order[x.status] - order[y.status] || (x.a.n || 0) - (y.a.n || 0));
+  const judged = (round.accepted || 0) + (round.redone || 0);
+  return { round, items, held, rate: judged ? (round.accepted || 0) / judged : null, judged };
+}
+
+const LABEL = {
+  accepted: 'Accepted', redo: 'Redo', 'to-check': 'To check', 'with-agent': 'With the agent',
+  changed: 'Approval changed', gone: 'Approval gone', 'sent-back': 'Sent back',
+};
+
+// An inlined PNG, with its size (from the header) to decide between a slider and side by side.
+async function image(dir, rel) {
+  if (!rel) return null;
+  try {
+    const buf = await readFile(join(dir, rel));
+    return { src: `data:image/png;base64,${buf.toString('base64')}`, w: buf.readUInt32BE(16), h: buf.readUInt32BE(20) };
+  } catch {
+    return null;
+  }
+}
+
+/** Markdown for a PR comment or a chat: text first; images as paths into .redline/. */
+export function reportMarkdown(model, { storeDir = '.redline' } = {}) {
+  storeDir = storeDir.replace(/\/+$/, '');
+  if (!model) return 'No round yet.\n';
+  const { round, items, held, rate } = model;
+  const out = [`## Design review · round ${round.n}`, ''];
+  const facts = [
+    rate !== null ? `**${Math.round(rate * 100)}%** accepted first time` : null,
+    `${items.filter((i) => i.kind === 'fix').length} fix${items.filter((i) => i.kind === 'fix').length === 1 ? '' : 'es'}`,
+    items.some((i) => i.kind === 'guard') ? `**${items.filter((i) => i.kind === 'guard').length} approval${items.filter((i) => i.kind === 'guard').length === 1 ? '' : 's'} changed**` : null,
+    held.length ? `${held.length} approval${held.length === 1 ? '' : 's'} held` : null,
+  ].filter(Boolean);
+  out.push(facts.join(' · '), '');
+  if (round.summary) out.push(`> ${round.summary}`, '');
+  for (const i of items) {
+    const where = i.a.target ? `\`${i.a.target.selector}\`` : `page \`${i.a.page}\``;
+    out.push(`**${LABEL[i.status]}** · ${where}`);
+    if (i.kind === 'fix') {
+      if (i.asked) out.push(`- Asked: ${i.asked}`);
+      if (i.did) out.push(`- Done: ${i.did}`);
+      if (i.why) out.push(`- Still wrong: ${i.why}`);
+    } else for (const d of i.diff) out.push(`- ${plain(d)}`);
+    const shots = [i.before && `[${i.kind === 'guard' ? 'as approved' : 'before'}](${storeDir}/${i.before})`, i.after && `[${i.kind === 'guard' ? 'now' : 'after'}](${storeDir}/${i.after})`].filter(Boolean);
+    if (shots.length) out.push(`- ${shots.join(' · ')}`);
+    out.push('');
+  }
+  out.push('_Reviewed with Redline: mark it, send it, check it, accept it._', '');
+  return out.join('\n');
+}
+
+/** One self-contained page: open it anywhere, send it to anyone. */
+export async function reportHtml(model, { storeDir, title = 'Design review' } = {}) {
+  if (!model) return '<!doctype html><meta charset="utf-8"><title>Redline</title><p>No round yet.</p>';
+  const { round, items, held, rate } = model;
+  const pct = rate === null ? null : Math.round(rate * 100);
+  const C = 2 * Math.PI * 44;
+  const cards = [];
+  for (const i of items) {
+    const [before, after] = await Promise.all([image(storeDir, i.before), image(storeDir, i.after)]);
+    const where = i.a.target ? i.a.target.selector : i.a.page;
+    const labels = i.kind === 'guard' ? ['As approved', 'Now'] : ['Before', 'After'];
+    // Same framing: one picture with a slider. The fix resized it: side by side.
+    const alike = before && after && Math.abs(before.w - after.w) / before.w < 0.1 && Math.abs(before.h - after.h) / before.h < 0.2;
+    const media = alike
+      ? `<div class="cmp" style="--at:50%;max-width:${Math.max(before.w, after.w)}px"><img src="${after.src}" alt="${labels[1]}"><img class="top" src="${before.src}" alt="${labels[0]}"><i></i>
+          <span class="l">${labels[0]}</span><span class="r">${labels[1]}</span></div>`
+      : before && after
+        ? `<div class="sbs"><figure><img src="${before.src}" alt="" style="max-width:${before.w}px"><figcaption>${labels[0]}</figcaption></figure><figure><img src="${after.src}" alt="" style="max-width:${after.w}px"><figcaption>${labels[1]}</figcaption></figure></div>`
+        : before || after ? `<img class="solo" src="${(before || after).src}" alt="" style="max-width:${(before || after).w}px">` : '';
+    const text = i.kind === 'fix'
+      ? `${i.asked ? `<p class="asked"><b>Asked</b>${esc(i.asked)}</p>` : ''}${i.did ? `<p class="did"><b>Done</b>${esc(i.did)}</p>` : ''}${i.why ? `<p class="why"><b>Still wrong</b>${esc(i.why)}</p>` : ''}`
+      : `<p class="asked"><b>Approved</b>${esc(i.a.comment || 'Kept as it was')}</p><ul class="diff">${i.diff.map((d) => `<li>${esc(plain(d))}</li>`).join('')}</ul>`;
+    cards.push(`<article class="item s-${i.status}">
+      <header><span class="pill">${LABEL[i.status]}</span><code>${esc(where)}</code></header>
+      ${text}${media}
+    </article>`);
+  }
+  return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)} · round ${round.n}</title>
+<style>
+:root { --bg: #fafaf9; --card: #fff; --text: #18181b; --muted: #71717a; --line: #e7e5e4; --good: #16a34a; --fix: #e11d48; --idea: #d97706; --soft: #f4f4f5; }
+@media (prefers-color-scheme: dark) { :root { --bg: #0c0c0e; --card: #151518; --text: #f4f4f5; --muted: #a1a1aa; --line: #27272a; --good: #22c55e; --fix: #f43f5e; --idea: #f59e0b; --soft: #1c1c20; } }
+* { box-sizing: border-box; }
+body { margin: 0; background: var(--bg); color: var(--text); font: 15px/1.55 ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif; -webkit-font-smoothing: antialiased; }
+main { max-width: 880px; margin: 0 auto; padding: 56px 20px 80px; }
+.kicker { font: 600 12px ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: .08em; text-transform: uppercase; color: var(--muted); }
+h1 { font-size: clamp(26px, 4.2vw, 38px); text-wrap: balance; line-height: 1.08; letter-spacing: -.03em; margin: 10px 0 18px; font-weight: 750; }
+.hero { display: grid; grid-template-columns: 1fr auto; gap: 28px; align-items: center; margin-bottom: 40px; }
+.summary { font-size: 17px; color: var(--muted); margin: 0; max-width: 56ch; }
+.facts { display: flex; flex-wrap: wrap; gap: 8px; margin-top: 18px; }
+.facts span { font-size: 13px; padding: 4px 10px; border-radius: 999px; background: var(--soft); border: 1px solid var(--line); }
+.facts .bad { color: var(--fix); border-color: color-mix(in srgb, var(--fix) 35%, transparent); }
+.ring { position: relative; width: 132px; height: 132px; display: grid; place-items: center; }
+.ring svg { position: absolute; inset: 0; transform: rotate(-90deg); }
+.ring circle { fill: none; stroke-width: 9; } .ring .t { stroke: var(--line); } .ring .f { stroke: var(--good); stroke-linecap: round; }
+.ring b { font-size: 32px; letter-spacing: -.03em; font-variant-numeric: tabular-nums; }
+.ring small { position: absolute; bottom: -24px; width: 160px; text-align: center; font-size: 12px; color: var(--muted); }
+.items { display: grid; gap: 18px; }
+.item { background: var(--card); border: 1px solid var(--line); border-radius: 18px; padding: 18px; display: grid; gap: 12px; }
+.item header { display: flex; align-items: center; gap: 10px; min-width: 0; }
+.item code { font: 12px ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--muted); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.pill { flex: none; font-size: 12px; font-weight: 650; padding: 3px 10px; border-radius: 999px; background: var(--soft); }
+.s-accepted .pill { background: color-mix(in srgb, var(--good) 14%, transparent); color: var(--good); }
+.s-redo .pill, .s-to-check .pill { background: color-mix(in srgb, var(--idea) 16%, transparent); color: var(--idea); }
+.s-changed .pill, .s-gone .pill, .s-sent-back .pill { background: color-mix(in srgb, var(--fix) 14%, transparent); color: var(--fix); }
+.item p { margin: 0; display: grid; grid-template-columns: 92px 1fr; gap: 12px; }
+.item p b { font-size: 12px; font-weight: 600; color: var(--muted); padding-top: 2px; }
+.why { color: var(--idea); }
+.diff { margin: 0; padding: 0; list-style: none; display: grid; gap: 6px; font: 13px ui-monospace, SFMono-Regular, Menlo, monospace; }
+.diff li { padding: 6px 10px; border-left: 2px solid var(--fix); background: color-mix(in srgb, var(--fix) 7%, transparent); border-radius: 6px; }
+.cmp { position: relative; width: 100%; margin: 0 auto; border-radius: 12px; overflow: hidden; border: 1px solid var(--line); background: #fff; cursor: ew-resize; user-select: none; touch-action: none; }
+.cmp img { display: block; width: 100%; height: auto; pointer-events: none; }
+.cmp .top { position: absolute; inset: 0; height: 100%; object-fit: cover; object-position: top left; clip-path: inset(0 calc(100% - var(--at)) 0 0); }
+.cmp i { position: absolute; top: 0; bottom: 0; left: var(--at); width: 2px; margin-left: -1px; background: #fff; box-shadow: 0 0 0 1px rgba(0,0,0,.25); }
+.cmp i::after { content: '⇆'; position: absolute; top: 50%; left: 50%; translate: -50% -50%; width: 30px; height: 30px; border-radius: 50%; background: #fff; color: #18181b; display: grid; place-items: center; font-size: 14px; box-shadow: 0 2px 10px rgba(0,0,0,.3); }
+.cmp span { position: absolute; top: 10px; font-size: 11px; font-weight: 600; padding: 3px 8px; border-radius: 6px; background: rgba(24,24,27,.75); color: #fff; }
+.cmp .l { left: 10px; } .cmp .r { right: 10px; }
+.sbs { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; align-items: start; }
+.sbs figure { margin: 0; display: grid; gap: 6px; } .sbs img { width: 100%; border-radius: 10px; border: 1px solid var(--line); background: #fff; }
+.sbs figcaption { font-size: 12px; color: var(--muted); }
+.solo { width: 100%; border-radius: 12px; border: 1px solid var(--line); }
+.held { margin-top: 28px; font-size: 14px; color: var(--muted); display: flex; gap: 10px; align-items: flex-start; }
+.held i { flex: none; width: 14px; height: 16px; margin-top: 3px; background: var(--good); clip-path: polygon(50% 0, 100% 18%, 100% 55%, 50% 100%, 0 55%, 0 18%); }
+footer { margin-top: 48px; font-size: 12px; color: var(--muted); }
+@media (max-width: 600px) { .hero { grid-template-columns: 1fr; } .ring { margin-bottom: 20px; } .item p { grid-template-columns: 1fr; gap: 2px; } }
+</style></head>
+<body><main>
+<section class="hero">
+  <div>
+    <div class="kicker">${esc(title)} · round ${round.n}</div>
+    <h1>${esc(round.summary || 'What changed this round')}</h1>
+    ${round.reading ? `<p class="summary">${esc(round.readingCorrection || round.reading)}</p>` : ''}
+    <div class="facts">
+      <span>${items.filter((i) => i.kind === 'fix').length} fixes</span>
+      ${items.filter((i) => i.status === 'accepted').length ? `<span>${items.filter((i) => i.status === 'accepted').length} accepted</span>` : ''}
+      ${items.filter((i) => i.status === 'redo').length ? `<span>${items.filter((i) => i.status === 'redo').length} to redo</span>` : ''}
+      ${items.some((i) => i.kind === 'guard') ? `<span class="bad">${items.filter((i) => i.kind === 'guard').length} approval${items.filter((i) => i.kind === 'guard').length === 1 ? '' : 's'} changed</span>` : ''}
+      ${held.length ? `<span>${held.length} approval${held.length === 1 ? '' : 's'} held</span>` : ''}
+    </div>
+  </div>
+  ${pct === null ? '' : `<div class="ring"><svg viewBox="0 0 100 100"><circle class="t" cx="50" cy="50" r="44"/><circle class="f" cx="50" cy="50" r="44" stroke-dasharray="${C.toFixed(1)}" stroke-dashoffset="${(C * (1 - rate)).toFixed(1)}"/></svg><b>${pct}%</b><small>accepted first time</small></div>`}
+</section>
+<section class="items">${cards.join('\n')}</section>
+${held.length ? `<p class="held"><i></i><span>Still exactly as approved: ${held.map((a) => `<code>${esc(a.target ? a.target.selector : a.page)}</code>`).join(', ')}</span></p>` : ''}
+<footer>Reviewed with Redline: mark it, send it, check it, accept it. Drag a picture to compare.</footer>
+</main>
+<script>
+for (const c of document.querySelectorAll('.cmp')) {
+  const at = (e) => { const r = c.getBoundingClientRect(); c.style.setProperty('--at', Math.max(0, Math.min(100, ((e.clientX - r.left) / r.width) * 100)) + '%'); };
+  c.addEventListener('pointerdown', (e) => { c.setPointerCapture(e.pointerId); at(e); c.onpointermove = at; });
+  c.addEventListener('pointerup', () => (c.onpointermove = null));
+}
+</script>
+</body></html>
+`;
+}