@palate/cli 0.0.0-stage → 0.0.1

package/src/motion.mjs

@@ -0,0 +1,207 @@
+// The motion check: lets the agent SEE motion as frame strips, and flags what motion must never do.
+// - On load: frames at 0/150/400/800/1500ms after the HTML arrives.
+// - Each section scrolled into view: frames at 0/150/400/800ms.
+// - Content still invisible 1s after it should show, and layout shift (CLS) with its sources.
+// - prefers-reduced-motion emulated: what still moves, and whether anything is left hidden.
+// - JavaScript off: whether content is left at opacity 0 (e.g. entrance styles rendered into server HTML).
+import fs from "node:fs";
+import path from "node:path";
+import { contactSheet, findSections, HIDE_DEV, MOTION_INIT, slugOf, stamp, withBrowser } from "./look.mjs";
+import { normalizeRoute } from "./shoot.mjs";
+
+const SHIFT_INIT = `window.__palateShifts = [];
+try { new PerformanceObserver((l) => { for (const e of l.getEntries()) if (!e.hadRecentInput) window.__palateShifts.push({ value: e.value, t: Math.round(e.startTime), nodes: (e.sources || []).map((s) => { const n = s.node && (s.node.nodeType === 1 ? s.node : s.node.parentElement); return n ? (n.id ? "#" + n.id : n.tagName.toLowerCase() + (typeof n.className === "string" && n.className ? "." + n.className.trim().split(/\\s+/).slice(0, 2).join(".") : "")) : null; }).filter(Boolean) }); }).observe({ type: "layout-shift", buffered: true }); } catch {}`;
+
+// Content inside the viewport that a reader can't see: opacity under 0.1 or visibility hidden, from itself
+// or an ancestor. Skips things hidden on purpose: aria-hidden, closed popovers and menus, sr-only text, and
+// stacked layers (a cross-fade's hidden layer sits under a visible sibling).
+export const HIDDEN = `(() => {
+  const vh = innerHeight;
+  const out = new Map();
+  const clean = (s) => (s || "").replace(/\\s+/g, " ").trim();
+  const name = (e) => e.id ? "#" + e.id : e.tagName.toLowerCase() + (typeof e.className === "string" && e.className ? "." + e.className.trim().split(/\\s+/).slice(0, 2).join(".") : "");
+  for (const el of document.body.querySelectorAll("h1,h2,h3,h4,h5,h6,p,li,img,video,button,a,figure,blockquote,td,label,span,svg,input")) {
+    const r = el.getBoundingClientRect();
+    if (r.width < 4 || r.height < 4 || r.bottom < 0 || r.top > vh) continue;
+    if (el.closest("[aria-hidden=true], .sr-only, [hidden], template, noscript, dialog:not([open]), [role=menu], [role=tooltip], [role=listbox], [data-state=closed], [popover]:not(:popover-open)")) continue;
+    const media = ["IMG", "VIDEO", "svg", "INPUT"].includes(el.tagName);
+    if (!media && ![...el.childNodes].some((n) => n.nodeType === 3 && n.textContent.trim().length > 1)) continue;
+    let op = 1, by = null;
+    for (let e = el; e && e.nodeType === 1; e = e.parentElement) {
+      const cs = getComputedStyle(e);
+      op *= parseFloat(cs.opacity);
+      if (cs.visibility === "hidden") op = 0;
+      if (op < 0.1) { by = e; break; }
+    }
+    if (!by || out.has(by)) continue;
+    // A native control made transparent on purpose (a custom radio or checkbox) whose label shows: the label
+    // is what a reader sees, not hidden content.
+    if (by === el && el.matches("input[type=radio], input[type=checkbox], input[type=file], input[type=range], input[type=color], select")) {
+      const shown = (l) => { let o = 1; for (let e = l; e && e.nodeType === 1; e = e.parentElement) { const c = getComputedStyle(e); o *= parseFloat(c.opacity); if (c.visibility === "hidden") o = 0; } return o >= 0.1; };
+      const label = [...(el.labels || [])].concat(el.closest("label") || [], el.nextElementSibling || [], el.previousElementSibling || []).find((l) => { const lr = l.getBoundingClientRect(); return lr.width > 4 && lr.height > 4 && clean(l.textContent) && shown(l); });
+      if (label) continue;
+    }
+    const br = by.getBoundingClientRect();
+    const stacked = by.parentElement && [...by.parentElement.children].some((s) => {
+      if (s === by) return false;
+      const sr = s.getBoundingClientRect();
+      const ix = Math.max(0, Math.min(sr.right, br.right) - Math.max(sr.left, br.left)) * Math.max(0, Math.min(sr.bottom, br.bottom) - Math.max(sr.top, br.top));
+      return parseFloat(getComputedStyle(s).opacity) > 0.5 && ix > 0.8 * br.width * br.height;
+    });
+    if (stacked) continue;
+    out.set(by, { selector: name(by), text: clean(by.textContent).slice(0, 50) || el.tagName.toLowerCase(), opacity: Math.round(op * 100) / 100 });
+  }
+  return [...out.values()].slice(0, 12);
+})()`;
+
+const RUNNING = `document.getAnimations ? document.getAnimations().filter((a) => a.playState === "running").map((a) => { const t = a.effect && a.effect.target; const timing = a.effect && a.effect.getTiming ? a.effect.getTiming() : {}; return { target: t ? (t.id ? "#" + t.id : t.tagName.toLowerCase() + (typeof t.className === "string" && t.className ? "." + t.className.trim().split(/\\s+/)[0] : "")) : "?", name: a.animationName || a.transitionProperty || a.id || "script", duration: Number(timing.duration) || 0, infinite: timing.iterations === Infinity }; }).slice(0, 12) : []`;
+// Transitions that change how something looks without moving it (allowed under prefers-reduced-motion).
+const CHANGE_ONLY = /^(color|background-color|background|border-color|outline-color|text-decoration-color|fill|stroke|opacity|box-shadow|filter)$/;
+
+const wait = (ms) => new Promise((r) => setTimeout(r, Math.max(0, ms)));
+const same = (a, b) => a && b && Buffer.compare(a, b) === 0;
+
+export async function motionCheck(dir, rawRoute, { url, out } = {}) {
+  const route = normalizeRoute(rawRoute);
+  const session = out ?? path.join(dir, ".palate", "motion", slugOf(route), stamp());
+  fs.mkdirSync(path.join(session, "frames"), { recursive: true });
+  fs.writeFileSync(path.join(dir, ".palate", ".gitignore"), "*\n");
+
+  return withBrowser(dir, { url }, async ({ base, browser }) => {
+    const target = base + route;
+    const shot = async (page, file) => {
+      const buf = await page.screenshot({ type: "jpeg", quality: 70 });
+      fs.writeFileSync(file, buf);
+      return buf;
+    };
+    // Warm up: the first request may compile the route.
+    {
+      const p = await browser.newPage();
+      await p.goto(target, { waitUntil: "networkidle", timeout: 90_000 }).catch(() => {});
+      await p.close();
+    }
+
+    // 1. Normal motion: load frames, then each section scrolled into view.
+    const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, reducedMotion: "no-preference" });
+    const page = await ctx.newPage();
+    await page.addInitScript(HIDE_DEV);
+    await page.addInitScript(MOTION_INIT);
+    await page.addInitScript(SHIFT_INIT);
+    // Frames count from the load event, so late images and fonts don't pass for an entrance.
+    await page.goto(target, { waitUntil: "load", timeout: 60_000 });
+    let t0 = Date.now();
+    const load = [];
+    for (const t of [0, 150, 400, 800, 1500]) {
+      await wait(t0 + t - Date.now());
+      const file = path.join(session, "frames", `load-${t}.jpg`);
+      load.push({ t, at: Date.now() - t0, file, buf: await shot(page, file) });
+    }
+    await page.waitForLoadState("networkidle").catch(() => {});
+    await page.waitForTimeout(1000);
+    const loadHidden = await page.evaluate(HIDDEN);
+    const sections = (await findSections(page)).slice(0, 10);
+    const vh = 900;
+    const perSection = [];
+    for (const s of sections) {
+      if (s.sticky && s.index === 1) continue;
+      await page.evaluate((y) => window.scrollTo({ top: y, behavior: "instant" }), Math.max(0, s.box.y - vh * 0.1));
+      t0 = Date.now();
+      const frames = [];
+      for (const t of [0, 150, 400, 800]) {
+        await wait(t0 + t - Date.now());
+        const file = path.join(session, "frames", `s${String(s.index).padStart(2, "0")}-${t}.jpg`);
+        frames.push({ t, at: Date.now() - t0, file, buf: await shot(page, file) });
+      }
+      await wait(t0 + 1100 - Date.now());
+      const hidden = await page.evaluate(HIDDEN);
+      perSection.push({ index: s.index, name: s.name, selector: s.selector, frames, moved: frames.some((f, i) => i && !same(f.buf, frames[0].buf)), hidden });
+    }
+    const shifts = await page.evaluate(() => window.__palateShifts ?? []);
+    const counters = await page.evaluate(() => ({ io: window.__palateMotion?.io ?? 0, waapi: window.__palateMotion?.waapi ?? 0, started: window.__palateMotion?.started ?? 0, styled: window.__palateMotion?.styled?.size ?? 0 }));
+    await ctx.close();
+
+    // 2. Reduced motion: nothing should travel, and nothing should be left hidden.
+    const rctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, reducedMotion: "reduce" });
+    const rpage = await rctx.newPage();
+    await rpage.addInitScript(HIDE_DEV);
+    await rpage.goto(target, { waitUntil: "networkidle", timeout: 60_000 }).catch(() => {});
+    await rpage.waitForTimeout(300);
+    const reduced = { hidden: await rpage.evaluate(HIDDEN), moving: [], running: [] };
+    for (const s of perSection) {
+      const box = sections.find((x) => x.index === s.index).box;
+      await rpage.evaluate((y) => window.scrollTo({ top: y, behavior: "instant" }), Math.max(0, box.y - vh * 0.1));
+      await rpage.waitForTimeout(80);
+      const a = await rpage.screenshot({ type: "jpeg", quality: 70 });
+      const running = await rpage.evaluate(RUNNING);
+      await rpage.waitForTimeout(400);
+      const b = await rpage.screenshot({ type: "jpeg", quality: 70 });
+      // Reduced motion forbids travel, not change: a colour or opacity transition (a scrollspy lighting the current
+      // link, a fade) is allowed. Frames that differ only while such transitions run don't count as moving.
+      const travel = running.filter((r) => !CHANGE_ONLY.test(String(r.name)));
+      let moved = !same(a, b) && (travel.length > 0 || !running.length);
+      // No animation running: a one-off state change after the scroll (a scrollspy, a sticky bar) settles; only
+      // a page that keeps changing (script-driven travel) is moving.
+      if (moved && !travel.length) {
+        await rpage.waitForTimeout(400);
+        moved = !same(b, await rpage.screenshot({ type: "jpeg", quality: 70 }));
+      }
+      if (moved) reduced.moving.push(s.index);
+      for (const r of travel) if ((r.duration > 20 || r.infinite) && !reduced.running.some((x) => x.target === r.target && x.name === r.name)) reduced.running.push({ ...r, section: s.index });
+      const h = await rpage.evaluate(HIDDEN);
+      for (const x of h) if (!reduced.hidden.some((y) => y.selector === x.selector)) reduced.hidden.push({ ...x, section: s.index });
+    }
+    await rctx.close();
+
+    // 3. JavaScript off: server-rendered content must not wait for a script to become visible.
+    const nctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, javaScriptEnabled: false });
+    const npage = await nctx.newPage();
+    await npage.goto(target, { waitUntil: "load", timeout: 60_000 }).catch(() => {});
+    const textLen = await npage.evaluate(() => document.body.innerText.trim().length).catch(() => 0);
+    const noJs = { rendered: textLen > 80, hidden: [] };
+    if (noJs.rendered)
+      for (const s of perSection) {
+        const box = sections.find((x) => x.index === s.index).box;
+        await npage.evaluate((y) => window.scrollTo({ top: y, behavior: "instant" }), Math.max(0, box.y - vh * 0.1));
+        await npage.waitForTimeout(150);
+        for (const x of await npage.evaluate(HIDDEN)) if (!noJs.hidden.some((y) => y.selector === x.selector)) noJs.hidden.push({ ...x, section: s.index });
+      }
+    await nctx.close();
+
+    // Frame strips the agent can read in one look.
+    const loadStrip = await contactSheet(browser, [{ label: `On load (ms after the load event)`, cells: load.map((f) => ({ caption: `${f.t}ms (actual ${f.at})`, file: f.file })) }], path.join(session, "load-strip.png"), { cell: 340, maxCell: 220 });
+    const sectionStrip = perSection.length
+      ? await contactSheet(browser, perSection.map((s) => ({ label: `Section ${s.index} · ${s.name.slice(0, 60)}${s.moved ? " · moves" : " · still"}`, cells: s.frames.map((f) => ({ caption: `${f.t}ms`, file: f.file })) })), path.join(session, "sections-strip.png"), { cell: 300, maxCell: 190 })
+      : null;
+
+    const cls = Math.round(shifts.reduce((n, s) => n + s.value, 0) * 1000) / 1000;
+    const loadMoved = load.some((f, i) => i && !same(f.buf, load[0].buf));
+    const problems = [];
+    if (loadHidden.length) problems.push(`Still invisible 1s after load: ${loadHidden.map((h) => `${h.selector} "${h.text}"`).join(", ")}.`);
+    for (const s of perSection) if (s.hidden.length) problems.push(`Section ${s.index} (${s.name.slice(0, 40)}): still invisible 1.1s after scrolling into view: ${s.hidden.map((h) => `${h.selector} "${h.text}"`).join(", ")}.`);
+    if (cls > 0.05) problems.push(`Layout shift: CLS ${cls} (good is under 0.1, ideally 0). Sources: ${[...new Set(shifts.flatMap((s) => s.nodes))].slice(0, 6).join(", ") || "unknown"}.`);
+    if (reduced.moving.length) problems.push(`Under prefers-reduced-motion, something still moves in section(s) ${reduced.moving.join(", ")}${reduced.running.length ? `: ${reduced.running.slice(0, 5).map((r) => `${r.target} ${r.name} ${Math.round(r.duration)}ms${r.infinite ? " (infinite)" : ""}`).join(", ")}` : ""}. Replace travel with an opacity fade or nothing.`);
+    if (reduced.hidden.length) problems.push(`Under prefers-reduced-motion, content is left hidden: ${reduced.hidden.map((h) => `${h.selector} "${h.text}"`).join(", ")}.`);
+    if (noJs.hidden.length) problems.push(`With JavaScript off, content is left hidden (entrance styles rendered into the HTML): ${noJs.hidden.map((h) => `${h.selector} "${h.text}"`).join(", ")}. Start from visible, or hide only under a class a script sets.`);
+
+    const moving = perSection.filter((s) => s.moved).map((s) => s.index);
+    const still = perSection.filter((s) => !s.moved).map((s) => s.index);
+    const report = [
+      `## Motion check: ${route} at 1440`,
+      `- On load: ${slash(loadStrip)}: ${loadMoved ? "the first screen changes during the first 1.5s (an entrance runs)" : "nothing changes during the first 1.5s"}.`,
+      sectionStrip ? `- Sections scrolled into view: ${slash(sectionStrip)}: moving ${moving.length ? moving.join(", ") : "none"} · still ${still.length ? still.join(", ") : "none"}.` : "",
+      `- Scripted motion during the run: ${counters.started} CSS animation(s) or transition(s) started, ${counters.waapi} Web Animations, ${counters.styled} element(s) moved or faded by script.`,
+      `- Layout shift: CLS ${cls}${shifts.length ? ` over ${shifts.length} shift(s)` : ""}.`,
+      `- Reduced motion (emulated): ${reduced.moving.length ? `still moving in section(s) ${reduced.moving.join(", ")}` : "nothing moves"}; ${reduced.hidden.length ? `${reduced.hidden.length} hidden item(s)` : "nothing hidden"}.`,
+      `- JavaScript off: ${noJs.rendered ? (noJs.hidden.length ? `${noJs.hidden.length} hidden item(s)` : "all content visible") : "the page renders nothing without JavaScript (client-rendered), so this check doesn't apply"}.`,
+      !loadMoved && !moving.length ? "- Nothing moves on load or on scroll: the page is static." : "",
+      problems.length ? `\n### Problems\n${problems.map((p) => `- ⚠ ${p}`).join("\n")}` : "- No motion problems measured. Look at the strips: does the motion explain something?",
+    ]
+      .filter(Boolean)
+      .join("\n");
+    const data = { route, load: load.map(({ buf, ...f }) => f), sections: perSection.map((s) => ({ ...s, frames: s.frames.map(({ buf, ...f }) => f) })), cls, shifts, reduced, noJs, counters, problems, static: !loadMoved && !moving.length };
+    fs.writeFileSync(path.join(session, "motion.json"), JSON.stringify(data, null, 1));
+    return { report, problems, session, files: [loadStrip, sectionStrip].filter(Boolean), data };
+  });
+}
+
+const slash = (p) => String(p).replace(/\\/g, "/");

package/src/moves.mjs

@@ -0,0 +1,242 @@
+// The moves library: named creative techniques ("moves") with palate's own recipes, one Markdown file each in
+// kb/moves/*.md (YAML frontmatter + body). A move is the craft knowledge behind a memorable page: which technique
+// fits which product, and how to execute it well. Research, ideation and the ambition pass read it through this API:
+//   loadMoves()                       every move, frontmatter + body + sections
+//   matchMoves({ tags, kind, signature, exclude, limit, history, screen })
+//                                     ranked by fits overlap minus avoid overlap, plus the user's own history
+//                                     (moves they kept on this kind of screen rise, reverted ones sink)
+//   moveBrief(ids)                    the chosen moves' recipes as compact Markdown for a build brief
+// (kb/moves/moves.yaml is the older, shorter list palate concept uses; it is not read here.)
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import YAML from "yaml";
+import { KB_ROOT } from "./paths.mjs";
+
+const KB_DIR = process.env.PALATE_KB ?? KB_ROOT;
+export const MOVES_DIR = path.join(KB_DIR, "moves");
+
+export const KINDS = ["hero", "texture", "motion", "interaction", "type", "layout", "imagery", "footer", "easter-egg", "navigation", "data", "sound-free-feedback"];
+export const EFFORTS = ["s", "m", "l"];
+export const REQUIRED = ["id", "name", "kind", "fits", "avoid", "signature", "effort", "perf", "a11y", "pairs_with"];
+export const SECTIONS = ["What it is", "Why it works", "When to use / when not", "Recipe", "Pitfalls", "How to verify", "Examples"];
+
+// The words fits/avoid may use, so a search for "calm" finds every calm move. Mood first, then the kind of product
+// or audience, then contexts that are mostly worth avoiding. Add a word here before using it in a move.
+export const TAGS = [
+  // mood and brand
+  "calm", "crafted", "editorial", "heritage", "nature", "playful", "bold", "technical", "minimal", "premium", "luxury",
+  "warm", "friendly", "energetic", "serious", "trustworthy", "data-rich", "scientific", "retro", "experimental", "artsy",
+  "cultural", "community", "honest", "cinematic", "tactile", "quiet",
+  // product, audience, moment
+  "developer", "saas", "ai", "finance", "health", "education", "kids", "gaming", "music", "fashion", "food", "travel",
+  "nonprofit", "ecommerce", "portfolio", "agency", "media", "publishing", "sustainability", "hardware", "productivity",
+  "consumer", "b2b", "enterprise", "launch", "waitlist", "docs", "local", "events",
+  // contexts where a move tends to hurt
+  "playful-kids", "finance-trust-first", "enterprise-compliance", "clinical", "data-dense-tool", "low-bandwidth",
+  "accessibility-first", "government", "serious-news", "crisis", "daily-tool",
+];
+
+const list = (v) => (Array.isArray(v) ? v : v == null || v === "" ? [] : [v]).map((x) => String(x).trim()).filter(Boolean);
+
+// The body's "## Heading" sections, by heading.
+export function sectionsOf(body) {
+  const out = {};
+  let cur = null;
+  for (const line of body.split("\n")) {
+    const h = line.match(/^##\s+(.+?)\s*$/);
+    if (h) {
+      cur = h[1];
+      out[cur] = [];
+    } else if (cur) out[cur].push(line);
+  }
+  for (const k of Object.keys(out)) out[k] = out[k].join("\n").trim();
+  return out;
+}
+
+export function parseMove(src, file = "") {
+  const m = src.replace(/\r\n/g, "\n").match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!m) throw new Error(`${path.basename(file)}: no frontmatter`);
+  const meta = YAML.parse(m[1]) ?? {};
+  const body = m[2].trim();
+  return {
+    ...meta,
+    fits: list(meta.fits),
+    avoid: list(meta.avoid),
+    pairs_with: list(meta.pairs_with),
+    signature: meta.signature === true,
+    body,
+    sections: sectionsOf(body),
+    file,
+  };
+}
+
+let cache = null;
+export function loadMoves({ fresh = false } = {}) {
+  if (cache && !fresh) return cache;
+  if (!fs.existsSync(MOVES_DIR)) return (cache = []);
+  cache = fs
+    .readdirSync(MOVES_DIR)
+    .filter((f) => f.endsWith(".md"))
+    .sort()
+    .map((f) => {
+      const file = path.join(MOVES_DIR, f);
+      return parseMove(fs.readFileSync(file, "utf8"), file);
+    });
+  return cache;
+}
+
+// Problems with one move (missing fields, unknown words, missing sections); [] when it is sound.
+export function lintMove(mv, known = new Set(loadMoves().map((x) => x.id))) {
+  const p = [];
+  for (const k of REQUIRED) if (mv[k] == null || mv[k] === "") p.push(`missing ${k}`);
+  if (mv.file && mv.id && path.basename(mv.file, ".md") !== mv.id) p.push(`file name should be ${mv.id}.md`);
+  if (mv.kind && !KINDS.includes(mv.kind)) p.push(`unknown kind ${mv.kind}`);
+  if (mv.effort && !EFFORTS.includes(mv.effort)) p.push(`effort must be s, m or l`);
+  if (!mv.fits.length) p.push("fits is empty");
+  for (const t of [...mv.fits, ...mv.avoid]) if (!TAGS.includes(t)) p.push(`unknown tag ${t}`);
+  for (const id of mv.pairs_with) if (!known.has(id)) p.push(`pairs_with ${id} does not exist`);
+  for (const s of SECTIONS) if (!mv.sections?.[s]) p.push(`missing section "${s}"`);
+  return p;
+}
+
+// A query tag matches a move's tag exactly, or as a family ("playful" ~ "playful-kids") at half weight.
+const near = (q, t) => q !== t && (t.startsWith(`${q}-`) || q.startsWith(`${t}-`));
+const hits = (query, tags) => {
+  const exact = query.filter((q) => tags.includes(q));
+  const partial = query.filter((q) => !exact.includes(q) && tags.some((t) => near(q, t)));
+  return { exact, partial };
+};
+
+// The user's history with a move: palate grows with each user, so a move they kept on this kind of screen rises
+// and one they reverted sinks. history is [{ id, outcome: "kept" | "reverted", kind }], where kind is the kind of
+// screen it was used on (landing, pricing, app…), read from ~/.palate by the caller. An entry for the same kind of
+// screen as `screen` (or with no kind, or when no screen is given) counts in full; one from another kind of screen
+// counts a quarter. Kept: +0.75 each, up to +2. Reverted: −1.5 each, down to −4.
+export const HISTORY = { kept: 0.75, keptMax: 2, reverted: -1.5, revertedMin: -4, otherScreen: 0.25 };
+function historyFor(id, history, screen) {
+  let kept = 0, reverted = 0;
+  const notes = [];
+  for (const h of history) {
+    if (!h || h.id !== id || (h.outcome !== "kept" && h.outcome !== "reverted")) continue;
+    const w = !screen || !h.kind || h.kind === screen ? 1 : HISTORY.otherScreen;
+    if (h.outcome === "kept") kept += w;
+    else reverted += w;
+  }
+  const adj = Math.min(HISTORY.keptMax, kept * HISTORY.kept) + Math.max(HISTORY.revertedMin, reverted * HISTORY.reverted);
+  const n = (x) => (Number.isInteger(x) ? x : x.toFixed(2));
+  if (kept) notes.push(`you kept it ${n(kept)}×${screen ? ` (weighted to ${screen})` : ""}`);
+  if (reverted) notes.push(`you reverted it ${n(reverted)}×${screen ? ` (weighted to ${screen})` : ""}`);
+  return { adj, notes };
+}
+
+/**
+ * Ranks moves for a brief. Score = fits overlap (1 per exact tag, 0.5 per family match) minus avoid overlap
+ * (1.5 per exact tag, 0.75 per family match), plus a little for a focused move (its fits mostly matched), plus the
+ * user's history with it (see HISTORY: kept moves rise, reverted ones sink, weighted to `screen`, the kind of screen
+ * being built). Filters by kind (the move's kind; one or several) and signature; drops excluded ids (e.g. moves this
+ * project used recently). With no tags, every move that passes the filters comes back, ranked by history alone, then
+ * signature moves first.
+ */
+export function matchMoves({ tags = [], kind, signature, exclude = [], limit = 8, history = [], screen } = {}) {
+  const q = [...new Set(list(tags).flatMap((t) => t.split(",")).map((t) => t.trim().toLowerCase()).filter(Boolean))];
+  const kinds = list(kind).flatMap((k) => k.split(",")).map((k) => k.trim()).filter(Boolean);
+  const skip = new Set(list(exclude));
+  const past = Array.isArray(history) ? history : [];
+  const rows = loadMoves()
+    .filter((mv) => !skip.has(mv.id))
+    .filter((mv) => !kinds.length || kinds.includes(mv.kind))
+    .filter((mv) => signature == null || mv.signature === Boolean(signature))
+    .map((mv) => {
+      const f = hits(q, mv.fits);
+      const a = hits(q, mv.avoid);
+      const fit = f.exact.length + 0.5 * f.partial.length;
+      const focus = mv.fits.length ? (f.exact.length + 0.5 * f.partial.length) / mv.fits.length : 0;
+      const base = q.length ? fit - 1.5 * a.exact.length - 0.75 * a.partial.length + 0.25 * focus : 0;
+      const h = historyFor(mv.id, past, screen);
+      const score = Math.round((base + h.adj) * 100) / 100;
+      const parts = [];
+      if (f.exact.length || f.partial.length) parts.push(`fits ${[...f.exact, ...f.partial.map((t) => `~${t}`)].join(", ")}`);
+      if (a.exact.length || a.partial.length) parts.push(`but avoid ${[...a.exact, ...a.partial.map((t) => `~${t}`)].join(", ")}`);
+      parts.push(...h.notes);
+      parts.push(`${mv.signature ? "signature " : ""}${mv.kind}, effort ${mv.effort}`);
+      return { id: mv.id, name: mv.name, kind: mv.kind, signature: mv.signature, effort: mv.effort, score, base, reason: parts.join("; "), move: mv };
+    })
+    // With tags, only moves that fit (before history: a kept move still has to suit this brief).
+    .filter((r) => !q.length || (r.base > 0 && r.score > 0));
+  rows.sort((a, b) => b.score - a.score || Number(b.signature) - Number(a.signature) || a.id.localeCompare(b.id));
+  return rows.slice(0, Math.max(0, Number(limit) || 0) || rows.length).map(({ base, ...r }) => r);
+}
+
+export function getMove(id) {
+  return loadMoves().find((mv) => mv.id === id) ?? null;
+}
+
+// One move in full, for `palate moves show`.
+export function showMove(id) {
+  const mv = getMove(id);
+  if (!mv) return `No move "${id}". Run palate moves to list them.`;
+  return [
+    `# ${mv.name} (${mv.id})`,
+    `kind: ${mv.kind} · effort: ${mv.effort}${mv.signature ? " · signature" : ""}${mv.deps && mv.deps !== "none" ? ` · deps: ${mv.deps}` : ""}`,
+    `fits: ${mv.fits.join(", ")}`,
+    `avoid: ${mv.avoid.join(", ") || "-"}`,
+    `perf: ${mv.perf}`,
+    `a11y: ${mv.a11y}`,
+    mv.pairs_with.length ? `pairs with: ${mv.pairs_with.join(", ")}` : null,
+    "",
+    mv.body,
+  ]
+    .filter((l) => l != null)
+    .join("\n");
+}
+
+const firstPara = (s = "") => s.split(/\n\s*\n/)[0].replace(/\s+/g, " ").trim();
+
+/** The chosen moves' recipes as compact Markdown, for a build brief: what it is, the recipe, pitfalls, how to verify. */
+export function moveBrief(ids) {
+  const all = loadMoves();
+  const out = [];
+  for (const id of list(ids).flatMap((x) => x.split(","))) {
+    const mv = all.find((x) => x.id === id.trim());
+    if (!mv) {
+      out.push(`### ${id}\n(no such move)`);
+      continue;
+    }
+    const s = mv.sections;
+    out.push(
+      [
+        `### ${mv.name} (${mv.id}) · ${mv.kind}, effort ${mv.effort}${mv.signature ? ", signature" : ""}`,
+        firstPara(s["What it is"]),
+        `- perf: ${mv.perf}`,
+        `- a11y: ${mv.a11y}`,
+        mv.deps && mv.deps !== "none" ? `- deps: ${mv.deps}` : null,
+        "",
+        "**Recipe**",
+        s["Recipe"],
+        "",
+        "**Pitfalls**",
+        s["Pitfalls"],
+        "",
+        "**Verify**",
+        s["How to verify"],
+      ]
+        .filter((l) => l != null)
+        .join("\n"),
+    );
+  }
+  return out.join("\n\n");
+}
+
+// The ranked list as text, for `palate moves` and the MCP tool.
+export function movesReport(rows, { tags = [], kind, signature } = {}) {
+  if (!rows.length) return "No moves match. Try other tags, or palate moves with no filters.";
+  const head = [tags.length ? `tags ${list(tags).join(", ")}` : null, kind ? `kind ${list(kind).join(", ")}` : null, signature ? "signature only" : null].filter(Boolean).join(" · ");
+  return [
+    head ? `Moves for ${head}:` : `All moves (${rows.length}):`,
+    "",
+    ...rows.map((r) => `${r.id.padEnd(36)} ${String(r.kind).padEnd(20)} ${tags.length ? String(r.score).padStart(5) + "  " : ""}${r.reason}`),
+    "",
+    "Read one in full: palate moves show <id>",
+  ].join("\n");
+}

package/src/novelty.mjs

@@ -0,0 +1,116 @@
+// Originality check for `palate shoot`: compares a page with the screens built before (its skeleton in this
+// project; skeleton, first-screen shape, type, colour and picture against the layout memory of every project
+// on this machine) and names any AI defaults found on it. Every shot joins the layout memory.
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { PALATE_HOME } from "./catalog/store.mjs";
+import { loadMoves } from "./concept.mjs";
+import { DUPLICATE, SIMILAR, compare, layoutRecord, appendLayouts, isProjectDir, readLayouts, sameScreen, skeletonSimilarity, whereOf } from "./loop/layouts.mjs";
+import { gateLines, saveGate, similarityGate } from "./loop/similar.mjs";
+import { REF_CLOSE, REF_TOO_CLOSE, referenceMatches } from "./loop/research.mjs";
+
+// ---- palate research: ideas, never the expression. A page too close to a captured reference fails; a build
+// from a research direction is reminded of the signature moment it promised.
+export function referenceLines(dir, route, rec) {
+  const out = [];
+  const refs = referenceMatches(dir, rec);
+  const fail = refs.filter((m) => m.total >= REF_TOO_CLOSE);
+  const close = refs.filter((m) => m.total >= REF_CLOSE && m.total < REF_TOO_CLOSE);
+  for (const m of fail.slice(0, 2)) out.push(`- ✗ Originality FAILS: too close to the research reference ${m.name} (${m.url}), ${Math.round(m.total * 100)}% (structure ${Math.round(m.structure * 100)}%). Use the ideas, never the expression: change the first screen's structure and the signature moves so it looks like this product, not that site.`);
+  for (const m of close.slice(0, 2)) out.push(`- ⚠ Close to the research reference ${m.name} (${Math.round(m.total * 100)}%): make sure nothing looks lifted from it.`);
+  if (refs.length && !fail.length && !close.length) out.push(`- Distinct from all ${refs.length} research references (closest ${refs[0].name}, ${Math.round(refs[0].total * 100)}%).`);
+  try {
+    const root = path.join(dir, ".palate", "variants");
+    for (const n of fs.existsSync(root) ? fs.readdirSync(root) : []) {
+      const meta = readJson(path.join(root, n, "loop.json"), null);
+      const sig = meta?.mode === "build" && meta.route === route ? meta.direction?.signature : null;
+      if (sig) out.push(`- Signature moment promised by the direction "${meta.direction.idea}": ${sig.move}: ${sig.moment}. Open the screenshot and confirm it is on the page and works; it is the point of this build.`);
+    }
+  } catch {}
+  return out;
+}
+
+const GLOBAL = path.join(PALATE_HOME, "fingerprints.json");
+const readJson = (f, fallback) => {
+  try {
+    return JSON.parse(fs.readFileSync(f, "utf8"));
+  } catch {
+    return fallback;
+  }
+};
+
+export const similarity = skeletonSimilarity;
+
+// The newest first-screen shot of this route at desktop width, as shoot just wrote it.
+function latestFold(dir, route) {
+  const slug = route.replace(/[^a-z0-9]+/gi, "-").replace(/^-|-$/g, "") || "home";
+  const d = path.join(dir, ".palate", "shots", slug);
+  if (!fs.existsSync(d)) return null;
+  const shots = fs.readdirSync(d).map((f) => f.match(/^r(\d+)-w(\d+)-fold\.png$/)).filter((m) => m && Number(m[2]) >= 1000).sort((x, y) => Number(y[1]) - Number(x[1]));
+  return shots.length ? path.join(d, shots[0][0]) : null;
+}
+
+// Which loop a route belongs to (pricing-a1 → pricing), if that loop exists here.
+function loopOf(dir, route) {
+  const m = route.match(/^\/(.+)-[a-z]\d+$/);
+  const meta = m && readJson(path.join(dir, ".palate", "variants", m[1], "loop.json"), null);
+  return meta ? { loop: m[1], meta } : null;
+}
+
+// like: projects the user asked to match (the similarity gate lets their look through). The returned lines carry
+// the gate's result as .gate.
+// The record palate compares a shot page by, built one way for palate shoot and the quality gate (the gate built a
+// bare one, so the same Moveday page was 40% like another project at the shoot and 48% at the gate).
+export function shotRecord(dir, route, fp) {
+  const owner = loopOf(dir, route);
+  return layoutRecord(dir, route, fp, { file: latestFold(dir, route), loop: owner?.loop, meta: owner?.meta, source: owner ? "variant" : "screen" });
+}
+
+export function noveltyReport(dir, route, fp, { like = [] } = {}) {
+  const project = crypto.createHash("sha1").update(path.resolve(dir).toLowerCase()).digest("hex").slice(0, 12);
+  const localFile = path.join(dir, ".palate", "fingerprints.json");
+  const local = readJson(localFile, {});
+  const global = readJson(GLOBAL, []);
+  const what = Object.fromEntries((loadMoves().cliches ?? []).map((c) => [c.id, c.what]));
+  const cliches = fp.cliches.includes("centred-hero") && fp.cliches.includes("glow") ? [...fp.cliches.filter((c) => c !== "centred-hero" && c !== "glow"), "centred-hero-glow"] : fp.cliches.filter((c) => c !== "glow");
+
+  const out = ["## Originality", `- Skeleton: ${fp.skeleton.join(" · ") || "(no bands found)"}  (C/L centred or left-led, digit = layout columns, w framed panel, m big media, gN grid of N equal items, b own background)`];
+  if (cliches.length) out.push(`- ⚠ AI defaults on this page: ${cliches.map((c) => `${c}${what[c] ? ` (${what[c]})` : ""}`).join("; ")}. Keep one only if the concept needs it, and then change it in a way the concept explains; otherwise replace it with a move from palate concept.`);
+  const siblings = Object.entries(local)
+    .filter(([r]) => r !== route)
+    .map(([r, f]) => [r, similarity(fp.skeleton, f.skeleton)])
+    .filter(([, s]) => s >= 0.6)
+    .sort((a, b) => b[1] - a[1]);
+  if (siblings.length) out.push(`- Same skeleton as ${siblings.slice(0, 3).map(([r, s]) => `${r} (${Math.round(s * 100)}%)`).join(", ")} in this project. Expected for sibling screens of one tool; a problem for pages meant to stand apart.`);
+  // The layout memory, across every project on this machine.
+  const owner = loopOf(dir, route);
+  const rec = shotRecord(dir, route, fp);
+  const matches = readLayouts()
+    .filter((h) => !(h.pid === rec.pid && h.route === route) && !(owner && h.pid === rec.pid && h.loop === owner.loop && h.run === rec.run))
+    .map((h) => ({ ...h, samePlace: h.pid === rec.pid, total: compare(rec, h).total }))
+    .sort((a, b) => b.total - a.total);
+  // Only screens of the same kind (a landing page against a pricing variant tells nobody much).
+  const elsewhere = matches.filter((m) => !m.samePlace && m.total >= SIMILAR && sameScreen(rec, m));
+  const here = matches.filter((m) => m.samePlace && m.total >= DUPLICATE);
+  if (rec.moves) out.push(`- Signature: ${rec.moves.hero}; product: ${rec.moves.product}; type: ${rec.moves.type}; palette: ${rec.moves.palette}`);
+  // Other projects: the similarity gate decides (below); only matches it lets through are mentioned here.
+  const gate = similarityGate(dir, route, rec, { like });
+  const gated = new Set([...gate.hits, ...gate.matched].map((h) => h.project));
+  for (const m of elsewhere.filter((x) => !gated.has(x.project) && x.total > 0.5).slice(0, 3)) out.push(`- ⚠ ${m.total >= DUPLICATE ? "Repeats" : "Close to"} ${whereOf(m)}, made ${m.at.slice(0, 10)} in another project (${Math.round(m.total * 100)}%). ${m.total >= DUPLICATE ? "This is the same design again: change the structure of the first screen and the signature moves, so it belongs to this product, not the last one." : "Make sure it belongs to this product, not the last one."}`);
+  for (const m of here.slice(0, 2))
+    out.push(!owner && m.picked ? `- The shipped version of ${m.route}, the variant the user picked (${Math.round(m.total * 100)}%).` : `- ${owner && m.loop === owner.loop ? "Repeats an earlier run of this loop" : "Repeats"}: ${m.route}${m.picked ? " (picked)" : ""}, made ${m.at.slice(0, 10)} (${Math.round(m.total * 100)}%).`);
+  if (!cliches.length && !siblings.length && !here.length) out.push("- No AI defaults found and no repeat of earlier screens.");
+  // palate research: this page against every page the project's research looked at, and the promised signature.
+  out.push(...referenceLines(dir, route, rec));
+
+  local[route] = { skeleton: fp.skeleton, cliches, at: new Date().toISOString() };
+  fs.writeFileSync(localFile, JSON.stringify(local, null, 2));
+  fs.mkdirSync(PALATE_HOME, { recursive: true });
+  const kept = global.filter((g) => !(g.project === project && g.route === route));
+  kept.push({ project, route, skeleton: fp.skeleton, at: new Date().toISOString() });
+  fs.writeFileSync(GLOBAL, JSON.stringify(kept.slice(-300), null, 2));
+  if (isProjectDir(dir)) appendLayouts([rec]);
+  saveGate(dir, route, gate);
+  return Object.assign([...out, "", ...gateLines(gate, route)], { gate });
+}