@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/match.mjs

@@ -0,0 +1,923 @@
+// `palate match <image|url|figma link> [--route /x] [--width 1440]`: build from the user's own design, faithfully.
+// Everywhere else palate designs its own look; here the user's screenshot, mockup or Figma frame is the spec, and
+// palate's taste (archetypes, the blueprint, the house-look check, the similarity gate) steps aside. The build
+// mustn't "improve" the design: what differs from it is OFF, however good it looks.
+//
+// 1. The source becomes .palate/match/<route>/reference.png (a PNG or JPG as given, a page captured at the width,
+//    or a Figma frame through the REST API when FIGMA_TOKEN is set), plus parts for a tall design.
+// 2. palate measures what a still image shows (the colours by share, the surfaces and the content blocks, the
+//    content's span) and writes a fidelity brief: spec.json first, every value tagged observed, inferred or
+//    substituted; then the build in the project's own stack; states and the phone layout are inferred and listed.
+// 3. `--check` renders the build at the design's width, writes the two side by side and a difference heatmap
+//    (tops aligned; a height difference is said, not hidden), measures what it can (palette distance, text sizes
+//    against the spec, content strings, motion, contrast and clipping as warnings) and writes one judge packet
+//    for a fresh subagent: content, geometry, type, assets, spacing, colour, details, motion, each MATCH, CLOSE or
+//    OFF. `--answers` gives the verdict: READY, READY WITH SUBSTITUTIONS, NOT READY (what's off, most visible
+//    first, with the fix) or UNVERIFIED. Two repair rounds at most, like the gate; a worse round can be restored.
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+import { acquireBrowser } from "../pool.mjs";
+import { HIDE_DEV, MOTION_INIT, openPage, scrollThrough, settle, shootFull, stamp, withBrowser } from "../look.mjs";
+import { cropImage, decodePng, writePng } from "../png.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { readJson } from "./common.mjs";
+import { matchRoot, matchedRoute } from "./matched.mjs";
+
+const slash = (p) => String(p).replace(/\\/g, "/");
+export const MAX_ROUNDS = 2;
+export const ORDER = ["content", "geometry", "type", "assets", "spacing", "colour", "details", "motion"];
+const TAGS = ["observed", "inferred", "substituted"];
+const PART_H = 1200;
+const MAX_PARTS = 6;
+
+// ---- the source
+
+// A Figma link (file key and node id), a page URL, or an image file.
+export function parseSource(raw) {
+  const s = String(raw ?? "").trim();
+  if (!s) return null;
+  const fig = s.match(/^(?:https?:\/\/)?(?:www\.)?figma\.com\/(?:file|design|proto|board)\/([A-Za-z0-9]+)[^?#]*(?:\?([^#]*))?/i);
+  if (fig) {
+    const node = new URLSearchParams(fig[2] ?? "").get("node-id");
+    return { kind: "figma", file: fig[1], node: node ? node.replace(/-/g, ":") : null, label: s.split("?")[0] + (node ? `?node-id=${node}` : "") };
+  }
+  if (/^https?:\/\//i.test(s)) return { kind: "url", url: s, label: s };
+  if (/\.(png|jpe?g|webp)$/i.test(s)) return { kind: "image", file: path.resolve(s), label: slash(s) };
+  return { kind: "unknown", label: s };
+}
+
+const NO_TOKEN = "Export the frame as PNG in Figma (select the frame, Export, PNG at 1x) and run palate match <file.png>, or set FIGMA_TOKEN (a personal access token with file read access) so palate can fetch it.";
+
+// The frame as PNG through Figma's images endpoint. Never says the token, even in an error.
+export async function figmaFrame(src, { token = process.env.FIGMA_TOKEN, fetchImpl = globalThis.fetch, scale = 1 } = {}) {
+  if (!token) return { ok: false, why: `No FIGMA_TOKEN set, so palate can't fetch the frame. ${NO_TOKEN}` };
+  if (!src.node) return { ok: false, why: "That link names a file, not a frame. In Figma, right-click the frame, choose Copy link to selection, and pass that link (it carries node-id)." };
+  const scrub = (s) => String(s ?? "").split(token).join("[token]");
+  const api = `https://api.figma.com/v1/images/${src.file}?ids=${encodeURIComponent(src.node)}&format=png&scale=${scale}`;
+  let res;
+  try {
+    res = await fetchImpl(api, { headers: { "X-Figma-Token": token } });
+  } catch (e) {
+    return { ok: false, why: `Figma could not be reached (${scrub(e.message)}). ${NO_TOKEN}` };
+  }
+  if (res.status === 403) return { ok: false, why: "Figma refused the token (403): it may be expired or unable to read this file. Check FIGMA_TOKEN, or export the frame as PNG." };
+  if (res.status === 404) return { ok: false, why: "Figma has no file with that key (404). Check the link, or export the frame as PNG." };
+  if (res.status === 429) return { ok: false, why: "Figma is rate-limiting requests (429). Wait a minute and run palate match again, or export the frame as PNG." };
+  if (!res.ok) return { ok: false, why: `Figma answered ${res.status}. Export the frame as PNG instead.` };
+  const body = await res.json().catch(() => ({}));
+  if (body.err) return { ok: false, why: `Figma said: ${scrub(body.err)}. Export the frame as PNG instead.` };
+  const link = body.images?.[src.node] ?? Object.values(body.images ?? {})[0];
+  if (!link) return { ok: false, why: "Figma rendered nothing for that frame (it may be empty, hidden or not a frame). Export it as PNG instead." };
+  let img;
+  try {
+    img = await fetchImpl(link);
+  } catch (e) {
+    return { ok: false, why: `The rendered frame could not be downloaded (${scrub(e.message)}).` };
+  }
+  if (!img.ok) return { ok: false, why: `The rendered frame could not be downloaded (${img.status}).` };
+  return { ok: true, buffer: Buffer.from(await img.arrayBuffer()) };
+}
+
+// The design's width in CSS pixels. A screenshot 2400 px or wider is read as @2x (a retina capture or a 2x
+// export) unless --width says otherwise.
+export function designWidth(natural, given) {
+  if (given) return { width: Math.round(given), scale: natural / given, assumed: false };
+  if (natural >= 2400) return { width: Math.round(natural / 2), scale: 2, assumed: true };
+  return { width: natural, scale: 1, assumed: false };
+}
+
+// Any image Chrome can decode, as PNG at its own size and at the design's CSS width. Up to 16,000 CSS px tall.
+async function normalize(browser, buf, mime, given) {
+  const page = await browser.newPage();
+  try {
+    const meta = await page.evaluate(async (src) => {
+      const img = new Image();
+      img.src = src;
+      await img.decode();
+      return { w: img.naturalWidth, h: img.naturalHeight };
+    }, `data:${mime};base64,${buf.toString("base64")}`);
+    const dw = designWidth(meta.w, given);
+    const cssH = Math.min(16_000, Math.round(meta.h / dw.scale));
+    const out = await page.evaluate(
+      async ([src, w, h, scale]) => {
+        const img = new Image();
+        img.src = src;
+        await img.decode();
+        const draw = (cw, ch) => {
+          const c = document.createElement("canvas");
+          c.width = cw;
+          c.height = ch;
+          const g = c.getContext("2d");
+          g.imageSmoothingQuality = "high";
+          g.fillStyle = "#fff";
+          g.fillRect(0, 0, cw, ch);
+          g.drawImage(img, 0, 0, img.naturalWidth, Math.min(img.naturalHeight, ch * (img.naturalWidth / cw)), 0, 0, cw, ch);
+          return c.toDataURL("image/png");
+        };
+        return { full: scale === 1 ? null : draw(img.naturalWidth, Math.round(h * scale)), css: draw(w, h) };
+      },
+      [`data:${mime};base64,${buf.toString("base64")}`, dw.width, cssH, dw.scale],
+    );
+    const b64 = (d) => Buffer.from(d.split(",")[1], "base64");
+    return { natural: meta, ...dw, height: cssH, cut: Math.round(meta.h / dw.scale) > cssH, css: b64(out.css), full: out.full ? b64(out.full) : null };
+  } finally {
+    await page.close();
+  }
+}
+
+async function captureUrl(browser, url, width) {
+  const { BOT_WALL } = await import("../robots.mjs");
+  const ctx = await browser.newContext({ viewport: { width, height: 900 } });
+  try {
+    const page = await ctx.newPage();
+    await page.addInitScript(HIDE_DEV);
+    await page.goto(url, { waitUntil: "networkidle", timeout: 45_000 }).catch(() => page.waitForLoadState("load").catch(() => {}));
+    await page.waitForTimeout(700);
+    const text = await page.evaluate(() => `${document.title} ${document.body?.innerText?.slice(0, 2000) ?? ""}`).catch(() => "");
+    if (BOT_WALL.test(text) && text.length < 1500) throw new Error(`${url} showed a bot check instead of the page. Take a screenshot of it yourself and run palate match <file.png>.`);
+    await scrollThrough(page);
+    await settle(page);
+    const { encodePng } = await import("../png.mjs");
+    const { captureFull } = await import("../look.mjs");
+    return encodePng(await captureFull(page, { maxHeight: 16_000 }));
+  } finally {
+    await ctx.close();
+  }
+}
+
+// ---- what a still image shows, measured (pure: { width, height, channels, data } in, numbers out)
+
+const px = (img, x, y) => {
+  const i = (y * img.width + x) * img.channels;
+  return img.channels >= 3 ? [img.data[i], img.data[i + 1], img.data[i + 2]] : [img.data[i], img.data[i], img.data[i]];
+};
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+export const hex = (c) => `#${c.map((v) => Math.round(v).toString(16).padStart(2, "0")).join("")}`;
+const unhex = (h) => [1, 3, 5].map((i) => parseInt(String(h).slice(i, i + 2), 16));
+
+// CIE76 ΔE in Lab: under 2 can't be seen, under 5 is close, over 10 is another colour.
+export function deltaE(a, b) {
+  const lab = (c) => {
+    const [r, g, bl] = c.map((v) => {
+      v /= 255;
+      return v > 0.04045 ? ((v + 0.055) / 1.055) ** 2.4 : v / 12.92;
+    });
+    const f = (t) => (t > 0.008856 ? Math.cbrt(t) : 7.787 * t + 16 / 116);
+    const x = f((r * 0.4124 + g * 0.3576 + bl * 0.1805) / 0.95047), y = f(r * 0.2126 + g * 0.7152 + bl * 0.0722), z = f((r * 0.0193 + g * 0.1192 + bl * 0.9505) / 1.08883);
+    return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+  };
+  const A = lab(typeof a === "string" ? unhex(a) : a), B = lab(typeof b === "string" ? unhex(b) : b);
+  return Math.hypot(A[0] - B[0], A[1] - B[1], A[2] - B[2]);
+}
+
+// The image's colours by share: 5 bits a channel, near colours merged into the larger, the top `max` over 0.1%.
+export function palette(img, { max = 12, min = 0.001 } = {}) {
+  const step = Math.max(1, Math.round(Math.sqrt((img.width * img.height) / 400_000)));
+  const buckets = new Map();
+  let n = 0;
+  for (let y = 0; y < img.height; y += step)
+    for (let x = 0; x < img.width; x += step) {
+      const c = px(img, x, y);
+      const k = ((c[0] >> 3) << 10) | ((c[1] >> 3) << 5) | (c[2] >> 3);
+      const b = buckets.get(k) ?? buckets.set(k, { n: 0, r: 0, g: 0, b: 0 }).get(k);
+      b.n++, (b.r += c[0]), (b.g += c[1]), (b.b += c[2]);
+      n++;
+    }
+  const list = [...buckets.values()].sort((a, b) => b.n - a.n).map((b) => ({ n: b.n, rgb: [b.r / b.n, b.g / b.n, b.b / b.n] }));
+  const kept = [];
+  for (const c of list) {
+    const near = kept.find((k) => dist(k.rgb, c.rgb) < 24);
+    if (near) near.n += c.n;
+    else if (kept.length < 64) kept.push({ ...c });
+  }
+  return kept.sort((a, b) => b.n - a.n).filter((c) => c.n / n >= min).slice(0, max).map((c) => ({ hex: hex(c.rgb), share: +(c.n / n).toFixed(4) }));
+}
+
+// Each row's ground (its most common colour) and where something sits on it.
+function rows(img) {
+  const step = img.width > 800 ? 2 : 1;
+  const out = [];
+  for (let y = 0; y < img.height; y++) {
+    const count = new Map();
+    for (let x = 0; x < img.width; x += step * 2) {
+      const c = px(img, x, y);
+      const k = ((c[0] >> 3) << 10) | ((c[1] >> 3) << 5) | (c[2] >> 3);
+      count.set(k, (count.get(k) ?? 0) + 1);
+    }
+    const k = [...count.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    // The ground's own colour: the mean of the pixels in its bucket, not the bucket's centre.
+    const sum = [0, 0, 0];
+    let m = 0;
+    for (let x = 0; x < img.width; x += step * 2) {
+      const c = px(img, x, y);
+      if ((((c[0] >> 3) << 10) | ((c[1] >> 3) << 5) | (c[2] >> 3)) !== k) continue;
+      (sum[0] += c[0]), (sum[1] += c[1]), (sum[2] += c[2]), m++;
+    }
+    const bg = sum.map((v) => v / m);
+    let ink = 0, left = -1, right = -1;
+    for (let x = 0; x < img.width; x += step) {
+      if (dist(px(img, x, y), bg) > 48) {
+        ink++;
+        if (left < 0) left = x;
+        right = x;
+      }
+    }
+    out.push({ bg, ink: ink / Math.ceil(img.width / step), left, right });
+  }
+  return out;
+}
+
+// Rough structure: surfaces (runs of one ground colour) and content blocks (runs of rows with something on them,
+// split where 16 px or more stand empty), each with its span across the width.
+export function measureImage(img) {
+  const R = rows(img);
+  const surfaces = [];
+  for (let y = 0; y < R.length; y++) {
+    const last = surfaces.at(-1);
+    if (last && dist(last.rgb, R[y].bg) < 18) last.height++;
+    else surfaces.push({ y, height: 1, rgb: R[y].bg });
+  }
+  // Runs under 6 px (a divider, a rule) belong to the surface around them.
+  const solid = [];
+  for (const s of surfaces) {
+    const last = solid.at(-1);
+    if (s.height < 6 && last) last.height += s.height;
+    else if (last && dist(last.rgb, s.rgb) < 18) last.height += s.height;
+    else solid.push({ ...s });
+  }
+  const blocks = [];
+  let open = null, empty = 0;
+  for (let y = 0; y < R.length; y++) {
+    const on = R[y].ink >= 0.002 && R[y].left >= 0;
+    if (on) {
+      if (!open) open = { y, end: y, left: R[y].left, right: R[y].right };
+      open.end = y;
+      open.left = Math.min(open.left, R[y].left);
+      open.right = Math.max(open.right, R[y].right);
+      empty = 0;
+    } else if (open && ++empty >= 16) {
+      blocks.push(open);
+      open = null;
+    }
+  }
+  if (open) blocks.push(open);
+  const B = blocks.filter((b) => b.end - b.y >= 3).map((b) => ({ y: b.y, height: b.end - b.y + 1, left: b.left, right: b.right }));
+  const left = B.length ? Math.min(...B.map((b) => b.left)) : 0;
+  const right = B.length ? Math.max(...B.map((b) => b.right)) : img.width - 1;
+  return {
+    width: img.width,
+    height: img.height,
+    palette: palette(img),
+    surfaces: solid.map((s) => ({ y: s.y, height: s.height, colour: hex(s.rgb) })),
+    blocks: B,
+    span: { left, right, width: right - left + 1 },
+  };
+}
+
+// ---- the difference
+
+// Pixel difference with tops aligned, over the rows both have. heat: the design faded to grey with differing
+// pixels in red; rows only the build has in magenta, rows the build lacks in cyan. Returns the share of changed
+// pixels overall and per 100 px strip.
+export function diffImages(a, b, { threshold = 40 } = {}) {
+  const w = Math.min(a.width, b.width);
+  const overlap = Math.min(a.height, b.height);
+  const H = Math.max(a.height, b.height);
+  const data = Buffer.alloc(w * H * 3);
+  const strips = [];
+  let changed = 0;
+  for (let y = 0; y < H; y++) {
+    let rowChanged = 0;
+    for (let x = 0; x < w; x++) {
+      const o = (y * w + x) * 3;
+      if (y < overlap) {
+        const p = px(a, x, y), q = px(b, x, y);
+        const d = Math.max(Math.abs(p[0] - q[0]), Math.abs(p[1] - q[1]), Math.abs(p[2] - q[2]));
+        const g = 170 + ((p[0] * 0.3 + p[1] * 0.59 + p[2] * 0.11) / 255) * 70;
+        if (d > threshold) {
+          rowChanged++;
+          const t = Math.min(1, 0.45 + d / 255);
+          data[o] = 255 * t + g * (1 - t);
+          data[o + 1] = g * (1 - t);
+          data[o + 2] = g * (1 - t) + 30 * t;
+        } else data[o] = data[o + 1] = data[o + 2] = g;
+      } else {
+        const only = a.height > b.height ? px(a, x, y) : px(b, x, y);
+        const g = 150 + ((only[0] * 0.3 + only[1] * 0.59 + only[2] * 0.11) / 255) * 80;
+        if (a.height > b.height) [data[o], data[o + 1], data[o + 2]] = [g * 0.45, g, g];
+        else [data[o], data[o + 1], data[o + 2]] = [g, g * 0.45, g];
+      }
+    }
+    if (y < overlap) {
+      changed += rowChanged;
+      const s = Math.floor(y / 100);
+      strips[s] = (strips[s] ?? 0) + rowChanged / w / 100;
+    }
+  }
+  return {
+    width: w,
+    height: H,
+    overlap,
+    designHeight: a.height,
+    buildHeight: b.height,
+    changed: overlap ? +(changed / (w * overlap)).toFixed(4) : 1,
+    strips: strips.map((s, i) => ({ y: i * 100, changed: +s.toFixed(3) })),
+    image: { width: w, height: H, channels: 3, data },
+  };
+}
+
+// The strips that differ most, adjacent ones merged: where to look first.
+export function hotspots(strips, { max = 4, min = 0.04 } = {}) {
+  const runs = [];
+  for (const s of strips) {
+    const last = runs.at(-1);
+    if (s.changed >= min && last && last.end === s.y) (last.end = s.y + 100), (last.sum += s.changed), last.n++;
+    else if (s.changed >= min) runs.push({ y: s.y, end: s.y + 100, sum: s.changed, n: 1 });
+  }
+  return runs.map((r) => ({ y: r.y, end: r.end, changed: +(r.sum / r.n).toFixed(3) })).sort((a, b) => b.changed * (b.end - b.y) - a.changed * (a.end - a.y)).slice(0, max);
+}
+
+// Each main colour of the design (over 1% of it) beside the nearest colour in the build.
+export function palettePairs(design, build) {
+  return design.filter((c) => c.share >= 0.01).map((c) => {
+    const near = build.map((b) => ({ ...b, d: deltaE(c.hex, b.hex) })).sort((x, y) => x.d - y.d)[0];
+    return { design: c.hex, share: c.share, build: near?.hex ?? null, buildShare: near?.share ?? 0, dE: near ? +near.d.toFixed(1) : null };
+  });
+}
+
+// Half size, side by side: the design, the build and the difference, 16 px apart, on a light grey ground.
+function sideBySide(images, { y, height }) {
+  const half = images.map((img) => {
+    const h = Math.max(0, Math.min(height, img.height - y));
+    const w2 = Math.floor(img.width / 2), h2 = Math.floor(h / 2);
+    const data = Buffer.alloc(w2 * h2 * 3);
+    for (let r = 0; r < h2; r++)
+      for (let c = 0; c < w2; c++) {
+        let s0 = 0, s1 = 0, s2 = 0;
+        for (const [dx, dy] of [[0, 0], [1, 0], [0, 1], [1, 1]]) {
+          const p = px(img, c * 2 + dx, y + r * 2 + dy);
+          (s0 += p[0]), (s1 += p[1]), (s2 += p[2]);
+        }
+        const o = (r * w2 + c) * 3;
+        (data[o] = s0 / 4), (data[o + 1] = s1 / 4), (data[o + 2] = s2 / 4);
+      }
+    return { width: w2, height: h2, channels: 3, data };
+  });
+  const gap = 16;
+  const W = half.reduce((n, h) => n + h.width, 0) + gap * (half.length + 1);
+  const H = Math.max(1, ...half.map((h) => h.height)) + gap * 2;
+  const data = Buffer.alloc(W * H * 3, 226);
+  let x0 = gap;
+  for (const h of half) {
+    for (let r = 0; r < h.height; r++) h.data.copy(data, ((r + gap) * W + x0) * 3, r * h.width * 3, (r + 1) * h.width * 3);
+    x0 += h.width + gap;
+  }
+  return { width: W, height: H, channels: 3, data };
+}
+
+// ---- the spec
+
+// spec.json's values checked: each tagged, each substitution with what it replaces and why, the phone layout
+// and the states listed as inferred, text with a size so palate can check the type.
+export function checkSpec(spec) {
+  const values = Array.isArray(spec?.values) ? spec.values : [];
+  const errors = [];
+  const warnings = [];
+  if (!values.length) errors.push("spec.json has no values: write what you read from the design before building");
+  for (const v of values) {
+    const name = v?.what ?? v?.text ?? JSON.stringify(v).slice(0, 40);
+    if (!TAGS.includes(v?.tag)) errors.push(`"${name}" isn't tagged observed, inferred or substituted`);
+    else if (v.tag === "substituted" && (!v.why || !v.instead)) errors.push(`the substitution "${name}" needs instead (what the design uses) and why`);
+    else if (v.tag === "inferred" && !v.why) warnings.push(`the inferred "${name}" has no why`);
+  }
+  const inferred = values.filter((v) => v?.tag === "inferred");
+  const says = (re) => inferred.some((v) => re.test(`${v.what ?? ""} ${v.value ?? ""}`));
+  if (!says(/phone|mobile|390|small screen|narrow/i)) warnings.push("the phone layout isn't listed as inferred");
+  if (!says(/hover|focus|pressed|active|state/i)) warnings.push("the states (hover, focus, pressed) aren't listed as inferred");
+  const texts = values.filter((v) => v?.tag === "observed" && typeof v.text === "string" && v.text.trim());
+  if (!texts.some((v) => Number(v.size) > 0)) warnings.push("no observed text has a size: palate can't check the type against the spec");
+  return {
+    errors,
+    warnings,
+    texts: texts.map((v) => ({ what: v.what ?? v.text, text: v.text.trim(), size: Number(v.size) || null, y: Number.isFinite(Number(v.y)) && v.y !== null && v.y !== "" ? Number(v.y) : null, weight: v.weight ?? null })),
+    substitutions: values.filter((v) => v?.tag === "substituted").map((v) => ({ what: v.what ?? "?", value: v.value ?? "", instead: v.instead ?? "", why: v.why ?? "" })),
+    inferred: inferred.map((v) => ({ what: v.what ?? "?", value: v.value ?? "", why: v.why ?? "" })),
+  };
+}
+
+// Text found in the build against the spec: missing text is OFF; a size off by more than 20% is OFF, by more
+// than 2 px CLOSE; a top more than 48 px away is a geometry hint.
+export function compareTexts(spec, found, { height = 900 } = {}) {
+  const far = Math.max(48, Math.round(height * 0.05));
+  return spec.map((s, i) => {
+    const f = found[i];
+    if (!f) return { ...s, result: "OFF", id: "content", what: `"${s.text.slice(0, 60)}" is in the design but not on the page` };
+    const notes = [];
+    let result = "MATCH";
+    let id = "type";
+    if (s.size && f.size) {
+      const d = Math.abs(f.size - s.size);
+      if (d > Math.max(3, s.size * 0.2)) result = "OFF";
+      else if (d > 2) result = "CLOSE";
+      if (d > 0.5) notes.push(`size ${f.size}px, the design ${s.size}px`);
+    }
+    const dy = s.y != null && f.y != null ? f.y - s.y : 0;
+    if (Math.abs(dy) > 12) notes.push(`top at ${Math.round(f.y)}px, the design ${s.y}px`);
+    // Found, but far from where the design has it: moved.
+    if (Math.abs(dy) > far) [result, id] = ["OFF", "geometry"];
+    return { ...s, result, id, found: f, dy, what: notes.join(", ") || null };
+  });
+}
+
+// ---- rounds
+
+const roundsFile = (dir, route) => path.join(matchRoot(dir, route), "rounds.json");
+const readRounds = (dir, route) => readJson(roundsFile(dir, route), { rounds: [], best: null });
+
+// ---- 1. the design in
+
+export async function matchImport(dir, rawSource, { route: rawRoute = "/", width } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const src = parseSource(rawSource);
+  if (!src || src.kind === "unknown") throw new Error(`palate match takes a PNG or JPG (a screenshot or a Figma export), a page URL or a Figma frame link; got "${String(rawSource ?? "").slice(0, 80)}".`);
+  if (src.kind === "image" && !fs.existsSync(src.file)) throw new Error(`No image at ${slash(src.file)}.`);
+  const given = width ? Number(width) : null;
+  let buf;
+  let mime = "image/png";
+  if (src.kind === "figma") {
+    const f = await figmaFrame(src);
+    if (!f.ok) return { stopped: true, text: [`# Match ${route}: stopped`, "", f.why].join("\n") };
+    buf = f.buffer;
+  } else if (src.kind === "image") {
+    buf = fs.readFileSync(src.file);
+    mime = /\.jpe?g$/i.test(src.file) ? "image/jpeg" : /\.webp$/i.test(src.file) ? "image/webp" : "image/png";
+  }
+  const root = matchRoot(dir, route);
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  for (const f of fs.readdirSync(root)) if (/^(reference|part-\d+)/.test(f)) fs.rmSync(path.join(root, f), { force: true });
+  const { browser, release } = await acquireBrowser();
+  let n;
+  try {
+    if (src.kind === "url") buf = await captureUrl(browser, src.url, given ?? 1440);
+    n = await normalize(browser, buf, mime, src.kind === "url" ? (given ?? 1440) : given);
+  } finally {
+    await release();
+  }
+  const reference = path.join(root, "reference.png");
+  fs.writeFileSync(reference, n.css);
+  if (n.full) fs.writeFileSync(path.join(root, "reference-full.png"), n.full);
+  const img = decodePng(n.css);
+  const measure = measureImage(img);
+  fs.writeFileSync(path.join(root, "measure.json"), JSON.stringify(measure, null, 1));
+  const parts = [];
+  if (img.height > PART_H * 1.3)
+    for (let y = 0, i = 1; y < img.height && i <= MAX_PARTS; y += PART_H, i++) {
+      const f = path.join(root, `part-${i}.png`);
+      writePng(f, cropImage(img, { y, height: PART_H }));
+      parts.push({ file: f, y, end: Math.min(img.height, y + PART_H) });
+    }
+  // spec.json: palate's own observations to start from. Kept when it was written for this same source.
+  const specFile = path.join(root, "spec.json");
+  const prev = readJson(path.join(root, "match.json"), null);
+  const sameSource = prev?.source?.label === src.label;
+  if (fs.existsSync(specFile) && !sameSource) fs.renameSync(specFile, path.join(root, `spec.before-${stamp()}.json`));
+  if (!fs.existsSync(specFile)) fs.writeFileSync(specFile, JSON.stringify(starterSpec(src, n, measure), null, 1));
+  const m = { route, source: { kind: src.kind, label: src.label }, width: n.width, height: n.height, natural: n.natural, scale: +n.scale.toFixed(3), assumedScale: n.assumed, cut: n.cut, reference, referenceFull: n.full ? path.join(root, "reference-full.png") : null, parts, spec: specFile, brief: path.join(root, "brief.md"), at: new Date().toISOString() };
+  fs.writeFileSync(path.join(root, "match.json"), JSON.stringify(m, null, 1));
+  if (!sameSource) fs.rmSync(roundsFile(dir, route), { force: true });
+  fs.writeFileSync(m.brief, matchBrief(dir, m, measure));
+  const lines = [
+    `# Match ${route}: the user's design is the spec`,
+    "",
+    `- The design: ${slash(reference)} (${n.width}×${n.height} CSS px${n.scale !== 1 ? `, from a ${n.natural.w}×${n.natural.h} image read at ${+n.scale.toFixed(2)}x${n.assumed ? ": assumed @2x; pass --width if it isn't" : ""}` : ""})`,
+    n.cut ? `- ⚠ The design is taller than 16,000 px: palate kept the top 16,000.` : null,
+    parts.length ? `- In ${parts.length} parts for reading: ${parts.map((p) => slash(p.file)).join(", ")}` : null,
+    `- Measured: ${measure.palette.slice(0, 4).map((c) => `${c.hex} ${(c.share * 100).toFixed(c.share < 0.1 ? 1 : 0)}%`).join(", ")}; ${measure.surfaces.length} surface${measure.surfaces.length === 1 ? "" : "s"}, ${measure.blocks.length} content block${measure.blocks.length === 1 ? "" : "s"}; content spans x ${measure.span.left}–${measure.span.right}.`,
+    `- Brief: ${slash(m.brief)}`,
+    "",
+    `Read the brief and follow it: spec.json first (${slash(specFile)}), then the build, then palate match --check --route ${route}. palate's taste, archetypes, blueprint and house-look check don't apply to this route.`,
+  ];
+  return { text: lines.filter((l) => l != null).join("\n"), match: m };
+}
+
+function starterSpec(src, n, measure) {
+  const v = (what, value, extra = {}) => ({ what, value, tag: "observed", by: "palate", ...extra });
+  return {
+    source: src.label,
+    width: n.width,
+    height: n.height,
+    values: [
+      v("design size", `${n.width}×${n.height} CSS px`),
+      v("ground (most of the image)", measure.palette[0]?.hex ?? null, { share: measure.palette[0]?.share }),
+      ...measure.palette.slice(1, 6).map((c, i) => v(`colour ${i + 2} by share`, c.hex, { share: c.share })),
+      ...measure.surfaces.filter((s) => s.height >= 24).slice(0, 12).map((s, i) => v(`surface ${i + 1}`, s.colour, { y: s.y, height: s.height })),
+      v("content span", `x ${measure.span.left}–${measure.span.right} (${measure.span.width}px)`),
+    ],
+  };
+}
+
+function matchBrief(dir, m, measure) {
+  const route = m.route;
+  const W = m.width;
+  const surfaces = measure.surfaces.filter((s) => s.height >= 24).slice(0, 12);
+  const blocks = measure.blocks.slice(0, 24);
+  const margin = W - 1 - measure.span.right;
+  return [
+    `# Match ${route}: build it from the user's design`,
+    "",
+    "The user's design is the spec. Build it faithfully, in this project's own stack. palate's taste doesn't apply here: no blueprint, no archetypes, no house-look check, no similarity gate against other projects, and no improvements. If something in the design looks wrong to you, build it as designed and say so in your hand-off. Never fix it silently.",
+    "",
+    "## The design",
+    `- Source: ${m.source.label} (${{ image: "an image file", url: `a page captured at ${W} px`, figma: "a Figma frame" }[m.source.kind]})`,
+    `- The reference: ${slash(m.reference)} (${W}×${m.height} CSS px${m.scale !== 1 ? `, read at ${m.scale}x from a ${m.natural.w}×${m.natural.h} image${m.referenceFull ? `; full size: ${slash(m.referenceFull)}` : ""}` : ""})`,
+    m.parts.length ? `- Read it in parts, top to bottom: ${m.parts.map((p) => `${slash(p.file)} (rows ${p.y}–${p.end})`).join(", ")}` : null,
+    `- The design is ${W} px wide: palate renders the build at ${W} px to check it.`,
+    "",
+    "## What palate measured from the image (observed, rough: confirm each against the image)",
+    `- Colours by share: ${measure.palette.map((c) => `${c.hex} ${(c.share * 100).toFixed(1)}%`).join(", ")}. The first is likely the ground; small dark shares are likely text; a saturated small share is likely the accent.`,
+    `- Surfaces (bands of one ground colour, y in px): ${surfaces.map((s) => `${s.y}–${s.y + s.height} ${s.colour}`).join(" · ") || "one ground"}`,
+    `- Content blocks (rows with something on them, split where 16 px stand empty): ${blocks.map((b) => `y ${b.y}–${b.y + b.height} (x ${b.left}–${b.right})`).join(" · ")}${measure.blocks.length > blocks.length ? ` and ${measure.blocks.length - blocks.length} more in measure.json` : ""}`,
+    `- Content spans x ${measure.span.left}–${measure.span.right} (${measure.span.width} px; margins ${measure.span.left} and ${margin} px).`,
+    "",
+    "## 1. Write spec.json before any code",
+    `${slash(m.spec)} starts with palate's measurements. Add every value you read from the design, each tagged:`,
+    "- **observed**: read from the image: colours (sample them; don't guess), sizes, spacing, radii, borders, positions. Give each piece of text its exact `text`, its `size` in px and its `y` (top, in px from the top of the design): palate checks the build against them.",
+    "- **inferred**: what a still image can't show: hover, focus and pressed states, the phone layout, menus, hidden content, motion. Say what you chose and why.",
+    "- **substituted**: what you can't use as it is: a paid or unknown font replaced by the closest Google or OFL font, a photo you don't have, an icon set swapped. Give `instead` (what the design uses) and `why`.",
+    "```json",
+    '{"values": [',
+    '  {"what": "headline", "text": "<the words, exactly>", "size": 56, "y": 118, "value": "56px/1.05, 600, -0.02em, #0f1720", "tag": "observed"},',
+    '  {"what": "display font", "value": "Inter Tight", "instead": "<the design\'s font>", "why": "paid font; the closest free grotesk", "tag": "substituted"},',
+    '  {"what": "primary button hover", "value": "a step darker", "why": "not visible in a still", "tag": "inferred"},',
+    '  {"what": "phone layout", "value": "one column, same order", "why": "the design shows only desktop", "tag": "inferred"}',
+    "]}",
+    "```",
+    "",
+    "## 2. Build it",
+    "- In this project's stack, with its components and tokens: use a token where its value equals the design's; add tokens for the rest. Don't restyle the project's other pages.",
+    "- Order: geometry first (the container, columns and each block's top from the measurements), then type, then spacing, then colour and details.",
+    "- Content word for word: every label, number and link as the design shows it. Nothing added, nothing reworded, nothing removed.",
+    "- Fonts: the design's own when it is free (Google Fonts, OFL); else the closest free one, listed as substituted. Match size, weight, line height and letter spacing, not only the family.",
+    "- Images and icons: the project's own assets when it has them; else a stand-in of the same size and crop, listed as substituted. Icons from the same set when it is free (lucide, Heroicons, Phosphor, Hugeicons…), else the closest, listed.",
+    `- While you build, compare your page with the design yourself: \`palate shoot ${route} --widths ${W} --fold\` and open both images.`,
+    "",
+    "## 3. What the design doesn't show (inferred: list each in spec.json)",
+    "- States: hover, focus-visible and pressed on every control, in the design's own language; loading, empty and error where the screen has data.",
+    "- The phone layout at 390: the same content in the same order, in the design's spirit; nothing clipped, no sideways scroll.",
+    "- Accessibility: alt text, labels, visible focus. If the design itself fails contrast, build it as designed and tell the user: palate warns about it and never changes the design.",
+    "",
+    "## 4. The check (a fresh judge, never you)",
+    `\`palate match --check --route ${route}\`: palate renders the build at ${W} px beside the design, a difference image and its measurements, and writes one judge packet. Run it with a fresh subagent ("Read <packet> and follow it exactly"), then \`palate match --answers <dir> --route ${route}\`. NOT READY: fix what it lists, most visible first, and check again; two repair rounds at most.`,
+    "",
+    "## Hand-off",
+    "Tell the user the verdict in one line, then the substitutions (what you used instead, and why) and what you inferred (states, the phone layout), so they can correct them.",
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}
+
+// ---- 2. the check
+
+// Where each spec text sits in the build: the text node that holds it (so the second line of a headline gets
+// its own top), else the deepest element whose text holds it.
+const TEXT_SCRIPT = (items) => {
+  const norm = (s) => String(s ?? "").replace(/\s+/g, " ").trim().toLowerCase();
+  const visible = (el) => {
+    if (!el || el.closest("script,style,noscript,template")) return false;
+    const r = el.getBoundingClientRect();
+    const cs = getComputedStyle(el);
+    return r.width > 0 && r.height > 0 && cs.visibility !== "hidden" && cs.display !== "none";
+  };
+  const nodes = [];
+  const walker = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) if (n.textContent.trim() && visible(n.parentElement)) nodes.push(n);
+  const all = [...document.body.querySelectorAll("*")].filter(visible);
+  const facts = (el, rect) => {
+    const cs = getComputedStyle(el);
+    return { size: parseFloat(cs.fontSize), weight: cs.fontWeight, family: cs.fontFamily.split(",")[0].replace(/["']/g, "").trim(), lineHeight: cs.lineHeight, colour: cs.color, y: Math.round(rect.top + scrollY), x: Math.round(rect.left) };
+  };
+  return items.map(({ text: want, y: at }) => {
+    const w = norm(want);
+    if (!w) return null;
+    const re = new RegExp(w.split(" ").map((p) => p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join("\\s+"), "i");
+    // The same words can appear twice (a nav link and a button): the one nearest the spec's top, a whole match first.
+    const hits = [];
+    for (const n of nodes) {
+      const m = n.textContent.match(re);
+      if (!m) continue;
+      const range = document.createRange();
+      range.setStart(n, m.index);
+      range.setEnd(n, m.index + m[0].length);
+      const rect = range.getClientRects()[0] ?? range.getBoundingClientRect();
+      hits.push({ f: facts(n.parentElement, rect), whole: norm(n.textContent) === w });
+    }
+    if (hits.length) {
+      const score = (h) => (at == null ? 0 : Math.abs(h.f.y - at)) + (h.whole ? 0 : 1);
+      return hits.sort((a, b) => score(a) - score(b))[0].f;
+    }
+    // Text split across elements ("<span>$</span> tracewell init"): the deepest element that holds all of it.
+    let best = null;
+    for (const el of all) {
+      const t = norm(el.innerText);
+      if (t.includes(w) && (!best || t.length <= best.len)) best = { el, len: t.length };
+    }
+    return best ? facts(best.el, best.el.getBoundingClientRect()) : null;
+  });
+};
+
+async function renderBuild(dir, route, at, { url, width, texts }) {
+  const axe = createRequire(import.meta.url).resolve("axe-core/axe.min.js");
+  const Floor = await import("./floor.mjs").catch(() => null);
+  const CLIP = new Set(["CLIPPED", "TEXT_CLIPPED_EFFECT", "LABEL_WRAP", "HYPHEN_BREAK"]);
+  return withBrowser(dir, { url }, async ({ base, browser }) => {
+    const out = { warnings: [] };
+    // As a reader sees it (motion on, scrolled through so reveals fire, settled), at the design's width.
+    const { page, ctx, errors } = await openPage(browser, base, route, { width, init: MOTION_INIT });
+    try {
+      const overlay = await page.evaluate(() => document.querySelector("vite-error-overlay")?.shadowRoot?.querySelector(".message")?.textContent ?? null).catch(() => null);
+      if (overlay) throw new Error(`The page did not build: ${overlay.trim().slice(0, 300)}`);
+      out.build = path.join(at, "build.png");
+      await shootFull(page, out.build);
+      out.texts = await page.evaluate(TEXT_SCRIPT, texts.map((t) => ({ text: t.text, y: t.y }))).catch(() => texts.map(() => null));
+      out.motion = await page.evaluate(() => {
+        const M = window.__palateMotion;
+        const running = (document.getAnimations?.() ?? []).filter((a) => a.playState === "running").length;
+        return M ? { entrances: M.entrances, observers: M.io, waapi: M.waapi, running } : { entrances: 0, observers: 0, waapi: 0, running };
+      }).catch(() => null);
+      out.overflow = await page.evaluate(() => document.documentElement.scrollWidth - innerWidth).catch(() => 0);
+      await page.addScriptTag({ path: axe }).catch(() => {});
+      out.contrast = await page.evaluate(`axe.run(document, { runOnly: ["color-contrast"] }).then(r => r.violations.flatMap(v => v.nodes.map(n => (n.html.replace(/<[^>]+>/g, '').trim().slice(0, 40)) + ' ' + ((n.any[0] && n.any[0].data && n.any[0].data.contrastRatio) || '?') + ':1')))`).catch(() => []);
+      if (Floor?.floorOnPage) {
+        const { findSections } = await import("../look.mjs");
+        const sections = await findSections(page).catch(() => []);
+        out.clipped = (await Floor.floorOnPage(page, { width, sections }).catch(() => [])).filter((c) => CLIP.has(c.id)).map((c) => `${c.id}: ${c.what}`);
+      }
+      out.errors = errors.slice(0, 3);
+    } finally {
+      await ctx.close();
+    }
+    // The phone: inferred, so it only warns.
+    const p = await openPage(browser, base, route, { width: 390, reducedMotion: true });
+    try {
+      out.phone = path.join(at, "phone.png");
+      await shootFull(p.page, out.phone, { maxHeight: 8000 });
+      out.phoneOverflow = await p.page.evaluate(() => document.documentElement.scrollWidth - innerWidth).catch(() => 0);
+    } finally {
+      await p.ctx.close();
+    }
+    return out;
+  });
+}
+
+export async function matchCheck(dir, rawRoute = "/", { url } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const m = matchedRoute(dir, route);
+  if (!m) throw new Error(`${route} has no design to match yet: run palate match <image|url|figma link> --route ${route} first.`);
+  const root = matchRoot(dir, route);
+  const rr = readRounds(dir, route);
+  const n = rr.rounds.length;
+  const at = path.join(root, `check-${n}-${stamp()}`);
+  fs.mkdirSync(at, { recursive: true });
+  const spec = checkSpec(readJson(m.spec, {}));
+  const r = await renderBuild(dir, route, at, { url, width: m.width, texts: spec.texts });
+  const ref = decodePng(fs.readFileSync(m.reference));
+  const build = decodePng(fs.readFileSync(r.build));
+  const d = diffImages(ref, build);
+  const diffFile = path.join(at, "diff.png");
+  writePng(diffFile, d.image);
+  const H = Math.max(ref.height, build.height);
+  const parts = [];
+  for (let y = 0, i = 1; y < H && i <= MAX_PARTS; y += PART_H, i++) {
+    const p = { y, end: Math.min(H, y + PART_H), compare: path.join(at, `compare-${i}.png`) };
+    const rc = cropImage(ref, { y, height: PART_H });
+    const bc = cropImage(build, { y, height: PART_H });
+    if (rc) writePng((p.design = path.join(at, `design-${i}.png`)), rc);
+    if (bc) writePng((p.build = path.join(at, `build-${i}.png`)), bc);
+    writePng(p.compare, sideBySide([ref, build, d.image], { y, height: PART_H }));
+    parts.push(p);
+  }
+  const bm = measureImage(build);
+  const dm = readJson(path.join(root, "measure.json"), null) ?? measureImage(ref);
+  const pairs = palettePairs(dm.palette, bm.palette);
+  const texts = compareTexts(spec.texts, r.texts ?? [], { height: ref.height });
+  // What palate measured that is plainly off, whatever the judge says.
+  const measuredOff = [];
+  for (const t of texts.filter((x) => x.result === "OFF")) {
+    const fix = { content: "Add it word for word, where the design has it", type: `Set it to ${t.size}px as the design has it`, geometry: `Move it ${Math.abs(t.dy)}px ${t.dy > 0 ? "up" : "down"}, to where the design has it` }[t.id];
+    measuredOff.push({ id: t.id, by: "palate", where: `"${t.text.slice(0, 40)}"`, what: t.what, fix, visibility: t.id === "type" ? 2 : 3 });
+  }
+  for (const p of pairs.filter((x) => x.share >= 0.05 && x.dE != null && x.dE > 10)) measuredOff.push({ id: "colour", by: "palate", where: `${(p.share * 100).toFixed(0)}% of the design`, what: `the design's ${p.design} has no near colour in the build (nearest ${p.build}, ΔE ${p.dE})`, fix: `Use ${p.design} where the design has it`, visibility: 3 });
+  if (build.height < ref.height * 0.85) measuredOff.push({ id: "geometry", by: "palate", where: "the whole page", what: `the build is ${ref.height - build.height}px shorter than the design (${build.height} vs ${ref.height}): something is missing or squeezed`, fix: "Find the band that's missing or shorter in the difference image (cyan rows)", visibility: 3 });
+  const unverified = [];
+  if (build.height > ref.height * 1.1 && build.height - ref.height > 100) unverified.push({ id: "below the design", what: `the build is ${build.height}px tall and the design ${ref.height}px: rows ${ref.height}–${build.height} aren't in the design (a crop, or the build adds them)` });
+  if (m.cut) unverified.push({ id: "below 16,000 px", what: "the design was cut at 16,000 px" });
+  const warnings = [];
+  if (spec.errors.length) warnings.push(...spec.errors.map((e) => `spec.json: ${e}`));
+  warnings.push(...spec.warnings.map((e) => `spec.json: ${e}`));
+  if (r.contrast?.length) warnings.push(`${r.contrast.length} element(s) fail colour contrast (WCAG AA): ${r.contrast.slice(0, 3).join(" · ")}. palate doesn't change the design: tell the user.`);
+  for (const c of r.clipped ?? []) warnings.push(c);
+  if (r.overflow > 1) warnings.push(`At ${m.width}px the page scrolls sideways by ${r.overflow}px.`);
+  if (r.phoneOverflow > 1) warnings.push(`On a phone (390) the page scrolls sideways by ${r.phoneOverflow}px.`);
+  if (r.errors?.length) warnings.push(`Console errors: ${r.errors.join(" | ").slice(0, 300)}`);
+  const moves = r.motion && (r.motion.entrances > 0 || r.motion.waapi > 0 || r.motion.running > 0);
+  const state = { route, n, at, width: m.width, design: { file: m.reference, height: ref.height }, build: { file: r.build, height: build.height }, phone: r.phone, diff: { file: diffFile, changed: d.changed, overlap: d.overlap, hotspots: hotspots(d.strips) }, parts, pairs, texts, motion: r.motion, moves, measuredOff, unverified, warnings, substitutions: spec.substitutions, inferred: spec.inferred, specErrors: spec.errors, created: new Date().toISOString() };
+  state.packet = path.join(at, "packet-match.md");
+  state.out = path.join(at, "answers-match.json");
+  fs.writeFileSync(state.packet, matchPacket(state));
+  fs.writeFileSync(path.join(at, "state.json"), JSON.stringify(state, null, 1));
+  return [
+    `# Match check ${route}: round ${n}`,
+    "",
+    `- Side by side (the design, the build, the difference, half size): ${parts.map((p) => slash(p.compare)).join(", ")}`,
+    `- Difference: ${slash(diffFile)}: ${(d.changed * 100).toFixed(1)}% of pixels differ over the ${d.overlap}px both have${build.height !== ref.height ? `; the build is ${build.height}px tall, the design ${ref.height}px` : ""}.`,
+    state.diff.hotspots.length ? `- Most different: ${state.diff.hotspots.map((h) => `rows ${h.y}–${h.end} (${Math.round(h.changed * 100)}%)`).join(", ")}` : null,
+    ...measuredOff.map((o) => `- ✗ palate measured [${o.id}] ${o.where ? `${o.where}: ` : ""}${o.what}`),
+    ...warnings.slice(0, 8).map((w) => `- ! ${w}`),
+    "",
+    `Run the packet with one fresh subagent: "Read ${slash(state.packet)} and follow it exactly." Never judge it yourself. Then: palate match --answers ${slash(at)} --route ${route}`,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}
+
+function matchPacket(s) {
+  const pct = (x) => `${(x * 100).toFixed(1)}%`;
+  return [
+    "# Design review: does the build match the design?",
+    "",
+    "You are an independent reviewer. You made neither image. The first is the user's design: it is the spec. The second is a build of it. Judge fidelity, not taste: where the build differs from the design it is wrong, even when it looks better. Open every image with your image tool before answering.",
+    "",
+    `## The images (both ${s.width} px wide, tops aligned)`,
+    `- The design, whole: ${slash(s.design.file)} (${s.design.height} px tall)`,
+    `- The build, whole: ${slash(s.build.file)} (${s.build.height} px tall)`,
+    ...s.parts.map((p, i) => `- Part ${i + 1}, rows ${p.y}–${p.end}: the design ${p.design ? slash(p.design) : "(nothing: the design ends above)"} · the build ${p.build ? slash(p.build) : "(nothing: the build ends above)"} · side by side ${slash(p.compare)} (the design, the build, the difference, half size)`),
+    `- The difference: ${slash(s.diff.file)}. Red: pixels that differ. Cyan rows: in the design, missing from the build. Magenta rows: only in the build.`,
+    `- The build on a phone (390): ${slash(s.phone)}. The design shows no phone layout, so this is inferred.`,
+    "",
+    "## What palate measured (hints: trust your eyes over these)",
+    `- ${pct(s.diff.changed)} of pixels differ over the ${s.diff.overlap} px both images have${s.diff.hotspots.length ? `; most in ${s.diff.hotspots.map((h) => `rows ${h.y}–${h.end} (${Math.round(h.changed * 100)}%)`).join(", ")}` : ""}. Text shifted by a pixel shows red too: a red area is where to look, not a verdict.`,
+    s.build.height !== s.design.height ? `- Heights: the design ${s.design.height} px, the build ${s.build.height} px.` : null,
+    s.pairs.length ? `- Main colours, the design's beside the build's nearest (ΔE: under 2 can't be seen, over 10 is another colour): ${s.pairs.map((p) => `${p.design} (${pct(p.share)}) → ${p.build ?? "none"}${p.dE != null ? ` ΔE ${p.dE}` : ""}`).join(", ")}` : null,
+    s.texts.length ? `- Text from the spec, found in the build: ${s.texts.map((t) => `"${t.text.slice(0, 30)}" ${t.found ? `${t.found.size}px${t.size ? ` (spec ${t.size}px)` : ""} at y ${t.found.y}${t.y != null ? ` (spec ${t.y})` : ""}, ${t.found.family} ${t.found.weight}` : "NOT FOUND"}`).join("; ")}` : "- The spec gives no text with sizes: judge type by eye.",
+    `- Motion in the build: ${s.moves ? `yes (${s.motion.entrances} entrance transitions or animations, ${s.motion.running} still running)` : "none"}.`,
+    "",
+    "## Agreed in the spec (not OFF by themselves)",
+    ...(s.substitutions.length ? s.substitutions.map((x) => `- Substituted: ${x.what}: ${x.value} instead of ${x.instead} (${x.why})`) : ["- No substitutions."]),
+    ...(s.inferred.length ? s.inferred.map((x) => `- Inferred: ${x.what}: ${x.value}`) : []),
+    "A substitution that shows (a stand-in font, a placeholder photo) is CLOSE at best; it is OFF only when done badly (a substitute font so much wider that lines wrap differently, a stand-in of the wrong size).",
+    "",
+    "## Check in this order: each MATCH, CLOSE, OFF or UNVERIFIED",
+    "1. content: every text, label, number, link and image in the design is in the build, word for word, and nothing was added or removed.",
+    "2. geometry: the same columns and order; each element in the same place at the same size, within a few pixels.",
+    "3. type: family (or its agreed substitute), size, weight, line height, letter spacing, case.",
+    "4. assets: images, icons, logos and illustrations: the same ones (or agreed stand-ins), the same crop and size.",
+    "5. spacing: the gaps between elements and the padding inside them.",
+    "6. colour: grounds, text, borders and accents (palate's colour pairs above help).",
+    "7. details: borders, radii, shadows, dividers and the small marks the design shows.",
+    `8. motion: the design is a still image. MATCH if the build doesn't move, or only as the design implies (a hover). UNVERIFIED if the build animates something a still can't confirm.${s.moves ? "" : " palate saw no motion in the build."}`,
+    "",
+    "MATCH: you can't tell them apart at a glance. CLOSE: a small difference a careful reader sees only side by side. OFF: a difference anyone sees, or anything missing, added or moved. UNVERIFIED: the images can't show it.",
+    "For every item that isn't MATCH: `where` (the part: \"hero headline\", \"nav, right side\", with rows if you can), `what` (the design vs the build, under 25 words), `fix` (the change to the build, under 20 words) and `visibility` from 1 to 3 (3: anyone sees it at once).",
+    "Then `phone`: does the phone view hold up (nothing clipped, no sideways scroll, readable)? It is inferred, so it only warns.",
+    "",
+    "Answer only from what you see in the images. Be strict: the user will hold the build up against their design. Write the JSON file exactly as specified and nothing else.",
+    `Write ${slash(s.out)} as {"items": [{"id": "content", "result": "MATCH"}, {"id": "geometry", "result": "OFF", "where": "...", "what": "...", "fix": "...", "visibility": 3}, ...all eight in order], "phone": {"ok": true, "note": "..."}, "summary": "two sentences"}`,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}
+
+// ---- 3. the verdict
+
+const RESULTS = ["MATCH", "CLOSE", "OFF", "UNVERIFIED"];
+export function matchVerdict(state, answers) {
+  const items = ORDER.map((id) => {
+    const a = (answers?.items ?? []).find((x) => String(x?.id ?? "").toLowerCase() === id) ?? null;
+    const result = RESULTS.find((r) => r === String(a?.result ?? "").trim().toUpperCase()) ?? "UNVERIFIED";
+    return { id, result, where: a?.where ?? null, what: a ? (a.what ?? null) : "the judge didn't answer this", fix: a?.fix ?? null, visibility: Number(a?.visibility) || 2, by: "judge" };
+  });
+  const off = [...items.filter((x) => x.result === "OFF"), ...(state.measuredOff ?? [])];
+  const rank = (x) => ORDER.indexOf(x.id);
+  off.sort((a, b) => b.visibility - a.visibility || rank(a) - rank(b));
+  const unverified = [...items.filter((x) => x.result === "UNVERIFIED").map((x) => ({ id: x.id, what: x.what ?? "the images can't show it" })), ...(state.unverified ?? [])];
+  const close = items.filter((x) => x.result === "CLOSE");
+  const warnings = [...(state.warnings ?? [])];
+  if (answers?.phone && (answers.phone.ok === false || /^no$/i.test(String(answers.phone.ok)))) warnings.push(`Phone layout (inferred): ${answers.phone.note ?? "doesn't hold up"}`);
+  const subs = state.substitutions ?? [];
+  const verdict = off.length ? "NOT READY" : unverified.length ? "UNVERIFIED" : subs.length ? "READY WITH SUBSTITUTIONS" : "READY";
+  return { verdict, items, off, close, unverified, substitutions: subs, inferred: state.inferred ?? [], warnings, score: off.length * 10 + close.length + unverified.length, summary: answers?.summary ?? null };
+}
+
+function saveMatchVerdict(dir, route, v, state, { final = false } = {}) {
+  const f = path.join(dir, ".palate", "match.json");
+  const all = readJson(f, {});
+  all[route] = { verdict: v.verdict, final, round: state.n, at: new Date().toISOString(), off: v.off.map((o) => `[${o.id}] ${o.where ? `${o.where}: ` : ""}${o.what ?? ""}`) };
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(all, null, 1));
+}
+
+function repairBrief(state, v, round) {
+  return [
+    `# Match repair ${round} of ${MAX_ROUNDS}: ${state.route}`,
+    "",
+    "Make the build match the design. Change only what's listed, most visible first; don't restyle anything else. palate snapshotted the source before this round.",
+    `- The design: ${slash(state.design.file)} · the build now: ${slash(state.build.file)} · the difference: ${slash(state.diff.file)}`,
+    "",
+    "## What's off",
+    ...v.off.map((o, i) => `${i + 1}. [${o.id}]${o.where ? ` ${o.where}:` : ""} ${o.what ?? ""}${o.fix ? ` → ${o.fix}` : ""}${o.by === "palate" ? " (palate measured)" : ""}`),
+    ...(v.close.length ? ["", "## Close (fix if it's quick)", ...v.close.map((o) => `- [${o.id}]${o.where ? ` ${o.where}:` : ""} ${o.what ?? ""}${o.fix ? ` → ${o.fix}` : ""}`)] : []),
+    "",
+    `Then palate match --check --route ${state.route} again, and its packet with a fresh subagent.`,
+  ].join("\n");
+}
+
+export async function matchAnswers(dir, rawRoute = "/", given) {
+  const route = normalizeRoute(rawRoute);
+  const root = matchRoot(dir, route);
+  const dirGiven = given && fs.existsSync(given) && fs.statSync(given).isDirectory() ? given : null;
+  const latest = dirGiven ?? (fs.existsSync(root) ? fs.readdirSync(root).filter((x) => x.startsWith("check-")).map((x) => path.join(root, x)).sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs)[0] : null);
+  const state = latest ? readJson(path.join(latest, "state.json"), null) : null;
+  if (!state) throw new Error(`No match check for ${route} yet: run palate match --check --route ${route} first.`);
+  const file = given && !dirGiven && fs.existsSync(given) ? given : state.out;
+  const answers = readJson(file, null);
+  if (!answers) throw new Error(`No answers yet: the judge writes ${slash(state.out)}.`);
+  const v = matchVerdict(state, answers);
+  const rr = readRounds(dir, route);
+  const prevBest = rr.best != null ? rr.rounds.find((x) => x.n === rr.best) : null;
+  const worse = prevBest && v.off.length > prevBest.off;
+  let snap = null;
+  if (v.verdict === "NOT READY") {
+    const { snapshot } = await import("./gate.mjs");
+    const s = snapshot(dir, path.join(state.at, "source"));
+    if (s.ok) snap = path.join(state.at, "source");
+  }
+  rr.rounds = [...rr.rounds.filter((x) => x.n !== state.n), { n: state.n, at: state.at, verdict: v.verdict, off: v.off.length, score: v.score, snapshot: snap }];
+  if (!prevBest || !worse) rr.best = state.n;
+  fs.mkdirSync(root, { recursive: true });
+  fs.writeFileSync(roundsFile(dir, route), JSON.stringify(rr, null, 1));
+  const repairs = rr.rounds.length - 1;
+  saveMatchVerdict(dir, route, v, state, { final: repairs >= MAX_ROUNDS });
+  fs.writeFileSync(path.join(state.at, "verdict.json"), JSON.stringify(v, null, 1));
+  const line = (o) => `[${o.id}]${o.where ? ` ${o.where}:` : ""} ${o.what ?? ""}${o.fix ? ` → ${o.fix}` : ""}`;
+  const out = [
+    `# Match ${route}, round ${state.n}: ${v.verdict}`,
+    "",
+    `- ${v.items.map((x) => `${x.id} ${x.result}`).join(" · ")}`,
+    ...(v.off.length ? ["", "What's off, most visible first:", ...v.off.map((o, i) => `${i + 1}. ${line(o)}${o.by === "palate" ? " (palate measured)" : ""}`)] : []),
+    ...(v.close.length ? ["", "Close:", ...v.close.map((o) => `- ${line(o)}`)] : []),
+    ...(v.unverified.length ? ["", "Not verified (say so to the user):", ...v.unverified.map((u) => `- ${u.id}: ${u.what}`)] : []),
+    ...(v.substitutions.length ? ["", "Substitutions (tell the user):", ...v.substitutions.map((x) => `- ${x.what}: ${x.value} instead of ${x.instead} (${x.why})`)] : []),
+    ...(v.inferred.length ? ["", "Inferred, not in the design (tell the user; they may correct these):", ...v.inferred.map((x) => `- ${x.what}: ${x.value}`)] : []),
+    ...(v.warnings.length ? ["", "Warnings (palate never changes the design for these; tell the user):", ...v.warnings.slice(0, 10).map((w) => `- ${w}`)] : []),
+    "",
+  ];
+  if (v.verdict !== "NOT READY") {
+    out.push({ READY: "The build matches the design. Tell the user in one line.", "READY WITH SUBSTITUTIONS": "The build matches the design, with the substitutions above. Tell the user the verdict and each substitution, so they can send the real font or asset.", UNVERIFIED: "What could be checked matches. Tell the user which parts couldn't be checked, and why." }[v.verdict]);
+    return out.join("\n");
+  }
+  if (worse && prevBest?.snapshot) return [...out, `This round is worse than round ${prevBest.n} (${v.off.length} off vs ${prevBest.off}). Roll it back: palate match --restore ${prevBest.n} --route ${route}, then try the repair another way, or stop if this was the last round.`].join("\n");
+  if (repairs >= MAX_ROUNDS) return [...out, `That was the last repair round (${MAX_ROUNDS}). Tell the user honestly what still differs (the list above), and the substitutions.`].join("\n");
+  const brief = path.join(state.at, "repair.md");
+  fs.writeFileSync(brief, repairBrief(state, v, repairs + 1));
+  return [...out, `Repair brief: ${slash(brief)}. Do it yourself or with one subagent, then palate match --check --route ${route} again (repair round ${repairs + 1} of ${MAX_ROUNDS}).`].join("\n");
+}
+
+export function matchRestore(dir, rawRoute, round) {
+  const route = normalizeRoute(rawRoute);
+  const r = readRounds(dir, route).rounds.find((x) => x.n === Number(round));
+  if (!r?.snapshot || !fs.existsSync(r.snapshot)) throw new Error(`No snapshot for match round ${round} of ${route}.`);
+  let n = 0;
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else {
+        const to = path.join(dir, path.relative(r.snapshot, p));
+        fs.mkdirSync(path.dirname(to), { recursive: true });
+        fs.copyFileSync(p, to);
+        n++;
+      }
+    }
+  };
+  walk(r.snapshot);
+  return `Restored ${n} files from match round ${round} (${slash(r.snapshot)}). Files added since then are still there.`;
+}
+
+// One entry for the CLI and the MCP tool.
+export async function match(dir, source, { route = "/", width, check, answers, restore, url } = {}) {
+  if (restore != null) return { text: matchRestore(dir, route, restore) };
+  if (answers) {
+    const text = await matchAnswers(dir, route, answers === true ? undefined : answers);
+    return { text, notReady: /: NOT READY\n/.test(text) };
+  }
+  if (check) return { text: await matchCheck(dir, route, { url }) };
+  if (!source) {
+    const m = matchedRoute(dir, route);
+    if (m) return { text: `${normalizeRoute(route)} matches ${m.source.label}. Brief: ${slash(m.brief)}. Check the build: palate match --check --route ${normalizeRoute(route)}.` };
+    throw new Error("Usage: palate match <image|url|figma link> [--route /x] [--width 1440]  ·  palate match --check [--route /x]  ·  palate match --answers <dir> [--route /x]");
+  }
+  const r = await matchImport(dir, source, { route, width });
+  return { text: r.text, stopped: Boolean(r.stopped) };
+}