@myrtilleio/redline 0.1.0

package/client/variants.js

@@ -0,0 +1,117 @@
+// ---------------------------------------------------------------- options (variants)
+
+// For "I'm not sure what it should be": when a mark could be fixed several ways,
+// the agent proposes a few (CSS, and optionally new inner HTML, for the item's
+// element) instead of guessing, and the reviewer flips between them live on the
+// page and picks one. The pick becomes the instruction.
+
+const variantSheets = []; // constructed stylesheets we added to the document
+const variantHtml = new Map(); // element -> original innerHTML
+
+let ttPolicy;
+function trustedHtml(html) {
+  // Pages with Trusted Types need a policy; the HTML comes from the project's own agent.
+  if (window.trustedTypes && ttPolicy === undefined) {
+    try {
+      ttPolicy = trustedTypes.createPolicy('redline-options', { createHTML: (s) => s });
+    } catch {
+      ttPolicy = null;
+    }
+  }
+  return ttPolicy ? ttPolicy.createHTML(html) : html;
+}
+
+function clearVariantPreviews() {
+  if (variantSheets.length) {
+    document.adoptedStyleSheets = document.adoptedStyleSheets.filter((s) => !variantSheets.includes(s));
+    variantSheets.length = 0;
+  }
+  for (const [el, html] of variantHtml) el.innerHTML = trustedHtml(html);
+  variantHtml.clear();
+}
+
+// A preview must beat the page's own CSS whatever the selectors' specificity:
+// mark every declaration important (recursing into @media and friends).
+function forceImportant(rules) {
+  for (const rule of rules) {
+    if (rule.style) for (const prop of [...rule.style]) rule.style.setProperty(prop, rule.style.getPropertyValue(prop), 'important');
+    if (rule.cssRules) forceImportant(rule.cssRules);
+  }
+}
+
+/** Preview option `key` of item `a` on the page (on top of whatever is shown). */
+function applyVariant(a, key) {
+  const v = (a.variants || []).find((x) => x.key === key);
+  if (!v) return;
+  const selector = (a.target && a.target.selector) || 'body';
+  if (v.css) {
+    try {
+      const sheet = new CSSStyleSheet();
+      sheet.replaceSync(v.css.replace(/&/g, selector));
+      forceImportant(sheet.cssRules);
+      document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+      variantSheets.push(sheet);
+    } catch {}
+  }
+  const el = anchorEl(a);
+  if (v.html && el) {
+    if (!variantHtml.has(el)) variantHtml.set(el, el.innerHTML);
+    el.innerHTML = trustedHtml(v.html);
+  }
+}
+
+/**
+ * The Options section of the composer. Before the agent has answered, it offers to
+ * ask for options; afterwards it lists them to preview and pick.
+ * onPreview(key) is called when the reviewer flips to an option (null = original).
+ */
+function createOptions(a, { onPreview, onRequest, onPick }) {
+  const box = h('div', { class: 'options' });
+  let showing = a.chosen || null;
+
+  function render() {
+    if (!a.variants || !a.variants.length) {
+      // Nothing to show until the agent offers options (or a request made earlier is pending).
+      fill(box,
+        a.request
+          ? h('div', { class: 'opt-wait' }, `Waiting for ${a.request.variants} options from your agent…`,
+              h('button', { type: 'button', class: 'btn small', onclick: () => onRequest(null) }, "Don't ask"))
+          : null,
+      );
+      return;
+    }
+    const chip = (key, text, title) =>
+      h('button', {
+        type: 'button',
+        class: 'opt' + (a.chosen === key ? ' chosen' : ''),
+        'aria-pressed': String(showing === key),
+        title: title || text,
+        onclick: () => {
+          showing = key;
+          onPreview(key);
+          render();
+        },
+      }, text);
+    const current = showing && a.variants.find((v) => v.key === showing);
+    fill(box,
+      h('div', { class: 'opt-row' },
+        chip(null, 'Original', 'The page as built'),
+        a.variants.map((v) => chip(v.key, `${v.key} · ${v.label}`, v.note || v.label)),
+      ),
+      current && current.note ? h('div', { class: 'opt-note' }, current.note) : null,
+      current
+        ? h('button', {
+            type: 'button',
+            class: 'btn small primary',
+            onclick: () => onPick(current.key),
+          }, a.chosen === current.key ? '✓ Picked' : `Pick option ${current.key}`)
+        : null,
+    );
+  }
+  render();
+  return {
+    node: box,
+    showing: () => showing,
+    rerender: render,
+  };
+}

package/examples/demo-site/hero.svg

@@ -0,0 +1,18 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 520" font-family="system-ui, sans-serif">
+  <rect width="960" height="520" rx="20" fill="#fff"/>
+  <rect width="960" height="48" rx="20" fill="#f5f5f4"/>
+  <rect y="28" width="960" height="20" fill="#f5f5f4"/>
+  <circle cx="28" cy="24" r="6" fill="#fca5a5"/><circle cx="48" cy="24" r="6" fill="#fcd34d"/><circle cx="68" cy="24" r="6" fill="#86efac"/>
+  <rect x="32" y="80" width="260" height="400" rx="14" fill="#fff7ed" stroke="#fed7aa"/>
+  <text x="56" y="120" font-size="20" font-weight="700" fill="#7c2d12">Ethiopia Guji — V60</text>
+  <text x="56" y="160" font-size="15" fill="#78716c">Dose</text><text x="268" y="160" font-size="15" text-anchor="end" fill="#1c1917">15 g</text>
+  <text x="56" y="192" font-size="15" fill="#78716c">Water</text><text x="268" y="192" font-size="15" text-anchor="end" fill="#1c1917">250 g · 94°C</text>
+  <text x="56" y="224" font-size="15" fill="#78716c">Grind</text><text x="268" y="224" font-size="15" text-anchor="end" fill="#1c1917">Comandante 24</text>
+  <text x="56" y="256" font-size="15" fill="#78716c">Time</text><text x="268" y="256" font-size="15" text-anchor="end" fill="#1c1917">3:05</text>
+  <rect x="56" y="296" width="212" height="44" rx="22" fill="#9a3412"/>
+  <text x="162" y="324" font-size="15" font-weight="600" text-anchor="middle" fill="#fff">Log this brew</text>
+  <text x="332" y="112" font-size="18" font-weight="700" fill="#1c1917">Taste over the last 14 days</text>
+  <g stroke="#e7e5e4"><line x1="332" y1="160" x2="920" y2="160"/><line x1="332" y1="260" x2="920" y2="260"/><line x1="332" y1="360" x2="920" y2="360"/><line x1="332" y1="460" x2="920" y2="460"/></g>
+  <polyline fill="none" stroke="#9a3412" stroke-width="4" stroke-linejoin="round" points="332,380 390,350 448,360 506,300 564,310 622,250 680,270 738,210 796,220 854,180 912,170"/>
+  <polyline fill="none" stroke="#f59e0b" stroke-width="4" stroke-linejoin="round" points="332,420 390,410 448,380 506,390 564,360 622,370 680,340 738,330 796,300 854,310 912,290"/>
+</svg>

package/examples/demo-site/index.html

@@ -0,0 +1,96 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Brewlog — track every cup</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <!-- A typical first draft from a coding agent: decent bones, a few things a
+       designer would want changed. Use it to try Redline. -->
+  <header class="nav">
+    <a class="logo" href="/">☕ Brewlog</a>
+    <nav>
+      <a href="#features">Features</a>
+      <a href="#pricing">Pricing</a>
+      <a href="#faq">FAQ</a>
+    </nav>
+    <a class="btn btn-small" href="#pricing">Start free</a>
+  </header>
+
+  <main>
+    <section class="hero">
+      <p class="eyebrow">For home baristas</p>
+      <h1 class="hero-title">THE ULTIMATE REVOLUTIONARY COFFEE TRACKING PLATFORM FOR EVERYONE</h1>
+      <p class="hero-sub">Log grind size, ratio and taste notes in seconds. See which beans and recipes you actually love, and dial in every new bag faster.</p>
+      <div class="hero-actions">
+        <a class="btn" href="#pricing">Start free</a>
+        <a class="btn btn-ghost" href="#features">See how it works</a>
+      </div>
+      <img class="hero-shot" src="hero.svg" alt="Brewlog app showing a pour-over recipe with a taste chart">
+    </section>
+
+    <section id="features" class="features">
+      <h2>Everything you need to brew better</h2>
+      <div class="grid">
+        <article class="card">
+          <div class="icon">⚖️</div>
+          <h3>Recipes that remember</h3>
+          <p>Save dose, water, temperature and time. Brewlog suggests the next tweak based on how the last cup tasted.</p>
+        </article>
+        <article class="card">
+          <div class="icon">📈</div>
+          <h3>Taste over time</h3>
+          <p>Rate sweetness, acidity and body. Charts show how each bag evolves from roast day to the last scoop.</p>
+        </article>
+        <article class="card card-odd">
+          <div class="icon">🫘</div>
+          <h3>Your bean library</h3>
+          <p>Scan the bag, and origin, process and roaster notes fill in automatically.</p>
+        </article>
+      </div>
+    </section>
+
+    <section class="quote">
+      <blockquote>“I finally know why Tuesday’s V60 was amazing and Wednesday’s wasn’t.”</blockquote>
+      <p class="who">— Mara K., home barista</p>
+    </section>
+
+    <section id="pricing" class="pricing">
+      <h2>Pricing</h2>
+      <div class="plans">
+        <div class="plan">
+          <h3>Free</h3>
+          <p class="price">$0</p>
+          <ul><li>50 brews / month</li><li>Basic charts</li><li>1 device</li></ul>
+          <a class="btn btn-ghost" href="#">Get started</a>
+        </div>
+        <div class="plan plan-featured">
+          <h3>Pro</h3>
+          <p class="price">$6<span>/mo</span></p>
+          <ul><li>Unlimited brews</li><li>Recipe suggestions</li><li>Sync everywhere</li><li>Export to CSV</li></ul>
+          <a class="btn" href="#">Go Pro</a>
+        </div>
+        <div class="plan">
+          <h3>Café</h3>
+          <p class="price">$29<span>/mo</span></p>
+          <ul><li>Up to 10 baristas</li><li>Shared recipes</li><li>Priority support</li></ul>
+          <a class="btn btn-ghost" href="#">Contact sales</a>
+        </div>
+      </div>
+    </section>
+
+    <section id="faq" class="faq">
+      <h2>Questions</h2>
+      <details><summary>Does it work offline?</summary><p>Yes. Brews sync when you're back online.</p></details>
+      <details><summary>Which brew methods are supported?</summary><p>Pour-over, espresso, AeroPress, French press, cold brew, and custom methods.</p></details>
+      <details><summary>Can I import from a spreadsheet?</summary><p>Pro plans can import CSV files from the settings page.</p></details>
+    </section>
+  </main>
+
+  <footer class="footer">
+    <p>© 2026 Brewlog · Made for people who weigh their coffee.</p>
+  </footer>
+</body>
+</html>

package/examples/demo-site/styles.css

@@ -0,0 +1,64 @@
+:root {
+  --ink: #1c1917;
+  --muted: #78716c;
+  --paper: #fffbf5;
+  --brand: #9a3412;
+  --line: #e7e5e4;
+  font-family: Georgia, "Times New Roman", serif;
+  color: var(--ink);
+  background: var(--paper);
+}
+* { box-sizing: border-box; }
+body { margin: 0; line-height: 1.6; }
+a { color: inherit; }
+
+.nav { display: flex; align-items: center; gap: 32px; padding: 18px 40px; border-bottom: 1px solid var(--line); position: sticky; top: 0; background: var(--paper); z-index: 5; }
+.logo { font-weight: 700; text-decoration: none; font-size: 20px; }
+.nav nav { display: flex; gap: 24px; margin-left: auto; }
+.nav nav a { text-decoration: none; color: var(--muted); }
+
+.btn { display: inline-block; background: var(--brand); color: #fff; text-decoration: none; padding: 12px 22px; border-radius: 999px; font-family: system-ui, sans-serif; font-weight: 600; font-size: 15px; }
+.btn-small { padding: 8px 16px; font-size: 14px; }
+.btn-ghost { background: transparent; color: var(--brand); border: 2px solid var(--brand); }
+
+.hero { max-width: 980px; margin: 0 auto; padding: 80px 24px 40px; text-align: center; }
+.eyebrow { text-transform: uppercase; letter-spacing: .12em; font: 600 13px system-ui, sans-serif; color: var(--brand); }
+.hero-title { font-size: 76px; line-height: 1; margin: 12px 0 24px; letter-spacing: -.02em; color: #7c2d12; }
+.hero-sub { font-size: 20px; color: var(--muted); max-width: 640px; margin: 0 auto 32px; }
+.hero-actions { display: flex; gap: 12px; justify-content: center; }
+.hero-shot { display: block; width: 100%; margin-top: 56px; border-radius: 20px; box-shadow: 0 30px 60px -20px rgba(124, 45, 18, .35); }
+
+.features { max-width: 1100px; margin: 0 auto; padding: 80px 24px; }
+.features h2, .pricing h2, .faq h2 { text-align: center; font-size: 40px; margin: 0 0 40px; }
+.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px; }
+.card { background: #fff; border: 1px solid var(--line); border-radius: 16px; padding: 28px; }
+.card-odd { background: #fde68a; border-radius: 2px; padding: 12px; }
+.card .icon { font-size: 30px; }
+.card h3 { margin: 12px 0 8px; }
+.card p { color: var(--muted); margin: 0; }
+
+.quote { background: var(--ink); color: #fafaf9; padding: 90px 24px; text-align: center; }
+.quote blockquote { font-size: 32px; font-style: italic; max-width: 760px; margin: 0 auto 16px; }
+.who { color: #a8a29e; font-family: system-ui, sans-serif; }
+
+.pricing { max-width: 1100px; margin: 0 auto; padding: 90px 24px; }
+.plans { display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; align-items: start; }
+.plan { border: 1px solid var(--line); border-radius: 16px; padding: 32px; background: #fff; }
+.plan-featured { background: #fff7ed; border: 2px solid var(--brand); transform: translateY(-12px); }
+.plan h3 { margin: 0; font-family: system-ui, sans-serif; }
+.price { font-size: 44px; font-weight: 700; margin: 8px 0; }
+.price span { font-size: 16px; color: var(--muted); }
+.plan ul { padding-left: 18px; color: var(--muted); margin: 0 0 24px; }
+
+.faq { max-width: 720px; margin: 0 auto; padding: 40px 24px 100px; }
+details { border-bottom: 1px solid var(--line); padding: 16px 0; }
+summary { cursor: pointer; font-weight: 700; }
+
+.footer { text-align: center; padding: 32px; color: var(--muted); border-top: 1px solid var(--line); font-size: 14px; }
+
+@media (max-width: 800px) {
+  .hero-title { font-size: 44px; }
+  .grid, .plans { grid-template-columns: 1fr; }
+  .nav { padding: 14px 16px; gap: 12px; }
+  .nav nav { display: none; }
+}

package/integrations/claude-code/redline.md

@@ -0,0 +1,27 @@
+---
+description: Apply the design feedback left in the Redline overlay, then mark each item resolved
+allowed-tools: Bash(redline:*), Read, Edit, Write, Glob, Grep
+---
+
+The user reviewed the site in the Redline overlay: they drew on the page or boxed components to say why, and each mark's colour says what they want: red **✗ Fix** (change it), green **✓ Good** (keep it) or amber **? Idea** (a suggestion or question).
+
+Open feedback (it starts with this reviewer's taste; the full ledger is `.redline/TASTE.md`, read it if it exists):
+
+!`redline feedback`
+
+For each item:
+
+1. Find the element in the source. Match on the selector, classes and quoted text; the markup may have changed since the review.
+2. **Fix** items: make the change the comment asks for. If there's no comment, use the mark's shape and colour to infer the problem: crossed out means remove or rethink it, circled means that area needs attention.
+3. **Good** items: leave them alone. If a Fix would affect them, keep their look, and reuse their patterns where it fits. Redline checks every approval after each round and reports anything that changed. An item that says **Changed since the reviewer approved it** lists exactly what changed: put it back the way it was approved, without undoing other fixes.
+4. **Idea** items: apply the idea if it's clearly an improvement. If it's a question, answer it in the resolve note.
+5. **Proposed change** items carry exact values the reviewer tried live. Apply those values in the source, to every matching element when it says "on every".
+6. Look at the listed **screenshots** and **reference images** (Read the PNG/WebP files) before changing anything visual.
+7. When a mark could reasonably be fixed several ways and you can't tell which the reviewer wants (or they **asked for options**), don't guess and don't edit the code for it. Write 2–3 options to a JSON file as `[{"label", "css", "note"}]`, where `&` in css means the element and `html` optionally replaces its contents, then run `redline variants <id> --file options.json`. Once they have **picked** one, build that option in the source.
+8. If your fix restructured or moved the element, add `--target "<css selector>"` to the resolve command below, so the after-screenshot shows the new markup.
+9. The brief may show a **Conversation** under a mark: the reviewer is waiting for your answer, so reply with `redline reply <id> "…"`. If a mark is unclear, ask under it the same way instead of guessing.
+10. After changing the code, run `redline resolve <id> --note "<one line: what you changed>"`. The reviewer sees the note on the pin in their browser, and the page live-reloads.
+
+Resolve Good items too, with a note saying the pattern was kept. Before closing the round, check you didn't break anything the reviewer approved: `redline verify <site folder>` (or `--url <dev server>`). It photographs every approval now and lists what changed, in words, without recording anything. Restore whatever it lists. Then close the round: `redline done --summary "what you changed" --reading "what you think this page is for, in two sentences" --question "…"` (at most 3 questions, only if you really need an answer). The reviewer checks each fix and accepts it or asks for a redo in their next round.
+
+**Then wait for the next round, without the user having to prompt you.** Run `redline wait` as a background command (it blocks until the reviewer presses Send, then prints the new brief and exits; it returns at once if a round is already waiting). When it finishes, handle that round the same way, close it with `redline done`, and start `redline wait` in the background again. Keep looping until the user tells you to stop. Over MCP, the same loop is `wait_for_round` → `resolve` → `finish_round` → `wait_for_round`.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@myrtilleio/redline",
+  "version": "0.1.0",
+  "description": "Review the UI your AI agent built: mark it, send it, check each fix, accept it.",
+  "type": "module",
+  "bin": {
+    "redline": "bin/redline.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "client",
+    "integrations",
+    "examples/demo-site"
+  ],
+  "scripts": {
+    "test": "REDLINE_AUTH=off node --test test/*.test.js",
+    "test:account": "node --test test/account.test.js",
+    "demo": "node bin/redline.js demo --open",
+    "bundle": "node bin/redline.js bundle -o dist/redline.js",
+    "field-test": "cd examples/field-test && npm install --no-audit --no-fund && node run.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "design",
+    "feedback",
+    "annotation",
+    "ai",
+    "agent",
+    "review",
+    "overlay"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "playwright-core": "^1.63.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/account.js

@@ -0,0 +1,101 @@
+// Your Redline account, from the command line: an API key made in the dashboard,
+// saved once with `redline login`, and checked when a session starts. The key only
+// proves who you are: your site, notes and screenshots never leave your machine.
+import { chmod, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+
+// The hosted Redline (Vercel + Neon). Self-hosting: redline login <key> --server <url>, or REDLINE_SERVER.
+export const DEFAULT_SERVER = 'https://redline-nine-eta.vercel.app';
+const OFFLINE_GRACE = 7 * 24 * 3600 * 1000; // a key checked in the last week works offline
+const TIMEOUT = 4000;
+
+export function credentialsPath() {
+  const base = process.env.REDLINE_CONFIG_DIR || join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'redline');
+  return join(base, 'credentials.json');
+}
+
+export async function readCredentials() {
+  try {
+    return JSON.parse(await readFile(credentialsPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCredentials(data) {
+  const file = credentialsPath();
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 });
+  await chmod(file, 0o600).catch(() => {});
+}
+
+export async function forget() {
+  await rm(credentialsPath(), { force: true });
+}
+
+/** The key and server to use: the environment wins (MCP clients pass REDLINE_API_KEY), then the saved login. */
+export async function currentAccount() {
+  const saved = await readCredentials();
+  const key = process.env.REDLINE_API_KEY || (saved && saved.key) || null;
+  const server = (process.env.REDLINE_SERVER || (saved && saved.server) || DEFAULT_SERVER).replace(/\/$/, '');
+  return { key, server, saved, fromEnv: !!process.env.REDLINE_API_KEY };
+}
+
+/** Ask the accounts server who this key belongs to, and say what is starting. */
+export async function verifyKey({ key, server, event, client = 'redline cli' }) {
+  let res;
+  try {
+    res = await fetch(`${server}/api/v1/whoami`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-api-key': key },
+      body: JSON.stringify({ event, client }),
+      signal: AbortSignal.timeout(TIMEOUT),
+    });
+  } catch (err) {
+    return { ok: false, offline: true, message: `Can't reach the Redline accounts server at ${server} (${err.cause?.code || err.name}).` };
+  }
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) return { ok: false, offline: false, message: data.message || `The accounts server said no (${res.status}).` };
+  return { ok: true, user: data.user, key: data.key };
+}
+
+export function onboardingHelp(server = DEFAULT_SERVER) {
+  return [
+    'Redline needs a free account (it only unlocks the tool: your work stays on your machine).',
+    '',
+    `  1. Open ${server} and create an account.`,
+    '     (Running your own? docker compose up -d in the Redline folder, then add --server http://localhost:4700)',
+    '  2. Create an API key there, then:',
+    `       redline login <your-key>${server === DEFAULT_SERVER ? '' : ` --server ${server}`}`,
+  ].join('\n');
+}
+
+/** `redline login <key>`: check it, then remember it. */
+export async function login(key, { server } = {}) {
+  const target = (server || process.env.REDLINE_SERVER || DEFAULT_SERVER).replace(/\/$/, '');
+  if (!key || !/^\S{8,}$/.test(key)) throw new Error(`usage: redline login <your-key> [--server ${DEFAULT_SERVER}]`);
+  const v = await verifyKey({ key, server: target, event: 'login' });
+  if (!v.ok) throw new Error(v.message + (v.offline ? '\nIs the accounts server running? (docker compose up -d)' : ''));
+  await writeCredentials({ server: target, key, user: v.user, verifiedAt: new Date().toISOString() });
+  return v.user;
+}
+
+/**
+ * Before a session starts (serve, proxy, demo, mcp): a valid key, or a clear way to
+ * get one. Offline, a key checked within the last week still works.
+ * Returns { ok, user?, warning?, message? }.
+ */
+export async function requireAccount(event, { client } = {}) {
+  if (process.env.REDLINE_AUTH === 'off') return { ok: true, skipped: true };
+  const { key, server, saved, fromEnv } = await currentAccount();
+  if (!key) return { ok: false, message: onboardingHelp(server) };
+  const v = await verifyKey({ key, server, event, client });
+  if (v.ok) {
+    if (!fromEnv && saved && saved.key === key) await writeCredentials({ ...saved, user: v.user, verifiedAt: new Date().toISOString() }).catch(() => {});
+    return { ok: true, user: v.user };
+  }
+  const recent = saved && saved.key === key && saved.verifiedAt && Date.now() - Date.parse(saved.verifiedAt) < OFFLINE_GRACE;
+  if (v.offline && recent) return { ok: true, user: saved.user, warning: `${v.message} Working offline with the key checked ${new Date(saved.verifiedAt).toLocaleDateString()}.` };
+  return { ok: false, message: `${v.message}\n\n${onboardingHelp(server)}` };
+}

package/src/bundle.js

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+
+const read = (rel) => readFileSync(new URL(rel, import.meta.url), 'utf8');
+
+// Overlay sources, in order. They share one function scope: later files use the
+// core's helpers and state; boot.js must stay last.
+export const CLIENT_FILES = [
+  'core.js',
+  'select.js',
+  'pen.js',
+  'edits.js',
+  'references.js',
+  'shots.js',
+  'variants.js',
+  'composer.js',
+  'panel.js',
+  'check.js',
+  'devices.js',
+  'keyboard.js',
+  'boot.js',
+];
+
+/**
+ * Build the browser overlay as one classic script: the shared formatter with
+ * its ES `export` removed, followed by the overlay files, all inside one IIFE.
+ */
+export function buildClient() {
+  const format = read('./format.js').replace(/^export\s*\{[^}]*\};?\s*$/m, '');
+  const overlay = CLIENT_FILES.map((f) => `// ---- client/${f}\n` + read(`../client/${f}`)).join('\n');
+  const js = `/*! Redline design-feedback overlay */\n(function () {\n'use strict';\n${format}\n${overlay}\n})();\n`;
+  // Escape non-ASCII as \uXXXX so the script survives pages served without a charset.
+  return js.replace(/[^\x00-\x7f]/g, (c) => '\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));
+}

package/src/demo.js

@@ -0,0 +1,137 @@
+// `redline demo`: start at the payoff. Round 1 has already been played on a copy of
+// the demo site: four marks were sent, three to fix and one to keep. A scripted agent
+// fixed the three in the files and reported back, and, like agents do, quietly
+// changed the one it was asked to keep. So the first thing a new user sees is
+// "Check 4": three fixes to accept or redo, and a guard that caught the regression.
+import { cp, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { createRedlineServer } from './server.js';
+
+// A circle drawn around an element of about w×h, starting top-left and closing
+// past its start (the way people circle things), relative to the element.
+function circle(w, h, pad = 16) {
+  const pts = [];
+  for (let t = -0.35; t <= Math.PI * 2 + 0.2; t += 0.12) {
+    pts.push([Math.round(w / 2 + Math.cos(t + Math.PI) * (w / 2 + pad)), Math.round(h / 2 + Math.sin(t + Math.PI) * (h / 2 + pad))]);
+  }
+  return pts;
+}
+
+const CARD = { w: 334, h: 214, x: 814, y: 1062 }; // .card-odd at 1280px, near enough
+
+/** The marks a reviewer might leave on the demo site's first draft, and how the agent fixed each. */
+export const DEMO_ROUND = [
+  {
+    mark: {
+      kind: 'note',
+      verdict: 'fix',
+      comment: 'All caps feels shouty. Sentence case, and about half the size.',
+      target: { selector: 'h1.hero-title', html: '<h1 class="hero-title">', text: 'THE ULTIMATE REVOLUTIONARY COFFEE TRACKING PLATFORM FOR EVERYONE' },
+      section: { selector: 'section.hero', heading: 'THE ULTIMATE REVOLUTIONARY COFFEE TRACKING PLATFORM FOR EVERYONE' },
+    },
+    edits: [
+      ['index.html', 'THE ULTIMATE REVOLUTIONARY COFFEE TRACKING PLATFORM FOR EVERYONE', 'Dial in every cup'],
+      ['styles.css', '.hero-title { font-size: 76px;', '.hero-title { font-size: 48px;'],
+    ],
+    note: 'Headline is now "Dial in every cup", sentence case at 48px (44px on mobile)',
+  },
+  {
+    mark: {
+      kind: 'stroke',
+      verdict: 'fix',
+      comment: "Doesn't match the other two cards",
+      // A selector that still finds the card once its one-off class is gone.
+      target: { selector: '#features article:nth-of-type(3)', html: '<article class="card card-odd">', text: '🫘 Your bean library Scan the bag, and origin, process and roaster notes fill in automatically.', rect: { x: CARD.x, y: CARD.y, w: CARD.w, h: CARD.h } },
+      stroke: { local: [circle(CARD.w, CARD.h)], paths: [circle(CARD.w, CARD.h).map(([x, y]) => [x + CARD.x, y + CARD.y])], width: 4 },
+      section: { selector: '#features', heading: 'Everything you need to brew better' },
+    },
+    edits: [
+      ['index.html', '<article class="card card-odd">', '<article class="card">'],
+      ['styles.css', '.card-odd { background: #fde68a; border-radius: 2px; padding: 12px; }\n', ''],
+    ],
+    note: 'Removed the one-off yellow style: the bean library card now matches the other two',
+  },
+  {
+    mark: {
+      kind: 'note',
+      verdict: 'fix',
+      comment: 'The Pro card floats above the others. Line the tops up.',
+      target: { selector: 'div.plan.plan-featured', html: '<div class="plan plan-featured">', text: 'Pro $6/mo Unlimited brews Recipe suggestions Sync everywhere Export to CSV Go Pro' },
+      section: { selector: '#pricing', heading: 'Pricing' },
+    },
+    edits: [['styles.css', ' border: 2px solid var(--brand); transform: translateY(-12px); }', ' border: 2px solid var(--brand); }']],
+    note: 'Dropped the -12px lift, so all three plans start on the same line; the border still marks Pro',
+  },
+  {
+    // A keep. The agent doesn't resolve it (there was nothing to do), but its
+    // tidy-up of the type scale shrinks the quote anyway: the guard catches it.
+    mark: {
+      kind: 'note',
+      verdict: 'good',
+      comment: 'Love this quote. Keep it big and italic.',
+      target: { selector: 'section.quote > blockquote', html: '<blockquote>', text: '“I finally know why Tuesday’s V60 was amazing and Wednesday’s wasn’t.”' },
+      section: { selector: 'section.quote', heading: '' },
+    },
+    edits: [['styles.css', '.quote blockquote { font-size: 32px; font-style: italic;', '.quote blockquote { font-size: 24px; font-style: normal;']],
+  },
+];
+
+export const DEMO_REPORT = {
+  summary: 'Calmer headline, one card style for all three features, the pricing cards aligned, and a tidier type scale.',
+  reading: 'A landing page that sells a coffee-logging app to home baristas, and gets them to start the free plan.',
+  questions: ['Should the Café plan offer a trial instead of "Contact sales"?'],
+};
+
+const until = async (fn, ms) => {
+  for (const t0 = Date.now(); Date.now() - t0 < ms; await new Promise((r) => setTimeout(r, 200))) if (await fn()) return true;
+  return false;
+};
+
+/**
+ * Play round 1 against a running server: send the marks, let the screenshots of the
+ * page as reviewed be taken, apply the fixes to `siteDir`, resolve and report.
+ */
+export async function playDemoRound(server, siteDir, { shotWait = 45000 } = {}) {
+  const { store, shots } = server;
+  const items = [];
+  for (const { mark } of DEMO_ROUND) items.push(await store.create({ ...mark, page: '/', draft: true }));
+  await store.send();
+  // The "before" pictures (and the keep's baseline) must show the first draft, so wait for them before editing it.
+  const ready = (a) => a.shots?.before && (a.verdict !== 'good' || a.guard?.base);
+  if (shots.available) {
+    const ids = new Set(items.map((a) => a.id));
+    await until(async () => (await store.all()).filter((a) => ids.has(a.id) && ready(a)).length === ids.size, shotWait);
+  }
+  for (const { edits } of DEMO_ROUND) {
+    for (const [file, from, to] of edits) {
+      const path = join(siteDir, file);
+      const src = await readFile(path, 'utf8');
+      if (!src.includes(from)) throw new Error(`demo fix does not apply to ${file}: ${from.slice(0, 40)}`);
+      await writeFile(path, src.replace(from, to));
+    }
+  }
+  for (const [i, { note }] of DEMO_ROUND.entries()) if (note) await store.resolve(items[i].id, note);
+  await store.finishRound(DEMO_REPORT);
+  // Closing the round runs the guards: wait for the verdict on the keep.
+  if (shots.available) {
+    const kept = items.filter((a) => a.verdict === 'good').map((a) => a.id);
+    await until(async () => (await store.all()).filter((a) => kept.includes(a.id) && a.guard?.now).length === kept.length, shotWait);
+  }
+  return items;
+}
+
+/** Copy the demo site somewhere disposable, serve it, and play round 1. */
+export async function startDemo({ port = 4545, host = '127.0.0.1', log = () => {} } = {}) {
+  const dir = await mkdtemp(join(tmpdir(), 'redline-demo-'));
+  const siteDir = join(dir, 'site');
+  await cp(new URL('../examples/demo-site', import.meta.url), siteDir, { recursive: true });
+  const server = createRedlineServer({ root: siteDir, storeDir: join(dir, '.redline'), log, demo: true });
+  await new Promise((ok, fail) => {
+    server.once('error', fail);
+    server.listen(port, host, ok);
+  });
+  const cleanup = () => rm(dir, { recursive: true, force: true });
+  server.on('close', cleanup);
+  return { server, dir, siteDir, ready: playDemoRound(server, siteDir) };
+}