@palate/cli 0.0.0-stage → 0.0.1

package/src/point/trail.mjs

@@ -0,0 +1,219 @@
+// Pins on states that need a click first (an open modal, a dropdown, a tab, a hover menu, an expanded row).
+// The overlay records the user's steps since the last navigation (clicks, a few keys, typing, a hover) and,
+// when they pin, keeps the few steps that lead to the pinned element's state: its "trail". Every crop is
+// shot on a fresh page load, so the server replays the trail with real input before each one.
+//
+// trailCore() is shared with the overlay: the server pastes its source into overlay.js, so it must not use
+// anything outside itself.
+export function trailCore() {
+  // Fields whose values are never recorded: passwords, card numbers, one-time codes, tokens and the like.
+  const SECRET = /pass(word|code|phrase)?|pwd|cvc|cvv|csc|card|ccnum|\bcc-|ssn|social.?security|token|secret|\botp\b|one.?time|\bpin\b|iban|routing|account.?num/i;
+  const SECRET_AUTOCOMPLETE = /(^|\s)(cc-|one-time-code|current-password|new-password)/i;
+  const MAX = 10;
+  // How long after a step something that appeared counts as opened by it.
+  const CAUSE_MS = 2500;
+
+  const lastIndex = (a, f) => {
+    for (let i = a.length - 1; i >= 0; i--) if (f(a[i], i)) return i;
+    return -1;
+  };
+
+  // The minimal trail for a pin. steps: oldest first, each with
+  //   rest: the page was at rest just before it (no dialog, menu, popover or expanded part open, beyond what
+  //         was open when the user first did anything on this page),
+  //   keep: a tab or expander clicked earlier whose state still holds over the pinned element.
+  // inOpen: the pinned element sits inside an open dialog, menu, popover, listbox or expanded part.
+  // revealedAt: times the element or one of its parents appeared (added to the page, or unhidden).
+  // The heuristic:
+  //   1. In an open layer: everything from the last step taken while the page was at rest. That step opened
+  //      the first layer; the steps after it open the rest (a dropdown inside the modal, a tab in it).
+  //   2. Something it sits in appeared within 2.5 s after a step (a custom modal without roles, a panel
+  //      rendered on click): everything from the earliest such step.
+  //   3. Tabs and expanders clicked before that, still selected or open over the element, are kept too.
+  //   Nothing else: a page at rest with the element in plain view needs no steps. At most 10, the latest.
+  function trimTrail(steps, { inOpen = false, revealedAt = [], max = MAX } = {}) {
+    if (!Array.isArray(steps) || !steps.length) return [];
+    let from = steps.length;
+    if (inOpen) from = Math.max(0, lastIndex(steps, (s) => s.rest));
+    for (const t of revealedAt) {
+      const i = lastIndex(steps, (s) => s.at <= t);
+      if (i >= 0 && t - steps[i].at <= CAUSE_MS) from = Math.min(from, i);
+    }
+    return steps.filter((s, i) => i >= from || s.keep).slice(-max);
+  }
+
+  const quote = (t, n = 32) => {
+    const s = String(t ?? "").replace(/\s+/g, " ").trim();
+    return s ? `"${s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s}"` : "";
+  };
+  const KEY = { " ": "Space", Escape: "Esc", ArrowDown: "↓", ArrowUp: "↑", ArrowLeft: "←", ArrowRight: "→" };
+  // One step in plain words: click "Invite members", press Enter on "Role", type "ada" in "Search".
+  function stepWords(s) {
+    const what = quote(s.text || s.name);
+    if (s.type === "click") return `click ${what || "it"}`;
+    if (s.type === "hover") return `hover ${what || "it"}`;
+    if (s.type === "select") return `choose ${quote(s.label || s.value) || "an option"}${what ? ` in ${what}` : ""}`;
+    if (s.type === "type") return s.redacted ? `type in ${what || "a private field"} (not recorded)` : `type ${quote(s.value, 24) || "nothing"}${what ? ` in ${what}` : ""}`;
+    if (s.type === "key") return `press ${(s.shift ? "Shift+" : "") + (KEY[s.key] ?? s.key)}${what && s.key !== "Escape" && s.key !== "Tab" ? ` on ${what}` : ""}`;
+    return s.type;
+  }
+  // Short, for the overlay: Invite members → Role → the menu.
+  function stepShort(s) {
+    const t = String(s.text || s.name || "").replace(/\s+/g, " ").trim();
+    const short = t.length > 24 ? `${t.slice(0, 23).trimEnd()}…` : t;
+    if (s.type === "key") return (s.shift ? "Shift+" : "") + (KEY[s.key] ?? s.key);
+    if (s.type === "type") return s.redacted ? `typed in ${short || "a private field"}` : `typed ${quote(s.value, 16)}`;
+    if (s.type === "hover") return `hover ${short}`;
+    if (s.type === "select") return `chose ${quote(s.label || s.value, 16)}`;
+    return short || s.type;
+  }
+  return { SECRET, SECRET_AUTOCOMPLETE, MAX, trimTrail, stepWords, stepShort };
+}
+
+export const { SECRET, MAX, trimTrail, stepWords, stepShort } = trailCore();
+
+const TYPES = new Set(["click", "key", "type", "select", "hover"]);
+const KEYS = new Set(["Enter", " ", "Escape", "Tab", "ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight", "Home", "End"]);
+const LAYERS = new Set(["modal", "dialog", "menu", "popover", "listbox", "tooltip", "tab panel", "expanded part", "hover menu"]);
+const str = (v, n) => (typeof v === "string" && v.trim() ? v.replace(/\s+/g, " ").trim().slice(0, n) : undefined);
+
+// A trail from the overlay, made safe to store: known step types only, short strings, at most 10 steps, and
+// no value from anything that looks like a private field (checked again here, whatever the overlay said).
+export function cleanTrail(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const s of raw.slice(-MAX)) {
+    if (!s || typeof s !== "object" || !TYPES.has(s.type)) continue;
+    const step = {
+      type: s.type,
+      selector: str(s.selector, 400),
+      testid: str(s.testid, 120),
+      role: str(s.role, 40),
+      name: str(s.name, 120),
+      tag: /^[a-z][a-z0-9-]{0,30}$/.test(s.tag ?? "") ? s.tag : undefined,
+      text: str(s.text, 120),
+      at: Number.isFinite(s.at) ? Math.round(s.at) : undefined,
+    };
+    if (s.type === "key") {
+      if (!KEYS.has(s.key)) continue;
+      step.key = s.key;
+      if (s.shift) step.shift = true;
+    }
+    if (s.type === "type" || s.type === "select") {
+      const hint = [s.selector, s.testid, s.name, s.text, s.field].filter(Boolean).join(" ");
+      if (s.redacted || SECRET.test(hint)) step.redacted = true;
+      else if (typeof s.value === "string") step.value = s.value.slice(0, 200);
+      if (s.type === "select" && !step.redacted) step.label = str(s.label, 120);
+    }
+    for (const k of Object.keys(step)) if (step[k] === undefined) delete step[k];
+    if (!step.selector && !step.testid && !step.name && !step.text && step.type !== "key") continue;
+    out.push(step);
+  }
+  return out;
+}
+export const cleanLayer = (v) => (LAYERS.has(v) ? v : null);
+
+// The trail in the agent's words: click "Invite members" → the modal.
+export function trailWords(trail, layer) {
+  if (!trail?.length) return "";
+  return [...trail.map(stepWords), ...(layer ? [`the ${layer}`] : [])].join(" → ");
+}
+
+// What the server does for each step, in order: where to find its target (most exact first) and what to do.
+// loose (the other width): one more try by its words alone, since a menu may sit elsewhere on a phone.
+export function replayPlan(trail, { loose = false } = {}) {
+  return (trail ?? []).map((s, i) => {
+    const find = [];
+    if (s.selector) find.push({ by: "css", css: s.selector });
+    if (s.testid) find.push({ by: "css", css: `[data-testid="${s.testid.replace(/["\\]/g, "\\$&")}"]` });
+    if (s.role && s.name) find.push({ by: "role", role: s.role, name: s.name });
+    const words = s.text || s.name;
+    if (s.tag && words) find.push({ by: "text", tag: s.tag, text: words, exact: true });
+    if (loose && words) find.push({ by: "text", text: words, exact: false });
+    const step = { n: i + 1, words: stepWords(s), find };
+    if (s.type === "click") return { ...step, do: "click" };
+    if (s.type === "hover") return { ...step, do: "hover" };
+    if (s.type === "select") return s.redacted ? { ...step, do: "skip", why: "a private field: palate never records what's chosen there" } : { ...step, do: "select", value: s.value, label: s.label };
+    if (s.type === "type") return s.redacted || typeof s.value !== "string" ? { ...step, do: "skip", why: "a private field: palate never records what's typed there" } : { ...step, do: "fill", value: s.value };
+    const key = `${s.shift ? "Shift+" : ""}${s.key === " " ? "Space" : s.key}`;
+    // Esc and Tab act on whatever has focus; the rest act on their control, focused first.
+    return { ...step, do: "press", key, find: s.key === "Escape" || s.key === "Tab" ? [] : find };
+  });
+}
+
+// Runs the plan in a Playwright page with real input: waits for each target (up to 3 s), acts, settles.
+// Returns { state: "reopened" | "couldn't reopen", ran, steps, failed?, why?, skipped?, loose? }.
+export async function replay(page, trail, { loose = false, wait = 3000, settle = 350 } = {}) {
+  const plan = replayPlan(trail, { loose });
+  const skipped = [];
+  let hamburger = false;
+  let used = null;
+  const visibleOf = async (f) => {
+    const l =
+      f.by === "css"
+        ? page.locator(f.css)
+        : f.by === "role"
+          ? page.getByRole(f.role, { name: f.name, exact: true })
+          : f.tag
+            ? page.locator(f.tag).filter({ hasText: new RegExp(`^\\s*${f.text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+")}\\s*$`, "i") })
+            : page.getByText(f.text, { exact: f.exact });
+    try {
+      const v = l.filter({ visible: true });
+      return (await v.count()) ? v.first() : null;
+    } catch {
+      return null;
+    }
+  };
+  const findTarget = async (step, ms) => {
+    const until = Date.now() + ms;
+    for (;;) {
+      for (const f of step.find) {
+        const l = await visibleOf(f);
+        if (l) return { l, f };
+      }
+      if (Date.now() > until) return null;
+      await page.waitForTimeout(150);
+    }
+  };
+  // On a phone the desktop menu often hides behind a menu button: press it once, then look again.
+  const openMenu = async () => {
+    if (hamburger) return false;
+    hamburger = true;
+    const b = page.locator('button[aria-label*="menu" i], [role="button"][aria-label*="menu" i], button[aria-label*="navigation" i], button[aria-controls][aria-expanded="false"]').filter({ visible: true }).first();
+    if (!(await b.count().catch(() => 0))) return false;
+    await b.click({ timeout: 2000 }).catch(() => {});
+    await page.waitForTimeout(settle);
+    return true;
+  };
+  for (const step of plan) {
+    if (step.do === "skip") {
+      skipped.push(`step ${step.n} (${step.words}): ${step.why}`);
+      continue;
+    }
+    let hit = null;
+    if (step.find.length) {
+      hit = await findTarget(step, wait);
+      if (!hit && loose && (await openMenu())) {
+        hit = await findTarget(step, 1000);
+        if (hit) used = "opened the menu button first";
+      }
+      if (!hit) return { state: "couldn't reopen", ran: false, steps: plan.length, failed: step.n, step: step.words, why: `step ${step.n} (${step.words}): nothing on the page matched it`, skipped };
+      if (loose && hit.f.by === "text" && !hit.f.tag) used ??= `found ${step.words.replace(/^\w+ /, "")} by its words`;
+    }
+    try {
+      const l = hit?.l;
+      if (step.do === "click") await l.click({ timeout: wait }).catch(() => l.click({ timeout: 1000, force: true }));
+      else if (step.do === "hover") await l.hover({ timeout: wait }).catch(() => l.hover({ timeout: 1000, force: true }));
+      else if (step.do === "fill") await l.fill(step.value, { timeout: wait });
+      else if (step.do === "select") await l.selectOption(step.value ?? { label: step.label }, { timeout: wait }).catch(() => l.selectOption({ label: step.label }, { timeout: 1000 }));
+      else if (step.do === "press") {
+        if (l) await l.focus({ timeout: wait });
+        await page.keyboard.press(step.key);
+      }
+    } catch (e) {
+      return { state: "couldn't reopen", ran: false, steps: plan.length, failed: step.n, step: step.words, why: `step ${step.n} (${step.words}) didn't work: ${String(e.message).split("\n")[0].slice(0, 160)}`, skipped };
+    }
+    await page.waitForTimeout(settle);
+  }
+  return { state: "reopened", ran: true, steps: plan.length, ...(skipped.length ? { skipped } : {}), ...(used ? { loose: used } : {}) };
+}

package/src/pool.mjs

@@ -0,0 +1,80 @@
+// One browser and one dev server per process, shared by every render in it. A CLI command (judge, pick,
+// critique …) renders many pages; the MCP server runs a whole loop in one process. Launching Chrome and
+// finding or starting the dev server each time cost seconds per step, so in keep-alive mode they stay up
+// until closePool() (the CLI calls it when the command ends) or until they sit idle (the MCP server).
+import { chromium } from "playwright-core";
+import { startDevServer } from "./devserver.mjs";
+
+let keep = false;
+let idleMs = 0;
+let browserP = null;
+const servers = new Map();
+const live = new Set();
+let timer = null;
+
+export async function launch() {
+  if (process.env.PALATE_BROWSER) return chromium.launch({ executablePath: process.env.PALATE_BROWSER });
+  for (const channel of ["chrome", "msedge", "chromium"]) {
+    try {
+      return await chromium.launch({ channel });
+    } catch {}
+  }
+  throw new Error("No Chrome or Edge found. Install one, or set PALATE_BROWSER to a Chromium executable.");
+}
+
+// Turns sharing on. idle: close everything after this long without use (0: only on closePool).
+export function keepAlive({ idle = 0 } = {}) {
+  keep = true;
+  idleMs = idle;
+}
+
+function touch() {
+  if (!idleMs) return;
+  clearTimeout(timer);
+  timer = setTimeout(() => closePool().catch(() => {}), idleMs);
+  timer.unref?.();
+}
+
+// { browser, release }. Callers open and close their own pages or contexts; release() never closes a shared browser.
+export async function acquireBrowser() {
+  if (!keep) {
+    const browser = await launch();
+    return { browser, release: () => browser.close().catch(() => {}) };
+  }
+  touch();
+  if (browserP) {
+    const b = await browserP.catch(() => null);
+    if (b?.isConnected()) return { browser: b, release: touch };
+  }
+  browserP = launch();
+  return { browser: await browserP, release: touch };
+}
+
+// { base, stop, name }, like startDevServer; shared per project folder in keep-alive mode.
+export async function acquireServer(dir, { url } = {}) {
+  if (url || !keep) return startDevServer(dir, { url });
+  touch();
+  const key = dir.toLowerCase();
+  if (!servers.has(key)) servers.set(key, startDevServer(dir).catch((e) => (servers.delete(key), Promise.reject(e))));
+  const s = await servers.get(key);
+  live.add(s);
+  return { ...s, stop: touch };
+}
+
+export async function closePool() {
+  clearTimeout(timer);
+  const b = browserP;
+  browserP = null;
+  if (b) await (await b.catch(() => null))?.close().catch(() => {});
+  for (const [k, p] of servers) {
+    servers.delete(k);
+    const s = await p.catch(() => null);
+    live.delete(s);
+    s?.stop();
+  }
+}
+
+// A dev server palate started must not outlive the process (stop is synchronous).
+process.on("exit", () => {
+  for (const s of live) s.stop();
+});

package/src/principles.mjs

@@ -0,0 +1,279 @@
+// Design principles, measured: alignment, hierarchy, spacing and proximity, sizing and type, consistency
+// and density. page-principles.js runs inside the page and returns raw measurements with offenders; this
+// module turns them into short findings (what, where, the fix), each tagged with the kb/craft/principles.md
+// item it comes from ([P01]…), so critique findings can cite it.
+//
+//   import { measurePrinciples, principleFindings, principlesReport } from "./principles.mjs";
+//   const p = await measurePrinciples(page);          // a Playwright page, already loaded
+//   report.push(...principlesReport(p));              // markdown lines
+//
+// Run alone for calibration: node src/principles.mjs <url> [--width 1440] [--json]
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const load = (f) => fs.readFileSync(path.join(here, f), "utf8").trim().replace(/;\s*$/, "");
+const sectionsScript = load("page-sections.js");
+const principlesScript = load("page-principles.js");
+
+// Thresholds, tuned on palate-site, cal.com, plane.so, linear.app, vercel.com and stripe.com (Oct 2026).
+export const LIMITS = {
+  nearMissMax: 6, // px: an edge this close to a shared line, but not on it, is a near miss
+  flatStep: 1.2, // headline / next text below it: under this (without a weight gap) the step is too flat
+  jumpStep: 4.5, // ... over this next to text of 16px or less is a jump
+  focalShare: 0.85, // elements within 15% of the top weight compete for attention
+  primaryLead: 1.12, // the primary button should outweigh the next one by this much
+  offScaleShare: 15, // % of spacing values off the 4px scale before it is worth fixing
+  measure: [35, 85], // characters per line for body text on desktop
+  bodyLeading: [1.35, 1.8],
+  displayLeading: [0.9, 1.3],
+  weights: 4,
+  sizes: 10,
+  headingWords: 12,
+  radii: 4,
+  shadows: 4,
+  buttonVariants: 8,
+  hole: 280, // px of nothing inside a section
+};
+
+/** Measures the page at its current width. Scrolls to the top first; returns the raw measurements. */
+export async function measurePrinciples(page, { sections } = {}) {
+  await page.evaluate(() => window.scrollTo({ top: 0, behavior: "instant" }));
+  const secs = sections ?? (await page.evaluate(`(${sectionsScript})()`).catch(() => null));
+  return page.evaluate(`(${principlesScript})(${JSON.stringify(secs ?? null)})`);
+}
+
+const q = (s, n = 40) => `"${String(s ?? "").slice(0, n)}${String(s ?? "").length > n ? "…" : ""}"`;
+const at = (o) => (o ? `${o.label} ${q(o.text)}` : "");
+const where = (o) => (o ? { selector: o.selector, label: o.label, text: o.text, box: o.box } : null);
+const secName = (p, i) => (i ? `section ${i} (${p.sections.find((s) => s.index === i)?.name.slice(0, 30) ?? "?"})` : "the page");
+
+/** Turns raw measurements into findings: { id, area, severity, what, where[], fix }. */
+export function principleFindings(p, limits = LIMITS) {
+  const L = { ...LIMITS, ...limits };
+  const out = [];
+  const add = (id, area, severity, what, offenders, fix) => out.push({ id, area, severity, what, where: (offenders ?? []).filter(Boolean).map(where), fix });
+  const desktop = p.viewport.width >= 1000;
+
+  // ---- alignment ----
+  const a = p.alignment;
+  const misses = a.nearMisses.filter((m) => Math.abs(m.offBy) <= L.nearMissMax);
+  const byLine = new Map();
+  for (const m of misses) {
+    const k = `${m.side}:${m.line}`;
+    byLine.set(k, [...(byLine.get(k) ?? []), m]);
+  }
+  for (const ms of [...byLine.values()].slice(0, 6)) {
+    const m = ms[0];
+    add("P01", "alignment", m.lineCount >= 4 ? "medium" : "low",
+      `${ms.length} item(s) sit ${[...new Set(ms.map((x) => `${Math.abs(x.offBy)}px`))].join("/")} ${m.offBy > 0 ? "right" : "left"} of the ${m.side} edge at x=${m.line} that ${m.lineCount} items share (${secName(p, m.section)}): ${ms.slice(0, 3).map((x) => at(x.offender)).join(", ")}. On the line: ${at(m.onLine)}.`,
+      ms.map((x) => x.offender),
+      `Put them on the shared edge: match the container padding or max-width of ${m.onLine.label} instead of nudging.`);
+  }
+  // [P02] The count of distinct edges is reported as a fact, not a finding: grid columns legitimately add edges.
+  for (const m of a.mixed) {
+    const pr = m.pairs[0];
+    add("P03", "alignment", "medium", `Centred and left-aligned text are stacked in one column in ${secName(p, m.section)}: centred ${at(pr.centred)} over left-aligned ${at(pr.left)}.`, [pr.centred, pr.left], "Pick one alignment for the stack. Left-align when the text runs past two lines; centre only short, single-purpose blocks.");
+  }
+  for (const r of a.ragged) {
+    for (const i of r.issues) {
+      const sev = i.kind === "first lines" || i.kind === "item tops" || i.kind === "pair edges" ? "medium" : "low";
+      const what = {
+        "item tops": `items in a row start ${i.spread}px apart`,
+        "first lines": `the first lines of ${r.items} items in a row start ${i.spread}px apart${i.why ? ` (${i.why})` : ""}`,
+        "second lines": `the text under the titles starts ${i.spread}px apart${i.why ? ` because ${i.why}` : ""}`,
+        "card heights": `cards in one row differ in height by ${i.spread}px`,
+        "pair edges": `two blocks side by side almost line up: their ${i.why} edges are ${i.spread}px apart`,
+      }[i.kind];
+      const fix = {
+        "item tops": "Align the row to the top (align-items: start or stretch), not centre.",
+        "first lines": "Give every item the same lead-in (same icon slot or none) so the titles share a baseline.",
+        "second lines": "Shorten the titles to one line, or give the title a fixed line count (min-height in lines) so the body text lines up.",
+        "card heights": "Stretch the cards to the row height (align-items: stretch, height: 100%).",
+        "pair edges": "Line them up exactly: stretch both to the row's height (align-items: stretch, height: 100%), or align both tops, bottoms or centres. A near miss reads as a mistake.",
+      }[i.kind];
+      add("P04", "alignment", sev, `Ragged row in ${secName(p, r.section)}: ${what}. Items: ${r.offenders.slice(0, 3).map(at).join(", ")}.`, r.offenders, fix);
+    }
+  }
+
+  // ---- hierarchy ----
+  const h = p.hierarchy;
+  if (!h.h1Count) add("P06", "hierarchy", "medium", "The page has no <h1>. Screen readers and search engines lose the page's title, and there is no declared top of the hierarchy.", [], "Mark the main headline as the single <h1>.");
+  else if (h.h1Count > 1) add("P06", "hierarchy", "low", `${h.h1Count} <h1> elements: ${h.h1.map(at).join(", ")}.`, h.h1, "Keep one <h1>; make the others <h2>.");
+  for (const s of h.scopes) {
+    const scope = s.section ? secName(p, s.section) : "the first screen";
+    if (s.heading && s.headingRank > 1 && s.outranking.length) {
+      const o = s.outranking[0];
+      const by = o.score / s.heading.score;
+      if (by >= 1.1) add("P06", "hierarchy", !s.section && by >= 1.2 ? "high" : by >= 1.2 ? "medium" : "low", `In ${scope}, ${o.kind} ${at(o)} outweighs the heading ${at(s.heading)} (${Math.round((by - 1) * 100)}% more visual weight from size, weight and contrast).`, [o, s.heading], `Make the heading the heaviest thing: raise its size or weight, or quiet ${o.label} (smaller, lighter, lower contrast).`);
+    }
+    // Peers that are headings of the same style are parallel columns (no section heading above them), not rivals.
+    const rivals = (s.peers ?? []).filter((x) => x.kind !== s.heading?.kind || Math.abs(x.score - s.heading.score) > 0.5);
+    if (s.heading && rivals.length && s.headingRank <= 1 + s.peers.length) add("P08", "hierarchy", "low", `In ${scope}, ${rivals.length} element(s) carry as much weight as the heading ${at(s.heading)}: ${rivals.slice(0, 3).map(at).join(", ")}.`, [s.heading, ...rivals], "Let the heading lead: set the others a step smaller or lighter, or in a quieter colour.");
+    else if (s.focalPoints >= 3 && s.competing.length >= 2 && s.top[0].score >= 20) add("P08", "hierarchy", "medium", `${s.focalPoints} things compete for first look in ${scope} (within 15% of the top weight): ${[s.top[0], ...s.competing].slice(0, 4).map(at).join(", ")}.`, [s.top[0], ...s.competing], "Choose one focal point and step the others down a size or a weight.");
+    const st = s.steps;
+    const realLead = s.heading || (s.top[0] && s.top[0].size >= 20);
+    if (st?.next && st.headlineToNext && realLead) {
+      const lead = s.heading ?? s.top[0];
+      // Hierarchy carried by colour (a dimmer line under the heading) counts: only flat when size, weight and contrast all match.
+      if (st.headlineToNext < L.flatStep && (st.weightGap ?? 0) < 200 && (st.scoreRatio ?? 1) < 1.25 && st.headline >= st.next.size) add("P07", "hierarchy", "medium", `Flat step in ${scope}: the heading ${at(lead)} is ${st.headline}px/${st.headlineWeight} and the text under it ${at(st.next)} is ${st.next.size}px/${st.next.weight} (×${st.headlineToNext}).`, [lead, st.next], `Separate them by at least ×1.25 in size (e.g. ${Math.round(st.next.size * 1.25)}px+), two weight steps, or a clearly quieter colour for the second line.`);
+      if (st.headlineToNext > L.jumpStep && st.next.size <= 16) add("P07", "hierarchy", "low", `Big jump in ${scope}: ${st.headline}px heading straight onto ${st.next.size}px text (×${st.headlineToNext}); the small text looks like a caption.`, [lead, st.next], `Add a step between them: a ${Math.round(st.next.size * 1.25)}–${Math.round(st.next.size * 1.5)}px lead paragraph, or bring the heading down.`);
+    }
+    for (const g of s.buttonGroups ?? []) {
+      if (g.choiceSet) continue;
+      const [b1, b2] = g.buttons;
+      if (!g.clearPrimary) add("P09", "hierarchy", "medium", `No clear primary action in ${scope}: ${at(b1)} and ${at(b2)} carry about the same weight (${b1.prominence} vs ${b2.prominence}${g.equalStyle ? ", same style" : ""}).`, [b1, b2], "Fill the primary with the accent and make the others outline or text buttons.");
+      else if (!g.primaryFirst && !s.section) add("P09", "hierarchy", "low", `The strongest button in ${scope}, ${at(b1)}, is not first in reading order.`, [b1], "Put the primary action first (left), the secondary after it.");
+    }
+    if (!s.section && s.controls?.length >= 2) {
+      const heroTop = s.buttonGroups?.find((g) => !g.choiceSet)?.buttons?.[0] ?? s.controls.find((c) => !c.inNav && c.filled);
+      const navTop = s.controls.find((c) => c.inNav);
+      if (heroTop && navTop && navTop.prominence > heroTop.prominence * 1.1) add("P09", "hierarchy", "low", `The header button ${at(navTop)} outweighs the hero's main action ${at(heroTop)}.`, [navTop, heroTop], "Make the hero's primary the strongest control on the first screen; keep the header button smaller or quieter.");
+    }
+  }
+
+  // ---- spacing ----
+  const sp = p.spacing;
+  if (sp.offScaleShare > L.offScaleShare) add("P12", "spacing", "medium", `${sp.offScaleShare}% of spacing values are off a 4px scale (fractional em/fluid values excluded): ${sp.offScale.slice(0, 5).map((v) => `${v.value}px×${v.count} (${v.examples[0]?.prop} on ${v.examples[0]?.label})`).join(", ")}.`, sp.offScale.flatMap((v) => v.examples.slice(0, 1)), `Use the scale${sp.unit ? ` (${sp.unit}px unit)` : ""}: round each to the nearest step (e.g. 18→16 or 20, 30→32).`);
+  else if (sp.offScale.length && sp.offScale[0].count >= 3) add("P12", "spacing", "low", `Spacing mostly sits on a ${sp.unit ?? 4}px scale, except ${sp.offScale.slice(0, 3).map((v) => `${v.value}px×${v.count}`).join(", ")}.`, sp.offScale.flatMap((v) => v.examples.slice(0, 1)), "Round these to the nearest step on the scale.");
+  for (const x of sp.proximity.slice(0, 6)) add("P13", "spacing", x.gapAbove < x.gapBelow * 0.9 && x.gapBelow - x.gapAbove >= 4 ? "medium" : "low", `${at(x.offender)} sits ${x.gapAbove}px below ${at(x.above)} but ${x.gapBelow}px above ${at(x.below)}, the content it introduces: it reads as part of the wrong group.`, [x.offender, x.above, x.below], `Give it more space above than below (e.g. ${Math.max(x.gapBelow * 2, 24)}px above, ${Math.min(x.gapAbove, Math.round(x.gapBelow / 2)) || 8}px below).`);
+  const pads = sp.sectionPadding.sections.filter((s) => !s.ownBg || true);
+  if (pads.length >= 3) {
+    const gaps = pads.slice(1).map((s) => s.gapFromPrevious).filter((g) => g > 0);
+    const med = median(gaps);
+    const odd = pads.slice(1).filter((s) => s.gapFromPrevious > 0 && med && (s.gapFromPrevious < med * 0.6 || s.gapFromPrevious > med * 1.7) && Math.abs(s.gapFromPrevious - med) > 32);
+    if (odd.length) add("P14", "spacing", "low", `Section rhythm: the space between sections is mostly ~${Math.round(med)}px, but ${odd.slice(0, 3).map((s) => `${s.gapFromPrevious}px before ${secName(p, s.section)}`).join(", ")}.`, [], "Use one or two section spacings (e.g. 96 and 128px) and keep each one consistent.");
+  }
+
+  // ---- type ----
+  const t = p.type;
+  if (desktop) {
+    const wide = t.measure.filter((m) => m.cpl > L.measure[1]);
+    const narrow = t.measure.filter((m) => m.cpl < L.measure[0]);
+    if (wide.length) add("P17", "type", "medium", `${wide.length} paragraph(s) run ${wide.map((m) => m.cpl).slice(0, 3).join("/")} characters per line (comfortable: 45–75): ${wide.slice(0, 2).map(at).join(", ")}.`, wide, "Cap the measure with max-width: 65ch on the paragraph.");
+    if (narrow.length) add("P17", "type", "low", `${narrow.length} paragraph(s) are only ${narrow.map((m) => m.cpl).slice(0, 3).join("/")} characters wide: ${narrow.slice(0, 2).map(at).join(", ")}.`, narrow, "Widen the column or reduce the size so lines carry 45+ characters.");
+  }
+  const tight = t.lineHeight.filter((l) => l.kind === "body" && l.ratio < L.bodyLeading[0]);
+  const loose = t.lineHeight.filter((l) => l.kind === "body" && l.ratio > L.bodyLeading[1]);
+  const dispLoose = t.lineHeight.filter((l) => l.kind === "display" && l.ratio > L.displayLeading[1]);
+  const dispTight = t.lineHeight.filter((l) => l.kind === "display" && l.ratio < L.displayLeading[0]);
+  const headLoose = t.lineHeight.filter((l) => l.kind === "heading" && (l.ratio > 1.6 || l.ratio < 1.0));
+  if (tight.length) add("P18", "type", "medium", `Body text set tight (line-height ${[...new Set(tight.map((l) => l.ratio))].join("/")}): ${tight.slice(0, 2).map(at).join(", ")}.`, tight, "Use line-height 1.5 for body text (1.4–1.6).");
+  if (loose.length) add("P18", "type", "low", `Body text set loose (line-height ${[...new Set(loose.map((l) => l.ratio))].join("/")}): ${loose.slice(0, 2).map(at).join(", ")}.`, loose, "Bring body line-height to 1.5–1.6.");
+  if (dispLoose.length) add("P18", "type", "medium", `Display text wraps with body-text leading (${[...new Set(dispLoose.map((l) => l.ratio))].join("/")}): ${dispLoose.slice(0, 2).map(at).join(", ")}. The lines drift apart.`, dispLoose, "Set headings at line-height 1.0–1.15.");
+  if (dispTight.length) add("P18", "type", "low", `Display text so tight lines may collide (${dispTight.map((l) => l.ratio).join("/")}): ${dispTight.slice(0, 2).map(at).join(", ")}.`, dispTight, "Use at least 0.95 so descenders clear the next line.");
+  if (headLoose.length) add("P18", "type", "low", `Headings with off leading (${[...new Set(headLoose.map((l) => l.ratio))].join("/")}): ${headLoose.slice(0, 2).map(at).join(", ")}.`, headLoose, "Set small headings at line-height 1.2–1.35.");
+  const usedWeights = t.weights.filter((w) => w.chars >= 20);
+  if (usedWeights.length > L.weights) add("P19", "type", "low", `${usedWeights.length} font weights in use (${usedWeights.map((w) => `${w.weight}×${w.blocks}`).join(", ")}).`, [], "Use two or three weights (e.g. 400, 500, 600) and build hierarchy with size and colour.");
+  if (t.looseDisplay.length) add("P20", "type", "medium", `Large text set loose (positive tracking on ${t.looseDisplay.map((x) => `${x.size}px`).join("/")}): ${t.looseDisplay.slice(0, 2).map(at).join(", ")}.`, t.looseDisplay, "Display sizes want zero or slightly negative tracking (-0.01 to -0.03em).");
+  if (t.capsNoTracking.length) add("P21", "type", "low", `${t.capsNoTracking.length} all-caps label(s) without letter-spacing: ${t.capsNoTracking.slice(0, 3).map(at).join(", ")}.`, t.capsNoTracking, "Track caps out by 0.05–0.1em (letter-spacing: 0.06em).");
+  if (t.sizes.length > L.sizes) add("P22", "type", "low", `${t.sizes.length} font sizes: ${t.sizes.map((s) => `${s.size}×${s.blocks}`).join(", ")}.`, [], "Reduce to a scale of 5–7 sizes and map every text style onto it.");
+  if (t.scale && t.scale.of >= 5 && t.scale.fit / t.scale.of < 0.6) add("P22", "type", "low", `No consistent type scale: the best ratio (×${t.scale.ratio} from ${t.bodySize}px) fits ${t.scale.fit} of ${t.scale.of} sizes; off-scale: ${t.scale.outside.join(", ")}px.`, [], `Pick a ratio (e.g. ×1.25 from ${t.bodySize}px) and snap sizes to it.`);
+  for (const c of t.closeSizes.slice(0, 3)) add("P26", "type", "low", `${c.sizes[0]}px and ${c.sizes[1]}px are both used and too close to tell apart: ${c.examples.map(at).join(" vs ")}.`, c.examples, `Merge them into one size, or separate them by at least ×1.15.`);
+  for (const x of t.longHeadings.filter((x, i, a) => a.findIndex((y) => y.text === x.text) === i).slice(0, 3)) add("P23", "type", "low", `Heading of ${x.words} words: ${at(x, 70)}.`, [x], "Cut the heading to under 10 words; move the rest into the paragraph below.");
+  if (t.widows.length) add("P24", "type", "low", `${t.widows.length} heading(s) end with one word alone on the last line: ${t.widows.slice(0, 3).map((w) => `${q(w.text, 40)} → "${w.word}"`).join(", ")}.`, t.widows, "Add text-wrap: balance to headings (or rewrite to fit).");
+
+  // ---- consistency ----
+  const c = p.consistency;
+  const realRadii = c.radii.filter((r) => r.radius !== "0" && r.radius !== "pill/circle" && r.count >= 1);
+  if (realRadii.length > L.radii) add("P27", "consistency", "low", `${realRadii.length} corner radii in use: ${realRadii.map((r) => `${r.radius}px×${r.count}`).join(", ")}.`, realRadii.slice(-3).map((r) => r.example), "Use a radius scale of 2–3 values (e.g. 6, 12, pill) and nest them concentrically.");
+  const nestGroups = new Map();
+  for (const n of c.nestedRadii) nestGroups.set(`${n.inner}/${n.outer}/${n.inset}`, [...(nestGroups.get(`${n.inner}/${n.outer}/${n.inset}`) ?? []), n]);
+  for (const ns of [...nestGroups.values()].slice(0, 3)) {
+    const n = ns[0];
+    add("P27", "consistency", "medium", `Nested corners are not concentric${ns.length > 1 ? ` (${ns.length} times)` : ""}: ${n.inner_.label} has radius ${n.inner}px inside ${n.outer_.label} (${n.outer}px) with ${n.inset}px between them; the inner corner should be ~${n.ideal}px.`, ns.flatMap((x) => [x.inner_, x.outer_]).slice(0, 6), n.ideal > 0 ? `Set the inner radius to outer − padding (${n.outer} − ${n.inset} = ${n.ideal}px).` : `The padding is larger than the outer radius, so the inner corner should be nearly square (0–4px), or raise the outer radius to ~${n.inner + n.inset}px.`);
+  }
+  if (c.borders.length > 4) add("P28", "consistency", "low", `${c.borders.length} different box borders: ${c.borders.slice(0, 6).map((b) => `${b.border}×${b.count}`).join(", ")}.`, c.borders.slice(0, 3).map((b) => b.example), "Use one border colour token (and maybe one stronger one for inputs).");
+  if (c.shadows.length > L.shadows) add("P29", "consistency", "low", `${c.shadows.length} different shadows.`, c.shadows.slice(0, 3).map((s) => s.example), "Define 2–3 elevation levels and use only those.");
+  const col = c.colors;
+  if (col.nearDuplicates.length) add("P30", "consistency", "low", `Near-duplicate colours (≤5 apart per channel): ${col.nearDuplicates.slice(0, 4).map((d) => d.join("≈")).join(", ")}.`, [], "Collapse each pair into one token.");
+  const hues = col.hueFamilies.filter((x) => x.share >= 0.5);
+  if (hues.length >= 3) add("P31", "consistency", "low", `${hues.length} colour families each cover 0.5%+ of the page: ${hues.map((x) => `${x.colors[0]} (${x.share}%)`).join(", ")}.`, [], "Keep one accent hue for actions and emphasis; turn the others neutral or into a single supporting tint.");
+  if (col.accent && col.accent.share > 30) add("P31", "consistency", "low", `The accent (${col.accent.colors[0]}) covers ${col.accent.share}% of the page; it stops signalling what to click.`, [], "Reserve the accent for actions and key highlights (~10% of the surface).");
+  const v = c.variants;
+  if (v.buttons.length > L.buttonVariants) add("P32", "consistency", "low", `${v.buttons.length} button styles: ${v.buttons.slice(0, 6).map((b) => `[${b.style}]×${b.count}`).join(", ")}.`, v.buttons.slice(0, 4).map((b) => b.example), "Reduce to primary, secondary and ghost at one or two sizes.");
+  for (const [kind, list] of Object.entries(v.near)) for (const n of list.slice(0, 2)) add("P32", "consistency", "medium", `Two ${kind} that are almost the same but differ in ${n.differs}: ${n.examples.map(at).join(" and ")}.`, n.examples, `Make them one component with one value for ${n.differs.split(" vs ")[0].replace(/[\d.]+.*$/, "") || "that property"}.`);
+  if (v.cards.length > 3) add("P32", "consistency", "low", `${v.cards.length} card styles: ${v.cards.slice(0, 5).map((x) => `[${x.style}]×${x.count}`).join(", ")}.`, v.cards.slice(0, 3).map((x) => x.example), "Use one card surface (fill, border, radius, padding) and vary content, not chrome.");
+  if (v.inputs.length > 2) add("P32", "consistency", "medium", `${v.inputs.length} input styles: ${v.inputs.map((x) => `[${x.style}]×${x.count}`).join(", ")}.`, v.inputs.slice(0, 3).map((x) => x.example), "Inputs should share one height, radius, border and fill.");
+
+  // ---- density ----
+  const content = p.density.filter((d) => !d.chrome && d.height >= 200);
+  const medInk = median(content.map((d) => d.ink));
+  for (let i = 0; i < content.length; i++) {
+    const d = content[i];
+    if (d.items === 0 && d.height > p.viewport.height * 0.5) add("P38", "density", "low", `${secName(p, d.section)} has no measurable content in its ${d.height}px (nothing palate can see: it may be drawn in WebGL or a CSS background, revealed by scrolling, or failed to render).`, [], "Check the screenshot: if it is empty there too, remove the section or fix what failed to load.");
+    else if (medInk >= 6 && d.ink < medInk * 0.35 && d.ink < 8 && d.height > p.viewport.height * 0.6) add("P37", "density", "low", `${secName(p, d.section)} is much emptier than the rest (${d.ink}% ink vs ~${medInk}% typical, ${d.height}px tall).`, [], "Shorten it (less padding, fewer empty rows) or give it content that earns the space.");
+    const busy = (x) => x.textInk + (x.ctlInk ?? 0);
+    const medBusy = median(content.map(busy));
+    if (medBusy >= 2 && busy(d) > Math.max(medBusy * 3, 45)) add("P37", "density", "low", `${secName(p, d.section)} is much denser than its neighbours (${busy(d)}% of it is text and controls vs ~${medBusy}% typical).`, [], "Give it room: more padding, fewer items per row, or split it.");
+    const pinned = d.height > p.viewport.height * 2.5;
+    if (d.emptiestRun > Math.max(L.hole, p.viewport.height * 0.35)) add("P38", "density", pinned ? "low" : "medium", `${secName(p, d.section)} has ${d.emptiestRun}px of nothing at y=${d.emptiestAt}${pinned ? ` (the section is ${d.height}px tall: probably a scroll-pinned sequence)` : ""}.`, [], "Close the gap, or check that something there did not fail to render (a lazy image, an animation that never ran).");
+  }
+
+  const rank = { high: 0, medium: 1, low: 2 };
+  return out.sort((a, b) => rank[a.severity] - rank[b.severity]);
+}
+
+function median(a) {
+  if (!a.length) return 0;
+  const s = [...a].sort((x, y) => x - y);
+  const m = s.length >> 1;
+  return s.length % 2 ? s[m] : (s[m - 1] + s[m]) / 2;
+}
+
+/** A short summary of the measurements (facts, not judgements), as markdown lines. */
+export function principleFacts(p) {
+  const t = p.type;
+  const c = p.consistency;
+  const sp = p.spacing;
+  const fs = p.hierarchy.scopes.find((s) => !s.section);
+  const lines = [];
+  if (fs) lines.push(`- Hierarchy (first screen): ${fs.top.slice(0, 3).map((x) => `${x.kind} ${x.size}px/${x.weight} ${q(x.text, 30)} (${x.score})`).join(" > ")}${fs.steps ? `; steps ${fs.steps.headline}:${fs.steps.subhead ?? "–"}:${fs.steps.body}px` : ""}.`);
+  lines.push(`- Alignment: page edges ${p.alignment.pageLines.map((l) => `x=${l.x} (${l.sections} sections)`).join(", ") || "none shared by 3+ sections"}; ${p.alignment.nearMisses.length} near miss(es).`);
+  lines.push(`- Spacing: ${sp.unit ? `${sp.unit}px unit` : "no clear unit"} (${sp.on8}% on 8, ${sp.on4}% on 4); ${sp.offScaleShare}% off-scale; most used ${sp.common.slice(0, 8).join(", ")}${sp.fluid.length ? `; fluid ${sp.fluid.slice(0, 4).join(", ")}` : ""}.`);
+  lines.push(`- Type: ${t.sizes.length} sizes (${t.sizes.map((s) => s.size).join(", ")}), body ${t.bodySize}px${t.scale ? `, best scale ×${t.scale.ratio} fits ${t.scale.fit}/${t.scale.of}` : ""}; weights ${t.weights.map((w) => w.weight).join("/")}; ${t.families.map((f) => f.family).join(", ")}.`);
+  lines.push(`- Surfaces: radii ${c.radii.map((r) => `${r.radius}×${r.count}`).join(", ")}; ${c.borders.length} border style(s); ${c.shadows.length} shadow(s); ${c.variants.buttons.length} button, ${c.variants.cards.length} card, ${c.variants.inputs.length} input style(s).`);
+  lines.push(`- Colour: ${c.colors.distinct} colours, ${c.colors.text} text colours${c.colors.accent ? `; accent ${c.colors.accent.colors[0]} covers ${c.colors.accent.share < 0.1 ? "<0.1" : c.colors.accent.share}%` : "; no accent hue"}.`);
+  lines.push(`- Density (ink % per section): ${p.density.map((d) => `${d.section}:${d.ink}%`).join(" ")}.`);
+  return lines;
+}
+
+/** Facts plus findings, as markdown lines for a report (shoot, critique). */
+export function principlesReport(p, { max = 14 } = {}) {
+  const f = principleFindings(p);
+  const lines = [`### Principles (${p.viewport.width}px)`, ...principleFacts(p)];
+  if (!f.length) lines.push("- No principle checks fired.");
+  for (const x of f.slice(0, max)) lines.push(`- ${x.severity === "high" ? "⚠⚠" : x.severity === "medium" ? "⚠" : "·"} [${x.id}] ${x.what} Fix: ${x.fix}${x.where[0]?.selector ? ` (\`${x.where[0].selector}\`)` : ""}`);
+  if (f.length > max) lines.push(`- …and ${f.length - max} more (low).`);
+  return lines;
+}
+
+// CLI for calibration: node src/principles.mjs <url> [--width 1440] [--json] [--raw]
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  const args = process.argv.slice(2);
+  const url = args.find((a) => /^(https?|file):/.test(a));
+  const width = Number(args[args.indexOf("--width") + 1]) || 1440;
+  if (!url) {
+    console.error("usage: node src/principles.mjs <url> [--width 1440] [--json] [--raw]");
+    process.exit(1);
+  }
+  const { launch } = await import("./shoot.mjs");
+  const { scrollThrough } = await import("./look.mjs");
+  const browser = await launch();
+  try {
+    const ctx = await browser.newContext({ viewport: { width, height: width < 600 ? 844 : 900 } });
+    const page = await ctx.newPage();
+    await page.goto(url, { waitUntil: "networkidle", timeout: 60_000 }).catch(() => {});
+    await page.waitForTimeout(800);
+    await scrollThrough(page);
+    const t0 = Date.now();
+    const p = await measurePrinciples(page);
+    const ms = Date.now() - t0;
+    if (args.includes("--raw")) console.log(JSON.stringify(p, null, 1));
+    else if (args.includes("--json")) console.log(JSON.stringify(principleFindings(p), null, 1));
+    else console.log([`# ${url} @${width} (${ms}ms)`, ...principlesReport(p, { max: 60 })].join("\n"));
+  } finally {
+    await browser.close();
+  }
+}