@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/ambition.mjs

@@ -0,0 +1,620 @@
+// `palate ambition <route>`: the pass after the finishing pass that asks "is this remarkable?", not "is it correct?".
+// palate renders the page at 1440, crops each section, and puts the first screen and every section beside the
+// strongest references it has (the research step's captures, else the user's own references, else palate's
+// library of the same kind of section), with the chosen signature move. It measures what it can (type scale
+// and character, contrast, whitespace, centring, stock grids, colour against common SaaS palettes, the
+// signature in the DOM, how close each section is to a stock component-library section) and asks the calling
+// agent, who can see, to score each section on a strict rubric. Then it picks the weakest section and writes
+// one upgrade brief: what's generic, moves that fit this product (with recipes), what to keep. The agent
+// upgrades that section once; `--verify` re-renders it, before | after, with new scores. Each upgrade and its
+// later fate (kept, reverted, pointed at again) is logged in ~/.palate so the next choice of moves follows
+// what this user keeps. Runs without asking the user anything.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { contactSheet, cropSections, findSections, openPage, shootFull, slugOf, stamp, withBrowser } from "../look.mjs";
+import { normalizeRoute } from "../shoot.mjs";
+import { readJson, TASTE_DIR } from "./common.mjs";
+import { LIB_DIR, sectionKind, slash } from "./craft.mjs";
+import { logGrowth, preferMoves, setOutcome, upgrades } from "./growth.mjs";
+import { layoutRecord, projectId, readLayouts, visualSimilarity } from "./layouts.mjs";
+import { rememberedRefs } from "./myrefs.mjs";
+import { kindTags } from "./rules.mjs";
+import { gateLines, normSignature, readResearch, saveGate, similarityGate } from "./similar.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const ambitionScript = fs.readFileSync(path.join(here, "..", "page-ambition.js"), "utf8").trim().replace(/;\s*$/, "");
+const fingerprintScript = fs.readFileSync(path.join(here, "..", "page-fingerprint.js"), "utf8").trim().replace(/;\s*$/, "");
+
+// The rubric the agent scores every section on, 0–10 each (10 is remarkable).
+export const RUBRIC = [
+  { id: "screenshot", label: "Screenshot-worthy", q: "Would a designer screenshot this section to save or share it?" },
+  { id: "moment", label: "Memorable moment", q: "Is there one moment here someone would describe tomorrow?" },
+  { id: "signature", label: "Signature delivered", q: "Is the chosen signature move delivered (score the section that should carry it; leave null elsewhere)?" },
+  { id: "type", label: "Type with character", q: "A deliberate face, scale, weight and tracking, not defaults?" },
+  { id: "copy", label: "Point of view", q: "Copy that only this product could say, not a sentence any SaaS could use?" },
+  { id: "hierarchy", label: "Hierarchy and rhythm", q: "Hierarchy and rhythm at the level of the references beside it?" },
+  { id: "generic", label: "Nothing generic", q: "No template look, stock patterns or centred-everything? (10 = nothing generic)" },
+];
+
+const clamp = (v, lo = 0, hi = 10) => Math.max(lo, Math.min(hi, v));
+const r1 = (v) => (v == null ? null : Math.round(v * 10) / 10);
+const pct = (v) => `${Math.round((v ?? 0) * 100)}%`;
+const mean = (xs) => {
+  const v = xs.filter((x) => typeof x === "number" && !Number.isNaN(x));
+  return v.length ? v.reduce((a, b) => a + b, 0) / v.length : null;
+};
+
+// Faces that read as "nobody chose this".
+const GENERIC_FONT = /^(ui-sans-serif|system-ui|-apple-system|blinkmacsystemfont|segoe ui|roboto|helvetica( neue)?|arial|inter|geist|sans-serif|open sans|lato|poppins|montserrat|ui-serif|times new roman|times)$/i;
+// Sentences any product could print.
+const GENERIC_COPY = [/everything (you|your [a-z]+|a [a-z]+(?: [a-z]+)?) needs?\b/i, /\ball[- ]in[- ]one\b/i, /\bpowerful\b/i, /\bseamless(ly)?\b/i, /\beffortless(ly)?\b/i, /\bsupercharge/i, /\bbuilt for (modern )?teams\b/i, /\bmade (simple|easy)\b/i, /\bwork smarter\b/i, /\bstreamline/i, /\bboost (your )?productivity\b/i, /\bunlock\b/i, /\btransform (the way|your)\b/i, /\bsimple,? (yet|but) powerful\b/i, /\bnext[- ]gen/i, /\bgame[- ]chang/i, /\bwhy choose\b/i, /\bfeatures that\b/i, /\bat your fingertips\b/i, /\btake (it|your [a-z]+) to the next level\b/i];
+// Accents every SaaS template ships with (Tailwind defaults, the usual brand blues and violets, near-black).
+const COMMON_ACCENTS = { "Tailwind blue": "#2563eb", "Tailwind indigo": "#4f46e5", "Tailwind violet": "#7c3aed", "Tailwind purple": "#9333ea", "Tailwind sky": "#0284c7", "Tailwind emerald": "#059669", "Tailwind green": "#16a34a", "Tailwind teal": "#0d9488", "Tailwind orange": "#ea580c", "Tailwind rose": "#e11d48", "Stripe violet": "#635bff", "Linear indigo": "#5e6ad2", "near-black": "#111111", "slate-900": "#0f172a" };
+const hexRgb = (h) => (h && /^#[0-9a-f]{6}$/i.test(h) ? [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16)) : null);
+const dist = (a, b) => Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+
+// How distinct the page's accent is: from template palettes, and from the user's other projects.
+export function colourCheck(accent, dir) {
+  const a = hexRgb(accent);
+  if (!a) return { accent, line: "No chromatic accent found (a page in neutrals only).", score: null };
+  const near = Object.entries(COMMON_ACCENTS).map(([name, h]) => ({ name, h, d: dist(a, hexRgb(h)) })).sort((x, y) => x.d - y.d)[0];
+  const pid = dir ? projectId(dir) : null;
+  const mine = readLayouts().filter((r) => r.pid !== pid && hexRgb(r.style?.accent) && dist(a, hexRgb(r.style.accent)) < 28);
+  const projects = [...new Set(mine.map((r) => r.project))];
+  const score = r1(clamp((near.d / 120) * 10 - (projects.length ? 4 : 0)));
+  return { accent, near, projects, score, line: `Accent ${accent}: ${Math.round(near.d)} from ${near.name} (${near.h})${near.d < 40 ? ", a template colour" : ""}${projects.length ? `; the same colour as your other project${projects.length > 1 ? "s" : ""} ${projects.join(", ")}` : ""}. Distinctiveness ${score}/10.` };
+}
+
+// palate's own scores for a section (0–10; null where it can't measure), with what it found generic.
+export function measuredScores(m, { libSim = null, signature = null } = {}) {
+  if (!m || m.empty) return { scores: {}, flags: [], templateness: null, mean: null };
+  const flags = [];
+  // A product window is judged as product UI on the sheet; its small app type isn't page typography.
+  if (m.productUI) {
+    const lib = libSim == null ? 0 : clamp((libSim - 0.35) / 0.4, 0, 1);
+    if (lib >= 0.5) flags.push(`close to a stock component-library section (${pct(libSim)})`);
+    if (!m.animated) flags.push("the product window doesn't move: a still picture of the product");
+    const scores = { screenshot: null, moment: r1(clamp(5 + (m.animated ? 2 : 0) + (m.mediaShare >= 0.35 ? 0.5 : 0) - 2 * lib)), signature: signature && m.signature ? 9 : null, type: null, copy: null, hierarchy: null, generic: r1(clamp(10 * (1 - 0.6 * lib))) };
+    return { scores, flags, templateness: +(0.6 * lib).toFixed(2), mean: r1(mean(Object.values(scores))) };
+  }
+  const h = m.headline;
+  const defaultFace = GENERIC_FONT.test(h.family ?? "");
+  let type = 5;
+  if (defaultFace) flags.push(`headline in a default face (${h.family})`);
+  else type += 2 + (h.family !== m.body.family ? 0.5 : 0);
+  if (Math.abs(h.track ?? 0) >= 0.01) type += 1;
+  if (m.scale >= 4.5) type += 1.5;
+  else if (m.scale >= 3) type += 0.5;
+  else if (m.scale < 1.8) {
+    type -= 2;
+    flags.push(`headline only ${m.scale}× the body size: no scale drama`);
+  }
+  if (h.weight - m.body.weight >= 250 || (h.weight <= 350 && h.size >= 56)) type += 0.5;
+  if (h.italic || h.upper) type += 0.5;
+  let hierarchy = 6;
+  if (m.scale < 1.8) hierarchy -= 2;
+  else if (m.scale >= 2.5) hierarchy += 1;
+  if (m.focal > 2) {
+    hierarchy -= 2;
+    flags.push(`${m.focal} elements share the biggest size: no single focal point`);
+  }
+  // Tight on both sides; one open edge is often a section running on into the next on purpose.
+  const edge = Math.max(m.padTop, m.padBottom);
+  if (edge < 40 && m.height > 300 && m.mediaShare < 0.3) {
+    hierarchy -= 1.5;
+    flags.push(`tight edges (${edge}px of air)`);
+  } else if (Math.min(m.padTop, m.padBottom) >= 96) hierarchy += 0.5;
+  if (h.contrast != null && h.contrast < 4.5) {
+    hierarchy -= 1;
+    flags.push(`headline contrast ${h.contrast}:1`);
+  }
+  if (m.body.contrast < 4.5) {
+    hierarchy -= 1;
+    flags.push(`body text contrast ${m.body.contrast}:1`);
+  }
+  const stock = GENERIC_COPY.map((re) => m.copy.match(re)?.[0]).filter(Boolean);
+  let copy = 6 - 2 * stock.length + (/\d/.test(h.text) ? 1 : 0) - (h.text.split(/\s+/).length <= 2 && !/\d/.test(h.text) ? 1 : 0);
+  if (stock.length) flags.push(`stock copy: "${stock.join('", "')}"`);
+  const grid = m.grid >= 3 && m.grid <= 6;
+  const centred = m.centred >= 0.7 && m.blocks >= 2;
+  const lib = libSim == null ? 0 : clamp((libSim - 0.35) / 0.4, 0, 1);
+  if (grid) flags.push(`a row of ${m.grid} equal cards`);
+  if (centred) flags.push("centred everything");
+  if (lib >= 0.5) flags.push(`close to a stock component-library section (${pct(libSim)})`);
+  const templateness = +(0.4 * lib + 0.25 * (grid ? 1 : 0) + 0.2 * (centred ? 1 : 0) + 0.15 * (defaultFace ? 1 : 0)).toFixed(2);
+  let moment = 4 + (m.scale >= 4 ? 2 : 0) + (m.mediaShare >= 0.35 || m.animated > 0 ? 1 : 0) + (m.ownBg ? 0.5 : 0) + (defaultFace ? 0 : 1) + 2 * (1 - templateness) - 1;
+  const scores = { screenshot: null, moment, signature: signature && m.signature ? 9 : null, type, copy, hierarchy, generic: 10 * (1 - templateness) };
+  for (const k of Object.keys(scores)) scores[k] = scores[k] == null ? null : r1(clamp(scores[k]));
+  return { scores, flags, templateness, mean: r1(mean(Object.values(scores))) };
+}
+
+// The agent's scores, in any of the shapes an agent might write them.
+export function readAgentScores(input) {
+  const j = typeof input === "string" ? readJson(input, null) : input;
+  if (!j) throw new Error(`Could not read the scores${typeof input === "string" ? ` in ${input}` : ""}. Write JSON: {"sections": [{"index": 2, "scores": {"screenshot": 3, …}, "generic": "…", "keep": "…"}]}`);
+  const list = Array.isArray(j) ? j : Array.isArray(j.sections) ? j.sections : Object.entries(j).filter(([k]) => /^\d+$/.test(k)).map(([k, v]) => ({ index: Number(k), ...v }));
+  return Object.fromEntries(list.map((s) => [Number(s.index ?? s.section), { scores: s.scores ?? Object.fromEntries(RUBRIC.map((r) => [r.id, s[r.id]]).filter(([, v]) => v != null)), generic: s.generic ?? s.why ?? null, keep: s.keep ?? null }]));
+}
+
+// The agent's eyes count most; palate's measures keep it honest.
+export function combine(measured, agent) {
+  const a = agent ? mean(RUBRIC.map((r) => agent[r.id])) : null;
+  return r1(a != null ? (measured != null ? 0.7 * a + 0.3 * measured : a) : measured);
+}
+
+// The weakest content section (not the header, navigation or footer); ties go to the one higher on the page.
+export function pickWeakest(sections) {
+  const ok = sections.filter((s) => s.final != null && !["header", "nav", "footer"].includes(s.tag) && !/^(header|footer|navigation)$/i.test(s.name ?? "") && (s.height ?? 999) >= 160);
+  return [...ok].sort((a, b) => a.final - b.final || a.index - b.index)[0] ?? null;
+}
+
+// ---- moves: the moves library when it is there (src/moves.mjs), else kb/moves/moves.yaml.
+const words = (s) => String(s ?? "").toLowerCase().match(/[a-z0-9]+/g) ?? [];
+async function yamlMoves() {
+  try {
+    const { loadMoves } = await import("../concept.mjs");
+    return loadMoves().moves ?? [];
+  } catch {
+    return [];
+  }
+}
+const FAMILY_FOR = { type: ["type"], generic: ["composition", "data"], moment: ["composition", "interaction", "motion"], copy: ["content"], hierarchy: ["composition", "type"], screenshot: ["composition", "type"], signature: ["composition", "interaction"], colour: ["colour"] };
+// The moves library's kinds of move that answer each weak rubric item, and that fit each kind of section.
+const MOVE_KINDS_FOR = { type: ["type"], generic: ["layout", "imagery", "data"], moment: ["interaction", "motion", "hero"], hierarchy: ["layout", "type"], screenshot: ["layout", "imagery", "texture"], signature: ["hero", "interaction"], colour: ["texture", "imagery"] };
+const sectionMoveKinds = (sk = "") => (/hero/.test(sk) ? ["hero", "type", "layout", "imagery", "motion", "interaction", "texture"] : /footer/.test(sk) ? ["footer", "easter-egg"] : ["layout", "type", "data", "imagery", "interaction", "motion", "texture"]);
+export const recipeOf =(m) => `### ${m.id}${m.family ? ` (${m.family}${m.cost ? `, ${m.cost} effort` : ""})` : ""}\n${m.do ?? m.recipe ?? m.what ?? ""}${m.test ? `\nIt worked if: ${m.test}` : ""}`;
+
+// Moves that could lift a section, best first, led by what this user keeps; reverted ones are skipped.
+// weak: rubric ids that scored lowest. Returns { ids, text, skipped, why, source }.
+export async function movesFor({ tags = [], kind = "marketing", signature = null, weak = [], sectionKind: sk = null, words: extra = "", limit = 3 } = {}) {
+  let lib = null;
+  try {
+    lib = await import("../moves.mjs");
+  } catch {}
+  let candidates = [];
+  if (lib?.matchMoves) {
+    try {
+      // The library's kinds are kinds of move (hero, layout, type…): the ones that can change this section,
+      // led by the ones that answer its weakest rubric items. The user's history goes in too.
+      const kinds = sectionMoveKinds(sk);
+      const history = upgrades().filter((u) => ["kept", "reverted"].includes(u.outcome)).flatMap((u) => (u.moves ?? []).slice(0, 1).map((id) => ({ id, outcome: u.outcome, kind: u.sectionKind })));
+      const r = await lib.matchMoves({ tags: [...tags, ...words(extra)], kind: kinds, limit: limit + 8, history, screen: sk ?? undefined });
+      const lead = new Set(weak.flatMap((w) => MOVE_KINDS_FOR[w] ?? []));
+      candidates = (Array.isArray(r) ? r : r?.moves ?? [])
+        .map((m) => (typeof m === "string" ? { id: m } : m))
+        .filter((m) => m?.id && m.id !== signature?.move)
+        .map((m, i) => ({ ...m, rank: (m.score ?? 0) + (lead.has(m.kind) ? 1 : 0) - i * 0.01 }))
+        .sort((a, b) => b.rank - a.rank);
+    } catch {}
+  }
+  const source = candidates.length ? "moves library" : "kb/moves/moves.yaml";
+  const all = await yamlMoves();
+  if (!candidates.length) {
+    const kinds = kind === "app" ? ["tool"] : ["marketing"];
+    const q = new Set(words(`${tags.join(" ")} ${extra} ${sk ?? ""}`).flatMap((w) => [w, w.replace(/s$/, "")]));
+    const fams = new Set(weak.flatMap((w) => FAMILY_FOR[w] ?? []));
+    candidates = all
+      .filter((m) => (m.kinds ?? []).some((k) => kinds.includes(k)) && m.do)
+      .map((m) => ({ m, s: (m.signals ?? []).filter((s) => words(s).every((w) => q.has(w))).length + (fams.has(m.family) ? 2 : 0) + (m.cost && m.cost !== "low" ? 0.3 : 0) }))
+      .sort((a, b) => b.s - a.s)
+      .slice(0, limit + 5)
+      .map((x) => x.m);
+  }
+  const { order, skipped, why } = preferMoves(candidates.map((m) => m.id), { sectionKind: sk });
+  const ids = order.slice(0, limit);
+  let text = null;
+  if (lib?.moveBrief && source === "moves library") {
+    try {
+      const t = await lib.moveBrief(ids);
+      text = typeof t === "string" ? t : Array.isArray(t) ? t.join("\n\n") : t?.text ?? null;
+    } catch {}
+  }
+  text ??= ids.map((id) => recipeOf(candidates.find((c) => c.id === id && c.do) ?? all.find((c) => c.id === id) ?? { id })).join("\n\n");
+  return { ids, text, skipped, why, source };
+}
+
+// The upgrade brief for one section. Plain data in, markdown out (tests call it directly).
+export function upgradeBrief({ route, section, measured, agent, moves, signature, sourceFiles = [], crop, scoreLine, verifyCmd }) {
+  const low = RUBRIC.filter((r) => (agent?.scores?.[r.id] ?? measured.scores?.[r.id]) != null).sort((a, b) => (agent?.scores?.[a.id] ?? measured.scores[a.id]) - (agent?.scores?.[b.id] ?? measured.scores[b.id]));
+  const high = low.slice().reverse().filter((r) => (agent?.scores?.[r.id] ?? measured.scores[r.id]) >= 7);
+  return [
+    `# Upgrade one section: ${section.name} (section ${section.index} of ${route})`,
+    "",
+    scoreLine,
+    crop ? `Crop: ${slash(crop)}` : null,
+    sourceFiles.length ? `Source: ${sourceFiles.map(slash).join(", ")}` : `Source: find the component that renders "${section.heading ?? section.name}" (\`${section.selector}\`).`,
+    "",
+    "## What's generic",
+    ...(agent?.generic ? [`- You saw: ${agent.generic}`] : []),
+    ...(measured.flags.length ? measured.flags.map((f) => `- Measured: ${f}`) : ["- Nothing measurable stands out; the rubric scores say where it falls short."]),
+    `- Lowest on the rubric: ${low.slice(0, 3).map((r) => `${r.label} ${agent?.scores?.[r.id] ?? measured.scores[r.id]}/10`).join(", ")}.`,
+    signature ? `- The signature move "${signature.name}"${signature.what ? ` (${signature.what})` : ""}: ${section.signature ? "is here; make it the moment of this section" : "isn't in this section; bring it here if this is where it belongs"}.` : null,
+    "",
+    "## Moves that could lift it (use one; two only if they work together)",
+    moves.why && Object.keys(moves.why).length ? `What this user did with these before: ${Object.entries(moves.why).map(([id, w]) => `${id}: ${w}`).join("; ")}.` : null,
+    moves.skipped?.length ? `Left out because the user undid them before: ${moves.skipped.join(", ")}.` : null,
+    moves.text || "No moves library found: make one structural change that only this product could make.",
+    "",
+    "## Keep",
+    "- The section's job and its content: every fact, name and number stays (all from the project).",
+    ...(agent?.keep ? [`- ${agent.keep}`] : []),
+    ...high.map((r) => `- What already works: ${r.label.toLowerCase()} (${agent?.scores?.[r.id] ?? measured.scores[r.id]}/10).`),
+    "- The project's tokens and components, the user's rules, every other section exactly as it is, and every state (loading, empty, error) the section has.",
+    "",
+    "## Do it once",
+    "- Upgrade this one section, once, without asking the user: this is part of the finishing pass. Ask only if two moves above pull in clearly different directions and the choice is a matter of taste; then show both ideas in one line each and let them choose.",
+    `- Then: \`${verifyCmd}\` (add \`--moves <id>\` with the move you used, so palate learns what this user keeps).`,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}
+
+// ---- rendering helpers
+const dataUri = (f) => `data:image/${/\.jpe?g$/i.test(f) ? "jpeg" : /\.webp$/i.test(f) ? "webp" : "png"};base64,${fs.readFileSync(f).toString("base64")}`;
+// A 16×10 grid of a picture's top (1.6:1): ink against its own background and mean colour per cell, the same
+// shape as the layout memory's thumbnails, so visualSimilarity compares them. Decoded by the browser (JPEG too).
+const GRID = `async (src) => {
+  const img = new Image(); img.src = src; await img.decode();
+  const W = 320, H = 200, cols = 16, rows = 10;
+  const c = document.createElement("canvas"); c.width = W; c.height = H;
+  const g = c.getContext("2d", { willReadFrequently: true });
+  const sh = Math.min(img.naturalHeight, img.naturalWidth / 1.6);
+  g.fillStyle = "#fff"; g.fillRect(0, 0, W, H);
+  g.drawImage(img, 0, 0, img.naturalWidth, sh, 0, 0, W, H * (sh / (img.naturalWidth / 1.6)));
+  const d = g.getImageData(0, 0, W, H).data;
+  const counts = new Map();
+  for (let i = 0; i < d.length; i += 12) { const k = ((d[i] >> 3) << 10) | ((d[i + 1] >> 3) << 5) | (d[i + 2] >> 3); counts.set(k, (counts.get(k) || 0) + 1); }
+  const mode = [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+  const bg = [(mode >> 10) << 3, ((mode >> 5) & 31) << 3, (mode & 31) << 3];
+  const ink = [], rgb = [];
+  for (let gy = 0; gy < rows; gy++) for (let gx = 0; gx < cols; gx++) {
+    let r = 0, gg = 0, b = 0, n = 0, k = 0;
+    for (let y = gy * 20; y < gy * 20 + 20; y += 2) for (let x = gx * 20; x < gx * 20 + 20; x += 2) {
+      const i = (y * W + x) * 4; r += d[i]; gg += d[i + 1]; b += d[i + 2]; n++;
+      if (Math.abs(d[i] - bg[0]) + Math.abs(d[i + 1] - bg[1]) + Math.abs(d[i + 2] - bg[2]) > 36) k++;
+    }
+    ink.push(Math.round((100 * k) / n)); rgb.push(Math.round(r / n), Math.round(gg / n), Math.round(b / n));
+  }
+  return { ink, rgb };
+}`;
+async function pictureGrids(browser, files) {
+  const page = await browser.newPage();
+  try {
+    const out = [];
+    for (const f of files) out.push(f && fs.existsSync(f) ? await page.evaluate(`(${GRID})(${JSON.stringify(dataUri(f))})`).catch(() => null) : null);
+    return out;
+  } finally {
+    await page.close().catch(() => {});
+  }
+}
+
+// The newest build loop for this route: its job and tags (what the product is).
+function buildLoop(dir, route) {
+  const base = path.join(dir, ".palate", "variants");
+  if (!fs.existsSync(base)) return null;
+  return fs.readdirSync(base).map((n) => readJson(path.join(base, n, "loop.json"), null)).filter((m) => m && m.route === route).sort((a, b) => String(b.created).localeCompare(String(a.created)))[0] ?? null;
+}
+
+// The source files that render a section, found by its heading text.
+function sourceOf(dir, section) {
+  const head = (section.heading ?? "").replace(/[’']/g, "'").trim();
+  if (!head) return [];
+  const probes = [head.slice(0, 32), head.split(/\s+/).slice(0, 3).join(" ")].filter((p) => p.length >= 6);
+  const roots = ["src", "app", "pages", "components"].map((r) => path.join(dir, r)).filter((r) => fs.existsSync(r));
+  const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.name === "node_modules" || e.name.startsWith(".") ? [] : e.isDirectory() ? walk(path.join(d, e.name)) : /\.(tsx|jsx|vue|svelte|astro|html|mdx)$/.test(e.name) ? [path.join(d, e.name)] : []));
+  const files = roots.flatMap(walk);
+  for (const p of probes) {
+    const hits = files.filter((f) => fs.readFileSync(f, "utf8").replace(/&apos;|&#39;|’/g, "'").replace(/\s+/g, " ").includes(p));
+    if (hits.length) return hits.slice(0, 2);
+  }
+  return [];
+}
+
+const isChrome = (s) => ["header", "nav", "footer"].includes(s.tag) || /^(header|footer|navigation)$/i.test(s.name ?? "");
+
+// The newest ambition session for a route.
+function latestSession(dir, route) {
+  const base = path.join(dir, ".palate", "ambition", slugOf(route));
+  if (!fs.existsSync(base)) return null;
+  const s = fs.readdirSync(base).filter((d) => fs.existsSync(path.join(base, d, "ambition.json"))).sort().at(-1);
+  return s ? path.join(base, s) : null;
+}
+
+// Earlier upgrades on this route: still there (kept), undone (reverted), or pinned again (pointed).
+function checkOutcomes(dir, route, sections, grids) {
+  const project = path.basename(path.resolve(dir));
+  const pointLog = path.join(TASTE_DIR, "point.jsonl");
+  const points = fs.existsSync(pointLog) ? fs.readFileSync(pointLog, "utf8").split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter((p) => p && p.kind === "point-request") : [];
+  const lines = [];
+  for (const u of upgrades({ project, route }).filter((x) => x.outcome === "pending")) {
+    const age = Date.now() - Date.parse(u.at);
+    const sel = u.section?.selector ?? "";
+    const pinned = points.find((p) => p.project === project && p.route === route && p.at > u.at && sel && (p.selector ?? "").startsWith(sel));
+    if (pinned) {
+      setOutcome(u.id, "pointed", { pin: pinned.id });
+      lines.push(`- Your upgrade of "${u.section?.name}" (${u.moves?.[0] ?? "a move"}) was pointed at again (pin ${pinned.id}).`);
+      continue;
+    }
+    if (age < 10 * 60_000) continue;
+    const i = sections.findIndex((s) => (u.section?.heading && s.heading === u.section.heading) || s.selector === sel);
+    const g = i >= 0 ? grids[i] : null;
+    const toAfter = g && u.afterGrid ? visualSimilarity(g, u.afterGrid) : null;
+    const toBefore = g && u.beforeGrid ? visualSimilarity(g, u.beforeGrid) : null;
+    const outcome = i < 0 ? "reverted" : toAfter != null && toAfter >= 0.8 && toAfter >= (toBefore ?? 0) ? "kept" : toBefore != null && toBefore > (toAfter ?? 0) + 0.05 ? "reverted" : null;
+    if (outcome) {
+      setOutcome(u.id, outcome);
+      lines.push(`- Your earlier upgrade of "${u.section?.name}" (${u.moves?.[0] ?? "a move"}): ${outcome}.`);
+    }
+  }
+  return lines;
+}
+
+// References for each row of the sheet: research captures, else the user's own, else palate's library.
+async function referencesFor(dir, rows, { research, job }) {
+  const { searchLibrary } = await import("./library.mjs");
+  // The library's best-rated entries of this kind first (it is mostly component libraries: the bar, not the goal).
+  const lib = (kind, n = 3) => searchLibrary(kind, { n: 12, preferWhole: true }).filter((r) => fs.existsSync(path.join(LIB_DIR, "thumbs", `${r.id}.jpg`))).sort((a, b) => (b.quality ?? 1) - (a.quality ?? 1)).slice(0, n).map((r) => ({ caption: `library · ${r.source}`, file: path.join(LIB_DIR, "thumbs", `${r.id}.jpg`), id: r.id }));
+  const mine = research?.refs?.length ? [] : rememberedRefs(job ?? "landing", { limit: 3 }).map((r) => ({ caption: `your reference · ${r.source}`, file: (r.files ?? []).find((f) => /fold|\.png$|\.jpe?g$/i.test(f) && fs.existsSync(f)) })).filter((r) => r.file);
+  return rows.map((row) => {
+    if (research?.refs?.length) {
+      const kw = words(row.kind).filter((w) => !["section", "marketing"].includes(w));
+      const bySection = research.refs.flatMap((r) => r.sections.filter((s) => kw.some((w) => words(`${s.kind} ${s.name}`).includes(w))).map((s) => ({ caption: `research · ${r.name} · ${s.name}`, file: s.file })));
+      if (row.first) return research.refs.filter((r) => r.fold).slice(0, 3).map((r) => ({ caption: `research · ${r.name}`, file: r.fold }));
+      if (bySection.length) return bySection.slice(0, 3);
+    }
+    if (row.first && mine.length) return mine.slice(0, 3);
+    return lib(row.kind);
+  });
+}
+
+// ---- the pass
+export async function ambition(dir, rawRoute, { url, scores, verify = false, moves } = {}) {
+  const route = normalizeRoute(rawRoute);
+  if (verify) return verifyAmbition(dir, route, { url, moves });
+  if (scores) return scoreAmbition(dir, route, scores);
+  return runAmbition(dir, route, { url });
+}
+
+async function runAmbition(dir, route, { url }) {
+  const session = path.join(dir, ".palate", "ambition", slugOf(route), stamp());
+  const cropDir = path.join(session, "sections");
+  fs.mkdirSync(cropDir, { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+  const loop = buildLoop(dir, route);
+  const research = readResearch(dir);
+  // The signature move: the research step's chosen direction, else the build's direction ({ move, moment }).
+  const signature = research?.signature ?? normSignature(loop?.direction?.signature) ?? (loop?.direction?.idea ? { name: loop.direction.idea } : null);
+  const job = loop?.job ?? "";
+
+  const r = await withBrowser(dir, { url }, async ({ base, browser }) => {
+    const { page, ctx } = await openPage(browser, base, route, { width: 1440 });
+    try {
+      const sections = await findSections(page);
+      const crops = await cropSections(page, sections, cropDir, "w1440");
+      const measures = await page.evaluate(`(${ambitionScript})(${JSON.stringify({ sections, signature })})`);
+      const fp = await page.evaluate(`(${fingerprintScript})()`).catch(() => null);
+      const full = path.join(session, "full-1440.png");
+      await shootFull(page, full);
+      await page.evaluate(() => window.scrollTo({ top: 0, behavior: "instant" }));
+      await page.waitForTimeout(300);
+      const fold = path.join(session, "fold-1440.png");
+      await page.screenshot({ path: fold });
+      // What each section is, for the library and the references.
+      const firstContent = crops.find((s) => !isChrome(s))?.index;
+      const rows = crops.map((s) => ({ ...s, kind: measures.sections.find((m) => m.index === s.index)?.productUI && s.index !== firstContent ? "mockup product showcase marketing section" : sectionKind(s, { first: s.index === firstContent, media: (measures.sections.find((m) => m.index === s.index)?.mediaShare ?? 0) > 0.3 }), measures: measures.sections.find((m) => m.index === s.index) }));
+      const refRows = await referencesFor(dir, [{ first: true, kind: "hero section" }, ...rows.filter((s) => !isChrome(s)).map((s) => ({ kind: s.kind }))], { research, job });
+      // Template-ness: each section against stock library sections of its kind, as pictures.
+      const { searchLibrary } = await import("./library.mjs");
+      const libFor = rows.map((s) => searchLibrary(s.kind, { n: 8, preferWhole: true }).filter((x) => fs.existsSync(path.join(LIB_DIR, "thumbs", `${x.id}.jpg`))).slice(0, 6));
+      const libFiles = [...new Set(libFor.flat().map((x) => path.join(LIB_DIR, "thumbs", `${x.id}.jpg`)))];
+      const grids = await pictureGrids(browser, [...rows.map((s) => s.file), ...libFiles]);
+      const cropGrids = grids.slice(0, rows.length);
+      const libGrid = Object.fromEntries(libFiles.map((f, i) => [f, grids[rows.length + i]]));
+      rows.forEach((s, i) => {
+        const sims = libFor[i].map((x) => ({ id: x.id, source: x.source, sim: visualSimilarity(cropGrids[i], libGrid[path.join(LIB_DIR, "thumbs", `${x.id}.jpg`)]) ?? 0 })).sort((a, b) => b.sim - a.sim);
+        s.lib = sims[0] ?? null;
+        s.grid = cropGrids[i];
+      });
+      const outcomes = checkOutcomes(dir, route, rows, cropGrids);
+      // The side-by-side sheets: the first screen, then each content section, next to its references.
+      const sigLabel = signature ? ` · signature: ${signature.name}` : " · no signature move chosen";
+      await contactSheet(browser, [{ label: `First screen${sigLabel}`, cells: [{ caption: "ours", file: fold }, ...refRows[0]] }], path.join(session, "first-screen.png"), { cell: 460, maxCell: 300 });
+      const content = rows.filter((s) => !isChrome(s));
+      await contactSheet(browser, content.map((s, i) => ({ label: `S${s.index} · ${s.name.slice(0, 50)} · ${s.kind}`, cells: [{ caption: "ours", file: s.file }, ...refRows[i + 1]] })), path.join(session, "sections-side-by-side.png"), { cell: 420, maxCell: 520 });
+      return { sections: rows, measures, fp, fold, full, refRows, outcomes };
+    } finally {
+      await ctx.close().catch(() => {});
+    }
+  });
+
+  // The gate, on this render (the page isn't done while it fails).
+  let gate = null;
+  if (r.fp?.skeleton?.length) {
+    gate = similarityGate(dir, route, layoutRecord(dir, route, r.fp, { file: r.fold, source: "screen" }));
+    saveGate(dir, route, gate);
+  }
+  const colour = colourCheck(r.measures.page.accent, dir);
+  // Found (data-signature, its selector or words), missing (it could have been found), or unknown (nothing to look for).
+  const sigFound = !signature ? null : r.measures.sections.some((m) => m.signature) ? true : signature.selector || signature.words?.length ? false : null;
+  const firstContent = r.sections.find((s) => !isChrome(s))?.index;
+  const sections = r.sections.map((s) => {
+    const m = measuredScores(s.measures, { libSim: s.lib?.sim ?? null, signature });
+    // A signature found nowhere counts against the first screen, where it should land first.
+    if (signature && sigFound === false && s.index === firstContent) {
+      m.scores.signature = 2;
+      m.flags.push(`the signature move "${signature.name}" isn't on the page`);
+      m.mean = r1(mean(Object.values(m.scores)));
+    }
+    return { index: s.index, name: s.name, tag: s.tag, selector: s.selector, heading: s.heading, kind: s.kind, height: s.box.height, crop: s.file, grid: s.grid, lib: s.lib, measures: s.measures, measured: m, final: m.mean };
+  });
+  const state = { route, at: new Date().toISOString(), session, job, signature, sigFound, research: research?.file ?? null, colour, gate: gate ? { pass: gate.pass, lines: gateLines(gate, route) } : null, fold: r.fold, full: r.full, sections, outcomes: r.outcomes };
+  const weakest = pickWeakest(sections);
+  state.weakest = weakest?.index ?? null;
+  fs.writeFileSync(path.join(session, "ambition.json"), JSON.stringify(state, null, 1));
+  const brief = weakest ? await writeBrief(dir, state, weakest, null) : null;
+  return sheetText(state, { brief, provisional: true });
+}
+
+async function writeBrief(dir, state, weakest, agent) {
+  const loopTags = kindTags({ route: state.route, words: state.job });
+  const weak = RUBRIC.filter((r) => (agent?.scores?.[r.id] ?? weakest.measured.scores[r.id]) != null)
+    .sort((a, b) => (agent?.scores?.[a.id] ?? weakest.measured.scores[a.id]) - (agent?.scores?.[b.id] ?? weakest.measured.scores[b.id]))
+    .slice(0, 2)
+    .map((r) => r.id);
+  if (state.colour?.score != null && state.colour.score < 4) weak.push("colour");
+  const moves = await movesFor({ tags: [...loopTags, ...words(state.job)], kind: loopTags.includes("app") && !loopTags.includes("marketing") ? "app" : "marketing", signature: state.signature, weak, sectionKind: weakest.kind, words: `${weakest.name} ${weakest.heading ?? ""}` });
+  const median = mean(state.sections.filter((s) => s.final != null && !isChrome(s)).map((s) => s.final));
+  const text = upgradeBrief({
+    route: state.route,
+    section: { ...weakest, signature: weakest.measures?.signature },
+    measured: weakest.measured,
+    agent,
+    moves,
+    signature: state.signature,
+    sourceFiles: sourceOf(dir, weakest),
+    crop: weakest.crop,
+    scoreLine: `Score ${weakest.final}/10 (${agent ? "your rubric 70%, palate's measures 30%" : "palate's measures only: score the sheet to confirm"}); the page's sections average ${r1(median)}.`,
+    verifyCmd: `palate ambition ${state.route} --verify`,
+  });
+  const file = path.join(state.session, "upgrade.md");
+  fs.writeFileSync(file, text);
+  const st = readJson(path.join(state.session, "ambition.json"), state);
+  fs.writeFileSync(path.join(state.session, "ambition.json"), JSON.stringify({ ...st, weakest: weakest.index, offered: moves.ids, agent: agent ? true : st.agent ?? false }, null, 1));
+  return { file, text, moves };
+}
+
+function sheetText(state, { brief, provisional }) {
+  const s = state.session;
+  const scoresFile = path.join(s, "scores.json");
+  const row = (x) => `- S${x.index} **${x.name}** (${x.kind}) · ${x.final ?? "–"}/10 · ${RUBRIC.filter((r) => x.measured.scores?.[r.id] != null).map((r) => `${r.id} ${x.measured.scores[r.id]}`).join(", ")}${x.lib ? ` · stock-likeness ${pct(x.lib.sim)}` : ""}${x.measured.flags.length ? `\n    ${x.measured.flags.join("; ")}` : ""}\n    crop: ${slash(x.crop)}`;
+  const content = state.sections.filter((x) => !isChrome(x));
+  return [
+    `# Ambition: ${state.route}`,
+    "",
+    "Correct isn't the bar; remarkable is. Look at the sheets, score every section, upgrade the weakest once. Don't ask the user: this is part of the finishing pass.",
+    "",
+    ...(state.gate && !state.gate.pass ? [...state.gate.lines, "Fix the similarity gate first: it's the bigger upgrade, and the page isn't done while it fails.", ""] : state.gate ? [state.gate.lines[0], ""] : []),
+    "## Look",
+    `- First screen beside its references: ${slash(path.join(s, "first-screen.png"))}`,
+    `- Every section beside references of its kind: ${slash(path.join(s, "sections-side-by-side.png"))}`,
+    `- Full page: ${slash(state.full)}`,
+    `- References from: ${state.research ? `the research step (${slash(state.research)})` : "your saved references and palate's library (no research.json for this project)"}.`,
+    `- Signature move: ${state.signature ? `${state.signature.name}${state.signature.what ? `: ${state.signature.what}` : ""} (${state.sigFound ? "found on the page" : state.sigFound === false ? "not found on the page" : "palate can't locate it: the builder should mark its element with data-signature; judge it on the sheet"})` : "none chosen. The upgrade brief proposes moves instead."}`,
+    `- Colour: ${state.colour.line}`,
+    ...(state.outcomes?.length ? ["", "## Earlier upgrades", ...state.outcomes] : []),
+    "",
+    "## Measured (palate's scores, 0–10; it can't see everything)",
+    ...content.map(row),
+    "",
+    "## Score every section yourself (strict: 5 is competent, 8 is a section a designer would save)",
+    ...RUBRIC.map((r) => `- ${r.id}: ${r.q}`),
+    `Write ${slash(scoresFile)}:`,
+    "```json",
+    JSON.stringify({ sections: content.slice(0, 2).map((x) => ({ index: x.index, scores: Object.fromEntries(RUBRIC.map((r) => [r.id, r.id === "signature" ? null : 5])), generic: "what reads as template here", keep: "what already works" })) }),
+    "```",
+    `Then: palate ambition ${state.route} --scores ${slash(scoresFile)}   (no re-render: it picks the weakest from your scores and writes the upgrade brief)`,
+    "",
+    brief
+      ? `## Weakest section${provisional ? " (from palate's measures; your scores decide)" : ""}: S${state.weakest}\nUpgrade brief: ${slash(brief.file)}${provisional ? "" : `\n\n${brief.text}`}`
+      : "No content section to upgrade.",
+  ].join("\n");
+}
+
+async function scoreAmbition(dir, route, input) {
+  const session = latestSession(dir, route);
+  if (!session) throw new Error(`No ambition sheet for ${route} yet. Run palate ambition ${route} first.`);
+  const state = readJson(path.join(session, "ambition.json"), null);
+  const agent = readAgentScores(input);
+  for (const s of state.sections) {
+    s.agent = agent[s.index] ?? null;
+    s.final = combine(s.measured.mean, s.agent?.scores);
+  }
+  const weakest = pickWeakest(state.sections);
+  state.weakest = weakest?.index ?? null;
+  fs.writeFileSync(path.join(session, "ambition.json"), JSON.stringify(state, null, 1));
+  if (!weakest) return "No content section to upgrade.";
+  const brief = await writeBrief(dir, state, weakest, weakest.agent);
+  const ranked = state.sections.filter((s) => s.final != null && !isChrome(s)).sort((a, b) => a.final - b.final);
+  return [
+    `# Ambition: ${route}, scored`,
+    "",
+    ...ranked.map((s) => `- S${s.index} ${s.name}: ${s.final}/10${s.agent ? "" : " (palate's measures only: you didn't score it)"}`),
+    "",
+    `Weakest: S${weakest.index} ${weakest.name}. Brief: ${slash(brief.file)}`,
+    "",
+    brief.text,
+  ].join("\n");
+}
+
+async function verifyAmbition(dir, route, { url, moves: used } = {}) {
+  const session = latestSession(dir, route);
+  if (!session) throw new Error(`No ambition sheet for ${route} yet. Run palate ambition ${route} first.`);
+  const state = readJson(path.join(session, "ambition.json"), null);
+  const before = state.sections.find((s) => s.index === state.weakest);
+  if (!before) throw new Error(`No weakest section recorded for ${route}. Run palate ambition ${route} again.`);
+  const r = await withBrowser(dir, { url }, async ({ base, browser }) => {
+    const { page, ctx } = await openPage(browser, base, route, { width: 1440 });
+    try {
+      const sections = await findSections(page);
+      const s = sections.find((x) => before.heading && x.heading === before.heading) ?? sections.find((x) => x.selector === before.selector) ?? sections.find((x) => x.name === before.name) ?? sections.find((x) => x.index === before.index);
+      if (!s) throw new Error(`Section "${before.name}" is no longer on ${route}.`);
+      const [crop] = await cropSections(page, [s], path.join(session, "after"), "w1440");
+      const measures = await page.evaluate(`(${ambitionScript})(${JSON.stringify({ sections: [s], signature: state.signature })})`);
+      const fp = await page.evaluate(`(${fingerprintScript})()`).catch(() => null);
+      await page.evaluate(() => window.scrollTo({ top: 0, behavior: "instant" }));
+      await page.waitForTimeout(300);
+      const fold = path.join(session, "after", "fold-1440.png");
+      await page.screenshot({ path: fold });
+      const libFiles = before.lib ? [path.join(LIB_DIR, "thumbs", `${before.lib.id}.jpg`)] : [];
+      const [g, ...lg] = await pictureGrids(browser, [crop.file, ...libFiles]);
+      const sheet = path.join(session, "before-after.png");
+      await contactSheet(browser, [{ label: `S${before.index} · ${before.name}`, cells: [{ caption: "before", file: before.crop }, { caption: "after", file: crop.file }] }], sheet, { cell: 640, maxCell: 900 });
+      return { s, crop: crop.file, measures: measures.sections[0], fp, fold, grid: g, libSim: lg[0] ? visualSimilarity(g, lg[0]) : null, sheet };
+    } finally {
+      await ctx.close().catch(() => {});
+    }
+  });
+  const after = measuredScores(r.measures, { libSim: r.libSim, signature: state.signature });
+  let gate = null;
+  if (r.fp?.skeleton?.length) {
+    gate = similarityGate(dir, route, layoutRecord(dir, route, r.fp, { file: r.fold, source: "screen" }));
+    saveGate(dir, route, gate);
+  }
+  const moves = used?.length ? used : (state.offered ?? []).slice(0, 1);
+  const rec = logGrowth({
+    type: "upgrade",
+    id: `${path.basename(session)}-s${before.index}`,
+    project: path.basename(path.resolve(dir)),
+    route,
+    section: { name: before.name, heading: r.s.heading, selector: r.s.selector, index: before.index },
+    sectionKind: before.kind,
+    moves,
+    guessed: !used?.length,
+    before: before.crop,
+    after: r.crop,
+    beforeGrid: before.grid ?? null,
+    afterGrid: r.grid,
+    scoresBefore: before.measured.scores,
+    scoresAfter: after.scores,
+    final: { before: before.final, after: after.mean },
+  });
+  const delta = (k) => {
+    const [a, b] = [before.measured.scores[k], after.scores[k]];
+    return a == null && b == null ? null : `${RUBRIC.find((x) => x.id === k).label} ${a ?? "–"} → ${b ?? "–"}`;
+  };
+  return [
+    `# Ambition verify: ${route}, S${before.index} ${before.name}`,
+    "",
+    `- Before | after: ${slash(r.sheet)}`,
+    `- palate's measures: ${before.measured.mean ?? "–"} → ${after.mean ?? "–"}/10 (${RUBRIC.map((x) => delta(x.id)).filter(Boolean).join("; ")}).`,
+    before.lib && r.libSim != null ? `- Stock-likeness: ${pct(before.lib.sim)} → ${pct(r.libSim)}.` : null,
+    after.flags.length ? `- Still measured: ${after.flags.join("; ")}.` : "- Nothing generic measured any more.",
+    gate ? (gate.pass ? "- Similarity gate: pass." : `- Similarity gate still fails: ${gateLines(gate, route)[1].replace(/^- ✗ /, "")} Run palate shoot ${route} for what to change.`) : null,
+    `- Logged: upgrade with ${moves.length ? moves.join(", ") : "no named move"}${rec.guessed ? " (guessed: pass --moves <id> to name the move you used)" : ""}. palate checks later whether the user keeps it.`,
+    "",
+    "Open the before | after and score the after on the rubric yourself. If it isn't clearly better, revert to the before. One upgrade per finishing pass: don't start another section.",
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}