@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/layouts.mjs

@@ -0,0 +1,492 @@
+// The layout memory: every variant and screen palate has rendered, on any project on this machine, in
+// ~/.palate/history/layouts.jsonl. Each record keeps the page's skeleton, the shape of its first screen, its
+// type and colour, and a tiny picture of the first screen. Briefs read it to avoid repeating what has been
+// made, the judge drops near-duplicates with it, and shoot says when a screen repeats one built elsewhere.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import zlib from "node:zlib";
+import { PALATE_HOME } from "../catalog/store.mjs";
+import { screenKind } from "./common.mjs";
+import { KB_ROOT } from "../paths.mjs";
+
+export const HISTORY_DIR = path.join(PALATE_HOME, "history");
+export const LAYOUTS = path.join(HISTORY_DIR, "layouts.jsonl");
+
+// Similarity thresholds, chosen on the real loops on this machine (5 loops, 25 variants: 61 pairs inside
+// loops, 264 across them). The two pairs a person calls "the same design in another skin" scored 0.73 and
+// 0.79; the closest pair that is a different idea scored 0.68; pairs across loops: median 0.22, max 0.68.
+// DUPLICATE: the same idea; inside a loop one of the two goes, against history it is a repeat.
+// SIMILAR: close enough to something already made to say so.
+export const DUPLICATE = 0.72;
+export const SIMILAR = 0.6;
+
+export const projectId = (dir) => crypto.createHash("sha1").update(path.resolve(dir).toLowerCase()).digest("hex").slice(0, 12);
+
+// What kind of screen, in one word, so a pricing loop is compared with pricing screens first.
+const SCREENS = [
+  ["landing", /\b(home|landing|waitlist|homepage|marketing page)\b/],
+  ["hero", /\bhero\b/],
+  ["pricing", /\b(pricing|plans?)\b/],
+  ["features", /\bfeatures?\b/],
+  ["onboarding", /\b(onboarding|setup|first-run|welcome)\b/],
+  ["team", /\b(team|members?|people)\b/],
+  ["settings", /\bsettings?\b/],
+  ["table", /\b(table|list|companies|records|pipeline)\b/],
+  ["dashboard", /\b(dashboard|overview|analytics)\b/],
+  ["auth", /\b(login|sign ?in|sign ?up|signup)\b/],
+  ["docs", /\b(docs|documentation|blog|article)\b/],
+];
+export function screenOf(name = "", job = "") {
+  for (const t of [name, job]) {
+    const s = String(t).toLowerCase().replace(/[-_]/g, " ");
+    const hit = SCREENS.find(([, re]) => re.test(s));
+    if (hit) return hit[0];
+  }
+  return "other";
+}
+
+// The kind of screen a record is, for like-for-like comparisons (a landing page against landing pages, pricing
+// against pricing): its screen field, else read from its loop or route, else from its skeleton (a marketing
+// page at the site root, or of five or more bands, is a landing page). A hero variant is a landing page's
+// first screen, so it counts as one. null when it can't be told.
+const SCREEN_FAMILY = { hero: "landing" };
+export function screenKindOf(r) {
+  const fam = (s) => SCREEN_FAMILY[s] ?? s;
+  if (r?.screen && r.screen !== "other") return fam(r.screen);
+  const route = String(r?.route ?? "").split("?")[0];
+  const named = screenOf(r?.loop ?? "", route.replace(/^\//, ""));
+  if (named !== "other") return fam(named);
+  if (r?.kind === "app") return null;
+  if (route === "/" || route === "") return "landing";
+  if ((r?.skeleton?.length ?? 0) >= 5) return "landing";
+  return null;
+}
+// Two records are the same kind of screen: both known and equal; when either is unknown, pages of a like
+// length (a 3-band pricing variant is no landing page's twin).
+export function sameScreen(a, b) {
+  const [x, y] = [screenKindOf(a), screenKindOf(b)];
+  if (x && y) return x === y;
+  const [m, n] = [a?.skeleton?.length ?? 0, b?.skeleton?.length ?? 0];
+  return Math.abs(m - n) <= Math.max(1, Math.round(0.25 * Math.max(m, n)));
+}
+
+// ---- reading screenshots: a 16×10 colour grid of the first screen, from the PNG itself (no dependencies).
+export function pngThumb(file, { cols = 16, rows = 10 } = {}) {
+  try {
+    const buf = fs.readFileSync(file);
+    if (buf.readUInt32BE(0) !== 0x89504e47) return null;
+    let w = 0, h = 0, depth = 0, type = 0, interlace = 0;
+    const idat = [];
+    for (let o = 8; o < buf.length; ) {
+      const len = buf.readUInt32BE(o);
+      const t = buf.toString("ascii", o + 4, o + 8);
+      if (t === "IHDR") [w, h, depth, type, interlace] = [buf.readUInt32BE(o + 8), buf.readUInt32BE(o + 12), buf[o + 16], buf[o + 17], buf[o + 20]];
+      else if (t === "IDAT") idat.push(buf.subarray(o + 8, o + 8 + len));
+      else if (t === "IEND") break;
+      o += 12 + len;
+    }
+    const bpp = { 2: 3, 6: 4, 0: 1, 4: 2 }[type];
+    if (depth !== 8 || interlace || !bpp) return null;
+    const raw = zlib.inflateSync(Buffer.concat(idat));
+    const stride = w * bpp;
+    // The first screen at this width (900 tall at 1440).
+    const H = Math.min(h, Math.round((w * 900) / 1440));
+    const px = Buffer.alloc(stride * H);
+    for (let y = 0; y < H; y++) {
+      const f = raw[y * (stride + 1)];
+      const src = y * (stride + 1) + 1;
+      const row = y * stride;
+      for (let x = 0; x < stride; x++) {
+        const a = x >= bpp ? px[row + x - bpp] : 0;
+        const b = y ? px[row - stride + x] : 0;
+        const c = y && x >= bpp ? px[row - stride + x - bpp] : 0;
+        let v = raw[src + x];
+        if (f === 1) v += a;
+        else if (f === 2) v += b;
+        else if (f === 3) v += (a + b) >> 1;
+        else if (f === 4) {
+          const p = a + b - c;
+          const pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c);
+          v += pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+        }
+        px[row + x] = v;
+      }
+    }
+    // Ink: how much of each cell differs from the page's own background (its most common colour).
+    const counts = new Map();
+    for (let y = 0; y < H; y += 7)
+      for (let x = 0; x < w; x += 7) {
+        const i = y * stride + x * bpp;
+        const k = bpp >= 3 ? ((px[i] >> 3) << 10) | ((px[i + 1] >> 3) << 5) | (px[i + 2] >> 3) : px[i] >> 3;
+        counts.set(k, (counts.get(k) ?? 0) + 1);
+      }
+    const mode = [...counts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    const bg = bpp >= 3 ? [(mode >> 10) << 3, ((mode >> 5) & 31) << 3, (mode & 31) << 3] : [mode << 3, mode << 3, mode << 3];
+    const ink = [];
+    const rgb = [];
+    for (let gy = 0; gy < rows; gy++)
+      for (let gx = 0; gx < cols; gx++) {
+        let r = 0, g = 0, bl = 0, n = 0, inked = 0;
+        const y0 = Math.floor((gy * H) / rows), y1 = Math.floor(((gy + 1) * H) / rows);
+        const x0 = Math.floor((gx * w) / cols), x1 = Math.floor(((gx + 1) * w) / cols);
+        for (let y = y0; y < y1; y += 3)
+          for (let x = x0; x < x1; x += 3) {
+            const i = y * stride + x * bpp;
+            const c = bpp >= 3 ? [px[i], px[i + 1], px[i + 2]] : [px[i], px[i], px[i]];
+            [r, g, bl] = [r + c[0], g + c[1], bl + c[2]];
+            if (Math.abs(c[0] - bg[0]) + Math.abs(c[1] - bg[1]) + Math.abs(c[2] - bg[2]) > 36) inked++;
+            n++;
+          }
+        ink.push(Math.round((100 * inked) / n));
+        rgb.push(Math.round(r / n), Math.round(g / n), Math.round(bl / n));
+      }
+    return { ink, rgb };
+  } catch {
+    return null;
+  }
+}
+
+// ---- describing a layout
+const MARKETING = (kind) => kind !== "app";
+// The shape of the first screen (marketing) or of the main structure (app screens), measured.
+export function shapeOf(fp, kind) {
+  const bands = (fp?.bands ?? []).filter((b) => !b.header);
+  if (!bands.length) return null;
+  if (MARKETING(kind)) {
+    const early = bands.filter((b) => b.top < 1100);
+    const hero = (early.length ? early : bands).reduce((a, b) => (b.focal > a.focal ? b : a));
+    if (hero.media >= 0.45 && hero.cols <= 2) return "fullbleed";
+    if (hero.cols >= 3) return hero.grid >= 3 && hero.ratio > 1.3 ? "bento" : "editorial";
+    if (hero.cols === 2) return hero.ratio >= 1.8 ? "asymmetric" : "split";
+    if (hero.centred) return "centred";
+    return "left-stack";
+  }
+  const main = bands.reduce((a, b) => (b.height > a.height ? b : a));
+  if (main.cols >= 3 && !main.grid) return "columns";
+  if (main.cols === 2) return main.ratio >= 2.2 ? "rail" : "master-detail";
+  if (main.grid >= 3 && main.cols >= 3) return "cards";
+  if (bands.length >= 4 && bands.every((b) => b.cols === 1)) return "document";
+  return "full-width";
+}
+
+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 lum = (rgb) => (rgb ? 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2] : 255);
+
+// Signature moves, in words: what a brief can tell the next designer not to repeat.
+export function movesOf(fp, kind, shape = shapeOf(fp, kind)) {
+  const s = fp?.style ?? {};
+  const bands = (fp?.bands ?? []).filter((b) => !b.header);
+  const h = s.headline;
+  const weight = (w) => (w <= 300 ? "light" : w <= 450 ? "regular" : w <= 650 ? "semibold" : "heavy");
+  const product = bands.map((b, i) => (b.panel ? `framed window (band ${i + 1})` : b.media >= 0.15 ? `big media (band ${i + 1})` : b.grid >= 3 ? `grid of ${b.grid} (band ${i + 1})` : null)).filter(Boolean);
+  const tinted = bands.filter((b) => b.ownBg).length;
+  const bg = hexRgb(s.bg);
+  return {
+    hero: `${ARCH_NAME[shape] ?? shape ?? "?"}${h ? `, ${h.size}px ${weight(h.weight)} ${h.family}${h.upper ? " caps" : ""}${h.italic ? " italic" : ""}, ${h.align === "center" ? "centred" : "left"}` : ""}`,
+    product: product.slice(0, 3).join(", ") || "text only",
+    rhythm: `${bands.length} bands${tinted ? `, ${tinted} tinted` : ""}${bands.some((b) => b.grid >= 3) ? `, grids of ${[...new Set(bands.filter((b) => b.grid >= 3).map((b) => b.grid))].join("/")}` : ""}`,
+    type: (s.fonts ?? []).join(" + ") || "?",
+    palette: `${lum(bg) < 90 ? "dark" : lum(bg) < 225 ? "tinted" : "light"} ${s.bg ?? "?"}${s.text ? `, text ${s.text}` : ""}${s.accent ? `, accent ${s.accent}` : ""}${s.radii?.length ? `, radii ${s.radii.join("/")}` : ""}`,
+  };
+}
+
+export const ARCH_NAME = {
+  split: "split hero", centred: "centred stack", fullbleed: "full-bleed product", editorial: "editorial grid", asymmetric: "asymmetric", "left-stack": "left-led stack", bento: "bento overview",
+  "full-width": "main object full width", "master-detail": "list + detail", rail: "main + summary rail", columns: "columns / board", document: "document flow", cards: "card overview",
+};
+
+export function describe(r) {
+  const m = r.moves;
+  if (!m) return `${ARCH_NAME[r.shape ?? r.archetype] ?? "skeleton only"}: ${r.skeleton.join(" · ")}`;
+  return `${m.hero}; product: ${m.product}; rhythm: ${r.skeleton.join(" · ")} (${m.rhythm}); type: ${m.type}; palette: ${m.palette}`;
+}
+
+// ---- similarity
+const grams = (raw) => {
+  const s = raw.map((t) => t.replace(/b/g, ""));
+  return new Set(s.slice(1).map((t, i) => `${s[i]}>${t}`).concat(s.map((t) => t.replace(/[mw]|g\d/g, ""))));
+};
+// Skeleton overlap (bands in order, then band types), 0–1.
+export function skeletonSimilarity(a, b) {
+  if (!a?.length || !b?.length || a.length < 3 || b.length < 3) return 0;
+  const A = grams(a);
+  const B = grams(b);
+  const inter = [...A].filter((g) => B.has(g)).length;
+  return inter / (A.size + B.size - inter);
+}
+
+export function styleSimilarity(a, b) {
+  if (!a || !b) return null;
+  const parts = [];
+  const fa = (a.fonts ?? []).map((f) => f.toLowerCase()), fb = (b.fonts ?? []).map((f) => f.toLowerCase());
+  if (fa.length && fb.length) parts.push(fa.filter((f) => fb.includes(f)).length / new Set([...fa, ...fb]).size);
+  if (a.headline && b.headline) {
+    const [x, y] = [a.headline, b.headline];
+    parts.push(1 - Math.min(1, (2 * Math.abs(x.size - y.size)) / Math.max(x.size, y.size)));
+    parts.push(1 - Math.min(1, Math.abs(x.weight - y.weight) / 400));
+    parts.push((x.align === "center") === (y.align === "center") ? 1 : 0);
+  }
+  const [ba, bb] = [hexRgb(a.bg), hexRgb(b.bg)];
+  if (ba && bb) parts.push(1 - Math.min(1, dist(ba, bb) / 120));
+  const [aa, ab] = [hexRgb(a.accent), hexRgb(b.accent)];
+  if (aa && ab) parts.push(1 - Math.min(1, dist(aa, ab) / 150));
+  if (a.radii?.length && b.radii?.length) parts.push(a.radii[0] === b.radii[0] ? 1 : 0);
+  return parts.length ? parts.reduce((x, y) => x + y, 0) / parts.length : null;
+}
+
+// The first screens compared as pictures: where the content sits (ink against the page's background), and
+// the colours.
+const pearson = (a, b) => {
+  const mean = (v) => v.reduce((x, y) => x + y, 0) / v.length;
+  const [ma, mb] = [mean(a), mean(b)];
+  let num = 0, da = 0, db = 0;
+  for (let i = 0; i < a.length; i++) {
+    num += (a[i] - ma) * (b[i] - mb);
+    da += (a[i] - ma) ** 2;
+    db += (b[i] - mb) ** 2;
+  }
+  // A near-blank screen has no layout to compare.
+  return da > 1 && db > 1 ? Math.max(0, num / Math.sqrt(da * db)) : 0;
+};
+export function visualSimilarity(a, b) {
+  if (!a?.ink || !b?.ink || a.ink.length !== b.ink.length) return null;
+  let diff = 0;
+  for (let i = 0; i < a.rgb.length; i += 3) diff += dist(a.rgb.slice(i, i + 3), b.rgb.slice(i, i + 3));
+  const colour = 1 - Math.min(1, diff / (a.rgb.length / 3) / 160);
+  return 0.7 * pearson(a.ink, b.ink) + 0.3 * colour;
+}
+
+// The first three bands under the header, position by position: same token 1, same alignment and columns 0.6.
+export function firstScreenSimilarity(a, b) {
+  if (!a?.length || !b?.length) return null;
+  const n = Math.max(a.length, b.length);
+  let s = 0;
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    const [x, y] = [a[i].replace(/b|g\d/g, ""), b[i].replace(/b|g\d/g, "")];
+    s += x === y ? 1 : x.slice(0, 2) === y.slice(0, 2) ? 0.6 : 0;
+  }
+  return s / n;
+}
+
+// 0–1, with its parts. Structure (skeleton and first-screen shape) counts most, then the picture, then style.
+export function compare(a, b) {
+  const parts0 = [[skeletonSimilarity(a.skeleton, b.skeleton), 0.5], [a.shape && b.shape ? (a.shape === b.shape ? 1 : 0) : null, 0.25], [firstScreenSimilarity(a.firstScreen, b.firstScreen), 0.25]].filter(([v]) => v != null);
+  const structure = parts0.reduce((s, [v, w]) => s + v * w, 0) / parts0.reduce((s, [, w]) => s + w, 0);
+  const style = styleSimilarity(a.style, b.style);
+  const visual = visualSimilarity(a.thumb, b.thumb);
+  const parts = [[structure, 0.5], [visual, 0.3], [style, 0.2]].filter(([v]) => v != null);
+  const total = parts.reduce((s, [v, w]) => s + v * w, 0) / parts.reduce((s, [, w]) => s + w, 0);
+  return { total, structure, visual, style };
+}
+
+// The same comparison with colour taken out: the page skeleton and first-screen shape, where the content sits on
+// the first screen (ink only), and the type's structure (shared faces, centred or not). Repainting a page
+// doesn't move it, so a page can't get past the similarity gate with a new colour alone.
+const typeStructure = (a, b) => {
+  if (!a || !b) return null;
+  const p = [];
+  const fa = (a.fonts ?? []).map((f) => f.toLowerCase()), fb = (b.fonts ?? []).map((f) => f.toLowerCase());
+  if (fa.length && fb.length) p.push(fa.filter((f) => fb.includes(f)).length / new Set([...fa, ...fb]).size);
+  if (a.headline && b.headline) p.push((a.headline.align === "center") === (b.headline.align === "center") ? 1 : 0);
+  return p.length ? p.reduce((x, y) => x + y, 0) / p.length : null;
+};
+export function structuralSimilarity(a, b) {
+  const c = compare(a, b);
+  const ink = a.thumb?.ink && b.thumb?.ink && a.thumb.ink.length === b.thumb.ink.length ? pearson(a.thumb.ink, b.thumb.ink) : null;
+  const parts = [[c.structure, 0.6], [ink, 0.25], [typeStructure(a.style, b.style), 0.15]].filter(([v]) => v != null);
+  return parts.reduce((s, [v, w]) => s + v * w, 0) / parts.reduce((s, [, w]) => s + w, 0);
+}
+
+// ---- the history file
+export function readLayouts() {
+  if (!fs.existsSync(LAYOUTS)) return [];
+  const byKey = new Map();
+  for (const line of fs.readFileSync(LAYOUTS, "utf8").split("\n").slice(-5000)) {
+    if (!line.trim()) continue;
+    let r;
+    try {
+      r = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    // A best-of-two alternative (?palate-alt=…) is a candidate, not a screen of the project.
+    if (/[?&]palate-alt=/.test(r.route ?? "")) continue;
+    // One entry per screen (per loop run for variants); the latest measurement wins, a pick sticks.
+    const key = `${r.pid}|${r.route}|${r.run ?? ""}`;
+    const prev = byKey.get(key);
+    byKey.delete(key);
+    byKey.set(key, { ...r, picked: Boolean(r.picked || prev?.picked) });
+  }
+  return [...byKey.values()];
+}
+
+// A folder that holds a page's source. A throwaway folder that only shot someone else's running page (palate shoot
+// --dir tmp --url …) is not a project: recording it would make the real project repeat a copy of itself.
+export function isProjectDir(dir) {
+  return Boolean(dir) && ["package.json", "index.html", "src", "app", "pages"].some((f) => fs.existsSync(path.join(dir, f)));
+}
+
+export function appendLayouts(records) {
+  if (!records.length) return;
+  fs.mkdirSync(HISTORY_DIR, { recursive: true });
+  fs.appendFileSync(LAYOUTS, records.map((r) => JSON.stringify(r)).join("\n") + "\n");
+}
+
+const loopMeta = (dir, name) => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(dir, ".palate", "variants", name, "loop.json"), "utf8"));
+  } catch {
+    return {};
+  }
+};
+
+// Builds a record from a rendered page's fingerprint (and its screenshot, when there is one).
+export function layoutRecord(dir, route, fp, { file, loop, meta = {}, kind, source = "variant", picked = false } = {}) {
+  const screen = screenOf(loop ?? route.replace(/^\//, ""), meta.job ?? "");
+  // A screen outside a loop: its kind from its name, else from its height (marketing pages run long).
+  const k = kind ?? meta.kind ?? (["landing", "hero", "pricing", "features"].includes(screen) ? "marketing" : screen !== "other" ? "app" : fp?.style?.height > 1800 ? "marketing" : "app");
+  const letter = loop ? route.match(new RegExp(`/${loop.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}-([a-z])\\d+$`))?.[1] : undefined;
+  const d = (meta.directions ?? []).find((x) => x.letter === letter);
+  const shape = fp ? shapeOf(fp, k) : null;
+  // A site's root page is its landing page.
+  const scr = screen === "other" && route === "/" && k === "marketing" ? "landing" : screen;
+  return {
+    at: new Date().toISOString(),
+    project: path.basename(path.resolve(dir)),
+    pid: projectId(dir),
+    // A benchmark project (palate bench new): measured, but not one of the user's own looks.
+    bench: fs.existsSync(path.join(dir, ".palate", "bench.json")) || undefined,
+    route,
+    loop: loop ?? null,
+    run: meta.created ?? null,
+    kind: k,
+    screen: scr,
+    source,
+    picked,
+    direction: d ? { id: d.id, name: d.name, generated: d.generated ?? undefined, brief: d.generated ? d.brief : undefined, style: d.generated ? d.style : undefined } : null,
+    archetype: d?.archetype ?? null,
+    shape,
+    skeleton: fp?.skeleton ?? [],
+    firstScreen: fp?.firstScreen ?? null,
+    style: fp?.style ?? null,
+    moves: fp ? movesOf(fp, k, shape) : null,
+    thumb: file ? pngThumb(file) : null,
+  };
+}
+
+// Records from benchmark projects: flagged since Oct 29, earlier ones known by the benchmark's project names.
+let benchNames = null;
+export function isBenchRecord(r) {
+  if (r?.bench) return true;
+  if (!benchNames) {
+    try {
+      const kb = process.env.PALATE_KB ?? KB_ROOT;
+      benchNames = new Set([...JSON.parse(fs.readFileSync(path.join(kb, "bench", "briefs.json"), "utf8")).briefs.map((b) => b.id), "kiln2"]);
+    } catch {
+      benchNames = new Set(["kiln2"]);
+    }
+  }
+  return benchNames.has(String(r?.project ?? ""));
+}
+
+// Judge and pick: record every rendered variant of a loop. `shots` come from common.render ({route, file, fp}).
+export function recordRender(dir, name, shots, { source = "variant", winner } = {}) {
+  const meta = loopMeta(dir, name);
+  meta.kind = meta.kind ?? screenKind(name, meta.job).kind;
+  const recs = shots.filter((s) => s.file && s.fp).map((s) => layoutRecord(dir, s.route, s.fp, { file: s.file, loop: name, meta, source: s.route === winner ? "picked" : source, picked: s.route === winner }));
+  if (isProjectDir(dir)) appendLayouts(recs);
+  return recs;
+}
+
+// pick: the user's winner joins the memory as picked. Uses the fingerprints render() left next to the shots.
+export function recordPick(dir, name, winner) {
+  try {
+    const session = path.join(dir, ".palate", "variants", name);
+    const shots = [];
+    for (const sub of ["shots", "judge"]) {
+      const d = path.join(session, sub);
+      if (!fs.existsSync(d)) continue;
+      for (const f of fs.readdirSync(d).filter((x) => x.endsWith(".fp.json"))) {
+        const j = JSON.parse(fs.readFileSync(path.join(d, f), "utf8"));
+        if (!shots.some((s) => s.route === j.route)) shots.push({ route: j.route, fp: j.fp, file: path.join(d, f.replace(/\.fp\.json$/, ".png")) });
+      }
+    }
+    return recordRender(dir, name, shots, { winner });
+  } catch {
+    return [];
+  }
+}
+
+// What has been made for this kind of screen, most relevant first: this loop's earlier runs, then this
+// project, then picked screens elsewhere, then the rest; near-identical entries collapse into one.
+export function alreadyMade({ dir, name, kind, screen, limit = 8, exclude = () => false } = {}) {
+  const pid = dir ? projectId(dir) : null;
+  const all = readLayouts().filter((r) => r.skeleton?.length && !exclude(r) && (r.screen === screen || (r.kind === kind && screen === "other") || (kind !== "app" && r.screen === "landing" && screen === "hero")));
+  // Fully measured records describe best, so they win a collapse; a pick carries over to the twin kept.
+  const rank = (r) => (r.pid === pid && r.loop === name ? 4 : 0) + (r.pid === pid ? 2 : 0) + (r.picked ? 2 : 0) + (r.source === "screen" ? 1 : 0) + (r.moves ? 1.5 : 0) + Date.parse(r.at) / 1e14;
+  const out = [];
+  for (const r of all.sort((a, b) => rank(b) - rank(a))) {
+    const twin = out.find((o) => compare(o, r).total >= DUPLICATE);
+    if (twin) {
+      if (r.picked && !twin.picked) twin.pickedAs = r.route;
+      continue;
+    }
+    if (out.length < limit) out.push({ ...r });
+  }
+  return out;
+}
+
+// Directions (and direction × structure pairs) this user has already seen for this kind of screen.
+export function seenDirections(kind, screen, picks = []) {
+  const dirs = new Set();
+  const combos = new Set();
+  const shapes = {};
+  for (const r of readLayouts()) {
+    if (r.kind !== kind && r.screen !== screen) continue;
+    if (r.direction?.id) {
+      dirs.add(r.direction.id);
+      combos.add(`${r.direction.id}|${r.archetype ?? r.shape}`);
+    }
+    for (const s of new Set([r.archetype, r.shape].filter(Boolean))) shapes[s] = (shapes[s] ?? 0) + (r.screen === screen ? 2 : 1);
+  }
+  for (const p of picks) if (p.kind === kind) for (const d of p.directions ?? []) dirs.add(d.id);
+  return { dirs, combos, shapes };
+}
+
+// Generated directions that were used before (so one that keeps winning can come back).
+export function pastGenerated() {
+  const out = new Map();
+  for (const r of readLayouts()) if (r.direction?.generated && r.direction.brief) out.set(r.direction.id, { id: r.direction.id, name: r.direction.name, brief: r.direction.brief, style: r.direction.style, generated: r.direction.generated });
+  return [...out.values()];
+}
+
+// The loop's variants compared with each other and with everything already made (minus this loop's own
+// records). Returns { pairs, history: {route: best match}, originality: {route: 0–1} }.
+export function originality(dir, recs, { run } = {}) {
+  const pid = projectId(dir);
+  const routes = new Set(recs.map((r) => r.route));
+  const past = readLayouts().filter((h) => !(h.pid === pid && routes.has(h.route) && (!h.run || h.run === run)));
+  const pairs = [];
+  for (let i = 0; i < recs.length; i++)
+    for (let j = i + 1; j < recs.length; j++) pairs.push({ a: recs[i].route, b: recs[j].route, ...round(compare(recs[i], recs[j])) });
+  const history = {};
+  const orig = {};
+  for (const r of recs) {
+    let best = null;
+    for (const h of past) {
+      const c = compare(r, h);
+      if (!best || c.total > best.total) best = { project: h.project, route: h.route, at: h.at, picked: h.picked, source: h.source, samePlace: h.pid === pid, ...round(c) };
+    }
+    history[r.route] = best;
+    const inLoop = Math.max(0, ...pairs.filter((p) => p.a === r.route || p.b === r.route).map((p) => p.total));
+    orig[r.route] = +(1 - Math.max(inLoop, best?.total ?? 0)).toFixed(2);
+  }
+  return { pairs: pairs.sort((x, y) => y.total - x.total), history, originality: orig };
+}
+const round = (c) => Object.fromEntries(Object.entries(c).map(([k, v]) => [k, v == null ? null : +v.toFixed(2)]));
+
+// Where a match lives, in words.
+export const whereOf = (m) => `${m.samePlace ? "" : `${m.project} `}${m.route}${m.picked ? " (picked)" : m.source === "screen" ? " (shipped)" : ""}`;

package/src/loop/library.mjs

@@ -0,0 +1,82 @@
+// palate's reference library at runtime: plain-text search over the shipped index (kb/references), no model.
+// The index was built on our side (packages/eye: tags by a vision model, quality from designers' picks); here
+// it is only words. Results are spread across categories and sources so a sheet never shows one library twice.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { acquireBrowser } from "../pool.mjs";
+import { KB_ROOT } from "../paths.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const LIB = process.env.PALATE_LIBRARY ?? path.join(KB_ROOT, "references");
+let cache;
+
+export function library() {
+  if (!cache) cache = fs.existsSync(path.join(LIB, "index.json")) ? JSON.parse(fs.readFileSync(path.join(LIB, "index.json"), "utf8")) : [];
+  return cache;
+}
+
+const STOP = new Set(["the", "and", "for", "with", "that", "this", "from", "your", "into", "page", "screen", "section", "show", "make", "build", "new", "user", "users", "their", "them", "should", "needs", "need", "has", "have", "just", "can"]);
+const stem = (w) => w.replace(/(ies)$/, "y").replace(/(es|s)$/, "");
+const words = (s) => (String(s).toLowerCase().match(/[a-z]{3,}/g) ?? []).filter((w) => !STOP.has(w)).map(stem);
+
+// The topic decides what's relevant; the style (a direction's words) only re-orders relevant results.
+export function searchLibrary(query, { n = 9, preferWhole = false, style = "" } = {}) {
+  const lib = library();
+  if (!lib.length) return [];
+  const q = [...new Set(words(query))];
+  // Rarer words count more (idf), category words most, tags next, the rest of the text least.
+  const df = Object.fromEntries(q.map((w) => [w, lib.filter((r) => words(r.text).includes(w)).length]));
+  const idf = (w) => Math.log(1 + lib.length / (1 + df[w]));
+  const scored = lib.map((r) => {
+    const cat = words(r.category);
+    const tags = words(r.tags.join(" "));
+    const rest = words(r.text);
+    let s = 0;
+    for (const w of q) s += idf(w) * (cat.includes(w) ? 3 : tags.includes(w) ? 2 : rest.includes(w) ? 0.5 : 0);
+    // A whole tag phrase in the query ("data table", "pricing section") is a strong signal.
+    for (const t of r.tags) if (t.split(" ").length > 1 && t.split(" ").every((x) => q.includes(stem(x)))) s += 4;
+    if (r.quality != null) s += 0.6 * (r.quality - 1.5);
+    // Designing a screen: whole pages and sections beat isolated components.
+    if (preferWhole && s > 0 && (r.kind === "section" || r.kind === "page")) s += 1.5;
+    return { r, s };
+  });
+  const styleWords = new Set(words(style));
+  const relevant = scored.filter((x) => x.s > 0).sort((a, b) => b.s - a.s).slice(0, 40);
+  for (const x of relevant) x.s += 0.8 * words(x.r.tags.join(" ")).filter((w) => styleWords.has(w)).length;
+  relevant.sort((a, b) => b.s - a.s);
+  const out = [];
+  const perCat = {};
+  const perLib = {};
+  for (const { r, s } of relevant) {
+    if (s <= 0 || out.length >= n) break;
+    const libName = r.source.split(" · ")[0];
+    if ((perCat[r.category] ?? 0) >= 2 || (perLib[libName] ?? 0) >= 3) continue;
+    perCat[r.category] = (perCat[r.category] ?? 0) + 1;
+    perLib[libName] = (perLib[libName] ?? 0) + 1;
+    out.push(r);
+  }
+  return out;
+}
+
+// A numbered contact sheet (one image an agent reads cheaply) plus an index with full-size paths.
+export async function librarySheet(records, out) {
+  const cells = records.map((r, i) => {
+    const f = path.join(LIB, "thumbs", `${r.id}.jpg`);
+    return `<figure><figcaption>#${i + 1}</figcaption><img src="data:image/jpeg;base64,${fs.readFileSync(f).toString("base64")}"></figure>`;
+  });
+  const { browser, release } = await acquireBrowser();
+  try {
+    const page = await browser.newPage({ viewport: { width: 1600, height: 900 } });
+    await page.setContent(`<!doctype html><body style="margin:0;background:#ecebe7;font:600 18px system-ui"><div id="g" style="display:grid;grid-template-columns:repeat(3,500px);gap:14px;padding:14px">${cells.join("")}</div><style>figure{margin:0}figcaption{margin-bottom:6px}img{width:500px;height:320px;object-fit:cover;object-position:top;display:block;border:1px solid #c9c8c2;background:#fff}</style></body>`);
+    await page.locator("#g").screenshot({ path: out });
+    await page.close();
+  } finally {
+    await release();
+  }
+  fs.writeFileSync(
+    out.replace(/\.png$/, ".json"),
+    JSON.stringify(records.map((r, i) => ({ n: i + 1, file: path.join(LIB, "thumbs", `${r.id}.jpg`).replace(/\\/g, "/"), source: r.source, category: r.category, tags: r.tags, license: r.license, url: r.url })), null, 1),
+  );
+  return out;
+}