@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/critique.mjs

@@ -0,0 +1,393 @@
+// `palate critique <route>`: a designer's review, section by section, as specific findings (not a score).
+// palate renders the route at 1440 and 390, crops each section, measures the whole page (repeated devices,
+// how the product is shown, logo rows, what moves) and writes a critique sheet: crops, facts, the user's
+// taste for this kind of screen, what they disagreed with before, library references per section, and a
+// rubric assembled from kb/craft. The agent (it has vision) writes findings; `palate critique --findings f`
+// opens a review board where the user agrees or disagrees with each one, and disagreements teach taste.
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { contactSheet, cropSections, findSections, MOTION_INIT, openPage, shootFull, slugOf, stamp, withBrowser } from "../look.mjs";
+import { freePort, normalizeRoute, shoot } from "../shoot.mjs";
+import { measurePrinciples, principlesReport } from "../principles.mjs";
+import { readJson, TASTE_DIR } from "./common.mjs";
+import { craftRubric, LIB_DIR, screenWords, sectionKind, slash, tasteFor } from "./craft.mjs";
+import { openBrowser } from "./pick.mjs";
+import { latestStates } from "./states.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const devicesScript = fs.readFileSync(path.join(here, "..", "page-devices.js"), "utf8").trim().replace(/;\s*$/, "");
+export const CRITIQUES = path.join(TASTE_DIR, "critiques.jsonl");
+export const SEVERITIES = ["high", "medium", "low", "idea"];
+
+const root = (dir, route) => path.join(dir, ".palate", "critique", slugOf(route));
+
+// The newest critique session for a route (or for any route), or null; withFindings: only sessions with findings.
+export function latestCritique(dir, route, { withFindings = false } = {}) {
+  const base = path.join(dir, ".palate", "critique");
+  const slugs = route ? [slugOf(route)] : fs.existsSync(base) ? fs.readdirSync(base) : [];
+  const all = slugs.flatMap((s) => (fs.existsSync(path.join(base, s)) ? fs.readdirSync(path.join(base, s)).map((t) => path.join(base, s, t)) : []));
+  const done = all.filter((d) => fs.existsSync(path.join(d, withFindings ? "findings.json" : "sections.json"))).sort((a, b) => path.basename(a).localeCompare(path.basename(b)));
+  return done.at(-1) ?? null;
+}
+
+// The states sheet, when `palate states` has run on this route: every part in every state, with findings.
+function statesLine(dir, route) {
+  const s = latestStates(dir, route);
+  if (!s) return `- States: not rendered yet. \`palate states ${route}\` shows every part empty, loading, failing, with long text and many items, at 320 wide; the critique covers the page as it is.`;
+  const rec = readJson(path.join(s, "findings.json"), { findings: [] });
+  const high = rec.findings.filter((f) => f.severity === "high").length;
+  return `- States (palate states ${path.basename(s)}): ${rec.sheet ? slash(rec.sheet) : slash(path.join(s, "sheet.png"))}, one row per part, one column per state. ${rec.findings.length} missing state(s)${high ? `, ${high} high` : ""}, in ${slash(path.join(s, "states.md"))}; don't repeat them as findings, palate fix includes them.`;
+}
+
+// One sheet line, at most ~230 characters (long selectors are in the files next to the sheet).
+const clip = (l) => (l.length > 230 ? `${l.slice(0, 227).replace(/\s+\S*$/, "")}…` : l);
+
+const REVIEW_GUIDE = `# How to review
+
+## 1. The whole page first (full-page screenshots and the facts in the sheet)
+- [page.1] Job: what is this page for, and does the first screen say it in one look?
+- [page.2] Repetition: which devices appear in more than one section (kicker labels, section numbers, frames, backdrops, rules, two-column heads, dark bands)? A device used everywhere stops meaning anything. Keep one at most, and say which.
+- [page.3] Showing the product: is it shown working (live UI, interaction, motion, real data) or only as pictures of it? Static screenshots in frames are the weakest proof; say which picture should become live and how.
+- [page.4] Motion: does anything move on load, on scroll or on interaction beyond hover colour? A page that never moves feels static. Say where motion would explain something (a state change, the product doing its job), never decoration.
+- [page.5] Rhythm: section lengths, density changes, where attention drops, where two sections say the same thing.
+- [page.6] Memorability: what will someone remember tomorrow? If nothing, which section should carry the signature idea?
+
+## 2. Then each section (both widths)
+- [section.1] Job: what must this section make the reader believe or do? Does it show and sell, or explain like documentation (process rows, step lists, inventories of features)?
+- [section.2] Hierarchy: one focal point; the order the eye takes.
+- [section.3] Type: sizes, weights, measure, wrapping, orphans.
+- [section.4] Spacing and alignment: shared edges, consistent rhythm, crowding.
+- [section.5] Legibility at a glance: anything too small, faint or low-contrast to read at 100% (logo rows, captions, labels, marks)?
+- [section.6] Details: icons, brand marks, avatars, inputs, numbers, empty and loading states, hover/focus/pressed.
+- [section.7] Phone (390): what breaks, crowds, gets too long or loses its point.
+- [section.8] Ideas: if the section is generic or forgettable, one structural idea that would make it memorable (cite a reference number if one fits).
+`;
+
+const pastDisagreements = (n = 15) => {
+  if (!fs.existsSync(CRITIQUES)) return [];
+  return fs
+    .readFileSync(CRITIQUES, "utf8")
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l))
+    .filter((r) => r.verdict === "disagree")
+    .slice(-n);
+};
+
+// Measured whole-page facts (from page-devices.js), as lines for the sheet.
+export function deviceLines(d) {
+  const out = [];
+  out.push(d.repeated.length ? `- Repeated devices (3+ sections): ${d.repeated.map((r) => `${r.device} in sections ${r.sections.join(", ")}`).join("; ")}.` : "- No device repeats in 3+ sections.");
+  const kick = [...new Map(d.kickers.map((k) => [`${k.text}|${k.section}`, k])).values()];
+  if (kick.length) out.push(`- Kicker labels above headings (${d.kickers.length}, in ${new Set(d.kickers.map((k) => k.section)).size} sections): ${kick.slice(0, 10).map((k) => `"${k.text}" (section ${k.section})`).join(", ")}.`);
+  const pics = d.media.filter((m) => m.kind === "static picture");
+  const live = d.media.filter((m) => m.kind.startsWith("live"));
+  out.push(`- How the product is shown: ${pics.length} large static picture(s)${pics.filter((p) => p.framed).length ? ` (${pics.filter((p) => p.framed).length} in frames or backdrops)` : ""}, ${live.length} live (video, canvas, iframe).${pics.length ? ` ${pics.map((p) => `Section ${p.section}: ${p.size}${p.alt ? ` "${p.alt.slice(0, 60)}"` : ""}`).join(" · ")}` : ""}`);
+  for (const r of d.logoRows) out.push(`- Logo row in section ${r.section} (${r.selector}): ${r.count} marks at ${r.markPx}px with ${r.textPx}px names${r.monochrome ? `, all one colour${r.paintedByMask ? " (painted through a CSS mask)" : ""}` : ""}${r.contrast ? `, mark contrast ${r.contrast}:1 against the background` : ""}${r.markPx < 20 ? "; marks under 20px read as texture, not as logos" : ""}: ${r.names.join(", ")}.`);
+  const m = d.motion;
+  // Entrances: CSS animations, opacity/transform transitions and scripted fades outside sticky or fixed chrome.
+  const entrances = (m.entrances ?? 0) + (m.scriptedAnimations ?? 0) + m.cssAnimations + (m.styled > 1 ? m.styled : 0);
+  out.push(`- Motion, during load and one scroll through the page: ${m.entrances ?? "?"} entrance-like animation(s) or opacity/transform transition(s), ${m.scriptedAnimations ?? "?"} Web Animations, ${m.styled ?? "?"} element(s) moved or faded by script; ${m.started ?? "?"} transition(s) ran in all (${(m.startedProps ?? []).join(", ") || "none"}). Transitions are declared on ${m.transitions} element(s) (${m.transitionProps.join(", ") || "none"}) for hover and state changes.${entrances ? "" : " Nothing enters or reveals on load or scroll: the page is static apart from hover and state changes."}`);
+  return out;
+}
+
+export async function critique(dir, rawRoute, { url } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const session = path.join(root(dir, route), stamp());
+  fs.mkdirSync(path.join(session, "sections"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+
+  const { shot, widths, devices, title, refRows, principles } = await withBrowser(dir, { url }, async ({ base, browser }) => {
+    // Its principles pass is replaced by the section-aware one below.
+    const shot = await shoot(dir, route, { url: base, principles: false });
+    const widths = {};
+    const principles = {};
+    let devices = null;
+    let title = "";
+    for (const w of [1440, 390]) {
+      const { page, ctx } = await openPage(browser, base, route, { width: w, init: MOTION_INIT });
+      const sections = await findSections(page);
+      widths[w] = await cropSections(page, sections, path.join(session, "sections"), `w${w}`);
+      principles[w] = await measurePrinciples(page, { sections }).catch(() => null);
+      if (w === 1440) {
+        await shootFull(page, path.join(session, "full-1440.png"));
+        devices = await page.evaluate(`(${devicesScript})(${JSON.stringify(sections)})`);
+        title = await page.title();
+      }
+      await ctx.close();
+    }
+    // References from the library for each section's kind, and for logo rows found inside sections.
+    const { searchLibrary } = await import("./library.mjs");
+    const used = new Set();
+    const refRows = [];
+    const kinds = widths[1440].map((s, i) => ({ label: `Section ${s.index} · ${s.name.slice(0, 40)}`, kind: sectionKind(s, { first: i === (widths[1440][0]?.tag === "header" ? 1 : 0), media: devices.media.some((m) => m.section === s.index) }) }));
+    for (const r of devices.logoRows) kinds.push({ label: `Logo row in section ${r.section}`, kind: "logo cloud" });
+    for (const k of kinds) {
+      const refs = searchLibrary(k.kind, { n: 6, preferWhole: true }).filter((r) => !used.has(r.id) && fs.existsSync(path.join(LIB_DIR, "thumbs", `${r.id}.jpg`))).slice(0, 3);
+      refs.forEach((r) => used.add(r.id));
+      if (refs.length) refRows.push({ ...k, refs });
+    }
+    // All sections at 1440 in one image, for agents that take images inline.
+    await contactSheet(browser, widths[1440].map((s) => ({ label: `Section ${s.index} · ${s.name.slice(0, 70)}`, cells: [{ file: s.file }] })), path.join(session, "sections.png"), { cell: 960, maxCell: 900 });
+    if (refRows.length) {
+      let n = 0;
+      for (const row of refRows) for (const r of row.refs) r.n = `R${++n}`;
+      await contactSheet(browser, refRows.map((row) => ({ label: `${row.label}: ${row.kind}`, cells: row.refs.map((r) => ({ caption: `${r.n} · ${r.source}`, file: path.join(LIB_DIR, "thumbs", `${r.id}.jpg`) })) })), path.join(session, "references.png"), { cell: 360, maxCell: 240 });
+    }
+    return { shot, widths, devices, title, refRows, principles };
+  });
+
+  const sections = widths[1440].map((s) => ({ ...s, crops: Object.fromEntries(Object.entries(widths).map(([w, list]) => [w, list.find((x) => x.index === s.index)?.file ?? list.find((x) => x.name === s.name)?.file ?? null])) }));
+  const kind = screenWords(route, sections.map((s) => s.name), title);
+  fs.writeFileSync(path.join(session, "sections.json"), JSON.stringify({ route, title, kind, sections, at390: widths[390], devices, references: refRows.map((r) => ({ label: r.label, kind: r.kind, refs: r.refs.map((x) => ({ n: x.n, id: x.id, source: x.source, url: x.url, license: x.license, thumb: slash(path.join(LIB_DIR, "thumbs", `${x.id}.jpg`)) })) })) }, null, 1));
+  fs.writeFileSync(path.join(session, "shoot.md"), shot.report);
+  fs.writeFileSync(path.join(session, "principles.json"), JSON.stringify(principles, null, 1));
+  // shoot's own principles block is replaced by the section-aware one in the sheet.
+  // From shoot, only what it found wrong (its facts repeat the principles' facts) and the originality notes.
+  const shootLines = shot.report
+    .replace(/### Principles[\s\S]*?(?=\n## |$)/g, "")
+    .split(/\n(?=## )/)
+    .flatMap((block) => {
+      const head = block.match(/^## (.+)/)?.[1] ?? "";
+      const lines = block.split("\n").filter((l) => (/originality/i.test(head) ? /^- / : /^- ⚠/).test(l));
+      return lines.length ? [`${/^\d+px$/.test(head) ? `At ${head}:` : `${head}:`}`, ...lines.map(clip)] : [];
+    });
+  const factLine = /^- (Hierarchy|Alignment|Spacing|Type|Surfaces|Colour|Density)/;
+
+  // The sheet is a summary (about 12KB): the crops, the facts, the top principle findings and the taste.
+  // The rubric (titles and detections, and the full entries with fixes), every principle finding, the
+  // review guide and shoot's report go in files next to it, opened when needed.
+  const rubric = craftRubric(null, { compact: true });
+  const full = craftRubric();
+  if (full.text) fs.writeFileSync(path.join(session, "rubric.md"), full.text);
+  if (rubric.text) fs.writeFileSync(path.join(session, "rubric-compact.md"), `# Rubric (kb/craft): each item's title and how to detect it\nFlag an item only when its detection is met, and quote the element. Fixes: rubric.md.\n\n${rubric.text}`);
+  const rubricIndex = rubric.files.map((f) => {
+    const src = fs.readFileSync(f, "utf8");
+    const t = src.match(/^title:\s*(.+)$/m)?.[1].replace(/^["']|["']$/g, "") ?? src.match(/^#\s+(.+)$/m)?.[1] ?? path.basename(f, ".md");
+    return `${t} (${path.basename(f, ".md")})`;
+  });
+  fs.writeFileSync(path.join(session, "principles.md"), [principles[1440] && principlesReport(principles[1440], { max: 99 }).join("\n"), principles[390] && principlesReport(principles[390], { max: 99 }).join("\n")].filter(Boolean).join("\n\n"));
+  fs.writeFileSync(path.join(session, "review-guide.md"), REVIEW_GUIDE);
+  const taste = tasteFor(kind, { sections: 1, lean: true, project: path.basename(path.resolve(dir)) });
+  const past = pastDisagreements(8);
+  const findings = path.join(session, "findings.json");
+  const cropDir = path.join(session, "sections");
+  // A finding already listed at 1440 (same check, same section) isn't repeated at 390.
+  const key = (l) => {
+    const id = l.match(/\[(P\d+)\]/)?.[1];
+    return id ? `${id}|${l.match(/section (\d+)/)?.[1] ?? ""}` : null;
+  };
+  const at1440 = new Set((principles[1440] ? principlesReport(principles[1440], { max: 5 }) : []).map(key).filter(Boolean));
+  const seen1440 = (l) => at1440.has(key(l));
+  const sheet = [
+    `# Critique: ${route}${title ? ` (${title})` : ""}`,
+    "",
+    "You are a senior product designer reviewing this page for the person who owns it. Write specific findings, not a score: name the element, what is wrong, why it matters, and the exact fix (values, tokens, components, copy). Include ideas, not only defects: where a section is generic or forgettable, say what would make it memorable.",
+    "",
+    "## Look at it",
+    `- Full page: ${slash(path.join(session, "full-1440.png"))} (1440) and ${shot.files.filter((f) => /w390-full\.png$/.test(f)).map(slash).join("") || "the 390 shot from palate shoot"} (390)`,
+    `- All sections at 1440 in one image: ${slash(path.join(session, "sections.png"))}`,
+    `- Sections (open every crop, 1440 first, then 390; all in ${slash(cropDir)}/):`,
+    ...sections.map((s) => `  ${s.index}. **${s.name}** \`${s.selector}\`${s.sticky ? " (sticky)" : ""}: ${Object.entries(s.crops).filter(([, f]) => f).map(([, f]) => path.basename(f)).join(" · ")}`),
+    statesLine(dir, route),
+    refRows.length ? `- References from palate's library for each kind of section: ${slash(path.join(session, "references.png"))} (numbers R1…; sources in sections.json). Point to one when an idea would borrow from it.` : "",
+    "",
+    "## Whole page (measured at 1440)",
+    ...deviceLines(devices),
+    "",
+    "## Principles (the top findings, measured; confirm on the crops before reporting)",
+    ...(principles[1440] ? principlesReport(principles[1440], { max: 5 }).slice(1).map(clip) : ["- Not measured at 1440."]),
+    ...(principles[390] ? ["At 390 (only what 1440 didn't already show):", ...principlesReport(principles[390], { max: 2 }).slice(1).filter((l) => !factLine.test(l) && !/^- …and/.test(l) && !seen1440(l)).map(clip)] : []),
+    `Every finding at both widths, with selectors: ${slash(path.join(session, "principles.md"))}`,
+    "",
+    "## Measured by palate shoot (problems only; the full report: shoot.md next to this sheet)",
+    shootLines.join("\n") || "- No measurable problems.",
+    "",
+    "## The user's taste for this kind of screen",
+    taste || "No taste profile yet: judge clarity first, with one crafted touch at most.",
+    past.length ? `\n## The user disagreed with these before (do not raise them again)\n${past.map((p) => `- ${p.what}${p.note ? ` (their note: ${p.note})` : ""}`).join("\n")}` : "",
+    "",
+    "## How to review",
+    `The whole page first, then each section at both widths. The questions, in full: ${slash(path.join(session, "review-guide.md"))}.`,
+    "- Page: [page.1] job, [page.2] repeated devices, [page.3] the product shown working or only pictured, [page.4] motion, [page.5] rhythm, [page.6] memorability.",
+    "- Each section: [section.1] job (sells or documents?), [section.2] hierarchy, [section.3] type, [section.4] spacing and alignment, [section.5] legibility at a glance, [section.6] details and states, [section.7] phone, [section.8] one idea if it's generic.",
+    "",
+    "## Rubric (kb/craft)",
+    rubric.text ? `Open ${slash(path.join(session, "rubric-compact.md"))} (each item's title and detection) and check the page against it; fixes are in ${slash(path.join(session, "rubric.md"))}. Flag an item only when its detection is met, and quote the element. It covers: ${rubricIndex.join(", ")}.` : "No craft checklists installed (kb/craft is empty). Use the review questions above.",
+    "",
+    "## Write the findings",
+    `Write JSON to ${slash(findings)}:`,
+    "```json",
+    JSON.stringify(
+      {
+        route,
+        findings: [
+          { id: "F1", section: "2", severity: "high", what: "What is wrong, naming the element", why: "Why it matters to this page's job or reader", fix: "The concrete change: values, components, copy", rubric: "page.2" },
+          { id: "F2", section: "page", severity: "idea", what: "Where the page is generic or forgettable", why: "…", fix: "The idea, concretely, and the reference it borrows from (e.g. R3)", rubric: "page.6", width: 1440 },
+        ],
+      },
+    ).replace(/\{"id"/g, '\n  {"id"'),
+    "```",
+    "- section: the section number above, or \"page\" for a whole-page finding.",
+    "- severity: high (hurts the page's job, or a visible bug) · medium (a designer would notice) · low (polish) · idea (not wrong, could be memorable).",
+    "- rubric: the item it comes from, e.g. page.2, section.5, or a kb/craft id (M16, D01, …). width: 1440 or 390 when it only shows at one width.",
+    "- Aim for 8–20 findings, most important first. Whole-page findings when devices repeat. At least one idea for every section that is generic. Skip anything the taste profile says the user likes, and anything they disagreed with before.",
+    "",
+    `Then run: palate critique --findings ${slash(findings)}`,
+    "It opens a review board in the user's browser; they agree or disagree with each finding. Then: palate fix " + route,
+  ]
+    .filter((l) => l !== "")
+    .join("\n")
+    .replace(/\n(#{2,3} )/g, "\n\n$1");
+  fs.writeFileSync(path.join(session, "sheet.md"), sheet);
+  return { sheet: `${sheet}\n\n(Sheet saved to ${slash(path.join(session, "sheet.md"))})`, session, sections, findings, images: [path.join(session, "sections.png"), ...(refRows.length ? [path.join(session, "references.png")] : [])] };
+}
+
+// Reads and normalises a findings file. Accepts a few common aliases so a slightly-off file still loads.
+export function loadFindings(file) {
+  const raw = readJson(file, null);
+  if (!raw) throw new Error(`Could not read findings JSON from ${file}`);
+  const list = Array.isArray(raw) ? raw : raw.findings;
+  if (!list?.length) throw new Error(`No findings in ${file}. Expected {"route": "/", "findings": [{ id, section, severity, what, why, fix, rubric }]}`);
+  const sev = (s) => {
+    const v = String(s ?? "").toLowerCase();
+    return SEVERITIES.includes(v) ? v : /crit|block|major/.test(v) ? "high" : /minor|polish|nit/.test(v) ? "low" : /idea|sugg|opportun/.test(v) ? "idea" : "medium";
+  };
+  const findings = list.map((f, i) => {
+    const what = f.what ?? f.issue ?? f.problem ?? f.title;
+    const fix = f.fix ?? f.suggestion ?? f.change;
+    if (!what || !fix) throw new Error(`Finding ${f.id ?? i + 1} needs "what" and "fix".`);
+    return { id: String(f.id ?? `F${i + 1}`), section: String(f.section ?? "page"), severity: sev(f.severity), what, why: f.why ?? f.reason ?? "", fix, rubric: f.rubric ?? "", width: f.width ? Number(f.width) : null };
+  });
+  return { route: raw.route ? normalizeRoute(raw.route) : null, findings };
+}
+
+// Which session a findings file belongs to: its own folder if it is a session, else the latest for its route.
+function sessionFor(dir, file, route) {
+  const own = path.dirname(path.resolve(file));
+  if (fs.existsSync(path.join(own, "sections.json"))) return own;
+  const s = latestCritique(dir, route);
+  if (!s) throw new Error(`No critique session found${route ? ` for ${route}` : ""}. Run: palate critique <route>`);
+  return s;
+}
+
+// The review board: a local page where the user agrees or disagrees with each finding. Saves as they go.
+export async function startBoard(dir, file, { open = true } = {}) {
+  const { route: given, findings } = loadFindings(file);
+  const session = sessionFor(dir, file, given);
+  const meta = readJson(path.join(session, "sections.json"), {});
+  const route = given ?? meta.route;
+  const target = path.join(session, "findings.json");
+  if (path.resolve(file) !== path.resolve(target)) fs.copyFileSync(file, target);
+  const reviewFile = path.join(session, "review.json");
+  const review = readJson(reviewFile, { verdicts: {} });
+  const save = () => fs.writeFileSync(reviewFile, JSON.stringify(review, null, 1));
+
+  const sections = meta.sections ?? [];
+  const sectionOf = (f) => {
+    const n = Number(String(f.section).match(/^\s*#?(\d+)/)?.[1]);
+    if (n) return sections.find((s) => s.index === n) ?? null;
+    const q = f.section.toLowerCase();
+    return q === "page" ? null : sections.find((s) => s.name.toLowerCase() === q) ?? sections.find((s) => s.name.toLowerCase().includes(q) || q.includes(s.name.toLowerCase())) ?? null;
+  };
+  const items = findings.map((f) => {
+    const s = sectionOf(f);
+    return { ...f, sectionIndex: s?.index ?? 0, sectionName: s?.name ?? "The whole page" };
+  });
+  const crops = {};
+  for (const s of sections) for (const [w, f] of Object.entries(s.crops ?? {})) if (f) crops[`${w}-${s.index}`] = f;
+  if (fs.existsSync(path.join(session, "full-1440.png"))) crops["1440-0"] = path.join(session, "full-1440.png");
+
+  let finish;
+  const done = new Promise((r) => (finish = r));
+  let finished = false;
+  const body = (req) => new Promise((r) => {
+    let b = "";
+    req.on("data", (c) => (b += c));
+    req.on("end", () => r(b ? JSON.parse(b) : {}));
+  });
+  const server = http.createServer(async (req, res) => {
+    const u = new URL(req.url, "http://x");
+    try {
+      if (u.pathname === "/") {
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        return res.end(fs.readFileSync(path.join(here, "board.html")));
+      }
+      if (u.pathname === "/api/state") {
+        res.writeHead(200, { "content-type": "application/json" });
+        return res.end(JSON.stringify({ route, title: meta.title ?? "", project: path.basename(dir), findings: items, crops: Object.keys(crops), verdicts: review.verdicts, finished }));
+      }
+      if (u.pathname === "/api/verdict" && req.method === "POST") {
+        const { id, verdict, note } = await body(req);
+        if (!items.some((f) => f.id === id)) throw new Error(`No finding ${id}`);
+        const v = (review.verdicts[id] ??= {});
+        if (verdict !== undefined) v.verdict = ["agree", "disagree"].includes(verdict) ? verdict : null;
+        if (note !== undefined) v.note = String(note).slice(0, 2000);
+        v.at = new Date().toISOString();
+        save();
+        res.writeHead(204);
+        return res.end();
+      }
+      if (u.pathname === "/api/done" && req.method === "POST") {
+        res.writeHead(204);
+        res.end();
+        if (!finished) {
+          finished = true;
+          setTimeout(finish, 200);
+        }
+        return;
+      }
+      const m = /^\/img\/(\d+)-(\d+)\.png$/.exec(u.pathname);
+      if (m && crops[`${m[1]}-${m[2]}`]) {
+        res.writeHead(200, { "content-type": "image/png" });
+        return fs.createReadStream(crops[`${m[1]}-${m[2]}`]).pipe(res);
+      }
+      res.writeHead(404);
+      res.end();
+    } catch (e) {
+      res.writeHead(400, { "content-type": "text/plain" });
+      res.end(String(e.message));
+    }
+  });
+  const port = await freePort();
+  await new Promise((r) => server.listen(port, "127.0.0.1", r));
+  const link = `http://localhost:${port}`;
+  if (open) openBrowser(link);
+  const result = done.then(() => {
+    server.close();
+    return report();
+  });
+  return { link, session, count: items.length, done: result };
+
+  function report() {
+    review.finishedAt = new Date().toISOString();
+    save();
+    fs.mkdirSync(TASTE_DIR, { recursive: true });
+    const lines = items.map((f) => ({ project: path.basename(dir), route, kind: meta.kind, id: f.id, section: f.sectionName, severity: f.severity, what: f.what, why: f.why, fix: f.fix, rubric: f.rubric, verdict: review.verdicts[f.id]?.verdict ?? null, note: review.verdicts[f.id]?.note ?? "", at: review.finishedAt }));
+    fs.appendFileSync(CRITIQUES, lines.map((l) => JSON.stringify(l)).join("\n") + "\n");
+    const by = (v) => items.filter((f) => (review.verdicts[f.id]?.verdict ?? null) === v);
+    const fmt = (f) => `- ${f.id} [${f.severity}] ${f.sectionName}: ${f.what}${review.verdicts[f.id]?.note ? `\n  the user's note: ${review.verdicts[f.id].note}` : ""}`;
+    return [
+      `# Critique of ${route}: the user's verdicts`,
+      "",
+      `Agreed: ${by("agree").length} · Disagreed: ${by("disagree").length} · Not marked: ${by(null).length}`,
+      by("agree").length ? `\n## Agreed\n${by("agree").map(fmt).join("\n")}` : "",
+      by("disagree").length ? `\n## Disagreed (the user does not consider these problems; leave them alone)\n${by("disagree").map(fmt).join("\n")}` : "",
+      by(null).length ? `\n## Not marked\n${by(null).map(fmt).join("\n")}` : "",
+      "",
+      `Saved to ${slash(reviewFile)} and the user's taste log (${slash(CRITIQUES)}).`,
+      `Next: palate fix ${route}   (a brief from the agreed findings, most severe first), then palate taste learn.`,
+    ]
+      .filter((l) => l !== "")
+      .join("\n");
+  }
+}
+
+// CLI: open the board, wait for the user, return their verdicts.
+export async function reviewFindings(dir, file, opts = {}) {
+  const b = await startBoard(dir, file, opts);
+  console.log(`Review board ready: ${b.link}  (${b.count} findings). Waiting for the user…`);
+  return b.done;
+}

package/src/loop/details.mjs

@@ -0,0 +1,225 @@
+// `palate details <route>`: a micro-component upgrade pass. Finds the generic small parts from the DOM
+// (page-details.js) and by interacting with the page (hover, keyboard focus, :active rules), crops each
+// one, and writes a brief that lists every part with its upgrade. Real content only.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { contactSheet, openPage, slugOf, stamp, withBrowser } from "../look.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { craftRubric, LIB_DIR, slash } from "./craft.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const detailsScript = fs.readFileSync(path.join(here, "..", "page-details.js"), "utf8").trim().replace(/;\s*$/, "");
+
+// What each kind of part should become.
+export const UPGRADES = {
+  avatar: "Use the real person's photo when the project has one (look in public/, content and data files). Otherwise a license-clean generated avatar seeded by the name, so each person always gets the same one: a soft two-stop gradient or a boring-avatars style shape (`boring-avatars` package, or a 20-line SVG), with initials only as a fallback. Never stock faces presented as customers, users or team.",
+  "brand-marks": "Use each brand's official mark in its own colours (Simple Icons ships official SVGs with brand hex colours, CC0; follow each brand's guidelines), 20–28px tall next to 14–15px names, or full-colour wordmarks without names. If the row stays one colour by choice, make it legible: marks at least 20px, colour at 4.5:1 or better against the background, not a pale grey. See the logo-cloud references below.",
+  inputs: "Style every control with the project's tokens: `appearance: none`, the project's radius and border, inherited font, a custom checkbox / radio / select arrow (or the project's component library's), a visible label (not a placeholder), and a clear :focus-visible ring.",
+  "empty-state": "Say what is empty and why, and offer the next action as a button (\"No invoices yet. Create your first invoice\"). Never show raw null, undefined or NaN: fix the data path.",
+  numbers: "Format with Intl.NumberFormat (thousands separators, currency, compact like 12.4k where precision doesn't matter), dates with Intl.DateTimeFormat or relative time, and `tabular-nums` on number columns only.",
+  emoji: "Replace with an icon from the project's own icon set (see palate context), or drop it. No emoji in UI copy.",
+  icons: "One icon family, one stroke width (e.g. Lucide at 1.5 or 2), consistent sizes (16 inline, 20 in buttons), aligned optically with the text.",
+  placeholder: "Replace with real content from the project. If none exists, leave the slot out or ask the user; never invent names, quotes or numbers.",
+  badges: "Keep the one or two badges that change a decision; turn the rest into plain metadata text, or group them behind one count.",
+  hover: "Add a hover state: a colour, background or underline shift, 150ms ease-out, inside `@media (hover: hover)` so touch screens don't get stuck states.",
+  focus: "Add a visible keyboard focus state: `:focus-visible` ring 2px, offset 2px, in the project's focus colour; never remove outlines without a replacement.",
+  pressed: "Add pressed feedback on buttons: `:active { scale: 0.97 }` (or a darker fill) over 100ms, disabled under reduced motion.",
+  meta: "Favicon: an icon file (Next: app/icon.svg or icon.png; elsewhere link rel=icon). apple-touch-icon 180×180. A social image 1200×630 made from the page's own headline and product (Next: app/opengraph-image.tsx with ImageResponse), og:title, meta description, twitter:card summary_large_image.",
+};
+
+// Hover, keyboard focus and :active rules on the page's interactive elements. A state counts when any
+// computed style that paints the element changes: colour, fills (including gradients and filter), borders,
+// shadows, text decoration, opacity, transforms, outline, on the element, its first children, or ::before/::after.
+export async function stateChecks(page) {
+  const count = await page.evaluate(() => {
+    const els = [...document.querySelectorAll("a[href], button, [role=button], input:not([type=hidden]), select, textarea, summary")].filter((e) => {
+      const r = e.getBoundingClientRect();
+      const cs = getComputedStyle(e);
+      return r.width > 4 && r.height > 4 && cs.visibility !== "hidden" && parseFloat(cs.opacity) > 0.05 && !e.closest(".sr-only");
+    });
+    els.slice(0, 28).forEach((e, i) => e.setAttribute("data-palate-i", String(i)));
+    return Math.min(els.length, 28);
+  });
+  const snap = (i) =>
+    page.evaluate((i) => {
+      const e = document.querySelector(`[data-palate-i="${i}"]`);
+      if (!e) return null;
+      const props = (c) => [c.color, c.backgroundColor, c.backgroundImage, c.backgroundSize, c.backgroundPosition, c.borderTopColor, c.borderRightColor, c.borderBottomColor, c.borderLeftColor, c.boxShadow, c.textShadow, c.textDecorationLine, c.textDecorationColor, c.textDecorationThickness, c.textUnderlineOffset, c.opacity, c.filter, c.backdropFilter, c.transform, c.scale, c.translate, c.rotate, c.outlineStyle, c.outlineWidth, c.outlineColor, c.outlineOffset, c.fill, c.stroke].join("|");
+      const pick = (el) => {
+        const pseudo = ["::before", "::after"].map((p) => getComputedStyle(el, p)).filter((c) => c.content && c.content !== "none" && c.content !== "normal").map((c) => `${props(c)}|${c.width}|${c.height}`);
+        return [props(getComputedStyle(el)), ...pseudo].join("~");
+      };
+      // A native control drawn by its label or a sibling (a transparent radio over a styled span) shows its
+      // states there.
+      const own = [e, ...e.querySelectorAll("*")].slice(0, 6);
+      const near = e.matches("input, select") ? [...(e.labels ?? []), e.closest("label"), e.nextElementSibling, e.previousElementSibling].filter((x) => x && !own.includes(x)) : [];
+      return [...own, ...near].map(pick).join("#");
+    }, i);
+  const describe = (i) =>
+    page.evaluate((i) => {
+      const e = document.querySelector(`[data-palate-i="${i}"]`);
+      // A live page can re-render and drop the element between steps.
+      if (!e) return null;
+      const r = e.getBoundingClientRect();
+      return { tag: e.tagName.toLowerCase(), text: (e.getAttribute("aria-label") || e.textContent || e.getAttribute("placeholder") || "").replace(/\s+/g, " ").trim().slice(0, 40), box: { x: Math.round(r.left + scrollX), y: Math.round(r.top + scrollY), width: Math.round(r.width), height: Math.round(r.height) }, button: e.matches("button, [role=button], input[type=submit]") || (getComputedStyle(e).backgroundColor !== "rgba(0, 0, 0, 0)" && e.matches("a")) };
+    }, i);
+  const base = [];
+  for (let i = 0; i < count; i++) base[i] = await snap(i);
+  // Disabled controls (disabled, aria-disabled, or in a disabled fieldset) have no hover or pressed state on purpose.
+  const off = await page.evaluate((count) => {
+    const out = [];
+    for (let i = 0; i < count; i++) {
+      const e = document.querySelector(`[data-palate-i="${i}"]`);
+      if (e && (e.matches(":disabled") || e.closest("[aria-disabled=true]"))) out.push(i);
+    }
+    return out;
+  }, count);
+  const noHover = [];
+  for (let i = 0; i < count; i++) {
+    if (off.includes(i)) continue;
+    const ok = await page.hover(`[data-palate-i="${i}"]`, { timeout: 1500 }).then(() => true).catch(() => false);
+    if (!ok) continue;
+    await page.waitForTimeout(260);
+    if ((await snap(i)) === base[i]) noHover.push(i);
+    await page.mouse.move(0, 0);
+    await page.waitForTimeout(60);
+  }
+  await page.evaluate(() => window.scrollTo({ top: 0, behavior: "instant" }));
+  const focused = new Map();
+  for (let k = 0; k < 45; k++) {
+    await page.keyboard.press("Tab");
+    await page.waitForTimeout(90);
+    const i = await page.evaluate(() => document.activeElement?.getAttribute("data-palate-i"));
+    if (i == null || focused.has(Number(i))) continue;
+    focused.set(Number(i), (await snap(Number(i))) !== base[Number(i)]);
+  }
+  const noFocus = [...focused].filter(([, changed]) => !changed).map(([i]) => i);
+  // Pressed: a CSS :active rule (nested rules included) that matches the button. Script-driven press feedback isn't seen.
+  const noPress = await page.evaluate((count) => {
+    const actives = [];
+    const walk = (rules, parent) => {
+      for (const r of rules) {
+        if (r.selectorText !== undefined) {
+          const full = r.selectorText.split(",").map((s) => (parent ? (s.includes("&") ? s.replace(/&/g, parent) : `${parent} ${s}`) : s)).join(",");
+          if (full.includes(":active")) actives.push(...full.split(",").filter((s) => s.includes(":active")).map((s) => s.replace(/:active/g, "").trim()));
+          if (r.cssRules?.length) walk(r.cssRules, full.split(",")[0]);
+        } else if (r.cssRules) walk(r.cssRules, parent);
+      }
+    };
+    for (const sh of document.styleSheets) {
+      try {
+        walk(sh.cssRules, null);
+      } catch {}
+    }
+    const out = [];
+    for (let i = 0; i < count; i++) {
+      const e = document.querySelector(`[data-palate-i="${i}"]`);
+      if (!e || !e.matches("button, [role=button], input[type=submit]") || e.matches(":disabled") || e.closest("[aria-disabled=true]")) continue;
+      if (!actives.some((s) => { try { return e.matches(s || "*") || [...e.querySelectorAll("*")].some((c) => c.matches(s)); } catch { return false; } })) out.push(i);
+    }
+    return out;
+  }, count);
+  const items = [];
+  for (const [kind, list] of [["hover", noHover], ["focus", noFocus], ["pressed", noPress]]) {
+    if (!list.length) continue;
+    const ds = (await Promise.all(list.map(describe))).filter(Boolean);
+    if (!ds.length) continue;
+    items.push({ kind, detail: `${list.length} ${kind === "pressed" ? "button(s) with no :active style" : kind === "hover" ? "element(s) that don't change on hover" : "element(s) with no visible keyboard focus"}: ${ds.slice(0, 6).map((d) => `<${d.tag}> "${d.text}"`).join(", ")}`, box: ds[0].box, selector: null, text: ds[0].text });
+  }
+  return { items, checked: count, tabbed: focused.size };
+}
+
+export async function details(dir, rawRoute, { url } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const session = path.join(dir, ".palate", "details", slugOf(route), stamp());
+  fs.mkdirSync(path.join(session, "crops"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+
+  const { items, states, phone, logoSheet } = await withBrowser(dir, { url }, async ({ base, browser }) => {
+    const { page, ctx } = await openPage(browser, base, route, { width: 1440 });
+    const found = await page.evaluate(`(${detailsScript})()`);
+    // Crop each part with some room around it.
+    const pageW = await page.evaluate(() => document.documentElement.clientWidth);
+    const pageH = await page.evaluate(() => document.documentElement.scrollHeight);
+    const crop = async (it, n) => {
+      if (!it.box || it.box.width < 2) return null;
+      const pad = 24;
+      const clip = { x: Math.max(0, it.box.x - pad), y: Math.max(0, it.box.y - pad), width: Math.min(pageW, it.box.width + pad * 2), height: Math.min(420, it.box.height + pad * 2, pageH - Math.max(0, it.box.y - pad)) };
+      clip.width = Math.min(clip.width, pageW - clip.x);
+      if (clip.width < 8 || clip.height < 8) return null;
+      const file = path.join(session, "crops", `${n}-${it.kind}.png`);
+      await page.screenshot({ path: file, fullPage: true, clip }).catch(() => null);
+      return fs.existsSync(file) ? file : null;
+    };
+    const items = found.map((it, i) => ({ ...it, n: `D${i + 1}` }));
+    for (const it of items) it.crop = await crop(it, it.n);
+    const states = await stateChecks(page);
+    for (const it of states.items) {
+      it.n = `D${items.length + 1}`;
+      it.crop = await crop(it, it.n);
+      items.push(it);
+    }
+    await ctx.close();
+    // The phone width only for what changes there: brand marks and inputs.
+    const m = await openPage(browser, base, route, { width: 390 });
+    const phone = (await m.page.evaluate(`(${detailsScript})()`)).filter((x) => ["brand-marks", "inputs"].includes(x.kind) && !items.some((y) => y.kind === x.kind && y.detail === x.detail));
+    await m.ctx.close();
+    if (items.length) await contactSheet(browser, [{ label: "", cells: items.filter((i) => i.crop).map((i) => ({ caption: `${i.n} · ${i.kind}`, file: i.crop })) }].map((r) => ({ ...r, cells: r.cells })), path.join(session, "details.png"), { cell: 320, maxCell: 260 });
+    // Logo clouds from the library, when brand marks need work.
+    let logoSheet = null;
+    if (items.some((i) => i.kind === "brand-marks")) {
+      const { searchLibrary } = await import("./library.mjs");
+      const refs = searchLibrary("logo cloud", { n: 6, preferWhole: true }).filter((r) => fs.existsSync(path.join(LIB_DIR, "thumbs", `${r.id}.jpg`))).slice(0, 4);
+      if (refs.length) {
+        logoSheet = path.join(session, "logo-cloud-refs.png");
+        await contactSheet(browser, [{ label: "Logo clouds from palate's library", cells: refs.map((r, i) => ({ caption: `L${i + 1} · ${r.source}`, file: path.join(LIB_DIR, "thumbs", `${r.id}.jpg`) })) }], logoSheet, { cell: 360, maxCell: 240 });
+      }
+    }
+    return { items, states, phone, logoSheet };
+  });
+
+  fs.writeFileSync(path.join(session, "details.json"), JSON.stringify({ route, items, phone, states: { checked: states.checked, tabbed: states.tabbed } }, null, 1));
+  const rubric = craftRubric(/detail|micro|component|finish/i);
+  const byKind = {};
+  for (const it of [...items, ...phone.map((p) => ({ ...p, n: "phone", detail: `${p.detail} (at 390px)` }))]) (byKind[it.kind] ??= []).push(it);
+  const order = ["placeholder", "empty-state", "brand-marks", "avatar", "inputs", "focus", "pressed", "hover", "numbers", "emoji", "icons", "badges", "meta"];
+  const kinds = Object.keys(byKind).sort((a, b) => order.indexOf(a) - order.indexOf(b));
+  const brief = [
+    `# Details: ${route}`,
+    "",
+    "A micro-component pass: upgrade the small parts that make a screen look generated. Keep the layout and the idea; change only the parts listed. Open the contact sheet first, then each crop.",
+    "",
+    items.length ? `Contact sheet: ${slash(path.join(session, "details.png"))} (numbers D1…; one crop per part in ${slash(path.join(session, "crops"))}).` : "",
+    "",
+    kinds.length ? "## What palate found, and the upgrade" : "## palate found no generic small parts. Look at the page yourself with the checklist below.",
+    ...kinds.flatMap((k) => [
+      "",
+      `### ${k}`,
+      ...byKind[k].map((it) => `- ${it.n}: ${it.detail}${it.selector ? ` \`${it.selector}\`` : ""}${it.text && !it.detail.includes(it.text) ? ` ("${it.text}")` : ""}${it.names ? ` · ${it.names.join(", ")}` : ""}${it.crop ? ` · crop ${slash(it.crop)}` : ""}`),
+      `Upgrade: ${UPGRADES[k] ?? "Bring it up to the project's standard."}`,
+      ...(k === "brand-marks" && logoSheet ? [`References: ${slash(logoSheet)} (logo clouds from palate's library: look at mark size, colour and spacing).`] : []),
+    ]),
+    "",
+    `Checked ${states.checked} interactive elements for hover and pressed states, and ${states.tabbed} reached by Tab for focus. Script-driven press feedback (e.g. Motion's whileTap) isn't seen by the pressed check; skip those.`,
+    "",
+    "## Also look for (not measurable)",
+    "- Icons that don't match the text weight or sit off the baseline; arrows that don't move on hover where the label says \"go\".",
+    "- Truncation without a tooltip, numbers without units, timestamps without a timezone or relative form.",
+    "- Loading and error states for every async part (skeletons shaped like the content, errors that say how to recover).",
+    "- Selection colour, scrollbar styling in scroll areas, caret colour in inputs, placeholder contrast.",
+    rubric.text ? `\n## Details checklist (kb/craft)\n${rubric.text}` : "",
+    "",
+    "## Rules",
+    "- Real content only. Avatars are real people the project has, or a generated, license-clean option seeded by the name; never stock faces presented as customers or team. Brand marks are the brands' official marks, used for the brands the project really works with.",
+    "- Use the project's tokens, icon set and components (palate context). Don't install packages without asking the user; a 20-line SVG often does the job.",
+    "- Keep changes scoped to the parts listed; no layout changes.",
+    "",
+    "## Verify",
+    `Run \`palate details ${route}\` again: each part you fixed should be gone from the list. Then \`palate shoot ${route}\` and look at the crops of what you changed.`,
+  ]
+    .filter((l, i, a) => !(l === "" && a[i - 1] === ""))
+    .join("\n");
+  fs.writeFileSync(path.join(session, "brief.md"), brief);
+  return `${brief}\n\n(Brief saved to ${slash(path.join(session, "brief.md"))})`;
+}