@palate/cli 0.0.0-stage → 0.0.2

package/src/loop/cost.mjs

@@ -0,0 +1,63 @@
+// What a loop costs in tokens, estimated: the briefs palate writes (measured) plus what an agent typically spends
+// per builder, judge render, build-out and finishing pass (rough constants, the same for every mode so modes
+// compare fairly). Each setup appends one line to ~/.palate/history/costs.jsonl; `palate stats` sums it by mode.
+// Many people call variant loops a waste of tokens: this makes the trade visible before anything is built.
+import fs from "node:fs";
+import path from "node:path";
+import { PALATE_HOME } from "../catalog/store.mjs";
+
+export const COSTS_LOG = path.join(PALATE_HOME, "history", "costs.jsonl");
+
+// Tokens an agent reads and writes per unit of work, beyond the brief itself.
+export const PER = {
+  sketch: 40_000, // one sketch route: read the project, write the first screen + centrepiece, one shoot
+  full: 80_000, // one whole page as a variant
+  build: 80_000, // build mode: the real route, finished
+  buildOut: 60_000, // completing the winning sketch after the pick
+  finish: 25_000, // shoot at both widths, details, the fixes they ask for
+  ambition: 30_000, // palate ambition: read the side-by-side sheets, score the sections, upgrade the weakest once, verify
+  judgeEach: 3_000, // one render read by the judge
+  judgeBase: 5_000,
+  direct: 12_000, // a fix in place: read the file, change it, one fold shoot, palate check
+  direction: 6_000, // three ideas with rough wireframes, no code
+  research: 22_000, // the web searches, reading research.md and the contact sheet, refining the notes
+  artDirection: 9_000, // three art directions with a signature moment, starter system and wireframe
+  match: 70_000, // palate match: read the design and write spec.json, build it, the check with its one judge, one repair
+};
+
+export const tokensOf = (chars) => Math.round(chars / 4);
+export const k = (n) => (n == null ? "?" : n >= 10_000 ? `${Math.round(n / 1000)}k` : `${(n / 1000).toFixed(1)}k`);
+
+// mode: build | direction | quick | full. briefs: the brief texts. builders: routes built. judged: renders judged.
+export function estimate({ mode, stage = "sketch", briefs = [], builders = 0, judged = 0 } = {}) {
+  const briefBytes = briefs.reduce((n, b) => n + Buffer.byteLength(String(b)), 0);
+  const briefTokens = tokensOf(briefBytes);
+  let work;
+  let how;
+  if (mode === "direct") [work, how] = [PER.direct, "a change in place, one fold shoot and palate check; no brief, no variants"];
+  else if (mode === "direction") [work, how] = [PER.direction, "the brief, then 3 ideas with rough wireframes; no code, no renders"];
+  else if (mode === "research") [work, how] = [PER.research, "web searches, reading the research and its contact sheet; the pages are captured locally, no tokens"];
+  else if (mode === "research-loop") [work, how] = [PER.research + PER.artDirection + PER.build + PER.finish + PER.ambition, "research (searches, notes, contact sheet), 3 art directions, then one build and the finishing pass with its ambition step"];
+  else if (mode === "build") [work, how] = [PER.build + PER.finish + PER.ambition, "one build of the real route, then the finishing pass with its ambition step"];
+  else if (mode === "match") [work, how] = [PER.match + PER.judgeBase + 4 * PER.judgeEach, "reading the design and writing its spec, one build in the project's stack, then the check: one judge over the design, the build and their difference, and a repair"];
+  else {
+    const judge = judged ? PER.judgeBase + judged * PER.judgeEach : 0;
+    const after = (stage === "sketch" ? PER.buildOut : 0) + PER.finish + PER.ambition;
+    work = builders * (PER[stage] ?? PER.sketch) + judge + after;
+    how = `${builders} ${stage === "sketch" ? "sketch" : "page"} builder${builders === 1 ? "" : "s"}${judged ? `, a judge over ${judged} renders` : ""}${stage === "sketch" ? ", the winner built out" : ""}, then the finishing pass with its ambition step`;
+  }
+  return { briefBytes, briefTokens, builders: mode === "build" || mode === "research-loop" || mode === "match" ? 1 : mode === "direction" || mode === "research" || mode === "direct" ? 0 : builders, estTokens: briefTokens + work, how };
+}
+
+// The typical cost of a mode before any brief exists (for the triage's comparison).
+export const typical = (mode, { variants = 0, judge = false } = {}) => estimate({ mode, stage: "sketch", briefs: [mode === "direct" ? "" : "x".repeat(mode === "direction" ? 6000 : mode === "research-loop" ? 30000 : 9000 * Math.max(1, mode === "build" ? 1 : Math.ceil(variants / 2)))], builders: variants, judged: judge ? Math.min(variants, 6) : 0 }).estTokens;
+
+export const costLine = (c) => `Cost: brief${c.builders === 1 || !c.builders ? "" : "s"} ${(c.briefBytes / 1024).toFixed(1)} KB (~${k(c.briefTokens)} tokens); this loop ~${k(c.estTokens)} tokens estimated (${c.how}).`;
+
+export function logCost(dir, name, mode, cost, extra = {}) {
+  if (process.env.PALATE_NO_LOG) return;
+  try {
+    fs.mkdirSync(path.dirname(COSTS_LOG), { recursive: true });
+    fs.appendFileSync(COSTS_LOG, JSON.stringify({ at: new Date().toISOString(), project: path.basename(path.resolve(dir)), name, mode, ...cost, ...extra }) + "\n");
+  } catch {}
+}

package/src/loop/craft.mjs

@@ -0,0 +1,152 @@
+// What the specific-job commands (critique, fix, vary, details, animate) read besides the page: the craft
+// checklists in kb/craft (assembled at runtime from whatever files exist), the user's taste for this kind
+// of screen, and the skills installed on this machine.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { TASTE_DIR } from "./common.mjs";
+import { findSkill } from "./polish.mjs";
+import { KB_ROOT } from "../paths.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const KB_DIR = process.env.PALATE_KB ?? KB_ROOT;
+export const CRAFT_DIR = path.join(KB_DIR, "craft");
+
+function walk(d) {
+  if (!fs.existsSync(d)) return [];
+  return fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => (e.isDirectory() ? walk(path.join(d, e.name)) : e.name.endsWith(".md") ? [path.join(d, e.name)] : []));
+}
+
+// Every kb/craft file (or those whose name or title matches `match`), with each top-level list item numbered
+// [file.n] so findings can cite the exact rubric item. Source links are left in the files. compact: only each
+// item's title and how to detect it (the fix stays in the file), for sheets that cover every file.
+// Returns { text, files }; text is "" when none exist.
+export function craftRubric(match, { compact = false } = {}) {
+  const files = walk(CRAFT_DIR).filter((f) => !/^(sources|readme|index)\.md$/i.test(path.basename(f))).sort();
+  const parts = [];
+  const used = [];
+  for (const f of files) {
+    const src = fs.readFileSync(f, "utf8").replace(/\r\n/g, "\n");
+    const front = src.match(/^---\n([\s\S]*?)\n---\n?/);
+    const body = front ? src.slice(front[0].length) : src;
+    const id = path.basename(f, ".md");
+    const title = front?.[1].match(/^title:\s*(.+)$/m)?.[1].replace(/^["']|["']$/g, "") ?? body.match(/^#\s+(.+)$/m)?.[1] ?? id;
+    if (match && !match.test(`${id} ${title}`)) continue;
+    let n = 0;
+    const isItem = (l) => /^(?:[-*]|\d+[.)])\s+/.test(l);
+    const lines = body
+      .trim()
+      .split("\n")
+      .filter((l) => !compact || isItem(l) || /^#{2,3}\s/.test(l))
+      // Items that carry their own id ("- **[M16] …") keep it; others get [file.n].
+      .map((l) => (isItem(l) && !/^(?:[-*]|\d+[.)])\s+\**\[[A-Z]+\d+\]/.test(l) ? l.replace(/^(?:[-*]|\d+[.)])\s+(?:\[[ x]\]\s+)?/, `- [${id}.${++n}] `) : l.replace(/^(#{1,3})\s/, "#### ")))
+      .map((l) => l.replace(/\s*\(Sources?:[^)]*\)/g, ""))
+      .map((l) => (compact && isItem(l) ? l.replace(/\s+(?:Fix|Do|Instead):.*$/, "") : l));
+    parts.push(`### ${title} (kb/craft/${path.relative(CRAFT_DIR, f).replace(/\\/g, "/")})\n${lines.join("\n")}`);
+    used.push(f);
+  }
+  return { text: parts.join("\n\n"), files: used };
+}
+
+// The parts of the taste profile that bear on this screen: the general rules plus the best-matching
+// "## <kind of screen>" sections. Returns "" when there is no profile.
+// lean: only the "constant across all screens" rules in full; other general blocks keep their first
+// paragraph (the rule itself, not the story behind it).
+// project: the project this is for. A section learned on another project is labelled as that product's
+// decision, and its look (colour, type, hero layout) is left out; how the user judged it stays.
+export function tasteFor(query, { sections = 2, lean = false, project } = {}) {
+  const file = path.join(TASTE_DIR, "profile.md");
+  if (!fs.existsSync(file)) return "";
+  const src = fs.readFileSync(file, "utf8").replace(/\r\n/g, "\n");
+  const blocks = src.split(/\n(?=#{1,2} )/).map((b) => ({ head: b.match(/^#{1,2} (.+)/)?.[1] ?? "", body: b.trim() }));
+  const STOP = new Set(["section", "page", "screen", "loop", "the", "and", "for", "with", "type"]);
+  const q = new Set((query.toLowerCase().match(/[a-z]{3,}/g) ?? []).map((w) => w.replace(/s$/, "")).filter((w) => !STOP.has(w)));
+  const general = blocks.filter((b) => /rule underneath|constant|general|always/i.test(b.head));
+  const scored = blocks
+    .filter((b) => !general.includes(b) && /^##? /.test(b.body) && b.head && !/^taste profile$|^by type of screen$/i.test(b.head))
+    .map((b) => ({ b, s: (b.head.toLowerCase().match(/[a-z]{3,}/g) ?? []).filter((w) => q.has(w.replace(/s$/, ""))).length }))
+    .filter((x) => x.s > 0)
+    .sort((a, b) => b.s - a.s)
+    .slice(0, sections)
+    .map((x) => x.b);
+  const firstPara = (b) => b.body.split(/\n\s*\n/).slice(0, 2).join("\n\n");
+  return [...general.map((b) => (lean && !/constant|always/i.test(b.head) ? firstPara(b) : b.body)), ...scored.map((b) => (project ? ownedSection(b, project) : b.body))].join("\n\n");
+}
+
+// ---- taste vs one project's look. The profile mixes how the user judges (holds across projects) with what one
+// project looked like (its colour, type and hero). Split at read time only: the profile file is never rewritten.
+// A line is a look decision when it names a colour, a typeface, a canvas, a centred hero or a pixel size.
+const LOOK = /#[0-9a-f]{3,8}\b|\b(emerald|klein blue|oxblood|teal|indigo|violet|purple|yellow|orange|navy|cobalt|crimson|olive|sage|lilac|pastel)\b|\b(geist|inter|helvetica|garamond|serif|sans|grotesk|condensed)\b|\b(canvas|centred|centered|wash|backdrop|dark band|picked deep)\b|\b\d{2,3}px\b/i;
+
+const jsonLines = (f) => (fs.existsSync(f) ? fs.readFileSync(f, "utf8").split("\n").filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean) : []);
+
+// Which project a profile section was learned on: a project named in its heading ("palate-site home, Oct 18"),
+// or the project whose picks used that loop ("loop 3" → the project with a loop3-… loop).
+export function sectionProject(head) {
+  const picks = jsonLines(path.join(TASTE_DIR, "picks.jsonl"));
+  const projects = [...new Set(picks.map((p) => p.project).filter(Boolean))].sort((a, b) => b.length - a.length);
+  const named = projects.find((p) => head.toLowerCase().includes(p.toLowerCase()));
+  if (named) return named;
+  const n = head.match(/\bloop (\d+)\b/i)?.[1];
+  return n ? (picks.find((p) => new RegExp(`^loop${n}(\\b|-)`).test(p.loop ?? ""))?.project ?? null) : null;
+}
+
+// A profile section with its project named; from another project, only the judgement stays.
+export function ownedSection(b, project) {
+  const from = sectionProject(b.head);
+  const [head, ...rest] = b.body.split("\n");
+  if (!from) return b.body;
+  if (from.toLowerCase() === String(project).toLowerCase()) return [head, `_From this project (${from})._`, ...rest].join("\n");
+  const kept = rest.filter((l) => !LOOK.test(l));
+  const dropped = rest.length - kept.length;
+  return [
+    head,
+    `_From ${from}: a decision for that product, not a template; don't reuse its layout, colour or type here. What carries over is how the user judged it.${dropped ? ` (${dropped} line${dropped > 1 ? "s" : ""} about ${from}'s own colour, type and hero left out.)` : ""}_`,
+    ...kept,
+  ].join("\n");
+}
+
+// Words for matching a loop's kind of screen to the profile's sections.
+const KIND_WORDS = { landing: "marketing landing waitlist homepage", hero: "hero", pricing: "pricing", features: "features", onboarding: "onboarding setup", team: "team members", settings: "settings", table: "data table list", dashboard: "dashboard overview", auth: "login signup", docs: "docs documentation" };
+export const kindWords = (screen, kind, name = "") => `${KIND_WORDS[screen] ?? ""} ${kind === "hero" ? "hero" : ""} ${screen === "other" ? name.replace(/[^a-z]+/gi, " ") : ""}`.trim() || kind;
+
+// Words that say what kind of screen a route is, for matching the profile and the reference library.
+export function screenWords(route, sectionNames = [], title = "") {
+  const t = `${route} ${title} ${sectionNames.join(" ")}`.toLowerCase();
+  const out = [];
+  if (route === "/" || /landing|waitlist|hero|join|sign ?up/.test(t)) out.push("marketing landing hero features");
+  for (const w of ["pricing", "dashboard", "table", "settings", "team", "onboarding", "setup", "docs", "blog", "checkout", "profile", "billing", "inbox", "features", "testimonials", "faq"]) if (t.includes(w)) out.push(w);
+  return out.join(" ") || route.replace(/[^a-z]+/gi, " ");
+}
+
+export function skillFiles(dir, ids) {
+  return ids.map((id) => ({ id, file: findSkill(dir, id) }));
+}
+
+export const slash = (p) => String(p).replace(/\\/g, "/");
+
+// The reference library's thumbnails (kb/references, or PALATE_LIBRARY).
+export const LIB_DIR = process.env.PALATE_LIBRARY ?? path.join(KB_DIR, "references");
+
+// What kind of section this is, as words the reference library understands.
+export function sectionKind(s, { first = false, media = false } = {}) {
+  const t = `${s.name} ${s.heading ?? ""} ${s.id ?? ""} ${(s.text ?? "").slice(0, 160)}`.toLowerCase();
+  if (s.tag === "footer") return "footer";
+  if (s.tag === "header" || s.tag === "nav") return "navbar header";
+  if (first) return "hero section";
+  // A live product demo: named as one, or interactive and mostly product.
+  if (/\b(demo|live|playground|try it)\b/.test(`${s.name} ${s.id ?? ""}`.toLowerCase())) return "mockup product showcase marketing section";
+  // "Plan" alone is too common (a step, a verb); pricing needs a price or a billing word.
+  if (/\bpric|per month|per seat|\/mo\b|[$€£]\s?\d|\bbilled\b|\b(free|pro|team|enterprise) plan\b/.test(t)) return "pricing section";
+  if (/\bfaq|frequently asked|questions\b/.test(t)) return "faqs section";
+  if (/testimonial|what .{1,30} say|loved by|\breviews?\b/.test(t)) return "testimonials section";
+  if (/trusted by|used by|works (with|in|inside)|integrat|partners|customers|any stack|frameworks?\b/.test(t) && (s.text ?? "").length < 300) return "logo cloud";
+  // A section that is mostly one big picture of the product.
+  if (media && (s.text ?? "").length < 200) return "mockup product showcase marketing section";
+  if (/waitlist|sign ?up|subscribe|newsletter|get started|join|request access/.test(t)) return "cta newsletter signup section";
+  if (/team|people|founders/.test(t)) return "team sections";
+  if (/step|how it works|process|loop|workflow/.test(t)) return "steps timeline section";
+  if (/\d+%|\bstats?\b|numbers/.test(t)) return "stats section";
+  if (/feature|capabilit|everything you need/.test(t)) return "feature grids section";
+  return "marketing section";
+}

package/src/loop/craftchecks.mjs

@@ -0,0 +1,148 @@
+// Craft checks: the edge cases a real design session (palate-site's retrospective, Nov 2026) showed slipping past
+// every layout check. A truck cut at the photo's edge (twice), portrait sources in landscape slots, a full-bleed
+// photo whose subject sat at the bleeding edge, a script "D" swash cut by clip-path on a reveal, "Cost-Conscious"
+// breaking at the hyphen on phones, "Time savings" wrapping onto two lines in a narrow column, an "01" chapter
+// label over a 01–05 list. src/page-craft.js measures in the page; craftChecks turns that into floor findings
+// ({ id, width, section, severity, what, fix }, the shape floor.mjs uses) and runFloor adds them at each width.
+//
+// The photo checks are heuristics on a 96px copy of the source: "detail energy" is the Sobel gradient of
+// luminance, blurred, minus its median (a flat sky or wall is zero). A subject is "clear" when the busiest
+// quarter of an 8×8 grid holds 40%+ of the energy (an even texture or an all-over painting doesn't, and then
+// nothing is said about subjects). Cross-origin images can't be read; they get the crop check only.
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { FONT_GENRES } from "../fontgenre.mjs";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const craftScript = fs.readFileSync(path.join(here, "..", "page-craft.js"), "utf8").trim().replace(/;\s*$/, "");
+
+// ---- thresholds
+// Share of a photo cut away by its crop (object-fit / background-size: cover, overflow, the viewport): a 3:2
+// photo in a square slot loses 33%, a 2:3 portrait in a 3:2 slot 56%.
+export const CUT_WARN = 0.35;
+export const CUT_FAIL = 0.55;
+// A heavy crop that keeps this much of the detail energy (with a clear subject and no edge sliced) is reported
+// as a warning, not a fail: the subject is in what shows.
+export const CUT_KEPT = 0.85;
+// Subject at an edge (page-craft.js finds candidates: a hot run along the edge ≥ 15% of it at 1.5× the shown
+// part's mean energy on both sides of a cut, ≥ 25% at 1.8× inside a bleeding edge). A fail needs a run this long
+// and this strong; anything weaker is a "likely" warning.
+export const EDGE_FAIL = { run: 0.35, score: 2.5 };
+// A photo with this share of it behind other content (sampled with elementFromPoint) is a backdrop: its crop
+// is reported, never failed (palate-site's hero painting under the form and the demo: 90% cut at 390, mostly covered).
+export const BACKDROP = 0.4;
+// HYPHEN_BREAK fails at phone widths for display sizes.
+export const PHONE_MAX = 430;
+export const DISPLAY_PX = 28;
+
+const short = (s, n = 48) => {
+  const t = String(s ?? "").replace(/\s+/g, " ").trim();
+  return t.length > n ? t.slice(0, n - 1) + "…" : t;
+};
+const ref = (s) => (s ? { index: s.index, heading: short(s.heading, 80) } : null);
+const pct = (v) => `${Math.round(v * 100)}%`;
+const shape = ([w, h]) => (w / h > 1.15 ? "landscape" : w / h < 0.87 ? "portrait" : "square");
+const list = (xs) => (xs.length <= 1 ? xs.join("") : `${xs.slice(0, -1).join(", ")} and ${xs[xs.length - 1]}`);
+
+function photoFinding(p, width) {
+  const parts = [];
+  const fixes = [];
+  let sev = null;
+  const raise = (s) => (sev = sev === "fail" || s === "fail" ? "fail" : "warn");
+  const name = `"${short(p.src, 40)}"${p.alt ? ` (${short(p.alt, 30)})` : ""}`;
+  const subject = p.subject;
+  const clear = !!subject?.clear;
+  const edges = clear ? subject.edges ?? [] : [];
+  const how = p.fit === "cover" ? (p.kind === "img" ? "object-fit: cover" : "background-size: cover") : p.kind === "img" ? `object-fit: ${p.fit}` : `background-size ${p.fit}`;
+
+  if (p.cut > CUT_WARN) {
+    let s = p.cut > CUT_FAIL ? "fail" : "warn";
+    const kept = clear && subject.kept >= CUT_KEPT && !edges.length;
+    if (s === "fail" && (kept || (p.read && subject && !clear))) s = "warn";
+    raise(s);
+    const sides = p.cutSides.filter((x) => ["left", "right"].includes(x)).length ? "left and right" : "top and bottom";
+    // Cut by the fit (cover) or by what holds it (an overflow box, the screen edge): say which.
+    const byBox = p.box.w < p.shown[0] - 2 || p.box.h < p.shown[1] - 2;
+    const cause = p.fit === "cover" && !byBox ? `a ${shape(p.natural)} ${p.natural[0]}×${p.natural[1]} source in a ${shape(p.shown)} ${p.shown[0]}×${p.shown[1]} slot (${how})` : `a ${shape(p.natural)} ${p.natural[0]}×${p.natural[1]} source${p.fit === "cover" ? ` in a ${p.shown[0]}×${p.shown[1]} slot (${how})` : ""}, of which its container or the screen edge shows ${p.box.w}×${p.box.h}`;
+    parts.push(`${pct(p.cut)} of it is cut away: ${cause}, cropped at the ${sides}${kept ? `; the detail sits inside what shows (${pct(subject.kept)} kept)` : p.read && subject && !clear ? "; no clear subject (even detail all over), so less is lost" : ""}${p.read ? "" : `; ${p.why ?? "not read"}`}`);
+    fixes.push(byBox && p.fit !== "cover" ? "Fit the photo to the box that shows it (width: 100% with object-fit: cover and a deliberate object-position), or let it show whole" : shape(p.natural) !== shape(p.shown) ? `Use a ${shape(p.shown)} source for this ${shape(p.shown)} slot (or a <picture> source per width), or change the slot to the photo's own shape` : "Choose a source closer to the slot's shape, or loosen the slot's aspect ratio");
+  }
+  for (const e of edges) {
+    const strong = e.run >= EDGE_FAIL.run && e.score >= EDGE_FAIL.score;
+    raise(strong ? "fail" : "warn");
+    const where = e.kind === "cut" ? (e.bleed ? `${e.side} edge, where the crop cuts it and the photo bleeds off the screen` : `${e.side} edge, where the crop cuts it`) : `${e.side} edge of this full-bleed photo`;
+    parts.push(`the subject ${strong ? "runs" : "likely runs"} off the ${where} (dense detail along ${pct(e.run)} of that edge, ${e.score}× the photo's average)`);
+    fixes.push(e.kind === "cut" ? `Move the crop off the subject (object-position toward the ${e.side === "left" ? "left" : e.side === "right" ? "right" : e.side}), or use a photo with the whole subject in frame` : `Use a photo whose subject sits away from the ${e.side} edge (or flip it), or stop the photo short of the screen edge`);
+  }
+  if (clear && subject.better && p.defaultPosition) {
+    const b = subject.better;
+    const val = b.axis === "x" ? `${b.pct}% 50%` : `50% ${b.pct}%`;
+    raise("warn");
+    parts.push(`its detail sits off-centre (centre of energy at ${b.axis === "x" ? `x ${pct(subject.centroid[0])}` : `y ${pct(subject.centroid[1])}`}) while the crop is centred; ${val} would keep ${pct(b.keptThen)} of it instead of ${pct(b.keptNow)}`);
+    fixes.push(`Set ${p.kind === "img" ? "object-position" : "background-position"}: ${val}`);
+  }
+  if (!sev) return null;
+  const backdrop = (p.behind ?? 0) >= BACKDROP;
+  if (backdrop) {
+    sev = "warn";
+    parts.push(`it is a backdrop (${pct(p.behind)} of it sits behind content), so this is a warning`);
+  }
+  return { id: "PHOTO_CROP", width, section: ref(p.section), severity: sev, what: `${name}: ${parts.join("; ")} (at ${p.box.w}×${p.box.h}, y=${p.box.y})`, fix: `${fixes.join(". ")}. Look at the source's edges, not just the crop.` };
+}
+
+// [{ id, width, section, severity, what, fix }] from page-craft.js's metrics at one width.
+export function craftChecks(metrics, { width = metrics?.width ?? 1440 } = {}) {
+  const checks = [];
+  if (!metrics || metrics.error) return checks;
+  const add = (id, severity, section, what, fix) => checks.push({ id, width, section: ref(section), severity, what, fix });
+
+  // PHOTO_CROP: one finding per photo, its worst problem deciding the severity.
+  for (const p of metrics.photos ?? []) {
+    const f = photoFinding(p, width);
+    if (f) checks.push(f);
+  }
+
+  // TEXT_CLIPPED_EFFECT: display or script ink cut by a clip.
+  for (const t of metrics.textClips ?? []) {
+    const sides = Object.entries(t.over).filter(([, v]) => v > 0.5).sort((a, b) => b[1] - a[1]);
+    add("TEXT_CLIPPED_EFFECT", "fail", t.section, `"${short(t.text, 32)}" (${t.family} ${t.fontSize}px${t.genre === "script" || t.genre === "display" ? `, ${t.genre}` : ""}) is cut by ${t.clip.kind}${t.clip.value ? ` (${t.clip.value})` : ""} on ${t.clip.on}: its glyphs reach ${list(sides.map(([k, v]) => `${v}px past the ${k}`))} of the clip`, t.clip.kind === "clip-path" ? "Keep clip-path reveals for photos; reveal text with opacity/transform, or give the clip room (clip-path: inset(-0.25em -0.15em)) so swashes, italics and descenders aren't cut." : t.clip.kind === "overflow" ? "Give the glyphs room: padding inside the clipping box (and a matching negative margin), or drop overflow: hidden around display text." : t.clip.kind === "mask" ? "Extend the mask beyond the text box (mask-size/position with room), or mask a wrapper with padding." : "Add padding to the gradient-text element (and a matching negative margin) so its background covers the swashes and descenders.");
+  }
+
+  // HYPHEN_BREAK: a heading or label broken at its hyphen (or inside a word).
+  for (const h of (metrics.hyphens ?? []).slice(0, 8)) {
+    const sev = width <= PHONE_MAX && h.fontSize >= DISPLAY_PX ? "fail" : "warn";
+    const word = h.word.slice(0, h.at) + "⏎" + h.word.slice(h.at);
+    add("HYPHEN_BREAK", sev, h.section, h.kind === "hyphen" ? `"${h.word}" breaks at its hyphen (${word}) in ${h.heading ? "a heading" : "a label"} at ${h.fontSize}px: "${short(h.text, 50)}"` : `"${h.word}" breaks inside the word (${word}) at ${h.fontSize}px: "${short(h.text, 50)}"`, h.kind === "hyphen" ? "Keep the compound on one line: a non-breaking hyphen (U+2011, &#8209;) or white-space: nowrap on the word; or a smaller size at this width, or reword." : "Let it break between words: a smaller size at this width, overflow-wrap: normal and hyphens: manual, or shorter words.");
+  }
+
+  // LABEL_WRAP: short labels on two lines. Buttons and tabs fail; one finding per section and kind.
+  const groups = new Map();
+  for (const w of metrics.wraps ?? []) {
+    const hard = w.role === "button" || w.role === "tab";
+    const k = `${w.section?.index ?? "-"}|${hard}`;
+    if (!groups.has(k)) groups.set(k, { hard, section: w.section, items: [] });
+    groups.get(k).items.push(w);
+  }
+  for (const g of groups.values()) {
+    const eg = g.items.slice(0, 4).map((w) => `"${w.text}" (${w.role === "label" ? w.tag : w.role}, ${w.width}px wide)`).join(", ");
+    const n = g.items.length;
+    add("LABEL_WRAP", g.hard ? "fail" : "warn", g.section, `${n} short ${g.hard ? (n > 1 ? "buttons/tabs" : g.items[0].role) : n > 1 ? "labels" : "label"} wrap${n > 1 ? "" : "s"} onto ${Math.max(...g.items.map((w) => w.lines))} lines: ${eg}`, g.hard ? "A button or tab label stays on one line: white-space: nowrap with room for it (shorter text, less padding, or let the row scroll or wrap as whole items)." : "Give the column room for its label (wider track, smaller gap), shorten the label, or set white-space: nowrap where it fits.");
+  }
+
+  // DOUBLE_NUMBERING: a numbered kicker over items numbered from 1.
+  for (const d of metrics.doubles ?? [])
+    add("DOUBLE_NUMBERING", "warn", d.section, `the numbered kicker "${short(d.kicker, 24)}" sits over ${d.list ? "an ordered list" : "items"} numbered ${d.items.slice(0, 3).join(", ")}${d.count > 3 ? "…" : ""} (${d.count})${d.sameLook ? ", in the same style" : ""}: two numberings at one level`, "Keep one numbering: drop the numbers from the list (bullets, or let order speak), or label the chapter with a word instead of a number.");
+
+  const rank = { fail: 0, warn: 1 };
+  return checks.sort((a, b) => rank[a.severity] - rank[b.severity]);
+}
+
+// Runs page-craft.js on an open page. Never throws: a measurement that failed comes back as { error }.
+export async function measureCraft(page, { sections = [] } = {}) {
+  try {
+    return await page.evaluate(`(${craftScript})(${JSON.stringify({ sections, genres: FONT_GENRES })})`);
+  } catch (e) {
+    return { error: String(e?.message ?? e).split("\n")[0].slice(0, 200) };
+  }
+}