@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/similar.mjs

@@ -0,0 +1,276 @@
+// The similarity gate: a page may not look like the user's other projects, or copy a reference captured for it.
+// Repeating your own last look is the quiet way AI output converges. Used by palate shoot (it fails), palate
+// ambition and palate check (a page isn't done while it fails). The agent fixes it; it isn't a question for
+// the user, unless they asked to match another project (--like <project>, or "match <project>" in the job).
+import fs from "node:fs";
+import path from "node:path";
+import { readJson } from "./common.mjs";
+import { ARCH_NAME, compare, describe, firstScreenSimilarity, isBenchRecord, pngThumb, projectId, readLayouts, sameScreen, screenKindOf, shapeOf, skeletonSimilarity, structuralSimilarity, styleSimilarity, visualSimilarity } from "./layouts.mjs";
+import { logGate } from "./growth.mjs";
+import { MATCHED_NOTE, matchedRoute } from "./matched.mjs";
+
+// Thresholds on compare()'s 0–1 scale, measured on this machine's layout memory (50 screens, Oct 26 2026):
+// 290 pairs of screens of the same group (marketing or app) made independently in different projects score
+// median 0.23, 95th percentile 0.41, 99th 0.47, highest 0.51 (a pricing page against a landing variant). The
+// Tidepool landing that reused palate-site's emerald, centred hero and section rhythm scored 0.69. 0.50 sits
+// above 99% of independent pairs and well below that repeat (and below SIMILAR, 0.60, where shoot only warned).
+export const GATE = 0.5;
+// A captured reference is someone else's product, so the bar is stricter: about the independent pairs' 95th
+// percentile (0.41). A reference with only a screenshot (no fingerprint) is judged as a picture: its first
+// screen alike above 0.72 (98% of independent pairs score lower) and its type and colour alike too.
+export const REF_GATE = 0.42;
+// Structure alone (structuralSimilarity: no colour), against the user's other projects. On the layout memory
+// (Oct 27 2026, 321 pairs of independently made screens): median 0.12, 95th percentile 0.44, 99th 0.48. Kiln,
+// which passed the colour-inclusive gate at 50% by repainting itself sage, scored 0.46–0.48 against six
+// palate-site pages: the same skeleton in a new colour. 0.45 catches that and passes 95% of independent pairs.
+export const STRUCTURE_GATE = 0.45;
+export const REF_PICTURE_GATE = 0.72;
+
+const pct = (v) => `${Math.round((v ?? 0) * 100)}%`;
+// A score beside its gate, with a decimal when whole percents would make them look equal (49.6% vs a 50% gate).
+const pctBy = (v, gate) => (Math.round((v ?? 0) * 100) === Math.round(gate * 100) ? `${((v ?? 0) * 100).toFixed(1)}%` : pct(v));
+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]);
+const weightWord = (w) => (w <= 300 ? "light" : w <= 450 ? "regular" : w <= 650 ? "semibold" : "heavy");
+const headWords = (h) => (h ? `${h.size}px ${weightWord(h.weight)}${h.align === "center" ? " centred" : ""}` : "?");
+export const whereKey = (r) => `${r.project} ${r.route}`;
+const group = (kind) => (kind === "app" ? "app" : "marketing");
+
+// Why two screens are alike, part by part (0–1 each, most alike first), with what to change.
+export function whySimilar(a, b) {
+  const parts = [];
+  if (a.skeleton?.length && b.skeleton?.length)
+    parts.push({ id: "skeleton", label: "page skeleton", score: skeletonSimilarity(a.skeleton, b.skeleton), same: `${a.skeleton.length} bands vs ${b.skeleton.length}, in nearly the same order (${a.skeleton.join(" ")} | ${b.skeleton.join(" ")})`, change: "a different section rhythm: change the order and number of bands and how each is built (not every section a heading over a grid of cards)" });
+  if (a.shape && b.shape) {
+    const fs1 = firstScreenSimilarity(a.firstScreen, b.firstScreen) ?? 0;
+    const same = a.shape === b.shape;
+    const alt = a.shape === "centred" ? "a left-led or split first screen, or the product itself as the hero" : `a first screen that isn't ${ARCH_NAME[b.shape] ?? b.shape}`;
+    parts.push({ id: "hero", label: "hero structure", score: (same ? 0.6 : 0) + 0.4 * fs1, same: `${ARCH_NAME[a.shape] ?? a.shape} vs ${ARCH_NAME[b.shape] ?? b.shape}; headline ${headWords(a.style?.headline)} vs ${headWords(b.style?.headline)}`, change: `${alt}, built from this product's own metaphor` });
+  }
+  const sa = a.style ?? {}, sb = b.style ?? {};
+  const pal = [];
+  const [aa, ab] = [hexRgb(sa.accent), hexRgb(sb.accent)];
+  if (aa && ab) pal.push(1 - Math.min(1, dist(aa, ab) / 150));
+  const [ba, bb] = [hexRgb(sa.bg), hexRgb(sb.bg)];
+  if (ba && bb) pal.push(1 - Math.min(1, dist(ba, bb) / 120));
+  if (pal.length) parts.push({ id: "palette", label: "palette", score: pal.reduce((x, y) => x + y, 0) / pal.length, same: `accent ${sa.accent ?? "?"} vs ${sb.accent ?? "?"}, canvas ${sa.bg ?? "?"} vs ${sb.bg ?? "?"}`, change: `this product's own colour, from its name, users and direction${sb.accent ? ` (not ${sb.accent})` : ""}` });
+  const fa = (sa.fonts ?? []).map((f) => f.toLowerCase()), fb = (sb.fonts ?? []).map((f) => f.toLowerCase());
+  const type = [];
+  if (fa.length && fb.length) type.push(fa.filter((f) => fb.includes(f)).length / new Set([...fa, ...fb]).size);
+  if (sa.headline && sb.headline) {
+    type.push(1 - Math.min(1, (2 * Math.abs(sa.headline.size - sb.headline.size)) / Math.max(sa.headline.size, sb.headline.size)));
+    type.push(1 - Math.min(1, Math.abs(sa.headline.weight - sb.headline.weight) / 400));
+  }
+  if (type.length) parts.push({ id: "type", label: "type", score: type.reduce((x, y) => x + y, 0) / type.length, same: `${(sa.fonts ?? []).join(" + ") || "?"} vs ${(sb.fonts ?? []).join(" + ") || "?"}; headline ${headWords(sa.headline)} vs ${headWords(sb.headline)}`, change: "a display face, weight and scale with this product's character (not the same family at the same size and weight)" });
+  const vis = visualSimilarity(a.thumb, b.thumb);
+  if (vis != null) parts.push({ id: "picture", label: "first screen as a picture", score: vis, same: "content sits in the same places, in the same colours", change: "follows from changing the first screen's structure and colour" });
+  return parts.sort((x, y) => y.score - x.score);
+}
+
+// ---- what the user asked to match
+// "match palate-site", "like palate-site", "same look as palate-site", "consistent with palate-site": only
+// names of projects palate knows count.
+export function matchNote(text, projects) {
+  const t = String(text ?? "").toLowerCase();
+  return projects.filter((p) => new RegExp(`\\b(match(es|ing)?|like|same (look|style|design|feel) as|consistent with|in the style of|the look of)\\s+(the\\s+)?${p.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`).test(t));
+}
+
+const knownProjects = () => [...new Set(readLayouts().map((r) => r.project))];
+
+// The newest build loop for this route: its like list and its job's match note.
+export function likeOf(dir, route) {
+  const base = path.join(dir, ".palate", "variants");
+  if (!fs.existsSync(base)) return [];
+  const loops = fs.readdirSync(base).map((n) => readJson(path.join(base, n, "loop.json"), null)).filter((m) => m && m.mode === "build" && m.route === route).sort((a, b) => String(b.created).localeCompare(String(a.created)));
+  const m = loops[0];
+  if (!m) return [];
+  return [...new Set([...(m.like ?? []), ...matchNote(m.job, knownProjects())])];
+}
+
+// ---- research.json (the live research step), read defensively: field names vary between versions.
+const strings = (v) => (v == null ? [] : typeof v === "string" ? [v] : Array.isArray(v) ? v.flatMap(strings) : typeof v === "object" ? Object.values(v).flatMap(strings) : []);
+const hostOf = (u) => {
+  try {
+    return new URL(u).hostname.replace(/^www\./, "");
+  } catch {
+    return null;
+  }
+};
+export function readResearch(dir, { name } = {}) {
+  const base = path.join(dir, ".palate", "research");
+  if (!fs.existsSync(base)) return null;
+  const files = (name ? [name] : fs.readdirSync(base))
+    .map((n) => path.join(base, n, "research.json"))
+    .filter((f) => fs.existsSync(f))
+    .sort((a, b) => fs.statSync(b).mtimeMs - fs.statSync(a).mtimeMs);
+  if (!files.length) return null;
+  const file = files[0];
+  const j = readJson(file, null);
+  if (!j) return null;
+  const at = path.dirname(file);
+  const resolve = (p) => (!p || /^https?:/.test(p) ? null : path.isAbsolute(p) ? (fs.existsSync(p) ? p : null) : [path.join(at, p), path.join(dir, p)].find((f) => fs.existsSync(f)) ?? null);
+  const images = (v) => [...new Set(strings(v).filter((s) => /\.(png|jpe?g|webp)$/i.test(s)).map(resolve).filter(Boolean))];
+  // palate research keeps its references in `kept` (with their layout records); older shapes are read too.
+  const list = j.kept ?? j.references ?? j.refs ?? j.captured ?? j.captures ?? [];
+  const refs = (Array.isArray(list) ? list : Object.values(list)).map((r, i) => {
+    const shots = images([r.fold, r.screenshot, r.screenshots, r.shots, r.files, r.images, r.full, r.capture]);
+    const fold = shots.find((f) => /fold/i.test(f) && /\.png$/i.test(f)) ?? shots.find((f) => /\.png$/i.test(f)) ?? shots[0] ?? null;
+    const sections = (r.sections ?? []).map((s) => ({ kind: s.kind ?? s.name ?? "", name: s.name ?? s.kind ?? "", file: images([s.file, s.crop, s.screenshot, s.shot])[0] ?? null })).filter((s) => s.file);
+    return { id: r.id ?? `ref${i + 1}`, name: r.name ?? r.title ?? r.site ?? hostOf(r.url) ?? `reference ${i + 1}`, url: r.url ?? null, fold, shots, sections, layout: r.layout?.skeleton ? r.layout : null, fp: r.fingerprint ?? r.fp ?? null, measures: r.measures ?? r.measurements ?? null, notes: r.notes ?? r.why ?? r.take ?? r.works ?? null };
+  });
+  const d = j.direction ?? j.chosen ?? j.chosenDirection ?? j.choice ?? null;
+  const signature = normSignature(d?.signature ?? d?.signatureMove ?? d?.signature_move ?? j.signature ?? j.signatureMove ?? null);
+  return { file, name: path.basename(at), direction: d ? { name: d.name ?? d.title ?? null, summary: d.summary ?? d.why ?? d.what ?? null } : null, signature, refs, tags: j.tags ?? j.understanding?.tags ?? d?.tags ?? [], moves: j.moves ?? d?.moves ?? [] };
+}
+
+// A signature move in one shape: { name, what, move, selector, words }. Art directions write { move, moment }.
+export function normSignature(sig) {
+  if (!sig) return null;
+  if (typeof sig === "string") return { name: sig, move: sig };
+  return { name: sig.name ?? sig.title ?? sig.move ?? sig.id ?? "the signature move", what: sig.what ?? sig.moment ?? sig.description ?? sig.do ?? sig.summary ?? null, move: sig.move ?? sig.id ?? null, selector: sig.selector ?? null, words: sig.words ?? sig.keywords ?? null };
+}
+
+const rgbHex = (c) => {
+  const m = String(c ?? "").match(/[\d.]+/g);
+  if (!m || m.length < 3 || (m[3] != null && Number(m[3]) < 0.5)) return /^#[0-9a-f]{6}$/i.test(c ?? "") ? c : null;
+  return "#" + m.slice(0, 3).map((v) => Math.round(Number(v)).toString(16).padStart(2, "0")).join("");
+};
+// A reference as a layout record: its fingerprint when research kept one, else its measures and screenshot.
+export function refRecord(r, kind = "marketing") {
+  if (r.layout?.skeleton) return { ...r.layout, project: r.name, route: r.url ?? "" };
+  const thumb = r.fold && /\.png$/i.test(r.fold) ? pngThumb(r.fold) : null;
+  if (r.fp?.skeleton) return { project: r.name, route: r.url ?? "", skeleton: r.fp.skeleton, firstScreen: r.fp.firstScreen ?? null, shape: shapeOf(r.fp, kind), style: r.fp.style ?? null, thumb };
+  const m = r.measures?.[1440] ?? r.measures ?? null;
+  const style = m ? { fonts: m.fonts ?? [], headline: m.headline?.size ? { size: Math.round(parseFloat(m.headline.size)), weight: Number(m.headline.weight) || 400, align: m.headline.align ?? null } : null, bg: rgbHex(m.backgrounds?.[0] ?? m.bg), accent: rgbHex(m.accent) } : null;
+  if (!thumb && !style) return null;
+  return { project: r.name, route: r.url ?? "", skeleton: [], firstScreen: null, shape: null, style, thumb };
+}
+
+// ---- the gate
+// rec: this page as a layout record (layoutRecord). like: projects the user asked to match.
+export function similarityGate(dir, route, rec, { like = [] } = {}) {
+  // A route built from the user's own design (palate match) may look like anything, their other projects included.
+  if (matchedRoute(dir, route)) return { pass: true, exempt: true, screen: screenKindOf(rec), compared: 0, threshold: GATE, structureThreshold: STRUCTURE_GATE, refThreshold: REF_GATE, hits: [], refHits: [], matched: [], best: null, research: null, partsFor: () => null };
+  const pid = projectId(dir);
+  const likes = new Set([...like, ...likeOf(dir, route)].map((x) => String(x).toLowerCase()));
+  // Like against like: marketing pages against marketing pages (vary loops record a section kind, e.g. "hero"), app
+  // screens against app screens, and only the same kind of screen (a landing page against landing pages, not a
+  // three-band pricing variant: those skeletons can't be made unlike without breaking either page).
+  // Benchmark pages are palate's own test runs, not the user's projects: they don't count against a page.
+  const others = readLayouts().filter((h) => h.pid !== pid && !isBenchRecord(h) && group(h.kind) === group(rec.kind) && h.skeleton?.length && sameScreen(rec, h));
+  const scored = others.map((h) => ({ h, ...compare(rec, h), structural: structuralSimilarity(rec, h) })).sort((a, b) => Math.max(b.total, b.structural) - Math.max(a.total, a.structural));
+  const asked = (p) => likes.has(String(p).toLowerCase());
+  const over = (m) => m.total > GATE || m.structural > STRUCTURE_GATE;
+  // overall / structure: the two scores; overOverall / structural: which gate each one failed.
+  const hit = (m) => ({ where: whereKey(m.h), project: m.h.project, route: m.h.route, source: m.h.picked ? "picked" : m.h.source === "screen" ? "shipped" : "variant", at: m.h.at, total: m.structural > STRUCTURE_GATE && m.total <= GATE ? m.structural : m.total, overall: m.total, structure: m.structural, overOverall: m.total > GATE, structural: m.structural > STRUCTURE_GATE, parts: whySimilar(rec, m.h), look: describe(m.h) });
+  // One match per other project (its closest screen): three variants of one page are one problem.
+  const seen = new Set();
+  const hits = scored.filter((m) => over(m) && !asked(m.h.project) && !seen.has(m.h.project) && seen.add(m.h.project)).slice(0, 3).map(hit);
+  const matched = scored.filter((m) => asked(m.h.project)).slice(0, 1).map(hit);
+  const research = readResearch(dir);
+  const refHits = [];
+  for (const r of research?.refs ?? []) {
+    if (asked(r.name)) continue;
+    const rr = refRecord(r, rec.kind);
+    if (!rr) continue;
+    const c = compare(rec, rr);
+    const full = Boolean(rr.skeleton.length);
+    const style = styleSimilarity(rec.style, rr.style) ?? 0;
+    const over = full ? c.total > REF_GATE : (c.visual ?? 0) > REF_PICTURE_GATE && style >= 0.6;
+    if (over) refHits.push({ where: `reference ${r.name}`, project: r.name, route: r.url ?? "", source: "reference", total: full ? c.total : c.visual, parts: whySimilar(rec, rr), picture: !full });
+  }
+  const best = scored[0] ? { where: whereKey(scored[0].h), total: scored[0].total, structure: scored[0].structural } : null;
+  const pass = !hits.length && !refHits.length;
+  const partsFor = (where) => {
+    const m = scored.find((x) => whereKey(x.h) === where);
+    return m ? { total: m.total, parts: Object.fromEntries(whySimilar(rec, m.h).map((p) => [p.id, p.score])) } : null;
+  };
+  return { pass, screen: screenKindOf(rec), compared: others.length, threshold: GATE, structureThreshold: STRUCTURE_GATE, refThreshold: REF_GATE, hits, refHits, matched, best, research: research ? research.file : null, partsFor };
+}
+
+// The gate in words, for shoot, ambition and check. Every number says which gate it is measured against: the
+// overall gate (structure, picture, type and colour) at 50%, the structure gate (colour left out) at 45%, a
+// captured reference's gate at 42% (or 72% for its screenshot alone).
+export function gateLines(g, route) {
+  const overallGate = g.threshold ?? GATE, structureGate = g.structureThreshold ?? STRUCTURE_GATE;
+  const gates = `overall gate ${pct(overallGate)}, structure gate ${pct(structureGate)}`;
+  const kind = g.screen ? `${g.screen} screen` : "screen of this kind";
+  if (g.exempt) return [`## Similarity gate: not applied`, `- ${MATCHED_NOTE(route)}`];
+  if (g.pass)
+    return [
+      `## Similarity gate: pass`,
+      `- ${g.best ? `Closest ${kind} in another project: ${g.best.where}: ${pctBy(g.best.total, overallGate)} overall${g.best.structure != null ? `, ${pctBy(g.best.structure, structureGate)} in structure` : ""} (${gates}).` : `No ${kind}s in your other projects yet (${gates}; other kinds of screen aren't compared).`}${g.research ? " No captured reference is too close." : ""}`,
+      ...g.matched.map((m) => `- Matches ${m.where} (${pct(m.total)}), as asked: that project's look is allowed here.`),
+    ];
+  const out = [`## Similarity gate: FAIL (palate shoot fails until this passes; the page isn't done)`];
+  const item = (m, limit, gateName) => {
+    const close = m.parts.filter((p) => p.score >= 0.6);
+    const list = (close.length ? close : m.parts.slice(0, 2)).slice(0, 4);
+    const where = m.source === "reference" ? `${m.where}${m.picture ? " (its screenshot)" : ""}` : `${m.where} (${m.source}, ${String(m.at ?? "").slice(0, 10)}), another of your projects`;
+    const recolour = "A new colour won't fix this: change the skeleton, the first screen's shape and the section archetypes";
+    let score;
+    if (m.source === "reference") score = `${pctBy(m.total, limit)} like ${where}; the ${gateName} is ${pct(limit)}`;
+    else if (m.structural && m.overOverall) score = `${pctBy(m.overall, overallGate)} overall like ${where} (the overall gate is ${pct(overallGate)}) and ${pctBy(m.structure, structureGate)} in structure alone (the structure gate is ${pct(structureGate)}). ${recolour}`;
+    else if (m.structural) score = `${pctBy(m.structure ?? m.total, structureGate)} in structure alone (colour left out) like ${where} (the structure gate is ${pct(structureGate)}; overall ${pctBy(m.overall ?? m.total, overallGate)}, under its ${pct(overallGate)} gate). ${recolour}`;
+    else score = `${pctBy(m.overall ?? m.total, overallGate)} overall like ${where} (the overall gate is ${pct(overallGate)}; structure alone ${pctBy(m.structure ?? 0, structureGate)}, under its ${pct(structureGate)} gate)`;
+    return [
+      `- ✗ ${score}.`,
+      `  Too close: ${list.map((p) => `${p.label} ${pct(p.score)} (${p.same})`).join("; ")}.`,
+      `  Change: ${list.map((p, i) => `${i + 1}) ${p.change}`).join(" ")}`,
+    ];
+  };
+  for (const m of g.hits) out.push(...item(m, overallGate, "overall gate"));
+  for (const m of g.refHits) out.push(...item(m, m.picture ? REF_PICTURE_GATE : g.refThreshold, m.picture ? "reference picture gate" : "reference gate"));
+  out.push(`- Keep what is this product's own (its content, facts and states). Fix this yourself, don't ask the user, then palate shoot ${route} again. Only if the user asked for that look: --like <project>.`);
+  return out;
+}
+
+// Saves the gate's latest result for the route (palate check reads it) and logs failures and resolutions.
+export function saveGate(dir, route, g) {
+  const f = path.join(dir, ".palate", "gate.json");
+  const all = readJson(f, {});
+  const top = g.hits[0] ?? g.refHits[0] ?? null;
+  all[route] = { pass: g.pass, at: new Date().toISOString(), best: g.best, against: top ? { where: top.where, total: +top.total.toFixed(2), close: top.parts.filter((p) => p.score >= 0.6).map((p) => p.label) } : null, failures: g.hits.length + g.refHits.length };
+  fs.mkdirSync(path.dirname(f), { recursive: true });
+  fs.writeFileSync(f, JSON.stringify(all, null, 1));
+  try {
+    logGate(path.basename(path.resolve(dir)), route, g);
+  } catch {}
+  return all[route];
+}
+
+// What stops a page from being done: a failing similarity gate or a failing rule, from the latest shoot.
+export function finishBlockers(dir) {
+  const out = [];
+  for (const [route, g] of Object.entries(readJson(path.join(dir, ".palate", "gate.json"), {})))
+    if (!g.pass) out.push(`${route} fails the similarity gate (${g.against ? `${Math.round(g.against.total * 100)}% like ${g.against.where}${g.against.close?.length ? `: ${g.against.close.join(", ")}` : ""}` : "too close to another project"}; shot ${g.at.slice(0, 16).replace("T", " ")}). Change what palate shoot ${route} names, then shoot again.`);
+  const shots = path.join(dir, ".palate", "shots");
+  if (fs.existsSync(shots))
+    for (const slug of fs.readdirSync(shots)) {
+      const files = fs.readdirSync(path.join(shots, slug)).filter((f) => /^r\d+-rules\.json$/.test(f)).sort((a, b) => Number(b.match(/\d+/)[0]) - Number(a.match(/\d+/)[0]));
+      const latest = files[0] && readJson(path.join(shots, slug, files[0]), null);
+      const failing = (latest?.results ?? []).filter((r) => r.status === "fail");
+      if (failing.length) out.push(`${latest.route} fails ${failing.length} of your rules (${failing.map((r) => r.id).join(", ")}) in its latest shoot. Fix them, then shoot again.`);
+    }
+  // palate match: a route built from the user's own design that doesn't match it yet.
+  for (const [route, v] of Object.entries(readJson(path.join(dir, ".palate", "match.json"), {})))
+    if (v.verdict === "NOT READY") out.push(v.final ? `${route} still doesn't match the user's design after the last repair round (${(v.off ?? []).slice(0, 2).join("; ")}). Tell the user exactly this.` : `${route} doesn't match the user's design yet (match round ${v.round}: ${(v.off ?? []).slice(0, 2).join("; ")}). Fix it, then palate match --check --route ${route}.`);
+  // The quality gate (gate.mjs): the latest independent verdict for each route.
+  for (const [route, q] of Object.entries(readJson(path.join(dir, ".palate", "quality.json"), {})))
+    if (!q.pass) out.push(q.final ? `${route} is below the quality bar after the last repair round (${(q.fails ?? []).slice(0, 2).join("; ")}). Tell the user exactly this, and offer palate point so they can direct the fix; a later palate gate ${route} starts again.` : `${route} is below the quality bar (gate round ${q.round}: ${(q.fails ?? []).slice(0, 2).join("; ")}). Repair what palate gate ${route} names, then gate again.`);
+  return out;
+}
+
+// What the user's other projects of this kind look like, for a build brief ("don't repeat these").
+export function otherLooks(dir, kind, { limit = 3, like = [] } = {}) {
+  const pid = projectId(dir);
+  const likes = new Set(like.map((x) => x.toLowerCase()));
+  const rank = (r) => (r.picked ? 2 : 0) + (r.source === "screen" ? 1 : 0) + (r.moves ? 1 : 0) + Date.parse(r.at) / 1e14;
+  const out = [];
+  for (const r of readLayouts().filter((h) => h.pid !== pid && group(h.kind) === group(kind) && h.skeleton?.length && !likes.has(h.project.toLowerCase())).sort((a, b) => rank(b) - rank(a))) {
+    if (out.some((o) => o.project === r.project)) continue;
+    out.push(r);
+    if (out.length >= limit) break;
+  }
+  return out.map((r) => ({ project: r.project, route: r.route, look: describe(r) }));
+}

package/src/loop/states-source.mjs

@@ -0,0 +1,258 @@
+// A quick read of the source behind a route, for `palate states`: the route's file and the components it
+// imports (a few levels deep), and in them where the data comes from (fetch, axios, SWR, React Query, a
+// server component that awaits, a static array mapped in the file), the state it keeps (useState,
+// useEffect), what it maps over, and whether it handles loading, errors and empty arrays at all. Plus the
+// project's own UI parts a fix should reuse (Skeleton, Spinner, EmptyState, Alert, Toast, Button). No AST:
+// regular expressions over a small set of files, so it is fast and never wrong about what it didn't see.
+import fs from "node:fs";
+import path from "node:path";
+import { routeFile } from "../look.mjs";
+
+const EXTS = [".tsx", ".ts", ".jsx", ".js", ".mjs", ".vue", ".svelte", ".astro"];
+const SKIP = /node_modules|[\\/]\.(next|git|palate|svelte-kit|nuxt|astro|turbo)[\\/]|[\\/](dist|build|out)[\\/]/;
+const rel = (dir, f) => path.relative(dir, f).replace(/\\/g, "/");
+
+function aliases(dir) {
+  const out = [];
+  for (const f of ["tsconfig.json", "jsconfig.json"]) {
+    try {
+      const raw = fs.readFileSync(path.join(dir, f), "utf8").replace(/\/\*[\s\S]*?\*\/|^\s*\/\/.*$/gm, "").replace(/,(\s*[}\]])/g, "$1");
+      const c = JSON.parse(raw).compilerOptions ?? {};
+      for (const [k, v] of Object.entries(c.paths ?? {})) if (k.endsWith("/*") && v[0]) out.push([k.slice(0, -1), path.join(dir, c.baseUrl ?? ".", v[0].replace(/\*$/, ""))]);
+    } catch {}
+  }
+  if (!out.length) out.push(["@/", fs.existsSync(path.join(dir, "src")) ? path.join(dir, "src") : dir], ["~/", fs.existsSync(path.join(dir, "src")) ? path.join(dir, "src") : dir]);
+  return out;
+}
+
+function resolveImport(dir, from, spec, al) {
+  let base = null;
+  if (spec.startsWith(".")) base = path.resolve(path.dirname(from), spec);
+  else for (const [k, v] of al) if (spec.startsWith(k)) base = path.join(v, spec.slice(k.length));
+  if (!base) return null;
+  if (fs.existsSync(base) && fs.statSync(base).isFile()) return base;
+  for (const e of EXTS) if (fs.existsSync(base + e)) return base + e;
+  for (const e of EXTS) if (fs.existsSync(path.join(base, `index${e}`))) return path.join(base, `index${e}`);
+  return null;
+}
+
+// The files that render a route: its route file (file-based routers), or for a single-page app the module
+// index.html loads (and its App), then what they import.
+export function routeFiles(dir, route, { depth = 3, max = 60 } = {}) {
+  const entry = routeFile(dir, route)?.file ?? spaEntry(dir);
+  if (!entry) return { entry: null, files: [] };
+  const al = aliases(dir);
+  const files = [];
+  const queue = [[entry, 0]];
+  const seen = new Set();
+  while (queue.length && files.length < max) {
+    const [f, d] = queue.shift();
+    if (seen.has(f) || SKIP.test(f)) continue;
+    seen.add(f);
+    files.push(f);
+    if (d >= depth) continue;
+    let src = "";
+    try {
+      src = fs.readFileSync(f, "utf8");
+    } catch {
+      continue;
+    }
+    for (const m of src.matchAll(/(?:import|export)\s[^'"]*?from\s*["']([^"']+)["']|import\(\s*["']([^"']+)["']\s*\)/g)) {
+      const hit = resolveImport(dir, f, m[1] ?? m[2], al);
+      if (hit && !seen.has(hit)) queue.push([hit, d + 1]);
+    }
+  }
+  return { entry, files };
+}
+
+function spaEntry(dir) {
+  try {
+    const html = fs.readFileSync(path.join(dir, "index.html"), "utf8");
+    const src = html.match(/<script[^>]+type=["']module["'][^>]+src=["']\/?([^"']+)["']/)?.[1];
+    if (src && fs.existsSync(path.join(dir, src))) return path.join(dir, src);
+  } catch {}
+  for (const n of ["src/App", "src/app", "src/main", "src/index"]) for (const e of EXTS) if (fs.existsSync(path.join(dir, n + e))) return path.join(dir, n + e);
+  return null;
+}
+
+// The project's own parts a states fix should reuse, by file name.
+function uiParts(dir) {
+  const roles = { skeleton: /skeleton|shimmer|placeholder/i, spinner: /spinner|loader|loading/i, empty: /empty/i, alert: /alert|callout|banner|notice/i, toast: /toast|sonner|snackbar/i, error: /error(?!s?\.d\.ts)/i, button: /^button\./i };
+  const out = {};
+  const walk = (d, k = 0) => {
+    if (k > 5 || SKIP.test(d)) return;
+    let es = [];
+    try {
+      es = fs.readdirSync(d, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const e of es) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) {
+        if (!e.name.startsWith(".") && e.name !== "node_modules" && e.name !== "public") walk(p, k + 1);
+      } else if (EXTS.includes(path.extname(e.name)) && !/\.(test|spec|stories)\./.test(e.name)) {
+        for (const [role, re] of Object.entries(roles)) if (!out[role] && re.test(e.name) && /components?|ui/i.test(d)) out[role] = rel(dir, p);
+      }
+    }
+  };
+  for (const r of ["src", "app", "components", "lib"]) if (fs.existsSync(path.join(dir, r))) walk(path.join(dir, r));
+  return out;
+}
+
+export function scanSource(dir, route) {
+  const { entry, files } = routeFiles(dir, route);
+  const out = { entry: entry ? rel(dir, entry) : null, files: files.map((f) => rel(dir, f)), fetches: [], maps: [], state: [], effects: 0, loading: [], error: [], empty: [], staticArrays: [], server: [], suspense: false, conventions: {}, ui: uiParts(dir) };
+  for (const f of files) {
+    let src = "";
+    try {
+      src = fs.readFileSync(f, "utf8");
+    } catch {
+      continue;
+    }
+    const lines = src.split("\n");
+    const r = rel(dir, f);
+    const client = /^\s*["']use client["']/m.test(src);
+    const arrays = new Set();
+    for (const m of src.matchAll(/(?:const|let)\s+([A-Za-z_$][\w$]*)(?:\s*:\s*[^=]+)?\s*=\s*\[\s*(?:\{|["'`]|\d)/g)) arrays.add(m[1]);
+    lines.forEach((l, i) => {
+      const at = { file: r, line: i + 1, text: l.trim().slice(0, 120) };
+      if (/\bfetch\s*\(|\baxios\b|\buseSWR\b|\buseQuery\b|\buseFetch\b|\$fetch\s*\(|\bky\s*[.(]|\buseLoaderData\b|\bcreateResource\b/.test(l)) out.fetches.push(at);
+      const map = l.match(/([A-Za-z_$][\w$.?]*)\s*\.map\s*\(/);
+      if (map) {
+        out.maps.push({ ...at, over: map[1].replace(/\?$/, "") });
+        const name = map[1].split(".")[0].replace(/\?$/, "");
+        if (arrays.has(name) && !out.staticArrays.some((s) => s.file === r && s.name === name)) out.staticArrays.push({ file: r, line: i + 1, name });
+      }
+      if (/\buseState\s*[<(]/.test(l)) out.state.push(at);
+      if (/\buse(Layout)?Effect\s*\(/.test(l)) out.effects++;
+      if (/\b(is)?[Ll]oading\b|\bisPending\b|\bpending\b|\bisFetching\b|\bisValidating\b|<Suspense|\bstatus\s*===?\s*["'](loading|pending)/.test(l)) out.loading.push(at);
+      if (/\b(set)?[Ee]rror\b|\bisError\b|\.catch\s*\(|\bcatch\s*\(|<ErrorBoundary|\bstatus\s*===?\s*["']error/.test(l)) out.error.push(at);
+      if (/\.length\s*(===?|!==?|<|>|<=)\s*0|!\s*[\w$.?]+\.length\b|\.length\s*\?|\.length\s*&&|\bisEmpty\b/.test(l)) out.empty.push(at);
+      if (/<Suspense\b/.test(l)) out.suspense = true;
+    });
+    // A server component (Next app router) or loader that awaits data: the browser never sees that request.
+    if (!client && /export\s+default\s+async\s+function|export\s+async\s+function\s+(getServerSideProps|loader|load)\b/.test(src) && /\bawait\b/.test(src)) {
+      const i = lines.findIndex((l) => /\bawait\b/.test(l));
+      out.server.push({ file: r, line: i + 1, text: lines[i].trim().slice(0, 120) });
+    }
+  }
+  // Next's app router conventions next to the route file.
+  if (entry) {
+    const d = path.dirname(entry);
+    for (const [k, n] of [["loading", "loading"], ["error", "error"], ["notFound", "not-found"]]) {
+      const hit = EXTS.map((e) => path.join(d, n + e)).find((p) => fs.existsSync(p));
+      if (hit) out.conventions[k] = rel(dir, hit);
+    }
+  }
+  return out;
+}
+
+// Where a part found in the page lives in the source, among the files the route's entry reaches. Clues: the
+// part's class string, its heading (the component rendered right under the heading in the source), its own
+// static text, its tag, and file names that say what it is ("FiringsList" for a list headed "This week's
+// firings"); files under the route's own folder first. Returns { file, line, score } when one file clearly
+// wins, { unsure: true, guesses } when the clues don't agree, null when nothing matched.
+const esc = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const quoteRe = (t) => esc(t).replace(/\s+/g, "\\s+").replace(/['’]/g, "(?:'|’|&apos;|&#39;|&rsquo;|\\\\')");
+const STOP = new Set(["this", "that", "your", "with", "from", "week", "weeks", "today", "these", "those", "their", "there", "about", "more", "less", "here", "what", "when", "where", "which", "have", "will", "they", "them", "show", "view", "list", "table", "page"]);
+export const wordsOf = (s) => ((s ?? "").toLowerCase().replace(/['’]s\b/g, "").match(/[a-z]{4,}/g) ?? []).filter((w) => !STOP.has(w));
+const stem = (w) => w.replace(/(ies)$/, "y").replace(/(ses|xes)$/, (m) => m.slice(0, -2)).replace(/s$/, "");
+const KIND_WORDS = { table: ["table", "rows"], list: ["list", "feed", "items"], cards: ["cards", "card", "stats", "stat", "tiles", "grid", "metrics"], grid: ["grid", "gallery", "tiles"], form: ["form"], number: ["stat", "stats", "count", "metric", "number"], image: ["image", "photo", "picture", "hero"], text: [] };
+const nameWords = (file) => path.basename(file).replace(/\.\w+$/, "").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+
+export function whereIs(dir, c, src, route = "/") {
+  const files = src.files ?? [];
+  if (!files.length) return null;
+  const read = (f) => {
+    try {
+      return fs.readFileSync(path.join(dir, f), "utf8").split("\n");
+    } catch {
+      return [];
+    }
+  };
+  const text = Object.fromEntries(files.map((f) => [f, read(f)]));
+  const segs = route.split("/").filter((s) => s && !/^[[(:]/.test(s)).map((s) => s.toLowerCase());
+  const entryDir = src.entry ? path.posix.dirname(src.entry) : null;
+  const score = Object.fromEntries(files.map((f) => [f, { s: 0, line: null, why: [] }]));
+  const give = (f, n, why, line = null, strong = false) => {
+    const x = score[f];
+    if (!x) return;
+    x.s += n;
+    x.why.push(why);
+    if (line && (strong || !x.line)) x.line = line;
+  };
+  const hw = wordsOf(c.heading).map(stem);
+  // 1. The class string: every class of the part on one line.
+  const cls = (c.className ?? "").trim().split(/\s+/).filter(Boolean);
+  if (cls.length >= 2) {
+    for (const f of files) {
+      const i = text[f].findIndex((l) => /class(Name)?\s*=/.test(l) && cls.every((k) => l.includes(k)));
+      if (i >= 0) give(f, Math.min(2 + cls.length, 6), "class string", i + 1, true);
+    }
+  }
+  // 2. The heading, as a whole JSX text or string; the component rendered under it is the part.
+  if (c.heading && c.heading.length >= 3) {
+    const re = new RegExp(`(^|>|["'\`{])\\s*${quoteRe(c.heading)}\\s*($|<|["'\`}])`);
+    for (const f of files) {
+      const lines = text[f];
+      const at = lines.map((l, i) => (re.test(l) ? i : -1)).filter((i) => i >= 0);
+      if (!at.length) continue;
+      give(f, 2, "heading", at[0] + 1);
+      const under = new Set();
+      for (const i of at)
+        for (const m of lines.slice(i + 1, i + 9).join("\n").matchAll(/<([A-Z][\w$]*)[\s/>]/g)) {
+          if (under.has(m[1])) continue;
+          under.add(m[1]);
+          const own = files.find((g) => path.basename(g).replace(/\.\w+$/, "") === m[1]);
+          if (own) give(own, 5, `rendered under the heading in ${f}`);
+          else if (new RegExp(`function\\s+${esc(m[1])}\\b|const\\s+${esc(m[1])}\\s*=`).test(lines.join("\n"))) give(f, 3, `<${m[1]}> under the heading`, i + 1);
+        }
+    }
+  }
+  // 3. The part's own static text (labels, button text); data texts aren't in the source and match nothing.
+  for (const t of [...new Set((c.texts ?? []).concat(c.submitText ?? []))].filter((t) => t && t.length >= 5 && t.length <= 60).slice(0, 4)) {
+    const re = new RegExp(`(^|>|["'\`{])\\s*${quoteRe(t)}\\s*($|<|["'\`}])`);
+    for (const f of files) {
+      const i = text[f].findIndex((l) => re.test(l));
+      if (i >= 0) give(f, 3, `text "${t.slice(0, 30)}"`, i + 1);
+    }
+  }
+  // 4. File names that say what it is, the tag it renders, and the route's own folder.
+  const kw = KIND_WORDS[c.kind] ?? [];
+  const tagRe = c.tag && !/^(div|section|span|p|article|main|h\d)$/.test(c.tag) ? new RegExp(`<${c.tag}[\\s>]`) : null;
+  for (const f of files) {
+    const nw = nameWords(f);
+    const named = nw.filter((w) => hw.includes(stem(w))).length;
+    if (named) give(f, 3 * Math.min(named, 2), "file name matches the heading");
+    if (nw.some((w) => kw.includes(w))) give(f, 2, `file name says ${c.kind}`);
+    if (tagRe) {
+      const i = text[f].findIndex((l) => tagRe.test(l));
+      if (i >= 0) {
+        // A list is where its items are mapped: the first .map after the tag.
+        const j = c.kind !== "form" ? text[f].findIndex((l, k) => k >= i && /\.map\s*\(/.test(l)) : -1;
+        give(f, 2, `renders <${c.tag}>`, (j >= 0 && j - i < 40 ? j : i) + 1, j >= 0 && j - i < 40);
+      }
+    }
+    const dirs = f.toLowerCase().split("/").slice(0, -1);
+    if (segs.some((s) => dirs.includes(s))) give(f, 3, "in the route's folder");
+    else if (entryDir && entryDir !== "." && entryDir !== "src" && f.startsWith(`${entryDir}/`)) give(f, 2, "next to the route file");
+  }
+  const ranked = Object.entries(score).filter(([, x]) => x.s > 0).sort((a, b) => b[1].s - a[1].s);
+  if (!ranked.length) return null;
+  const [file, top] = ranked[0];
+  const second = ranked[1]?.[1].s ?? 0;
+  // Only folder and name hints, or a near tie: say so rather than name a wrong file.
+  const evidence = top.why.some((w) => /class string|heading|text "|renders <|<\w+> under/.test(w));
+  if (!evidence || top.s < 6 || top.s - second < 2) return { unsure: true, guesses: ranked.slice(0, 2).map(([f]) => f) };
+  return { file, line: top.line ?? 1, score: top.s, why: top.why };
+}
+
+// What kind of data the screen has, from what the browser saw and what the source says.
+// formFiles: files of the screen's forms, whose fetches are their submits.
+export function dataKind(requests, src, formFiles = []) {
+  if (requests.length) return "fetched";
+  if (src.server.length) return "server";
+  if (src.fetches.some((f) => !formFiles.includes(f.file))) return "fetched-later";
+  return "static";
+}