@palate/cli 0.0.0-stage → 0.0.1

package/src/loop/lookvec.mjs

@@ -0,0 +1,645 @@
+// The look fingerprint: a page's visual language as a few measured categories (its ground, texture, faces,
+// call to action, header, hero composition, how the hero's object is framed, imagery, density, accent), and the
+// house-look check built on it. The similarity gate (similar.mjs) compares structure and colour numbers; it
+// passed four of five benchmark pages that a person saw as one house style: warm off-white paper with grain,
+// logo left with a light outlined CTA top right, a big headline left over a grey paragraph, a filled button and an
+// underlined link, a framed product card with a soft shadow, muted neutrals and one accent. Those pages differ in
+// skeleton and hue, and match in these categories.
+//
+// Calibration (Oct 29 2026): palate's pages (Kiln v2, Tracewell, Mabel's, Open Shelf, Mira: benchmark builds;
+// palate-site live) and four real sites, each at 1440 with reduced motion, scrolled through. As measured:
+//   kiln2      warm off-white paper with grain · serif headline over sans body · split hero with a framed card with a
+//              soft shadow · solid rounded CTA + underlined link · logo-left nav, outline CTA top right · one mid blue
+//              accent · product-ui imagery · balanced
+//   tracewell  warm off-white paper with grain · bold display-face headline over sans body · object-first hero with a
+//              framed card with a soft shadow · solid rounded CTA + ghost button · logo-left nav, outline CTA top
+//              right · one mid red-orange accent · mixed imagery · dense
+//   mabels     warm off-white paper with grain · serif headline over sans body · split hero with a framed card with a
+//              soft shadow · solid rounded CTA + underlined link · logo-left nav, outline CTA top right · one muted
+//              green accent · mixed imagery · balanced
+//   open-shelf warm off-white paper with grain · bold sans headline, sans body · object-first hero with a framed card
+//              with a soft shadow · solid rounded CTA + underlined link · logo-left nav, outline CTA top right · one
+//              mid red-orange accent · mixed imagery · balanced
+//   mira       dark ground with grain · serif headline over sans body · gallery hero with a framed card with a soft
+//              shadow · solid square CTA · logo-left nav, outline CTA top right · one mid red-orange accent · photo imagery
+//   site       full-bleed photo ground with grain · sans headline, sans body · full-bleed media hero · solid rounded
+//              CTA · logo-left nav, solid CTA top right · one mid green accent · product-ui imagery
+//   linear     dark ground with grain · sans · object-first hero, edge to edge · text-link CTA · solid pill CTA top right
+//   stripe     white paper · light sans headline, sans body · full-bleed media hero (the canvas wave) · solid rounded CTA
+//   notion     white paper · bold sans · centred hero with a framed card with a soft shadow · two solid CTAs · 3 colours
+//   raycast    dark ground · bold sans · centred hero · solid rounded CTA · one vivid red accent
+//
+// lookSimilarity:
+//                kiln2 trace mabel shelf  mira  site linear stripe notion raycast
+//   kiln2           -  0.56  0.83  0.59  0.44  0.25  0.26  0.15  0.21  0.09
+//   tracewell    0.56     -  0.60  0.72  0.36  0.29  0.38  0.27  0.29  0.23
+//   mabels       0.83  0.60     -  0.63  0.48  0.25  0.30  0.17  0.21  0.13
+//   open-shelf   0.59  0.72  0.63     -  0.36  0.37  0.46  0.33  0.37  0.31
+//   mira         0.44  0.36  0.48  0.36     -  0.17  0.34  0.13  0.25  0.35
+//   palate-site  0.25  0.29  0.25  0.37  0.17     -  0.42  0.48  0.20  0.20
+//   linear       0.26  0.38  0.30  0.46  0.34  0.42     -  0.38  0.26  0.42
+//   stripe       0.15  0.27  0.17  0.33  0.13  0.48  0.38     -  0.46  0.28
+//   notion       0.21  0.29  0.21  0.37  0.25  0.20  0.26  0.46     -  0.48
+//   raycast      0.09  0.23  0.13  0.31  0.35  0.20  0.42  0.28  0.48     -
+//
+// The four house-look siblings score 0.56–0.83 against each other; every other pair is at most 0.48 (Mabel's vs
+// Mira, two palate pages sharing a serif, grain and the outlined header button; Notion vs Raycast; palate-site vs
+// Stripe). HOUSE_LOOK_FAIL 0.53 fails every sibling pair and no other; HOUSE_LOOK_WARN 0.50 says so a step before,
+// above every independent pair. With the plain weights (every exact match full credit) the real sites converged on
+// the choices nearly every site makes (Notion vs Raycast 0.72 against Kiln vs Tracewell 0.58), so a match on such
+// a default counts half (COMMON), and the header's CTA and the action beside the primary button count inside their
+// axes: then the groups separate.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { stackGenre, fontGenre, FONT_GENRES } from "../fontgenre.mjs";
+import { PALATE_HOME } from "../catalog/store.mjs";
+import { buttonSimilarity, comparableButtonAxes, describeButtons, otherLanguages, resolveButtons, BUTTON_LANGUAGES } from "./buttons.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const lookScript = fs.readFileSync(path.join(here, "..", "page-look.js"), "utf8").trim().replace(/;\s*$/, "");
+
+export const LOOKS = path.join(PALATE_HOME, "history", "looks.jsonl");
+export const HOUSE_LOOK_FAIL = 0.53;
+export const HOUSE_LOOK_WARN = 0.5;
+export const RECENT = 12;
+
+// The class names (shared with the blueprint's planned look).
+export const AXES = {
+  ground: ["white", "light-warm", "light-cool", "light-neutral", "mid", "dark", "colour", "photo"],
+  header: ["logo-left-nav-cta", "centred-wordmark", "logo-cta", "split", "overlay", "side", "none"],
+  cta: ["solid-rounded", "solid-pill", "solid-square", "outline", "text-link", "gradient"],
+  hero: ["split", "split-reversed", "centred", "full-bleed", "type-only", "object-first", "editorial", "gallery"],
+  frame: ["shadow-card", "border-card", "flat", "bleed", "none"],
+  imagery: ["product-ui", "photo", "illustration", "type-only", "mixed"],
+  density: ["airy", "balanced", "dense"],
+};
+// buttons: the whole button language (shape, fill, size, label, adornment, the second action and, measured, the
+// finish), next to cta's coarse fill-and-shape class. One axis among eleven: the same button on two pages adds to
+// a shared look, it doesn't make one (the button check below says it on its own).
+export const WEIGHTS = { ground: 2, texture: 1, display: 2, body: 0.5, header: 1, cta: 1, buttons: 1, hero: 2, frame: 1, imagery: 1, accent: 0.5, density: 0.5 };
+// Pairs that are near each other: half a match.
+const NEAR = [
+  ["ground", "light-warm", "light-neutral"],
+  ["ground", "light-neutral", "white"],
+  ["ground", "light-cool", "light-neutral"],
+  ["ground", "light-cool", "white"],
+  ["ground", "mid", "dark"],
+  ["header", "logo-left-nav-cta", "logo-cta"],
+  ["header", "centred-wordmark", "split"],
+  ["cta", "solid-rounded", "solid-pill"],
+  ["cta", "solid-rounded", "solid-square"],
+  ["cta", "solid-rounded", "gradient"],
+  ["cta", "solid-pill", "gradient"],
+  ["hero", "split", "split-reversed"],
+  // A headline beside or over a product object: Tracewell's text-over-a-wide-framed-board is Kiln's split recipe
+  // stacked, and a person reads them as one hero.
+  ["hero", "split", "object-first"],
+  ["hero", "centred", "object-first"],
+  ["hero", "type-only", "editorial"],
+  ["hero", "full-bleed", "object-first"],
+  ["hero", "centred", "type-only"],
+  ["frame", "shadow-card", "border-card"],
+  ["frame", "flat", "none"],
+  ["imagery", "mixed", "product-ui"],
+  ["imagery", "mixed", "photo"],
+  ["imagery", "mixed", "illustration"],
+  ["density", "airy", "balanced"],
+  ["density", "balanced", "dense"],
+];
+const nearSet = new Set(NEAR.flatMap(([a, x, y]) => [`${a}:${x}:${y}`, `${a}:${y}:${x}`]));
+
+// ---- colour: sRGB hex → OKLab lightness, chroma and hue
+const hexRgb = (h) => (h && /^#[0-9a-f]{6}$/i.test(h) ? [1, 3, 5].map((i) => parseInt(h.slice(i, i + 2), 16)) : null);
+export function oklch(hexColour) {
+  const rgb = hexRgb(hexColour);
+  if (!rgb) return null;
+  const lin = rgb.map((v) => {
+    const c = v / 255;
+    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  const l = Math.cbrt(0.4122214708 * lin[0] + 0.5363325363 * lin[1] + 0.0514459929 * lin[2]);
+  const m = Math.cbrt(0.2119034982 * lin[0] + 0.6806995451 * lin[1] + 0.1073969566 * lin[2]);
+  const s = Math.cbrt(0.0883024619 * lin[0] + 0.2817188376 * lin[1] + 0.6299787005 * lin[2]);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const a = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const b = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const C = Math.hypot(a, b);
+  let H = (Math.atan2(b, a) * 180) / Math.PI;
+  if (H < 0) H += 360;
+  return { L, C, H };
+}
+
+// The class of a ground colour.
+export function groundClass(hexColour) {
+  const c = oklch(hexColour);
+  if (!c) return null;
+  const { L, C, H } = c;
+  if (C >= 0.075 || (L < 0.86 && L > 0.3 && C >= 0.05)) return "colour";
+  if (L >= 0.86) {
+    if (L >= 0.985 && C < 0.006) return "white";
+    // Warm: cream, beige, paper (OKLab hue from red-orange through yellow). Cool: blue-grey, mint, ice.
+    if (C >= 0.006 && H >= 20 && H <= 125) return "light-warm";
+    if (C >= 0.006 && H >= 150 && H <= 290) return "light-cool";
+    return "light-neutral";
+  }
+  if (L <= 0.36) return "dark";
+  return "mid";
+}
+const CHROMA = (C) => (C < 0.09 ? "muted" : C < 0.16 ? "mid" : "vivid");
+const SAT = 0.06; // a colour is "saturated" (an accent, not a neutral) from this OKLab chroma
+const hueBucket = (H) => Math.floor(((H % 360) + 360) % 360 / 30);
+// OKLab hue angles (not HSL): red sits near 25°, orange 55°, yellow 100°, green 145°, cyan 195°, blue 265°, violet 315°.
+const HUE_NAMES = ["red", "red-orange", "orange", "yellow", "lime", "green", "teal", "sky", "blue", "indigo", "violet", "pink"];
+
+// A family stack's genre, after removing what font loaders add (Next's "__Fraunces_6f2b1c", "Fraunces Variable",
+// "Inter Fallback") and trying the known families by prefix ("Tiempos Headline" → tiempos → serif).
+const KNOWN = Object.entries(FONT_GENRES).flatMap(([g, names]) => names.map((n) => [n, g])).sort((a, b) => b[0].length - a[0].length);
+export function familyGenre(stack) {
+  const parts = String(stack ?? "")
+    .split(",")
+    .map((x) =>
+      x
+        .replace(/["']/g, "")
+        .trim()
+        .replace(/^_+/, "")
+        .replace(/_(fallback_)?[0-9a-f]{5,}$/i, "")
+        .replace(/_/g, " ")
+        .replace(/\b(variable|vf|fallback|web|webfont)\b/gi, "")
+        .trim(),
+    )
+    .filter(Boolean);
+  // Known families first, exact then by prefix ("SF Pro Display" is SF Pro, a sans, not a display face), then the
+  // name's own words (fontgenre.mjs).
+  for (const p of parts) {
+    const lower = p.toLowerCase();
+    const hit = KNOWN.find(([n]) => lower === n) ?? KNOWN.find(([n]) => n.length >= 4 && lower.startsWith(n + " "));
+    if (hit) return hit[1];
+    const g = fontGenre(p);
+    if (g !== "unknown") return g;
+  }
+  return stackGenre(parts.join(", "));
+}
+const firstFamily = (stack) => String(stack ?? "").split(",")[0].replace(/["']/g, "").trim().replace(/^_+/, "").replace(/_(fallback_)?[0-9a-f]{5,}$/i, "").replace(/_/g, " ");
+
+// ---- raw page facts → the look vector
+export function vectorFrom(raw) {
+  const area = raw.width * raw.pageH;
+  // Ground: band colours by height, photo bands left out; a picture that covers the first screen is the ground.
+  // The first screen counts three times over: a reader takes the page's ground from it (Mira's dark contact-sheet
+  // hero over a light page reads as a dark page).
+  const byClass = new Map();
+  const byHex = new Map();
+  const vh = raw.vh ?? 900;
+  for (const b of raw.bands ?? []) {
+    if (b.photo) continue;
+    const k = groundClass(b.bg);
+    if (!k) continue;
+    const h = b.h + 2 * Math.max(0, Math.min(b.y + b.h, vh) - Math.max(b.y, 0));
+    byClass.set(k, (byClass.get(k) ?? 0) + h);
+    byHex.set(b.bg, (byHex.get(b.bg) ?? 0) + h);
+  }
+  const top = (m) => [...m.entries()].sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
+  const groundHex = top(byHex) ?? raw.rootBg;
+  const ground = raw.firstScreenPhoto ? "photo" : top(byClass) ?? groundClass(raw.rootBg) ?? "white";
+  const groundBands = (raw.bands ?? []).map((b) => (b.photo ? "photo" : groundClass(b.bg) ?? "?"));
+
+  const d = raw.display;
+  const display = d
+    ? {
+        genre: familyGenre(d.family),
+        family: firstFamily(d.family),
+        weight: d.weight <= 350 ? "light" : d.weight >= 800 ? "black" : d.weight >= 600 ? "bold" : "regular",
+        case: d.upper ? "upper" : "normal",
+        italic: Boolean(d.italic),
+        size: d.size <= 48 ? "s" : d.size <= 80 ? "m" : "l",
+        px: d.size,
+        tracking: d.tracking < -0.01 ? "tight" : d.tracking > 0.04 ? "wide" : "normal",
+      }
+    : null;
+  const body = raw.body ? { genre: familyGenre(raw.body), family: firstFamily(raw.body) } : null;
+
+  // Accent: the primary CTA's fill when it is saturated, else the most used saturated colour (fills by area,
+  // text by its ink). Colourfulness: saturated hues that cover a large area (2% of the page or more).
+  const sat = (h) => {
+    const c = oklch(h);
+    return c && c.C >= SAT && c.L > 0.2 && c.L < 0.97 ? c : null;
+  };
+  let accentHex = raw.cta?.fill && sat(raw.cta.fill) ? raw.cta.fill : null;
+  if (!accentHex) {
+    const use = new Map();
+    for (const f of [...(raw.fills ?? []), ...(raw.textColours ?? [])]) if (sat(f.hex)) use.set(f.hex, (use.get(f.hex) ?? 0) + f.a);
+    accentHex = top(use);
+  }
+  const ac = accentHex ? oklch(accentHex) : null;
+  const hueArea = new Map();
+  for (const f of raw.fills ?? []) {
+    const c = sat(f.hex);
+    if (c) hueArea.set(hueBucket(c.H), (hueArea.get(hueBucket(c.H)) ?? 0) + f.a);
+  }
+  const colourful = [...hueArea.values()].filter((a) => a >= 0.02 * area).length;
+  const accent = ac ? { hex: accentHex, hue: hueBucket(ac.H), hueName: HUE_NAMES[hueBucket(ac.H)], chroma: CHROMA(ac.C), colourful } : { hex: null, hue: null, hueName: null, chroma: "none", colourful };
+
+  const hdrCta = raw.header?.cta ?? "none";
+  const header = { pattern: raw.header?.pattern ?? "none", cta: hdrCta };
+  const ctaStyle = (s) => (!s ? "text-link" : s === "text-link-underlined" ? "text-link" : s === "outline-pill" ? "outline" : s);
+  const cta = { style: ctaStyle(raw.cta?.style), secondary: raw.secondary ?? "none", text: raw.cta?.text ?? null };
+  const buttons = measuredButtons(raw);
+
+  // Imagery: by area; nothing much is type-only; two modes each a third or more is mixed.
+  const ia = raw.imagery?.area ?? {};
+  const total = Object.values(ia).reduce((x, y) => x + y, 0);
+  let imagery;
+  if (!total || (raw.imagery?.share ?? 0) < 0.03) imagery = "type-only";
+  else {
+    const ranked = Object.entries(ia).sort((a, b) => b[1] - a[1]);
+    imagery = ranked[1] && ranked[1][1] >= 0.33 * total ? "mixed" : ranked[0][0];
+  }
+  // Density: ink over the first three screens (calibrated: sparse statement pages ~0.25, product pages 0.35–0.5,
+  // packed catalogues above 0.55).
+  const density = raw.ink < 0.3 ? "airy" : raw.ink > 0.55 ? "dense" : "balanced";
+
+  return {
+    v: 1,
+    ground,
+    groundHex,
+    groundBands,
+    texture: Boolean(raw.texture),
+    display,
+    body,
+    accent,
+    header,
+    cta,
+    buttons,
+    hero: raw.hero,
+    frame: raw.frame,
+    imagery,
+    density,
+    ink: raw.ink,
+  };
+}
+
+// The button language a page shows: the six axes of buttons.mjs plus the finish they're measured with.
+const SEC_OF = { "underlined-link": "text-link", "text-link": "text-link", ghost: "ghost", solid: "solid", none: "none" };
+export function measuredButtons(raw) {
+  const p = raw?.buttons?.primary;
+  if (!p) return null;
+  const boxless = p.fill === "underline" || p.fill === "ghost";
+  const share = p.h ? Math.min(p.radius, p.h / 2) / p.h : 0;
+  const shape = boxless ? "none" : p.radius <= 3 || share <= 0.08 ? "square" : share >= 0.45 ? "pill" : "soft";
+  const size = boxless ? (p.px >= 19 ? "large" : p.px <= 14 ? "compact" : "standard") : p.h < 40 ? "compact" : p.h < 54 ? "standard" : "large";
+  const genre = familyGenre(p.family);
+  const [mine, body, disp] = [firstFamily(p.family), firstFamily(raw.body), firstFamily(raw.display?.family)].map((x) => String(x ?? "").toLowerCase());
+  const label = genre === "mono" ? "mono" : p.upper ? "upper-tracked" : mine && mine !== body && (mine === disp || genre !== familyGenre(raw.body)) ? "display" : "sentence";
+  const sec = raw.buttons.secondaryStyle ?? raw.secondary ?? "none";
+  return {
+    shape,
+    fill: p.fill,
+    size,
+    label,
+    adornment: p.adornment ?? "none",
+    secondary: SEC_OF[sec] ?? "none",
+    finish: { h: p.h, radiusShare: +share.toFixed(2), px: p.px, weight: p.weight, tracking: p.tracking, edge: p.edge ?? null, genre, contrast: p.contrast, secondaryUnderlined: sec === "underlined-link" },
+    text: p.text ?? null,
+  };
+}
+
+// ---- similarity: weighted exact matches, near categories half. Missing axes (a planned look may have no
+// density, accent or body yet) are skipped and the weights renormalised.
+const axisValue = (v, axis) => {
+  if (!v) return undefined;
+  switch (axis) {
+    case "ground":
+      return v.ground;
+    case "texture":
+      return v.texture;
+    case "display":
+      return v.display?.genre ?? (typeof v.display === "string" ? v.display : undefined);
+    case "body":
+      return v.body?.genre ?? (typeof v.body === "string" ? v.body : undefined);
+    case "header":
+      return v.header?.pattern ?? (typeof v.header === "string" ? v.header : undefined);
+    case "cta":
+      return v.cta?.style ?? (typeof v.cta === "string" ? v.cta : undefined);
+    case "buttons":
+      // A language says enough to compare when it states at least four axes (a coarse cta says two or three).
+      return v.buttons && typeof v.buttons === "object" && AXIS_COUNT(v.buttons) >= 4 ? v.buttons : undefined;
+    case "hero":
+      return v.hero;
+    case "frame":
+      return v.frame;
+    case "imagery":
+      return v.imagery;
+    case "accent":
+      return v.accent?.hue ?? (typeof v.accent === "number" ? v.accent : undefined);
+    case "density":
+      return v.density;
+  }
+};
+const AXIS_COUNT = (b) => comparableButtonAxes(b, b).length;
+const known = (x) => x !== undefined && x !== null && x !== "unknown" && x !== "?";
+
+// The choices nearly every site makes: two pages sharing one of them says little about a shared look, so such a
+// match counts half (without this, Notion and Raycast, both a sans over a sans with a logo-left nav and a solid
+// rounded button and no texture, scored 0.72 and outranked two pages of palate's house style).
+export const COMMON = { texture: [false], display: ["sans"], body: ["sans"], density: ["balanced"], header: ["logo-left-nav-cta"], cta: ["solid-rounded"] };
+export const COMMON_CREDIT = 0.5;
+// Two button languages this close are the same button (the five Nov 6 benchmark pages score 0.8–0.97 with each
+// other; see the calibration under BUTTON_REPEAT_FAIL).
+export const BUTTON_SAME = 0.8;
+const sub = (a, b, key) => {
+  const x = a?.[key], y = b?.[key];
+  return x != null && y != null ? (x === y && x !== "none" ? 1 : 0) : null;
+};
+
+// { score 0–1, same: axes that match exactly, near: axes that match in part, parts: { axis: credit } }.
+export function lookSimilarity(a, b) {
+  let sum = 0, weight = 0;
+  const same = [], near = [], parts = {};
+  for (const [axis, w] of Object.entries(WEIGHTS)) {
+    const x = axisValue(a, axis), y = axisValue(b, axis);
+    if (!known(x) || !known(y)) continue;
+    weight += w;
+    let s = 0;
+    if (axis === "buttons") {
+      const m = buttonSimilarity(x, y);
+      s = m.score;
+      if (s >= BUTTON_SAME) same.push(axis);
+      else if (s > 0) near.push(axis);
+      parts[axis] = +s.toFixed(2);
+      sum += w * s;
+      continue;
+    }
+    if (axis === "accent") {
+      const d = Math.min(Math.abs(x - y), 12 - Math.abs(x - y));
+      s = d === 0 ? 1 : d === 1 ? 0.5 : 0;
+    } else if (x === y) s = COMMON[axis]?.includes(x) ? COMMON_CREDIT : 1;
+    else if (nearSet.has(`${axis}:${x}:${y}`)) s = 0.5;
+    // The header's own CTA (the house look's light outlined button top right) is part of the header; the action
+    // beside the primary button (the underlined link) is part of the CTA. Only when both looks say.
+    if (axis === "header") {
+      const c = sub(a.header, b.header, "cta");
+      if (c != null) s = 0.6 * s + 0.4 * c;
+    }
+    if (axis === "cta") {
+      const c = sub(a.cta, b.cta, "secondary");
+      if (c != null) s = 0.7 * s + 0.3 * c;
+    }
+    if (x === y) same.push(axis);
+    else if (s > 0) near.push(axis);
+    parts[axis] = +s.toFixed(2);
+    sum += w * s;
+  }
+  return { score: weight ? +(sum / weight).toFixed(3) : 0, same, near, parts, weight };
+}
+
+// ---- in words
+const GROUND_WORDS = { white: "white", "light-warm": "warm off-white", "light-cool": "cool light", "light-neutral": "light grey", mid: "mid-tone", dark: "dark", colour: "colour-field", photo: "full-bleed photo" };
+const HERO_WORDS = { split: "split hero", "split-reversed": "split hero (object left)", centred: "centred hero", "full-bleed": "full-bleed media hero", "type-only": "type-only statement hero", "object-first": "object-first hero", editorial: "editorial-column hero", gallery: "gallery hero" };
+const FRAME_WORDS = { "shadow-card": "a framed card with a soft shadow", "border-card": "a bordered card", flat: "an unframed object", bleed: "edge to edge", none: "no object" };
+const HEADER_WORDS = { "logo-left-nav-cta": "logo-left nav", "centred-wordmark": "centred wordmark", "logo-cta": "logo and one action", split: "split nav around a centred logo", overlay: "header over the image", side: "side navigation", none: "no header" };
+const CTA_WORDS = { "solid-rounded": "solid rounded CTA", "solid-pill": "solid pill CTA", "solid-square": "solid square CTA", outline: "outline CTA", "text-link": "text-link CTA", gradient: "gradient CTA" };
+const HDR_CTA_WORDS = { "outline-pill": "pill CTA top right", outline: "outline CTA top right", "solid-pill": "solid pill CTA top right", "solid-rounded": "solid CTA top right", "solid-square": "square CTA top right", gradient: "gradient CTA top right", "text-link": "text links only", "text-link-underlined": "text links only", none: "no CTA" };
+const SEC_WORDS = { "underlined-link": " + underlined link", "text-link": " + text link", ghost: " + ghost button", solid: " + second solid button", none: "" };
+
+export function describeLook(v) {
+  if (!v) return "no look measured";
+  const parts = [];
+  parts.push(`${GROUND_WORDS[v.ground] ?? v.ground ?? "?"} ${v.ground === "photo" ? "ground" : "paper"}${v.texture ? " with grain" : ""}`.replace("paper", v.ground === "dark" || v.ground === "colour" || v.ground === "mid" ? "ground" : "paper"));
+  const dg = v.display?.genre ?? v.display;
+  const bg = v.body?.genre ?? v.body;
+  if (dg) {
+    const mods = [v.display?.case === "upper" ? "uppercase" : null, v.display?.italic ? "italic" : null, v.display?.weight && v.display.weight !== "regular" ? v.display.weight : null].filter(Boolean).join(" ");
+    const g = (x) => (x === "display" ? "display-face" : x);
+    parts.push(`${mods ? mods + " " : ""}${g(dg)} headline${bg ? (bg === dg ? `, ${g(bg)} body` : ` over ${g(bg)} body`) : ""}`);
+  }
+  if (v.hero) parts.push(`${HERO_WORDS[v.hero] ?? v.hero}${v.frame && v.frame !== "none" && v.hero !== "full-bleed" ? ` with ${FRAME_WORDS[v.frame] ?? v.frame}` : ""}`);
+  const ctaStyle = v.cta?.style ?? v.cta;
+  if (v.buttons && AXIS_COUNT(v.buttons) >= 4) parts.push(`button: ${describeButtons(v.buttons)}`);
+  else if (ctaStyle) parts.push(`${CTA_WORDS[ctaStyle] ?? ctaStyle}${SEC_WORDS[v.cta?.secondary] ?? ""}`);
+  const hp = v.header?.pattern ?? v.header;
+  if (hp) parts.push(`${HEADER_WORDS[hp] ?? hp}${v.header?.cta && hp !== "none" && hp !== "side" ? `, ${HDR_CTA_WORDS[v.header.cta] ?? v.header.cta}` : ""}`);
+  if (v.accent && v.accent.chroma) {
+    const n = v.accent.colourful ?? 0;
+    parts.push(v.accent.chroma === "none" ? "no accent colour" : n >= 3 ? `${n} colours in large areas, ${v.accent.chroma} ${v.accent.hueName} lead` : `one ${v.accent.chroma} ${v.accent.hueName} accent`);
+  }
+  if (v.imagery) parts.push(v.imagery === "type-only" ? "type only" : `${v.imagery} imagery`);
+  if (v.density) parts.push(v.density);
+  return parts.join(" · ");
+}
+
+// ---- measuring
+// On an open page (any width ≥ 1000, scrolled through so reveals fired).
+export async function measureLook(page, { sections } = {}) {
+  const secs = sections ?? (await (await import("../look.mjs")).findSections(page));
+  const raw = await page.evaluate(`(${lookScript})(${JSON.stringify({ sections: secs })})`);
+  return { look: vectorFrom(raw), raw };
+}
+
+// Renders the route at 1440 with reduced motion, scrolled through, and measures its look.
+export async function lookOf(dir, route, { url, raw: withRaw = false } = {}) {
+  const { withBrowser, openPage, findSections } = await import("../look.mjs");
+  return withBrowser(dir, { url }, async ({ base, browser }) => {
+    const { page, ctx } = await openPage(browser, base, route, { width: 1440, reducedMotion: true });
+    try {
+      const sections = await findSections(page);
+      const m = await measureLook(page, { sections });
+      return withRaw ? m : m.look;
+    } finally {
+      await ctx.close();
+    }
+  });
+}
+
+// ---- the record: ~/.palate/history/looks.jsonl, one latest look per project and route
+const readLines = (f) => {
+  try {
+    return fs
+      .readFileSync(f, "utf8")
+      .split("\n")
+      .filter(Boolean)
+      .map((l) => {
+        try {
+          return JSON.parse(l);
+        } catch {
+          return null;
+        }
+      })
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+};
+// One record per project and route: the latest line wins. The file is append-only, so parallel runs (five benchmark
+// builds at once) never drop each other's records the way a read-filter-rewrite did.
+const latestLooks = (file) => {
+  const by = new Map();
+  for (const r of readLines(file)) {
+    const key = `${r.pid}|${r.route}`;
+    by.delete(key);
+    by.set(key, r);
+  }
+  return [...by.values()];
+};
+export const readLooks = (file = LOOKS) => latestLooks(file);
+
+export async function recordLook(dir, route, look, { screen, file = LOOKS, project } = {}) {
+  if (!look) return null;
+  const { projectId, isBenchRecord, isProjectDir, screenKindOf } = await import("./layouts.mjs");
+  // A throwaway folder that only shot someone else's page isn't a project: its record would be a copy of that one.
+  if (!isProjectDir(dir)) return null;
+  const name = project ?? path.basename(path.resolve(dir));
+  const pid = projectId(dir);
+  const bench = fs.existsSync(path.join(dir, ".palate", "bench.json")) || isBenchRecord({ project: name });
+  const rec = { project: name, pid, route, at: new Date().toISOString(), look, bench, screen: screen ?? screenKindOf({ route }) ?? null };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.appendFileSync(file, JSON.stringify(rec) + "\n");
+  return rec;
+}
+
+// The latest looks palate measured, newest first, without one project (the page being checked). Benchmark
+// pages count: the point is palate's own output.
+export function recentLooks({ excludePid, limit = RECENT, file = LOOKS } = {}) {
+  return latestLooks(file)
+    .filter((r) => r.look && r.pid !== excludePid)
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)))
+    .slice(0, limit);
+}
+
+// The closest recent look in another project: { record, score, same, near } or null.
+export function closestLook(look, { excludePid, exclude = [], limit = RECENT, file } = {}) {
+  const skip = new Set(exclude.map((x) => String(x).toLowerCase()));
+  let best = null;
+  for (const r of recentLooks({ excludePid, limit, file })) {
+    if (skip.has(String(r.project).toLowerCase())) continue;
+    const s = lookSimilarity(look, r.look);
+    if (!best || s.score > best.score) best = { record: r, ...s };
+  }
+  return best;
+}
+
+// ---- the house-look check
+const AXIS_WORDS = { ground: "the ground", texture: "the grain", display: "the display face's genre", body: "the body face's genre", header: "the header", cta: "the button style", buttons: "the button language", hero: "the hero composition", frame: "the hero object's frame", imagery: "the imagery", accent: "the accent hue", density: "the density" };
+const CHANGE = {
+  ground: (v) => `a ground of this product's own (not ${GROUND_WORDS[v.ground] ?? v.ground} again)`,
+  texture: (v) => (v.texture ? "drop the grain, or use a material that belongs to this product" : "a material that belongs to this product"),
+  display: (v) => `a display face that isn't a ${v.display?.genre ?? v.display}, chosen for this product's character`,
+  header: (v) => `a header that isn't ${HEADER_WORDS[v.header?.pattern ?? v.header] ?? "the same"} with ${HDR_CTA_WORDS[v.header?.cta] ?? "the same CTA"} (a centred wordmark, a split nav, over the image, or none)`,
+  cta: (v) => `another button language than the ${CTA_WORDS[v.cta?.style ?? v.cta] ?? "the same CTA"}${SEC_WORDS[v.cta?.secondary] ?? ""}`,
+  buttons: (v) => buttonChange(v.buttons),
+  hero: (v) => `a hero other than the ${HERO_WORDS[v.hero] ?? v.hero} (${AXES.hero.filter((h) => h !== v.hero && !nearSet.has(`hero:${h}:${v.hero}`)).slice(0, 4).join(", ")} …)`,
+  frame: (v) => `present the object other than as ${FRAME_WORDS[v.frame] ?? v.frame} (bleed it, set it flat, or let it be the page)`,
+  imagery: (v) => `another kind of imagery than ${v.imagery}`,
+};
+// What to change about a button, in words: two library languages far from it.
+function buttonChange(b, tags) {
+  const alt = otherLanguages(b, { tags });
+  return `a button language of this product's own, not ${b ? `"${describeButtons(b)}"` : "the same button"} again (from the research; e.g. ${alt.map((n) => `${n}: ${BUTTON_LANGUAGES[n].words}`).join("; or ")})`;
+}
+
+// The axes that carry a match, most weight first: exact or near, worth at least half their weight.
+const repeated = (m) => Object.entries(m.parts ?? {}).filter(([a, c]) => WEIGHTS[a] >= 1 && c >= 0.5).sort((x, y) => WEIGHTS[y[0]] * y[1] - WEIGHTS[x[0]] * x[1]).map(([a]) => a);
+const listWords = (xs) => (xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs.at(-1)}`);
+
+// One floor-style check ({ id, width, section, severity, what, fix }) or null. like: projects the user asked to
+// match (their look is allowed). keep: an existing page whose blueprint kept the brand (exempt).
+export function houseLookFinding(look, { excludePid, like = [], file, fail = HOUSE_LOOK_FAIL, warn = HOUSE_LOOK_WARN } = {}) {
+  const best = closestLook(look, { excludePid, exclude: like, file });
+  if (!best || best.score < warn) return { check: null, best };
+  const severity = best.score >= fail ? "fail" : "warn";
+  const strong = repeated(best);
+  const who = `${best.record.project} ${best.record.route}${best.record.bench ? " (a palate benchmark page)" : ""}`;
+  const sameButton = (best.parts?.buttons ?? 0) >= BUTTON_SAME ? `; the same button: ${describeButtons(look.buttons)}` : "";
+  const what = `the look is ${Math.round(best.score * 100)}% like ${who} (house-look gate ${Math.round(fail * 100)}%): ${listWords(strong.slice(0, 5).map((a) => AXIS_WORDS[a]))} all repeat ${best.record.project}'s ("${describeLook(best.record.look)}")${sameButton}`;
+  const fix = `Change at least two of ${listWords(strong.filter((a) => CHANGE[a]).slice(0, 3).map((a) => AXIS_WORDS[a]))}, from this product's own research: ${strong.filter((a) => CHANGE[a]).slice(0, 2).map((a) => CHANGE[a](look)).join("; ")}.`;
+  return { check: { id: "HOUSE_LOOK", width: 1440, section: null, severity, what, fix, score: best.score, against: `${best.record.project} ${best.record.route}` }, best };
+}
+
+// ---- the button check: the same button language as palate's recent pages, whatever else differs. The whole-look
+// check above can't see it: five pages with five grounds, faces and heroes stay far apart as looks (0.29–0.42 with
+// each other) while every one of them has the same button. It fails when the button repeats palate's recent pages
+// as a habit (at BUTTON_REPEAT_FAIL against two of them, or at BUTTON_REPEAT_WARN against three), and warns on
+// one. Older records that only know the coarse cta class aren't compared.
+//
+// Calibration (Nov 7 2026), measured at 1440 with reduced motion: the five r4 benchmark pages and palate-site
+// (running locally), linear.app, apple.com and stripe.com live. buttonSimilarity:
+//                trace mabel shelf  kiln  mira  site linear apple stripe
+//   tracewell       -  0.68  0.78  0.77  0.84  0.75  0.45  0.62  0.71
+//   mabels       0.68     -  0.79  0.84  0.65  0.68  0.33  0.70  0.62
+//   open-shelf   0.78  0.79     -  0.87  0.75  0.75  0.39  0.58  0.74
+//   kiln         0.77  0.84  0.87     -  0.74  0.78  0.35  0.60  0.70
+//   mira         0.84  0.65  0.75  0.74     -  0.86  0.52  0.52  0.72
+//   palate-site  0.75  0.68  0.75  0.78  0.86     -  0.52  0.61  0.79
+//   linear       0.45  0.33  0.39  0.35  0.52  0.52     -  0.50  0.60
+//   apple        0.62  0.70  0.58  0.60  0.52  0.61  0.50     -  0.75
+//   stripe       0.71  0.62  0.74  0.70  0.72  0.79  0.60  0.75     -
+// Each r4 page against the other four: tracewell, open-shelf, kiln and mira fail, mabels (a pill) warns. linear
+// (a boxless text action) and apple (a regular-weight pill with no ring and a ghost partner) pass; stripe (a 48px
+// solid box with a small radius, but regular weight and no ring) warns on two. palate-site fails: its button
+// (52px solid, small radius, ring and contact shadow, medium label, an arrow) is palate's own, the same family.
+export const BUTTON_REPEAT_FAIL = 0.8;
+export const BUTTON_REPEAT_WARN = 0.72;
+export const BUTTON_REPEAT_HABIT = 3;
+const BUTTON_AXIS_WORDS = { shape: "the shape", fill: "the fill", size: "the size", label: "the label", adornment: "the adornment", secondary: "the second action" };
+export function buttonRepeatFinding(look, { excludePid, like = [], file, planned = null, tags = [], fail = BUTTON_REPEAT_FAIL, warn = BUTTON_REPEAT_WARN, limit = RECENT } = {}) {
+  const mine = look?.buttons;
+  if (!mine || AXIS_COUNT(mine) < 4) return { check: null, matches: [] };
+  const skip = new Set(like.map((x) => String(x).toLowerCase()));
+  const matches = [];
+  for (const r of recentLooks({ excludePid, limit, file })) {
+    if (skip.has(String(r.project).toLowerCase())) continue;
+    const theirs = r.look?.buttons;
+    if (!theirs || AXIS_COUNT(theirs) < 4) continue;
+    const m = buttonSimilarity(mine, theirs);
+    if (m.score >= warn) matches.push({ record: r, ...m });
+  }
+  matches.sort((a, b) => b.score - a.score);
+  if (!matches.length) return { check: null, matches };
+  const severity = matches.filter((m) => m.score >= fail).length >= 2 || matches.length >= BUTTON_REPEAT_HABIT ? "fail" : "warn";
+  const who = listWords(matches.slice(0, 4).map((m) => `${m.record.project} (${Math.round(m.score * 100)}%)`));
+  const what = `the same button as ${who}: ${describeButtons(mine)}`;
+  const axes = matches[0].same.map((a) => BUTTON_AXIS_WORDS[a]).filter(Boolean);
+  const plan = planned && buttonSimilarity(planned, mine).score < 0.6 ? ` The blueprint planned "${describeButtons(planned)}": build that (.btn-primary and .btn-secondary in tokens.css carry it).` : "";
+  const fix = `Change at least three of ${listWords(axes.length ? axes : ["the shape", "the fill", "the label"])}, with ${buttonChange(mine, tags)}.${plan}`;
+  return { check: { id: "BUTTON_REPEAT", width: 1440, section: null, severity, what, fix, score: matches[0].score, against: matches.map((m) => m.record.project) }, matches };
+}
+
+// For the quality gate (gate.mjs prepare): measures the page's look, records it, and adds HOUSE_LOOK to the floor
+// result. Exempt: projects the user asked to match (like/likeOf) and an existing page whose blueprint kept the
+// brand. Never throws: a page that can't be measured just isn't checked.
+export async function houseLookCheck(dir, route, floor, { url } = {}) {
+  try {
+    const { projectId } = await import("./layouts.mjs");
+    const { likeOf } = await import("./similar.mjs");
+    const { loadBlueprint } = await import("./blueprint.mjs");
+    const look = await lookOf(dir, route, { url });
+    await recordLook(dir, route, look);
+    const bp = loadBlueprint(dir, { route });
+    floor.look = { describe: describeLook(look) };
+    if (bp?.mode === "existing" && bp.system?.keep !== false) {
+      floor.look.exempt = "an existing page that keeps its brand";
+      return floor;
+    }
+    const { check, best } = houseLookFinding(look, { excludePid: projectId(dir), like: likeOf(dir, route) });
+    if (best) floor.look.closest = { where: `${best.record.project} ${best.record.route}`, score: best.score };
+    const research = await import("./research.mjs").then((R) => R.loadResearch(dir, "latest")).catch(() => null);
+    const tags = [...(research?.understanding?.tags ?? []), ...(research?.understanding?.mood ?? [])];
+    const btn = buttonRepeatFinding(look, { excludePid: projectId(dir), like: likeOf(dir, route), planned: resolveButtons(bp?.look?.buttons), tags });
+    if (look.buttons) floor.look.buttons = describeButtons(look.buttons);
+    for (const c of [check, btn.check].filter(Boolean)) {
+      floor.checks = [...(floor.checks ?? []), c];
+      if (c.severity === "fail") floor.pass = false;
+    }
+  } catch (e) {
+    floor.look = { error: String(e?.message ?? e).slice(0, 160) };
+  }
+  return floor;
+}
+
+// One line for palate shoot (and a second when the button repeats palate's recent pages).
+export function lookLine(look, best, { buttons } = {}) {
+  const close = best ? `; closest recent look: ${best.record.project} ${best.record.route}, ${Math.round(best.score * 100)}%${best.score >= HOUSE_LOOK_FAIL ? ` (over the ${Math.round(HOUSE_LOOK_FAIL * 100)}% house-look gate: palate gate will fail it; change ${listWords(repeated(best).slice(0, 3).map((a) => AXIS_WORDS[a]))})` : best.score >= HOUSE_LOOK_WARN ? " (close to the house-look gate)" : ""}` : "";
+  const btn = buttons?.check ? `
+- Button ${buttons.check.severity === "fail" ? "repeats (palate gate will fail it)" : "is close to a recent page's"}: ${buttons.check.what}. ${buttons.check.fix}` : "";
+  return `- Look: ${describeLook(look)}${close}${btn}`;
+}