@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/matched.mjs

@@ -0,0 +1,26 @@
+// Which routes match the user's own design (palate match). Kept apart from match.mjs so the checks that must
+// step aside for a matched route (the similarity gate, the house-look check, the blueprint step, palate gate)
+// can ask without loading the browser code. A matched route's spec is the user's design, not palate's taste.
+import fs from "node:fs";
+import path from "node:path";
+
+const routeSlug = (route) => {
+  const r = String(route ?? "/").trim().replace(/\\/g, "/").replace(/\/{2,}/g, "/");
+  return (r.startsWith("/") ? r : `/${r}`).replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "") || "home";
+};
+
+export const matchRoot = (dir, route) => path.join(dir, ".palate", "match", routeSlug(route));
+
+// The route's match record ({ route, source, width, … }) when the user's design is its spec, else null.
+export function matchedRoute(dir, route) {
+  if (!dir || route == null) return null;
+  try {
+    const m = JSON.parse(fs.readFileSync(path.join(matchRoot(dir, route), "match.json"), "utf8"));
+    return m?.route ? m : null;
+  } catch {
+    return null;
+  }
+}
+
+// One line for reports that skip a taste check on a matched route.
+export const MATCHED_NOTE = (route) => `${route} is built from the user's own design (palate match): palate's taste checks don't apply. Its gate is palate match --check --route ${route}.`;

package/src/loop/myrefs.mjs

@@ -0,0 +1,151 @@
+// The user's own references: screenshots, image files or URLs they give palate. They come first in every
+// brief, shape the directions, and are kept in the user's personal library (~/.palate/refs) so later
+// designs can draw on them too. Each keeps the user's notes (what they like and dislike about it), and the
+// notes become rules tied to that reference. Nothing leaves the user's machine.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { PALATE_HOME } from "../catalog/store.mjs";
+import { acquireBrowser } from "../pool.mjs";
+import { readJson } from "./common.mjs";
+import { dropSource, kindTags, ruleFromRefNote } from "./rules.mjs";
+
+export const REFS_DIR = path.join(PALATE_HOME, "refs");
+const INDEX = path.join(REFS_DIR, "refs.json");
+const words = (s) => new Set(String(s ?? "").toLowerCase().match(/[a-z]{3,}/g) ?? []);
+
+export function listRefs() {
+  return readJson(INDEX, []);
+}
+
+const asList = (v) => (Array.isArray(v) ? v : v ? [v] : []).flatMap((x) => String(x).split(/\s*;\s*|\n+/)).map((x) => x.trim()).filter(Boolean);
+
+// Adds files or URLs to the personal library; returns their records (existing ones are reused). like / dislike:
+// what the user likes and dislikes about them, in their words; kept per reference and turned into rules tied to
+// it (rec.learned: [{ rule, added }]). kinds: the kinds of screen those rules apply to (default: from the job).
+export async function addRefs(sources, { note = "", job = "", like, dislike, kinds } = {}) {
+  fs.mkdirSync(REFS_DIR, { recursive: true });
+  const index = listRefs();
+  const out = [];
+  const likes = asList(like);
+  const dislikes = asList(dislike);
+  for (const src of sources.map((s) => s.trim()).filter(Boolean)) {
+    const isUrl = /^https?:\/\//i.test(src);
+    const id = crypto.createHash("sha1").update(isUrl ? src : path.resolve(src)).digest("hex").slice(0, 10);
+    let rec = index.find((r) => r.id === id);
+    const isNew = !rec;
+    if (!rec) {
+      rec = { id, kind: isUrl ? "url" : "image", source: src, files: [], note, job, added: new Date().toISOString() };
+      if (isUrl) {
+        const { capture } = await import("../capture.mjs");
+        const res = await capture(src, { widths: [1440], full: true });
+        for (const f of res.files) {
+          const dest = path.join(REFS_DIR, `${id}-${path.basename(f)}`);
+          fs.copyFileSync(f, dest);
+          rec.files.push(dest);
+        }
+        const m = res.measures?.[1440];
+        if (m) rec.measures = { headline: m.headline ? `${m.headline.size}px ${m.headline.family} ${m.headline.weight}, tracking ${m.headline.tracking}` : undefined, fonts: m.fonts, typeScale: m.typeScale, body: m.bodySize, textColours: m.textColors, backgrounds: m.backgrounds, radii: m.radii, contentWidth: m.contentWidth };
+      } else {
+        if (!fs.existsSync(src)) throw new Error(`Reference not found: ${src}`);
+        const dest = path.join(REFS_DIR, `${id}${path.extname(src) || ".png"}`);
+        fs.copyFileSync(src, dest);
+        rec.files.push(dest);
+      }
+      index.push(rec);
+    } else if (note && !rec.note.includes(note)) rec.note = `${rec.note} ${note}`.trim();
+    // The user's notes, kept per reference; each new one becomes rules tied to it.
+    const fresh = { like: likes.filter((l) => !(rec.likes ?? []).includes(l)), dislike: dislikes.filter((d) => !(rec.dislikes ?? []).includes(d)) };
+    if (fresh.like.length) rec.likes = [...(rec.likes ?? []), ...fresh.like];
+    if (fresh.dislike.length) rec.dislikes = [...(rec.dislikes ?? []), ...fresh.dislike];
+    const ruleKinds = kinds?.length ? kinds : refKinds(rec);
+    const learned = [...fresh.like.flatMap((l) => ruleFromRefNote(rec, "like", l, { kinds: ruleKinds })), ...fresh.dislike.flatMap((d) => ruleFromRefNote(rec, "dislike", d, { kinds: ruleKinds }))];
+    if (learned.length) rec.rules = [...new Set([...(rec.rules ?? []), ...learned.map((l) => l.rule.id)])];
+    out.push({ ...rec, isNew, learned });
+  }
+  fs.writeFileSync(INDEX, JSON.stringify(index, null, 2));
+  return out;
+}
+
+// The kinds of screen a reference's rules apply to: from the job it was given for, else every screen.
+function refKinds(rec) {
+  const tags = rec.job ? kindTags({ words: rec.job.slice(0, 200) }).filter((t) => t !== "marketing" && t !== "app") : [];
+  return tags.length ? tags : ["all"];
+}
+
+// Removes a reference, its files, and the rules that came only from its notes.
+export function removeRef(id) {
+  const index = listRefs();
+  const i = index.findIndex((r) => r.id === id || r.source === id);
+  if (i < 0) throw new Error(`No reference ${id}. palate refs mine lists them.`);
+  const [rec] = index.splice(i, 1);
+  for (const f of rec.files ?? []) if (f.startsWith(REFS_DIR)) fs.rmSync(f, { force: true });
+  fs.writeFileSync(INDEX, JSON.stringify(index, null, 2));
+  return { ref: rec, rules: dropSource(`ref:${rec.id}`) };
+}
+
+// What `palate refs add` (and the MCP tool) says: what was saved, the rules its notes became, and, when the
+// user gave no notes, the question to ask them.
+export function refsAddText(saved, { mcp = false } = {}) {
+  const out = [];
+  for (const r of saved) {
+    out.push(`Saved ${r.source} (${r.id})${r.isNew ? "" : r.learned?.length ? " (already saved: notes added)" : " (already saved)"}`);
+    for (const l of r.learned ?? []) out.push(`  ${l.added ? "New rule" : "Strengthened"} ${l.rule.id} [${l.rule.kinds.join(", ")}] ${l.rule.rule}  (${l.rule.check?.type === "judge" ? "the judge asks" : `measured: ${l.rule.check?.metric ?? l.rule.check?.selector}`})`);
+  }
+  const bare = saved.filter((r) => !r.likes?.length && !r.dislikes?.length);
+  if (bare.length)
+    out.push(
+      "",
+      `No notes yet for ${bare.map((r) => r.source).join(", ")}. Ask the user, for each reference: what do you like about it, and what don't you like? One short line each, in their words.`,
+      mcp ? "Then call palate_refs_add again with the same source and like / dislike: palate keeps the notes with the reference and turns them into rules." : `Then: palate refs add <source> --like "…" --dislike "…"   (palate keeps the notes with the reference and turns them into rules).`,
+    );
+  return out.join("\n");
+}
+
+// One line per reference for a brief: its number on the contact sheet, what the user likes and dislikes about
+// it (their words, and they beat everything else said about it), and what palate measured.
+export function refLines(records, { files = false } = {}) {
+  return records.map((r, i) => {
+    const notes = [r.likes?.length ? `likes: ${r.likes.join("; ")}` : null, r.dislikes?.length ? `dislikes: ${r.dislikes.join("; ")}` : null, r.note ? `note: ${r.note}` : null].filter(Boolean).join(" · ");
+    const m = r.measures;
+    const measured = m ? `measured: headline ${m.headline ?? "?"}; fonts ${(m.fonts ?? []).join(", ")}; type scale ${(m.typeScale ?? []).join(", ")}px; radii ${(m.radii ?? []).join(", ") || "none"}; content width ${m.contentWidth}px` : null;
+    const shot = files ? (r.files ?? []).find((x) => /fold|\.png$|\.jpe?g$|\.webp$/i.test(x)) : null;
+    return `- #U${i + 1} ${r.source}${notes ? `: ${notes}` : " (no notes from the user)"}${shot ? `\n  screenshot: ${String(shot).replace(/\\/g, "/")}` : ""}${measured ? `\n  ${measured}` : ""}`;
+  });
+}
+
+// The kind of screen a job is about; product names and filler words don't count.
+const SCREEN_WORDS = ["hero", "landing", "pricing", "features", "testimonials", "faq", "footer", "navigation", "dashboard", "table", "list", "settings", "team", "members", "billing", "invoices", "onboarding", "signup", "login", "profile", "checkout", "cart", "product", "docs", "documentation", "blog", "inbox", "chat", "calendar", "booking", "analytics", "report", "search", "empty", "modal", "form", "kanban", "notifications"];
+const screenWords = (s) => new Set([...words(s)].filter((w) => SCREEN_WORDS.includes(w.replace(/s$/, "")) || SCREEN_WORDS.includes(w)));
+
+// References the user gave earlier for the same kind of screen (or whose note mentions it).
+export function rememberedRefs(job, { exclude = [], limit = 2 } = {}) {
+  const q = screenWords(job);
+  return listRefs()
+    .filter((r) => !exclude.includes(r.id))
+    .map((r) => ({ r, score: [...screenWords(`${r.job} ${r.note} ${(r.likes ?? []).join(" ")}`)].filter((w) => q.has(w)).length }))
+    .filter((x) => x.score >= 1)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit)
+    .map((x) => x.r);
+}
+
+// A numbered contact sheet of the user's references (first screens), built with the browser palate already uses.
+export async function refSheet(records, out) {
+  const cells = records.map((r, i) => {
+    const f = r.files.find((x) => /fold|\.png$|\.jpe?g$|\.webp$/i.test(x)) ?? r.files[0];
+    const mime = /\.jpe?g$/i.test(f) ? "jpeg" : /\.webp$/i.test(f) ? "webp" : "png";
+    return `<figure><figcaption>#U${i + 1}</figcaption><img src="data:image/${mime};base64,${fs.readFileSync(f).toString("base64")}"></figure>`;
+  });
+  const { browser, release } = await acquireBrowser();
+  try {
+    const page = await browser.newPage({ viewport: { width: 1600, height: 900 } });
+    await page.setContent(`<!doctype html><body style="margin:0;background:#ecebe7;font:600 18px system-ui"><div id="g" style="display:grid;grid-template-columns:repeat(${Math.min(3, records.length)},500px);gap:14px;padding:14px">${cells.join("")}</div><style>figure{margin:0}figcaption{margin-bottom:6px}img{width:500px;max-height:340px;object-fit:cover;object-position:top;display:block;border:1px solid #c9c8c2}</style></body>`);
+    await page.locator("#g").screenshot({ path: out });
+    await page.close();
+  } finally {
+    await release();
+  }
+  fs.writeFileSync(out.replace(/\.png$/, ".json"), JSON.stringify(records.map((r, i) => ({ n: `U${i + 1}`, source: r.source, files: r.files.map((f) => f.replace(/\\/g, "/")), note: r.note, likes: r.likes ?? [], dislikes: r.dislikes ?? [] })), null, 1));
+  return out;
+}

package/src/loop/pick.mjs

@@ -0,0 +1,213 @@
+// `palate pick --name <loop>`: the user chooses, blind. Renders the loop's variants (only the judge's
+// survivors if `palate judge` ran), serves a local A/B picker, waits until every pair is answered, then
+// reports the ranking with the reasons the user tapped, and adds the picks to their taste log so palate
+// grows with them.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { freePort } from "../shoot.mjs";
+import { appendTaste, readJson, render, screenKind, sessionDir, variantRoutes, waitReady } from "./common.mjs";
+import { recordPick } from "./layouts.mjs";
+import { logLoop, loopTimeline, mark, tookLine } from "./timeline.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+// Opens a page in the user's default browser (PALATE_NO_OPEN=1 turns this off, e.g. in tests).
+export function openBrowser(url) {
+  if (process.env.PALATE_NO_OPEN) return;
+  const cmd = process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : process.platform === "darwin" ? ["open", [url]] : ["xdg-open", [url]];
+  try {
+    spawn(cmd[0], cmd[1], { detached: true, stdio: "ignore", windowsHide: true }).unref();
+  } catch {}
+}
+
+// ready: don't wait for the slowest builder; open as soon as this many variants are built (variants that land
+// later are left out). With a judge's result, later variants are added only if fewer than 4 survived it.
+export async function startPick(dir, name, { routes, url, open = true, pairsMode = false, ready } = {}) {
+  const session = sessionDir(dir, name);
+  const meta = readJson(path.join(session, "loop.json"), {});
+  const judged = readJson(path.join(session, "judge.json"), null);
+  mark(dir, name, "pick_start");
+  let list = routes?.length ? routes : judged?.keep ?? (ready ? await waitReady(dir, name, ready, { url }) : variantRoutes(dir, name));
+  if (!judged && !routes?.length) mark(dir, name, "build_done");
+  // Late variants fill the grid only when the judge left fewer than 4.
+  let late = [];
+  if (judged && !routes?.length && list.length < 4) {
+    const seen = new Set(readJson(path.join(session, "judge-key.json"), []).map((k) => k.route));
+    late = variantRoutes(dir, name).filter((r) => !seen.has(r) && !list.includes(r)).slice(0, 4 - list.length);
+    list = [...list, ...late];
+  }
+  // palate vary: the current section is one of the blind options.
+  if (meta.vary && !routes?.length && !list.includes(meta.vary.route)) list = [...list, meta.vary.route];
+  if (list.length < 2) throw new Error(`Need at least two variants to pick from; found ${list.length}. Variants are route files named ${name}-a1, ${name}-b1, …`);
+  const { full } = screenKind(name, meta.job);
+  // A varied section is shown in the page around it; whole screens as they are, reusing judge's renders
+  // where the route hasn't changed since.
+  const shots = meta.vary ? await (await import("./vary.mjs")).renderInContext(dir, list, meta.vary, path.join(session, "shots"), { url }) : await render(dir, list, path.join(session, "shots"), { full, url, reuse: [path.join(session, "judge")] });
+  const broken = shots.filter((s) => s.error);
+  const ok = shots.filter((s) => s.file);
+  if (ok.length < 2) throw new Error(`Only ${ok.length} variant(s) render. ${broken.map((b) => `${b.route}: ${b.error}`).join(" | ")}`);
+
+  // Blind: shuffled order, neutral ids. Grid mode shows them all at once; pairs mode asks every pair.
+  const ids = [...ok].sort(() => Math.random() - 0.5).map((s, i) => ({ id: `v${i + 1}`, ...s }));
+  const grid = !pairsMode;
+  const pairs = [];
+  for (let i = 0; i < ids.length; i++)
+    for (let j = i + 1; j < ids.length; j++) {
+      const [a, b] = Math.random() < 0.5 ? [ids[i], ids[j]] : [ids[j], ids[i]];
+      pairs.push({ id: `${a.id}-${b.id}`, a: a.id, b: b.id });
+    }
+  pairs.sort(() => Math.random() - 0.5);
+  const picksFile = path.join(session, "picks.jsonl");
+  fs.rmSync(picksFile, { force: true });
+
+  const answered = () => {
+    if (!fs.existsSync(picksFile)) return new Map();
+    const m = new Map();
+    for (const l of fs.readFileSync(picksFile, "utf8").split("\n").filter(Boolean)) {
+      const p = JSON.parse(l);
+      if (p.choice === "undo") m.delete(p.pair);
+      else m.set(p.pair, p);
+    }
+    return m;
+  };
+
+  let finish;
+  let chosen = null;
+  const done = new Promise((r) => (finish = r));
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://x");
+    if (u.pathname === "/") {
+      res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+      return res.end(fs.readFileSync(path.join(here, grid ? "grid.html" : "picker.html")));
+    }
+    if (u.pathname === "/api/state") {
+      res.writeHead(200, { "content-type": "application/json" });
+      return res.end(JSON.stringify(grid ? { title: meta.title ?? name, variants: ids.map((v) => ({ id: v.id })), chosen } : { title: meta.title ?? name, pairs, done: [...answered().keys()] }));
+    }
+    // One click in the grid: the winner beats every other variant (n-1 pairwise records, same format as pairs mode).
+    if (u.pathname === "/api/choose" && req.method === "POST") {
+      let b = "";
+      req.on("data", (c) => (b += c));
+      req.on("end", () => {
+        const { winner, reasons = [] } = JSON.parse(b || "{}");
+        chosen = winner ?? "none";
+        const lines = winner ? ids.filter((v) => v.id !== winner).map((v) => ({ pair: `${winner}-${v.id}`, a: winner, b: v.id, choice: "a", reasons, mode: "grid" })) : [{ pair: "none", choice: "none", reasons, mode: "grid" }];
+        fs.appendFileSync(picksFile, lines.map((l) => JSON.stringify(l)).join("\n") + "\n");
+        res.writeHead(204);
+        res.end();
+        setTimeout(finish, 300);
+      });
+      return;
+    }
+    if (u.pathname === "/api/pick" && req.method === "POST") {
+      let b = "";
+      req.on("data", (c) => (b += c));
+      req.on("end", () => {
+        fs.appendFileSync(picksFile, b.trim() + "\n");
+        res.writeHead(204);
+        res.end();
+        if (answered().size >= pairs.length) setTimeout(finish, 300);
+      });
+      return;
+    }
+    const m = /^\/img\/(v\d+)\.png$/.exec(u.pathname);
+    const v = m && ids.find((x) => x.id === m[1]);
+    if (v) {
+      res.writeHead(200, { "content-type": "image/png" });
+      return fs.createReadStream(v.file).pipe(res);
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  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);
+  mark(dir, name, "pick_opened");
+  const reused = ok.filter((s) => s.cached).length;
+  const summary = `${grid ? `${ids.length} variants side by side; one click picks the winner` : `${pairs.length} blind pairs from ${ids.length} variants`}${reused ? `; ${reused} reused from the judge's renders` : ""}${late.length ? `; ${late.length} added after the judge (${late.join(", ")})` : ""}`;
+  const finished = done.then(() => {
+    server.close();
+    return report();
+  });
+  return { link, summary, done: finished };
+
+  function report() {
+  // Ranking: wins, then reasons tallied on the winner's side.
+  const picks = [...answered().values()];
+  const wins = Object.fromEntries(ids.map((v) => [v.id, 0]));
+  const reasons = Object.fromEntries(ids.map((v) => [v.id, {}]));
+  let gridReasonsCounted = false;
+  for (const p of picks) {
+    const w = p.choice === "a" ? p.a : p.choice === "b" ? p.b : null;
+    if (!w) continue;
+    wins[w]++;
+    // A grid click writes one record per beaten variant; its reasons belong to the single click.
+    if (p.mode === "grid" && gridReasonsCounted) continue;
+    if (p.mode === "grid") gridReasonsCounted = true;
+    for (const r of p.reasons ?? []) reasons[w][r] = (reasons[w][r] ?? 0) + 1;
+  }
+  const ranking = ids.map((v) => ({ route: v.route, wins: wins[v.id], reasons: reasons[v.id] })).sort((a, b) => b.wins - a.wins);
+  const result = { name, job: meta.job, kind: screenKind(name, meta.job).kind, ranking, picks: picks.length, at: new Date().toISOString() };
+  fs.writeFileSync(path.join(session, "result.json"), JSON.stringify(result, null, 2));
+  const routeOf = (id) => ids.find((v) => v.id === id)?.route;
+  for (const p of picks) appendTaste({ project: path.basename(dir), dir: path.resolve(dir), loop: name, kind: result.kind, job: meta.job, winner: routeOf(p.choice === "a" ? p.a : p.choice === "b" ? p.b : null), a: routeOf(p.a), b: routeOf(p.b), choice: p.choice, reasons: p.reasons ?? [], directions: meta.directions });
+  if (ranking[0]?.wins) recordPick(dir, name, ranking[0].route);
+  mark(dir, name, "pick_done");
+  logLoop(dir, name, meta, { variants: ids.length, winner: ranking[0]?.wins ? ranking[0].route : null });
+  const took = tookLine(loopTimeline(dir, name));
+
+  const tally = (r) => Object.entries(r).sort((a, b) => b[1] - a[1]).map(([k, n]) => `${k} ×${n}`).join(", ");
+  if (meta.vary) {
+    const v = meta.vary;
+    const kept = ranking[0].route === v.route;
+    return [
+      `# ${name}: the user picked`,
+      "",
+      ...ranking.map((r, i) => `${i + 1}. ${r.route}${r.route === v.route ? " (the current section)" : ""}  ${r.wins}/${ids.length - 1} wins${Object.keys(r.reasons).length ? `  (why: ${tally(r.reasons)})` : ""}`),
+      broken.length ? `\nDid not render: ${broken.map((b) => `${b.route} (${b.error})`).join(", ")}` : "",
+      "",
+      kept ? `The user kept the current "${v.section}" section. Next:` : `Winner: ${ranking[0].route}. Next:`,
+      kept ? "1. Leave the page as it is." : `1. In ${v.file ? v.file.replace(/\\/g, "/") : "the page's source"}, replace the "${v.section}" section with the winner's section (the element marked data-palate-vary in ${ranking[0].route}'s file); drop the data-palate-vary attribute.`,
+      `2. Delete every variant route: ${(v.variants ?? []).map((f) => f.replace(/\\/g, "/")).join(", ") || list.filter((r) => r !== v.route).join(", ")}.`,
+      kept ? "3. Run: palate taste learn" : `3. Run: palate shoot ${v.route}, then palate taste learn`,
+    ]
+      .filter((l) => l !== "")
+      .join("\n");
+  }
+  return [
+    `# ${name}: the user picked`,
+    "",
+    ...ranking.map((r, i) => `${i + 1}. ${r.route}  ${r.wins}/${ids.length - 1} wins${Object.keys(r.reasons).length ? `  (why: ${tally(r.reasons)})` : ""}`),
+    broken.length ? `\nDid not render: ${broken.map((b) => b.route).join(", ")}` : "",
+    "",
+    `Winner: ${ranking[0].route}. Next:`,
+    ...(meta.stage === "sketch"
+      ? [
+          `1. Delete the other variants. Run: palate build --name ${name}   (the brief that builds the winning sketch out into the full page, then moves it to the real route)`,
+          `2. If a runner-up had a clearly better part (see its reasons), carry that one part over while building out.`,
+          `3. On the built-out winner only: palate shoot <route> (1440 and 390, principles), palate details, palate animate --check, then palate polish <route>`,
+          `4. Run: palate taste learn   (updates the user's taste profile from these picks)`,
+        ]
+      : [
+          `1. Make the winner the real screen (move its code to the target file or route), and delete the other variants.`,
+          `2. If a runner-up had a clearly better part (see its reasons), carry that one part over.`,
+          `3. Run: palate polish <route of the real screen>`,
+          `4. Run: palate taste learn   (updates the user's taste profile from these picks)`,
+        ]),
+    took ? `\n${took}` : undefined,
+  ]
+    .filter((l) => l !== undefined)
+    .join("\n");
+  }
+}
+
+// CLI: start the picker, wait for the user, return the report.
+export async function pick(dir, name, opts = {}) {
+  const s = await startPick(dir, name, opts);
+  console.log(`Picker ready: ${s.link}  (${s.summary}). Waiting…`);
+  return s.done;
+}

package/src/loop/picker.html

@@ -0,0 +1,118 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>palate pick</title>
+<link rel="icon" href="data:,">
+<style>
+  :root { --bg: #f4f4f2; --fg: #191917; --muted: #6a6964; --line: #dcdbd5; --card: #ffffff; --accent: #191917; --on-accent: #ffffff; --ring: #3b6cff; }
+  @media (prefers-color-scheme: dark) { :root:not([data-theme="light"]) { --bg: #141413; --fg: #ecebe6; --muted: #9c9b94; --line: #2c2b28; --card: #1c1c1a; --accent: #ecebe6; --on-accent: #141413; } }
+  :root[data-theme="dark"] { --bg: #141413; --fg: #ecebe6; --muted: #9c9b94; --line: #2c2b28; --card: #1c1c1a; --accent: #ecebe6; --on-accent: #141413; }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; }
+  body { margin: 0; background: var(--bg); color: var(--fg); font: 14px/1.45 system-ui, -apple-system, "Segoe UI", sans-serif; display: grid; grid-template-rows: auto 1fr auto; }
+  header { display: flex; align-items: center; gap: 16px; padding: 10px 16px; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
+  b { font-weight: 600; }
+  .muted { color: var(--muted); }
+  .bar { flex: 1; height: 4px; background: var(--line); border-radius: 2px; overflow: hidden; max-width: 280px; min-width: 120px; }
+  .bar i { display: block; height: 100%; background: var(--fg); width: 0; transition: width .2s ease-out; }
+  main { min-height: 0; padding: 12px 16px; display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
+  .pane { display: grid; grid-template-rows: auto 1fr; min-height: 0; background: var(--card); border: 1px solid var(--line); border-radius: 8px; overflow: hidden; }
+  .pane h2 { margin: 0; padding: 8px 12px; font-size: 13px; font-weight: 600; border-bottom: 1px solid var(--line); }
+  .scroll { overflow: auto; min-height: 0; }
+  .pane img { width: 100%; display: block; }
+  .flash { outline: 3px solid var(--ring); outline-offset: -3px; }
+  footer { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; padding: 10px 16px; border-top: 1px solid var(--line); }
+  button { font: inherit; border: 1px solid var(--line); background: var(--card); color: var(--fg); border-radius: 6px; padding: 7px 12px; cursor: pointer; }
+  button:hover { border-color: var(--muted); }
+  button.primary { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+  button:focus-visible { outline: 2px solid var(--ring); outline-offset: 1px; }
+  kbd { font: 11px ui-monospace, monospace; border: 1px solid var(--line); border-bottom-width: 2px; border-radius: 4px; padding: 0 4px; margin-left: 6px; color: var(--muted); }
+  .chip { padding: 4px 9px; border-radius: 999px; font-size: 13px; }
+  .chip[aria-pressed="true"] { background: var(--accent); color: var(--on-accent); border-color: var(--accent); }
+  .chip[aria-pressed="true"] kbd { color: inherit; border-color: currentColor; }
+  .done { grid-column: 1 / -1; display: grid; place-items: center; text-align: center; }
+  @media (max-width: 800px) { main { grid-template-columns: 1fr; } }
+</style>
+</head>
+<body>
+<header>
+  <b>Which is the better design?</b>
+  <span class="muted" id="title"></span>
+  <span style="flex:1"></span>
+  <span class="muted" id="count"></span>
+  <div class="bar"><i id="progress"></i></div>
+</header>
+<main id="main"></main>
+<footer>
+  <button data-c="a" class="primary">A is better<kbd>←</kbd></button>
+  <button data-c="tie">About the same<kbd>↓</kbd></button>
+  <button data-c="both-bad">Both bad<kbd>↑</kbd></button>
+  <button data-c="b" class="primary">B is better<kbd>→</kbd></button>
+  <span class="muted">Why? (optional)</span>
+  <button class="chip" data-why="calmer" aria-pressed="false">calmer<kbd>1</kbd></button>
+  <button class="chip" data-why="clearer" aria-pressed="false">clearer<kbd>2</kbd></button>
+  <button class="chip" data-why="more useful" aria-pressed="false">more useful<kbd>3</kbd></button>
+  <button class="chip" data-why="more crafted" aria-pressed="false">more crafted<kbd>4</kbd></button>
+  <button class="chip" data-why="better type" aria-pressed="false">better type<kbd>5</kbd></button>
+  <button class="chip" data-why="richer content" aria-pressed="false">richer content<kbd>6</kbd></button>
+  <button class="chip" data-why="less clutter" aria-pressed="false">less clutter<kbd>7</kbd></button>
+  <button id="undo">Undo<kbd>Z</kbd></button>
+</footer>
+<script>
+  const $ = (id) => document.getElementById(id);
+  let S, queue = [], cur = null, hist = [], shown = 0, saving = Promise.resolve();
+  const chips = [...document.querySelectorAll(".chip")];
+  const post = (rec) => { saving = saving.then(() => fetch("/api/pick", { method: "POST", body: JSON.stringify(rec) })).catch(() => alert("Could not save. Is palate pick still running?")); };
+  async function load() {
+    S = await (await fetch("/api/state")).json();
+    $("title").textContent = S.title;
+    const done = new Set(S.done);
+    queue = S.pairs.filter((p) => !done.has(p.id));
+    cur = queue.shift();
+    render();
+  }
+  function render() {
+    const total = S.pairs.length, left = queue.length + (cur ? 1 : 0);
+    $("count").textContent = `${total - left} of ${total}`;
+    $("progress").style.width = `${((total - left) / total) * 100}%`;
+    chips.forEach((b) => b.setAttribute("aria-pressed", "false"));
+    if (!cur) { $("main").innerHTML = '<div class="done"><div><h2>All picked. Thank you.</h2><p class="muted">You can close this tab; palate has your choice and your reasons.</p></div></div>'; return; }
+    $("main").innerHTML = `<section class="pane" id="paneA"><h2>A</h2><div class="scroll"><img alt="Design A" src="/img/${cur.a}.png"></div></section><section class="pane" id="paneB"><h2>B</h2><div class="scroll"><img alt="Design B" src="/img/${cur.b}.png"></div></section>`;
+    shown = performance.now();
+  }
+  function pick(choice) {
+    if (!cur) return;
+    const reasons = chips.filter((b) => b.getAttribute("aria-pressed") === "true").map((b) => b.dataset.why);
+    post({ pair: cur.id, a: cur.a, b: cur.b, choice, reasons, ms: Math.round(performance.now() - shown) });
+    const pane = choice === "a" ? $("paneA") : choice === "b" ? $("paneB") : null;
+    if (pane) pane.classList.add("flash");
+    hist.push(cur);
+    setTimeout(() => { cur = queue.shift(); render(); }, pane ? 90 : 0);
+  }
+  function undo() {
+    const last = hist.pop(); if (!last) return;
+    post({ pair: last.id, a: last.a, b: last.b, choice: "undo" });
+    if (cur) queue.unshift(cur);
+    cur = last; render();
+  }
+  const toggle = (b) => b.setAttribute("aria-pressed", String(b.getAttribute("aria-pressed") !== "true"));
+  chips.forEach((b) => (b.onclick = () => toggle(b)));
+  document.querySelectorAll("[data-c]").forEach((b) => (b.onclick = () => pick(b.dataset.c)));
+  $("undo").onclick = undo;
+  document.addEventListener("keydown", (e) => {
+    const k = e.key;
+    if (k === "ArrowLeft") pick("a");
+    else if (k === "ArrowRight") pick("b");
+    else if (k === "ArrowDown") pick("tie");
+    else if (k === "ArrowUp") pick("both-bad");
+    else if (/^[1-7]$/.test(k)) toggle(chips[Number(k) - 1]);
+    else if (k === "z" || k === "Z" || k === "Backspace") undo();
+    else return;
+    e.preventDefault();
+  });
+  load();
+</script>
+</body>
+</html>