@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/explore.mjs

@@ -0,0 +1,219 @@
+// How a loop stays varied: the structures (archetypes) a loop can assign, directions generated from the
+// user's references and from the library's style clusters for this job, the choice of directions (what won
+// first, one slot that explores something this user has never seen for this kind of screen), and references
+// split so no two directions share one.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TASTE_DIR, readJson } from "./common.mjs";
+import { pastGenerated, seenDirections } from "./layouts.mjs";
+import { listRefs } from "./myrefs.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+// Structures. Each has two forms so the two variants of one direction differ structurally too.
+export const ARCHETYPES = {
+  page: [
+    { id: "split", name: "Split hero", brief: "The first screen splits in two: headline, one line and the action on one side; the real product on the other, at a size you can read.", forms: ["text left, the product right and allowed to bleed off the right edge", "the product left and larger (about 7/12), text right, a thin proof strip spanning both underneath"] },
+    { id: "centred", name: "Centred stack", brief: "A centred headline, the action directly under it, then the product full width below, all on one axis.", forms: ["the product in one framed window under the action", "the product as a row of real outputs side by side, no window frame"] },
+    { id: "fullbleed", name: "Full-bleed product", brief: "The main content (the product, its real output, the plans) fills the first screen edge to edge; the headline is a compact block on or beside it.", forms: ["the headline in a compact panel over one corner of the content", "the headline in a slim band above an edge-to-edge strip of the content"] },
+    { id: "editorial", name: "Editorial grid", brief: "A type-led, multi-column grid like a well-made publication: a large headline spanning most columns, facts and captions in narrow columns, ruled or numbered sections.", forms: ["a 12-column grid: headline across 8, a narrow column of facts on the right", "three ruled columns of numbered entries under a full-width headline"] },
+    { id: "asymmetric", name: "Asymmetric", brief: "An off-centre composition: oversized type anchored to one side, content offset to a strong vertical line, a sticky index or side column while sections scroll.", forms: ["a sticky left index of section names, content scrolling on the right", "an oversized headline on the left, everything else starting at a 5/12 offset"] },
+    { id: "bento", name: "Bento overview", brief: "Right after a short headline, a grid of unequal tiles, each holding one real part of the content shown for real; tile size follows importance.", forms: ["one large tile and four small ones", "a 2-row mosaic with one tall tile at the side"] },
+  ],
+  app: [
+    { id: "full-width", name: "Main object full width", brief: "The main object (table, list, board, plans) takes the full width; filters and summaries sit in one slim bar above it.", forms: ["a single full-width table or list with a summary strip that doubles as a filter", "the main object grouped into labelled sections, each with its own totals"] },
+    { id: "master-detail", name: "List + detail", brief: "A scannable list on one side, the selected item's detail on the other, both visible at once.", forms: ["list left (about 5/12), detail right", "a compact list across the top, the selected item's detail filling the space below"] },
+    { id: "rail", name: "Main + summary rail", brief: "The main object with a narrow rail of summaries, quick filters or next actions beside it.", forms: ["rail on the right with live summaries", "rail on the left with quick filters and counts"] },
+    { id: "columns", name: "Columns / board", brief: "Items laid out in side-by-side columns (by stage, step or group), so the whole state reads at a glance.", forms: ["equal columns, one per stage or step", "columns of different widths, the active one widest"] },
+    { id: "document", name: "Document flow", brief: "One readable column, sections stacked like a document, controls inline where they apply.", forms: ["a single centred column with inline controls", "a column with a sticky outline beside it"] },
+    { id: "cards", name: "Card overview", brief: "A grid of equal cards, each a complete record or step with its own action.", forms: ["a 3-across grid of working cards", "a 2-across grid of larger cards with a progress or status strip on top"] },
+  ],
+};
+export const archetypesFor = (kind) => ARCHETYPES[kind === "app" ? "app" : "page"];
+
+// Phrases for the library's style tags; pairs of tags that co-occur in this job's references make a direction.
+const STYLE = {
+  "editorial serif typography": "a serif display face set large, with an editorial rhythm",
+  "bold large typography": "very large, heavy headline type as the main graphic element",
+  photography: "real photography from the project as a major surface",
+  "dark theme": "a dark canvas with light type",
+  "dense information": "dense, information-rich panels where density is the content",
+  monochrome: "a monochrome palette, contrast from value alone",
+  "soft shadows": "soft, layered shadows for depth",
+  "warm tones": "warm off-whites and earthy tones",
+  playful: "playful shapes and small moments of delight",
+  "rounded corners": "generous rounded corners",
+  "sharp corners": "square corners and hairline rules",
+  monospace: "monospace type for data, labels and numbers",
+  minimal: "radical reduction: few elements, each exact",
+  outlined: "outlined, line-drawn components instead of filled ones",
+  spacious: "generous spacing",
+  illustration: "one custom illustration drawn from the product's domain",
+  colorful: "a confident multi-colour palette used with discipline",
+  friendly: "friendly, approachable forms and copy",
+  enterprise: "sober, enterprise-grade structure",
+};
+const CLASH = [["dark theme", "light theme"], ["rounded corners", "sharp corners"], ["monochrome", "colorful"], ["dense information", "spacious"], ["dense information", "minimal"], ["playful", "enterprise"]];
+const clash = (a, b) => CLASH.some(([x, y]) => (a === x && b === y) || (a === y && b === x));
+const slug = (s) => s.replace(/[^a-z]+/gi, "-").toLowerCase();
+const cap = (s) => s[0].toUpperCase() + s.slice(1);
+
+export function baseDirections() {
+  return readJson(path.join(here, "directions.json"), []);
+}
+
+// Directions from the style tags that cluster in this job's library results. Skips pairs a base direction
+// already stands for.
+export function libraryDirections(pool) {
+  const base = baseDirections();
+  const pairs = new Map();
+  for (const r of pool) {
+    const tags = r.tags.filter((t) => STYLE[t]);
+    for (let i = 0; i < tags.length; i++)
+      for (let j = i + 1; j < tags.length; j++) {
+        if (clash(tags[i], tags[j])) continue;
+        const key = [tags[i], tags[j]].sort().join("|");
+        pairs.set(key, (pairs.get(key) ?? 0) + 1);
+      }
+  }
+  return [...pairs.entries()]
+    .filter(([k, n]) => n >= 2 && !base.some((d) => k.split("|").every((t) => (d.style ?? "").includes(t))))
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 4)
+    .map(([k, n]) => {
+      const [a, b] = k.split("|");
+      return { id: `gen-${slug(a)}+${slug(b)}`, name: `${cap(a)} + ${b}`, brief: `${cap(STYLE[a])}, and ${STYLE[b]}. Drawn from ${n} library references for this job that share it; everything else stays clear.`, style: `${a} ${b}`, generated: "library" };
+    });
+}
+
+// Directions from the user's own saved references: their measured type and colour, their notes.
+export function refDirections(exclude = []) {
+  return listRefs()
+    .filter((r) => !exclude.includes(r.id) && (r.measures || r.note))
+    .slice(-4)
+    .map((r) => {
+      const m = r.measures ?? {};
+      const host = r.kind === "url" ? r.source.replace(/^https?:\/\/(www\.)?/, "").split("/")[0] : path.basename(r.source);
+      const facts = [m.headline && `headline ${m.headline}`, m.fonts?.length && `fonts ${m.fonts.join(", ")}`, m.radii?.length && `radii ${m.radii.join(", ")}`, m.backgrounds?.length && `backgrounds ${m.backgrounds.slice(0, 3).join(", ")}`].filter(Boolean).join("; ");
+      return { id: `ref-${r.id}`, name: `The type and colour of ${host}`, brief: `From a reference the user saved (${r.source}${r.note ? `; their note: "${r.note}"` : ""}). ${facts ? `Measured: ${facts}. ` : ""}Take its type character, scale contrast and palette mood (never its text, logos or brand colours); the structure comes from your assigned archetype.`, style: "", generated: "user-ref" };
+    });
+}
+
+const picksLog = () => (fs.existsSync(path.join(TASTE_DIR, "picks.jsonl")) ? fs.readFileSync(path.join(TASTE_DIR, "picks.jsonl"), "utf8").split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean) : []);
+
+// Wins per direction id (2 for this kind of screen, 1 elsewhere) and per archetype for this kind.
+function wins(kind) {
+  const byDir = {};
+  const byArch = {};
+  for (const p of picksLog()) {
+    if (!p.winner || !p.directions) continue;
+    const letter = p.winner.match(/-([a-z])\d+$/)?.[1];
+    const d = p.directions.find((x) => x.letter === letter);
+    if (!d) continue;
+    const id = d.id.replace(/^blend-/, "");
+    byDir[id] = (byDir[id] ?? 0) + (p.kind === kind ? 2 : 1);
+    if (d.archetype && p.kind === kind) byArch[d.archetype] = (byArch[d.archetype] ?? 0) + 1;
+  }
+  return { byDir, byArch };
+}
+
+// Chooses `count` directions, each with its own structure:
+// - the directions that have won most for this user come first (base, generated or from their references);
+// - one slot explores: a direction this user has never seen for this kind of screen, or failing that a
+//   direction × structure pair never seen; generated directions count, so exploring never runs dry;
+// - structures never repeat inside a loop and prefer ones least made for this kind of screen.
+export function chooseDirections(count, { kind, screen, pool = [], exclude = [], keepSlots } = {}) {
+  const generated = [...libraryDirections(pool), ...refDirections(exclude)];
+  const revived = pastGenerated().filter((g) => !generated.some((x) => x.id === g.id));
+  const all = [...baseDirections(), ...generated, ...revived];
+  const { byDir, byArch } = wins(kind);
+  const seen = seenDirections(kind, screen, picksLog());
+  const jitter = () => Math.random() * 0.01;
+  const exploit = Math.max(1, keepSlots ?? count - 1);
+  // Revived generated directions only return when they have won.
+  const ranked = all.filter((d) => !d.generated || byDir[d.id] > 0).sort((a, b) => (byDir[b.id] ?? 0) - (byDir[a.id] ?? 0) || Math.random() - 0.5);
+  const keep = ranked.slice(0, exploit);
+  const archs = archetypesFor(kind);
+  const used = new Set();
+  const archOrder = (preferWinner) =>
+    [...archs].filter((a) => !used.has(a.id)).sort((a, b) => (preferWinner ? (byArch[b.id] ?? 0) - (byArch[a.id] ?? 0) : 0) || (seen.shapes[a.id] ?? 0) - (seen.shapes[b.id] ?? 0) || Math.random() - 0.5);
+  const out = keep.map((d, i) => {
+    // The first slot may keep the structure that has won for this kind of screen; the rest take the least made.
+    const a = archOrder(i === 0 && Object.keys(byArch).length > 0)[0];
+    used.add(a.id);
+    return { ...d, archetype: a.id, archetypeWon: i === 0 && byArch[a.id] > 0 };
+  });
+  // The explore slot.
+  while (out.length < count) {
+    const options = [];
+    for (const d of all.filter((x) => !out.some((o) => o.id === x.id) && !revived.includes(x)))
+      for (const a of archs.filter((x) => !used.has(x.id))) {
+        const newDir = !seen.dirs.has(d.id);
+        const newPair = !seen.combos.has(`${d.id}|${a.id}`);
+        options.push({ d, a, score: (newDir ? 4 : 0) + (newPair ? 2 : 0) + (d.generated ? 0.5 : 0) + 1 / (1 + (seen.shapes[a.id] ?? 0)) + jitter() + Math.random() });
+      }
+    if (!options.length) break;
+    const best = options.sort((x, y) => y.score - x.score)[0];
+    used.add(best.a.id);
+    out.push({ ...best.d, archetype: best.a.id, explore: true, neverSeen: !seen.dirs.has(best.d.id) ? "direction" : !seen.combos.has(`${best.d.id}|${best.a.id}`) ? "pair" : null });
+  }
+  return { directions: out, generated, used };
+}
+
+export function nextArchetype(kind, used, screenShapes = {}) {
+  return archetypesFor(kind).filter((a) => !used.has(a.id)).sort((a, b) => (screenShapes[a.id] ?? 0) - (screenShapes[b.id] ?? 0) || Math.random() - 0.5)[0];
+}
+
+// The reference pool for a job: several searches (the job's first sentence, the whole job, the kind of
+// screen), merged by rank, so three directions can each get their own references.
+const EXPAND = {
+  landing: ["landing page hero section", "call to action newsletter signup", "features section"],
+  hero: ["hero section landing page", "call to action"],
+  pricing: ["pricing section comparison table", "billing page"],
+  features: ["features section card grid", "landing page"],
+  onboarding: ["onboarding steps stepper", "empty state"],
+  team: ["team section user list", "settings page"],
+  settings: ["settings page form", "sidebar navigation"],
+  table: ["data table search and filters", "dashboard"],
+  dashboard: ["dashboard analytics chart", "stats section"],
+  auth: ["login form signup form"],
+  docs: ["documentation page", "blog list"],
+};
+export function referencePool(searchLibrary, job, { kind, screen } = {}) {
+  const first = job.split(/[.:]/)[0].slice(0, 160);
+  const queries = [[first, 3], [job.slice(0, 300), 2], ...(EXPAND[screen] ?? [kind === "app" ? "app section dashboard" : "marketing section landing page"]).map((q) => [q, 1])];
+  const score = new Map();
+  const rec = new Map();
+  for (const [q, w] of queries)
+    searchLibrary(q, { n: 40, preferWhole: true }).forEach((r, i) => {
+      rec.set(r.id, r);
+      score.set(r.id, (score.get(r.id) ?? 0) + w / (i + 3));
+    });
+  return [...rec.values()].sort((a, b) => score.get(b.id) - score.get(a.id)).map((r, i) => ({ ...r, rank: i }));
+}
+
+// Splits the pool so no two directions share a reference: each direction in turn takes its best remaining
+// match (relevance first, its style words second), until each has `per` or the pool runs out.
+export function splitReferences(pool, directions, styleOf, per = 6) {
+  const words = (s) => new Set(String(s ?? "").toLowerCase().split(/\s+/).filter(Boolean));
+  const taken = new Set();
+  const out = directions.map(() => []);
+  for (let round = 0; round < per; round++)
+    directions.forEach((d, i) => {
+      const sw = words(styleOf(d));
+      let best = null;
+      let bestScore = -Infinity;
+      for (const r of pool) {
+        if (taken.has(r.id)) continue;
+        const style = r.tags.filter((t) => t.split(" ").every((w) => sw.has(w))).length;
+        const s = style * 6 - r.rank;
+        if (s > bestScore) [best, bestScore] = [r, s];
+      }
+      if (best) {
+        taken.add(best.id);
+        out[i].push(best);
+      }
+    });
+  return out;
+}

package/src/loop/fail.mjs

@@ -0,0 +1,110 @@
+// `palate fail <route> "<why>"`: the user says a screen is bad. palate shoots it (or takes the screenshots
+// given with --shot), keeps them in ~/.palate/failures with the why, and proposes rules from it: the general
+// form of what it matches ("logos too small" → logo marks at least 24px, measured), else the user's words as a
+// rule the judge asks. A proposal applies nowhere until the user keeps it with a scope (palate rule review | ok).
+// Briefs for this kind of screen show the failure itself under "Don't do this".
+//   palate rule add "<rule>" [--kind landing | --only <Component> | --route /x] [--project <name>]   a rule in the user's words (active at once)
+//   palate rule list | edit <id> ["<words>"] [--kind k] [--project <name> | --project all] | rm <id> | learn [--all]
+//   palate rule review                           the proposals on a board in the browser: scope, wording, keep or discard
+//   palate rule ok <id> [--scope …|--kind …|--only <Component>|--route /x] [--project <name>] [--text "…"]   keep a proposal
+//   palate rule no <id>                          discard a proposal (remembered, so the same evidence won't bring it back)
+import path from "node:path";
+import { normalizeRoute, shoot } from "../shoot.mjs";
+import { approveRule, checkWords, classifyScope, dedupe, editRule, isProposed, learnedLines, learnRules, loadRules, projectOf, proposalLine, recordFailure, rejectRule, removeRule, reviewHint, routeTags, ruleFrom, RULES_FILE, scopeLabel } from "./rules.mjs";
+
+const slash = (p) => String(p).replace(/\\/g, "/");
+const kindsOf = (kind) => (kind ? String(kind).split(",").map((k) => k.trim().toLowerCase()).filter(Boolean) : null);
+const said = (list) =>
+  list.map(({ rule: r, added, discarded, needs }) =>
+    !r ? `- Not proposed: you discarded "${discarded.rule}" before (it comes back only after ${needs} more new ask${needs > 1 ? "s" : ""}).` : isProposed(r) ? `- Proposed, waiting for your OK: ${r.id} ${r.rule} (${checkWords(r)})` : `- ${added ? "New" : "Already a rule, strengthened"}: ${r.id} [${scopeLabel(r)}] ${r.rule} (${checkWords(r)})`,
+  );
+
+export async function fail(dir, rawRoute, why, { kind, shots, url, project } = {}) {
+  if (!rawRoute || !why) throw new Error('Usage: palate fail <route> "<why it is bad, in the user\'s words>" [--kind landing] [--shot file.png]');
+  const route = normalizeRoute(rawRoute);
+  // --shot "" records a failure with no screenshot.
+  let files = shots ?? [];
+  if (shots == null) {
+    // The whole page at 1440, the way the user saw it.
+    const shot = await shoot(dir, route, { url, widths: [1440], principles: false });
+    files = shot.files.filter((f) => f.endsWith("-full.png")).slice(0, 1);
+  }
+  const kinds = kindsOf(kind) ?? routeTags(dir, route);
+  const { failure, learned } = recordFailure({ project: project ?? path.basename(path.resolve(dir)), route, why, kinds, shots: files });
+  const proposals = learned.filter((l) => l.rule && isProposed(l.rule)).map((l) => l.rule.id);
+  return [
+    `Saved the failure: ${failure.id}${failure.shots.length ? ` (${failure.shots.join(", ")})` : ""}.`,
+    `Kinds: ${kinds.join(", ")}. Briefs for these screens now show it under "Don't do this".`,
+    "",
+    "What palate learned from it:",
+    ...said(learned),
+    ...(proposals.length ? ["", `This fix is for ${route}; whether it holds anywhere else is the user's call. ${reviewHint(proposals)}`] : []),
+    "",
+    `Rules file: ${slash(RULES_FILE)}.`,
+  ].join("\n");
+}
+
+const checkOf = (r) => (r.check?.type === "metric" ? `${r.check.metric} ${r.check.op} ${r.check.value}` : r.check?.type === "dom" ? `${r.check.selector}${r.check.min != null ? ` ≥ ${r.check.min}` : ""}${r.check.max != null ? ` ≤ ${r.check.max}` : ""}` : "judge");
+// The scope the user chose, from flags: --only <Component>, --route /x, --kind a,b, --scope <option>; --project
+// <name> keeps any of them to one project.
+const scopeFrom = ({ only, route, kind, scope, project }) => {
+  const s = only ? { component: only } : route ? { route } : kindsOf(kind) ? { kinds: kindsOf(kind) } : scope;
+  if (!project) return s;
+  return typeof s === "object" && s ? { ...s, project } : s ? { scope: s, project } : { project };
+};
+
+// dir: the project the user is in. With no scope given, palate picks one: a rule tied to this product's identity
+// (a colour, a font, its name, its agents and demos) stays in this project; a judgement about design holds everywhere.
+export function rule(sub, args, { kind, source, only, route, scope, text, project, dir } = {}) {
+  const kinds = kindsOf(kind);
+  if (sub === "add") {
+    // --project all means general taste, the same as on edit.
+    if (project?.trim().toLowerCase() === "all") project = undefined;
+    const words = args.join(" ").trim();
+    const narrow = only ? { component: String(only).replace(/^<|\/?>$/g, "") } : route ? { route: normalizeRoute(route) } : {};
+    const picked = !kinds && !only && !route && !project?.trim() && dir && words ? classifyScope(words, { project: projectOf(dir), dir }) : null;
+    if (picked?.project) project = picked.project;
+    const where = project?.trim() ? { ...narrow, project: project.trim() } : Object.keys(narrow).length ? narrow : undefined;
+    const learned = dedupe(ruleFrom(words, { kinds: kinds ?? undefined, source: source ?? `user:"${words.slice(0, 120)}"`, where }));
+    const ids = [...new Set(learned.filter((l) => l.rule).map((l) => l.rule.id))].join(" ");
+    // Words that match a known rule get its general form and its check; others stay a rule in the user's words.
+    return [
+      "From your words:",
+      ...said(learned),
+      ...(picked
+        ? [picked.project ? `Scope: only in ${picked.project}, because it's tied to this product: ${picked.why}. If it should hold in every project: palate rule edit ${ids || "<id>"} --project all` : `Scope: general taste (${picked.why}), so it holds in every project. If it's only for this one: palate rule edit ${ids || "<id>"} --project ${projectOf(dir)}`]
+        : []),
+    ].join("\n");
+  }
+  if (sub === "edit") {
+    const [id, ...rest] = args;
+    const r = editRule(id, { rule: rest.join(" ") || undefined, kinds: kinds ?? undefined, project });
+    return `${r.id} [${scopeLabel(r)}] ${r.rule}`;
+  }
+  if (sub === "rm" || sub === "remove") {
+    const r = removeRule(args[0]);
+    return `Removed ${r.id}: ${r.rule}`;
+  }
+  if (sub === "ok" || sub === "approve" || sub === "keep") {
+    if (!args[0]) throw new Error('Usage: palate rule ok <id> [--scope <option>|--kind team|--only <Component>|--route /x] [--project <name>] [--text "<new words>"]');
+    const { rule: r, scope: s, mergedFrom } = approveRule(args[0], { scope: scopeFrom({ only, route, kind, scope, project }), text });
+    return [`Kept ${mergedFrom ? `${mergedFrom} (merged into ${r.id}, which now applies to ${s.label.toLowerCase()})` : r.id}: ${r.rule}`, `Applies to: ${scopeLabel(r)} · ${checkWords(r)}. It's in every brief, shoot and judge for that scope from now on.`].join("\n");
+  }
+  if (sub === "no" || sub === "reject" || sub === "discard") {
+    if (!args[0]) throw new Error("Usage: palate rule no <id>");
+    const r = rejectRule(args[0]);
+    return `Discarded ${r.id}: ${r.rule}\nIt stays a one-off fix. palate remembers this, so the same evidence won't propose it again.`;
+  }
+  if (sub === "learn") return learnedLines(learnRules({ all: args.includes("--all") })).join("\n");
+  const all = loadRules();
+  const shown = kinds ? all.filter((r) => r.kinds.includes("all") || r.kinds.some((k) => kinds.includes(k))) : all;
+  const active = shown.filter((r) => !isProposed(r));
+  const proposed = shown.filter(isProposed);
+  if (sub === "proposed") return proposed.length ? [`# Waiting for your OK (${proposed.length}): not applied anywhere yet`, ...proposed.map(proposalLine), "", reviewHint(proposed.map((r) => r.id))].join("\n") : "Nothing waiting for your OK.";
+  if (!all.length) return 'No rules yet. Add one: palate rule add "<rule>" [--kind landing]';
+  return [
+    `# Your rules (${active.length}${kinds ? ` for ${kinds.join(", ")}` : ""}): ${slash(RULES_FILE)}`,
+    ...active.map((r) => `- ${r.id} [${scopeLabel(r)}] ${r.rule}\n    check: ${r.where?.component ? `the judge asks, for <${r.where.component}> only` : checkOf(r)} · from ${[r.source, ...(r.also ?? [])].join(", ")}`),
+    ...(proposed.length ? ["", `## Waiting for your OK (${proposed.length}): not applied anywhere yet`, ...proposed.map(proposalLine), "", reviewHint(proposed.map((r) => r.id))] : []),
+  ].join("\n");
+}

package/src/loop/fix.mjs

@@ -0,0 +1,194 @@
+// `palate fix <route>`: turns the findings the user agreed with in the latest critique into a brief, most
+// severe first, with each section's crops, and tells the agent to re-shoot and verify each one. With no
+// critique it fixes what is measurably wrong (palate shoot's problems).
+// `palate fix <route> --verify` re-renders the sections and puts each finding's section before | after.
+import fs from "node:fs";
+import path from "node:path";
+import { contactSheet, cropSections, findSections, openPage, shootFull, slugOf, stamp, withBrowser } from "../look.mjs";
+import { normalizeRoute, shoot } from "../shoot.mjs";
+import { readJson } from "./common.mjs";
+import { latestCritique, SEVERITIES } from "./critique.mjs";
+import { slash } from "./craft.mjs";
+import { projectOf, routeTags, rulesBlock } from "./rules.mjs";
+import { latestStates, STATES } from "./states.mjs";
+
+// shoot's ⚠ lines, each tagged with the width it was measured at.
+function problemsOf(report) {
+  let at = "";
+  const out = [];
+  for (const l of report.split("\n")) {
+    if (l.startsWith("## ")) at = l.slice(3);
+    else if (l.startsWith("- ⚠")) out.push(`- ⚠ (${at}) ${l.slice(4)}`);
+  }
+  return out.join("\n");
+}
+
+// The missing states from the latest `palate states` run for the route (or a pointer to run it).
+function statesLines(dir, route) {
+  const s = latestStates(dir, route);
+  if (!s) return ["", "## States", `Not checked yet. \`palate states ${route}\` renders empty, loading, error, long text, many items, failing images, 320 wide and forms pressed twice, and lists the missing ones.`];
+  const rec = readJson(path.join(s, "findings.json"), { findings: [] });
+  const stamp = path.basename(s);
+  if (!rec.findings.length) return ["", `## States (palate states ${stamp})`, "Every state palate could render held up."];
+  return [
+    "",
+    `## Missing states (palate states ${stamp}${rec.sheet ? `; contact sheet ${slash(rec.sheet)}` : ""})`,
+    ...rec.findings.map((f) => `- ${f.id} [${f.severity}] ${f.componentLabel} · ${f.states.map((s) => STATES[s] ?? s).join(", ")}: ${f.what} Build: ${f.fix}${f.where ? ` Where: ${f.where}.` : ""}${f.crop ? ` Crop: ${slash(f.crop)}` : ""}`),
+    `The full states brief, with copy guidance: ${slash(path.join(s, "states.md"))}. Verify these with \`palate states ${route} --verify\`.`,
+  ];
+}
+
+// Agreed findings (all of them when the user hasn't reviewed), most severe first, with their sections.
+function plan(session) {
+  const { findings = [] } = readJson(path.join(session, "findings.json"), {});
+  const meta = readJson(path.join(session, "sections.json"), {});
+  const review = readJson(path.join(session, "review.json"), null);
+  const verdicts = review?.verdicts ?? {};
+  const reviewed = Object.values(verdicts).some((v) => v.verdict);
+  const sectionOf = (f) => {
+    const n = Number(String(f.section).match(/^\s*#?(\d+)/)?.[1]);
+    return n ? meta.sections?.find((s) => s.index === n) ?? null : meta.sections?.find((s) => s.name.toLowerCase() === String(f.section).toLowerCase()) ?? null;
+  };
+  const rank = (f) => SEVERITIES.indexOf(String(f.severity).toLowerCase()) + 1 || 2;
+  const all = findings.map((f, i) => ({ ...f, id: f.id ?? `F${i + 1}`, verdict: verdicts[f.id]?.verdict ?? null, note: verdicts[f.id]?.note ?? "", sec: sectionOf(f) })).sort((a, b) => rank(a) - rank(b));
+  return {
+    meta,
+    reviewed,
+    todo: reviewed ? all.filter((f) => f.verdict === "agree") : all,
+    skip: all.filter((f) => f.verdict === "disagree"),
+    unmarked: reviewed ? all.filter((f) => !f.verdict) : [],
+  };
+}
+
+export async function fix(dir, rawRoute, { url, verify = false } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const session = latestCritique(dir, route, { withFindings: true });
+  if (verify) return verifyFixes(dir, route, session, { url });
+
+  const shot = await shoot(dir, route, { url });
+  const problems = problemsOf(shot.report);
+  const measured = /⚠/.test(problems);
+  // The user's rules for this page, marked where the shoot just measured them failing.
+  const mine = rulesBlock(shot.rules?.tags ?? routeTags(dir, route), { results: shot.rules?.results, route, project: projectOf(dir) });
+  if (!session || !fs.existsSync(path.join(session, "findings.json"))) {
+    const out = path.join(dir, ".palate", "fix", slugOf(route), stamp());
+    fs.mkdirSync(out, { recursive: true });
+    const brief = [
+      mine.line,
+      "",
+      `# Fix: ${route} (what is measurably wrong)`,
+      "",
+      ...mine.lines,
+      `No critique with findings for ${route} yet, so this fixes what palate can measure. For a designer's review first: palate critique ${route}.`,
+      "",
+      `Screenshots: ${shot.files.map(slash).join(", ")}`,
+      "",
+      measured ? problems : "palate shoot measured no problems. Open the screenshots and fix the three biggest problems you see, or run palate critique for a full review.",
+      ...statesLines(dir, route),
+      "",
+      "Fix each ⚠ at its cause (the element, not a global override), smallest change first. Keep the design's idea and layout.",
+      `Then run \`palate shoot ${route}\` again: every ⚠ above should be gone. Run the project's typecheck. Don't commit.`,
+    ].join("\n");
+    fs.writeFileSync(path.join(out, "fix.md"), brief);
+    return `${brief}\n\n(Brief saved to ${slash(path.join(out, "fix.md"))})`;
+  }
+
+  const { meta, reviewed, todo, skip, unmarked } = plan(session);
+  const full = path.join(session, "full-1440.png");
+  const crops = (f) => (f.sec ? Object.entries(f.sec.crops ?? {}).filter(([, c]) => c).sort((a, b) => b[0] - a[0]).map(([w, c]) => `${w}px ${slash(c)}`).join(" · ") : fs.existsSync(full) ? `full page ${slash(full)}` : "the full page");
+  const brief = [
+    mine.line,
+    "",
+    `# Fix: ${route}, from the critique of ${path.basename(session)}`,
+    "",
+    ...mine.lines,
+    reviewed ? `The user agreed with ${todo.length} finding(s)${skip.length ? ` and disagreed with ${skip.length}` : ""}. Fix the agreed ones, most severe first.` : `The user hasn't reviewed these findings yet (palate critique --findings ${slash(path.join(session, "findings.json"))} opens the board). Fixing all ${todo.length}, most severe first; ask the user before the ideas.`,
+    "",
+    "## Findings to fix",
+    ...todo.map((f, i) => [
+      `### ${i + 1}. ${f.id} [${f.severity}] ${f.sec ? `section ${f.sec.index}, ${f.sec.name}` : "the whole page"}`,
+      `- What: ${f.what}`,
+      f.why ? `- Why: ${f.why}` : "",
+      `- Fix: ${f.fix}`,
+      f.note ? `- The user's note: ${f.note} (this overrides the fix where they differ)` : "",
+      `- Before: ${crops(f)}`,
+    ].filter(Boolean).join("\n")),
+    skip.length ? `\n## Leave these alone (the user disagreed)\n${skip.map((f) => `- ${f.id}: ${f.what}${f.note ? ` (their note: ${f.note})` : ""}`).join("\n")}` : "",
+    unmarked.length ? `\n## Not marked by the user (skip unless trivial and clearly right)\n${unmarked.map((f) => `- ${f.id} [${f.severity}]: ${f.what}`).join("\n")}` : "",
+    measured ? `\n## Also measurably wrong now (palate shoot)\n${problems}` : "",
+    ...statesLines(dir, route),
+    "",
+    "## How",
+    "- One finding at a time, in this order. Change what the finding names; keep the rest of the design, its idea and its content.",
+    "- No fix may break one of your rules above; a rule marked FAILS NOW is a finding too.",
+    "- Ideas (severity idea) are bigger changes: build them only if the user agreed with them, and keep them to the section named.",
+    "- Use the project's tokens and components. Real content only. Don't install packages without asking.",
+    `- After each section you change, run \`palate shoot ${route}\` and look at that section at both widths.`,
+    "",
+    "## Verify",
+    `When all are done: \`palate fix ${route} --verify\`. It re-renders every section with a finding and puts it before | after. Open each pair and report, per finding: fixed, partly, or not, in one line. Fix what isn't, then run the project's typecheck. Don't commit.`,
+  ]
+    .filter((l) => l !== "")
+    .join("\n")
+    .replace(/\n(#{2,3} )/g, "\n\n$1");
+  fs.writeFileSync(path.join(session, "fix.md"), brief);
+  return `${brief}\n\n(Brief saved to ${slash(path.join(session, "fix.md"))})`;
+}
+
+async function verifyFixes(dir, route, session, { url }) {
+  if (!session || !fs.existsSync(path.join(session, "findings.json"))) {
+    const shot = await shoot(dir, route, { url });
+    return `# Verify: ${route}\n\n${problemsOf(shot.report) || "No measurable problems left."}\n\nScreenshots: ${shot.files.map(slash).join(", ")}`;
+  }
+  const { meta, todo } = plan(session);
+  const out = path.join(session, `after-${stamp()}`);
+  const { pairs, pagePairs, shotReport } = await withBrowser(dir, { url }, async ({ base, browser }) => {
+    const shotReport = (await shoot(dir, route, { url: base })).report;
+    const now = {};
+    for (const w of [1440, 390]) {
+      const { page, ctx } = await openPage(browser, base, route, { width: w });
+      now[w] = await cropSections(page, await findSections(page), out, `w${w}`);
+      if (w === 1440) await shootFull(page, path.join(out, "full-1440.png"));
+      await ctx.close();
+    }
+    // The same section after the changes: by id, then heading, then position.
+    const match = (w, s) => now[w].find((x) => s.id && x.id === s.id) ?? now[w].find((x) => x.name === s.name) ?? now[w].find((x) => x.index === s.index);
+    const bySection = new Map();
+    for (const f of todo) {
+      const key = f.sec?.index ?? 0;
+      if (!bySection.has(key)) bySection.set(key, { sec: f.sec, ids: [] });
+      bySection.get(key).ids.push(f.id);
+    }
+    const rows = [];
+    for (const [, g] of bySection) {
+      if (!g.sec) continue;
+      for (const w of [1440, 390]) {
+        const before = g.sec.crops?.[w];
+        const after = match(w, g.sec)?.file;
+        rows.push({ label: `Section ${g.sec.index} · ${g.sec.name.slice(0, 50)} · ${w}px · ${g.ids.join(", ")}`, cells: [{ caption: "before", file: before && fs.existsSync(before) ? before : null, note: "no before crop" }, { caption: "after", file: after ?? null, note: "section not found now" }] });
+      }
+    }
+    const pairs = rows.length ? await contactSheet(browser, rows, path.join(out, "before-after.png"), { cell: 620, maxCell: 520 }) : null;
+    // Whole-page findings: the full page, before | after.
+    const fullBefore = path.join(session, "full-1440.png");
+    const pagePairs = todo.some((f) => !f.sec) && fs.existsSync(fullBefore) ? await contactSheet(browser, [{ label: `The whole page · ${todo.filter((f) => !f.sec).map((f) => f.id).join(", ")}`, cells: [{ caption: "before", file: fullBefore }, { caption: "after", file: path.join(out, "full-1440.png") }] }], path.join(out, "page-before-after.png"), { cell: 560, maxCell: 6000 }) : null;
+    return { pairs, pagePairs, shotReport };
+  });
+  const text = [
+    `# Verify the fixes: ${route}`,
+    "",
+    pairs ? `Before | after for every section with a finding: ${slash(pairs)} (crops in ${slash(out)}).` : "",
+    pagePairs ? `The whole page, before | after: ${slash(pagePairs)}.` : "",
+    "",
+    "For each finding, open the pair and answer fixed, partly or not:",
+    ...todo.map((f) => `- ${f.id} [${f.severity}] ${f.sec ? `section ${f.sec.index}` : "page"}: ${f.what}`),
+    "",
+    "## Measured now (palate shoot)",
+    problemsOf(shotReport) || "No measurable problems.",
+    "",
+    `Fix anything not fixed, then run this again. When all are fixed: palate taste learn (the user's verdicts on this critique are in their taste log).`,
+    latestStates(dir, route) ? `The missing states are verified separately: palate states ${route} --verify (before | after per state, measured).` : "",
+  ].join("\n");
+  fs.writeFileSync(path.join(out, "verify.md"), text);
+  return text;
+}