font-lab 0.1.0

package/catalog-build.mjs

@@ -0,0 +1,126 @@
+// generateCatalog — the reusable parity-bundle builder (M5 extraction of gen-catalog's core).
+//
+// Given a project dir and a set of directions (curated OR agent-composed — both validated
+// against the catalog), it self-hosts each font's Google variable woff2, computes next/font's
+// exact adjusted fallback (M0-proven parity), and writes the generated module the dev panel
+// imports plus the woff2 into the project's public/fontlab/. Pure of policy — WHICH directions
+// to build is the caller's choice (the curator default, or the agent's own composition).
+
+import { execFileSync } from "node:child_process";
+import { writeFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { get as catalogGet } from "./catalog.mjs";
+import { fontsForDirections } from "./curator.mjs";
+
+const UA = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0 Safari/537.36";
+const slug = (family) => family.toLowerCase().replace(/[^a-z0-9]+/g, "-");
+const pct = (n) => `${(Math.abs(n) * 100).toFixed(2)}%`;
+const generic = (cat) => (cat === "serif" ? "serif" : cat === "monospace" ? "monospace" : "sans-serif");
+
+const metricsFor = async (s) => (await import("@capsizecss/metrics/" + s)).default;
+
+// next/font's adjusted-fallback descriptors for `main` measured against `fallback`.
+function overrides(main, fallback) {
+  const sizeAdjust = main.xWidthAvg / main.unitsPerEm / (fallback.xWidthAvg / fallback.unitsPerEm);
+  return {
+    sizeAdjust: pct(sizeAdjust),
+    ascent: pct(main.ascent / (main.unitsPerEm * sizeAdjust)),
+    descent: pct(main.descent / (main.unitsPerEm * sizeAdjust)),
+    lineGap: pct(main.lineGap / (main.unitsPerEm * sizeAdjust)),
+  };
+}
+
+/**
+ * Build the parity catalog for `directions` into `projectDir`.
+ * @param projectDir  absolute path to the Next.js project (panel lives at app/_fontlab/)
+ * @param directions  the directions to render (each role family MUST be a catalog member)
+ * @param meta        { target, replaces } baked into the generated module (from the analyzer)
+ * @param opts        { log?: (msg)=>void, fetch?: boolean }  fetch:false skips network (test)
+ * @returns { fonts, directions, outPath }
+ */
+export async function generateCatalog(projectDir, directions, meta = {}, opts = {}) {
+  const log = opts.log || (() => {});
+  const APP = projectDir.replace(/\/?$/, "/");
+  const PUBLIC = APP + "public/fontlab/";
+  mkdirSync(PUBLIC, { recursive: true });
+
+  const arial = await metricsFor("arial");
+  const timesNewRoman = await metricsFor("timesNewRoman");
+
+  const faceCss = [];
+  const stacks = {};
+  const families = fontsForDirections(directions);
+
+  for (const family of families) {
+    const spec = catalogGet(family); // throws if not a verified catalog member
+
+    if (opts.fetch !== false) {
+      const css = execFileSync("curl", ["-sSL", "-A", UA, `https://fonts.googleapis.com/css2?family=${spec.css2}&display=swap`], { encoding: "utf8" });
+      const m = css.match(/\/\* latin \*\/\s*@font-face\s*\{[^}]*?url\((https:[^)]+\.woff2)\)/);
+      if (!m) throw new Error(`Could not find latin woff2 for "${family}"`);
+      execFileSync("curl", ["-sSL", "-A", UA, "-o", PUBLIC + slug(family) + ".woff2", m[1]]);
+    }
+
+    const main = await metricsFor(spec.capsize);
+    const isSerif = main.category === "serif";
+    const fb = isSerif ? timesNewRoman : arial;
+    const fbName = isSerif ? "Times New Roman" : "Arial";
+    const o = overrides(main, fb);
+
+    faceCss.push(
+      `@font-face{font-family:'FL ${family}';font-style:normal;font-weight:100 900;font-display:swap;src:url('/fontlab/${slug(family)}.woff2') format('woff2');}`,
+      `@font-face{font-family:'FL ${family} Fallback';src:local('${fbName}');size-adjust:${o.sizeAdjust};ascent-override:${o.ascent};descent-override:${o.descent};line-gap-override:${o.lineGap};}`,
+    );
+    stacks[family] = `'FL ${family}', 'FL ${family} Fallback', ${generic(main.category)}`;
+    log(`  ${family.padEnd(20)} -> ${slug(family)}.woff2  (fallback ${fbName}, size-adjust ${o.sizeAdjust})`);
+  }
+
+  const outDirections = directions.map((d) => ({
+    id: d.id,
+    name: d.name,
+    vibe: d.vibe,
+    rationale: d.rationale,
+    roles: Object.fromEntries(
+      Object.entries(d.roles).map(([role, r]) => [role, { family: r.family, source: "google", weights: r.weights, stack: stacks[r.family] }]),
+    ),
+  }));
+
+  const ts = `// AUTO-GENERATED by cli/gen-catalog.mjs — do not edit by hand.
+import type { CSSProperties } from "react";
+
+export const catalogFontFaceCss = ${JSON.stringify("\n" + faceCss.join("\n") + "\n")};
+
+export const target = ${JSON.stringify(meta.target ?? null, null, 2)} as const;
+export const replaces = ${JSON.stringify(meta.replaces ?? null, null, 2)} as const;
+
+// Per-role preview swap target (M5/M6): which leaf var to override and on which element. The
+// portable panel reads this so the live swap is honest on any site. null = unswappable role.
+export const wiring = ${JSON.stringify(meta.wiring ?? null, null, 2)} as const;
+
+export type Role = "display" | "body" | "mono";
+export type RoleFont = { family: string; source: string; weights: number[]; stack: string };
+export type Direction = {
+  id: string;
+  name: string;
+  vibe: string;
+  rationale: string;
+  roles: Record<Role, RoleFont>;
+};
+
+export const directions: Direction[] = ${JSON.stringify(outDirections, null, 2)};
+
+// CSS-variable overrides a direction applies on :root (the swap mechanism, M0-proven).
+export function directionVars(d: Direction): CSSProperties {
+  return {
+    "--fl-display": d.roles.display.stack,
+    "--fl-sans": d.roles.body.stack,
+    "--fl-mono": d.roles.mono.stack,
+  } as CSSProperties;
+}
+`;
+
+  const outPath = path.join(APP, "app/_fontlab/catalog.generated.ts");
+  mkdirSync(path.dirname(outPath), { recursive: true });
+  writeFileSync(outPath, ts);
+  return { fonts: families, directions: outDirections, outPath };
+}

package/catalog.mjs

@@ -0,0 +1,79 @@
+// Font Lab catalog (M4) — the parity asset, not a taste moat (see ARCHITECTURE.md).
+//
+// Each entry is a font we can ship with the WYSIWYG guarantee intact. Membership is gated on
+// two hard requirements, both verified:
+//   1. **Capsize coverage** — `@capsizecss/metrics/<capsize>` resolves, so we can compute
+//      next/font's exact adjusted-fallback metrics (CLS-safe, identical to ship). Uncovered
+//      fonts throw "Failed to find font override values" at build — a hard gate.
+//   2. **Variable font** — a single latin woff2 spans the whole weight range, so preview and
+//      ship use the *same bytes* with no per-weight files and no `weight` arg (which would
+//      fork next/font off the variable file and break parity). The `css2` query below was
+//      auto-discovered and confirmed to return a weight-RANGE latin face.
+//
+// `roles` = which slots a family is suited to (display / body / mono). `tags` = vibe lookup
+// keys the curator selects on. Pure data; `cli/m4-test.mjs` re-verifies coverage for all.
+
+export const catalog = {
+  // ── sans — workhorse body / UI (some double as display) ──────────────────
+  Inter: { capsize: "inter", css2: "Inter:wght@100..900", roles: ["body", "display"], tags: ["neutral", "ui", "modern"] },
+  Geist: { capsize: "geist", css2: "Geist:wght@100..900", roles: ["body", "display"], tags: ["geometric", "minimal", "modern"] },
+  Figtree: { capsize: "figtree", css2: "Figtree:wght@300..700", roles: ["body", "display"], tags: ["geometric", "friendly", "modern"] },
+  "Hanken Grotesk": { capsize: "hankenGrotesk", css2: "Hanken+Grotesk:wght@100..900", roles: ["body", "display"], tags: ["humanist", "warm", "readable"] },
+  "Libre Franklin": { capsize: "libreFranklin", css2: "Libre+Franklin:wght@100..900", roles: ["body"], tags: ["grotesque", "classic", "readable"] },
+  "Work Sans": { capsize: "workSans", css2: "Work+Sans:wght@100..900", roles: ["body", "display"], tags: ["grotesque", "neutral", "readable"] },
+  "Plus Jakarta Sans": { capsize: "plusJakartaSans", css2: "Plus+Jakarta+Sans:wght@200..800", roles: ["body", "display"], tags: ["geometric", "friendly", "modern"] },
+  Manrope: { capsize: "manrope", css2: "Manrope:wght@200..800", roles: ["body", "display"], tags: ["geometric", "minimal", "modern"] },
+  "DM Sans": { capsize: "dMSans", css2: "DM+Sans:wght@100..900", roles: ["body", "display"], tags: ["geometric", "minimal", "friendly"] },
+  Onest: { capsize: "onest", css2: "Onest:wght@100..900", roles: ["body", "display"], tags: ["neutral", "modern", "readable"] },
+  "Source Sans 3": { capsize: "sourceSans3", css2: "Source+Sans+3:wght@200..800", roles: ["body"], tags: ["humanist", "neutral", "readable"] },
+  "Public Sans": { capsize: "publicSans", css2: "Public+Sans:wght@100..900", roles: ["body"], tags: ["grotesque", "neutral", "readable"] },
+  "Albert Sans": { capsize: "albertSans", css2: "Albert+Sans:wght@100..900", roles: ["body", "display"], tags: ["geometric", "modern", "friendly"] },
+  Sora: { capsize: "sora", css2: "Sora:wght@200..800", roles: ["body", "display"], tags: ["geometric", "technical", "modern"] },
+  Outfit: { capsize: "outfit", css2: "Outfit:wght@100..900", roles: ["body", "display"], tags: ["geometric", "minimal", "modern"] },
+  "Mona Sans": { capsize: "monaSans", css2: "Mona+Sans:wght@200..800", roles: ["body", "display"], tags: ["grotesque", "modern", "technical"] },
+  "Instrument Sans": { capsize: "instrumentSans", css2: "Instrument+Sans:wght@400..700", roles: ["body", "display"], tags: ["grotesque", "modern", "neutral"] },
+  Epilogue: { capsize: "epilogue", css2: "Epilogue:wght@100..900", roles: ["body", "display"], tags: ["geometric", "modern", "technical"] },
+  "Red Hat Display": { capsize: "redHatDisplay", css2: "Red+Hat+Display:wght@300..700", roles: ["display", "body"], tags: ["geometric", "technical", "modern"] },
+
+  // ── sans — display grotesques (heading-forward) ──────────────────────────
+  "Bricolage Grotesque": { capsize: "bricolageGrotesque", css2: "Bricolage+Grotesque:wght@200..800", roles: ["display"], tags: ["grotesque", "characterful", "editorial"] },
+  "Space Grotesk": { capsize: "spaceGrotesk", css2: "Space+Grotesk:wght@300..700", roles: ["display"], tags: ["grotesque", "technical", "characterful"] },
+  "Familjen Grotesk": { capsize: "familjenGrotesk", css2: "Familjen+Grotesk:wght@400..700", roles: ["display"], tags: ["grotesque", "modern", "characterful"] },
+  Archivo: { capsize: "archivo", css2: "Archivo:wght@100..900", roles: ["display", "body"], tags: ["grotesque", "technical", "bold"] },
+  Syne: { capsize: "syne", css2: "Syne:wght@400..700", roles: ["display"], tags: ["expressive", "bold", "editorial"] },
+  Unbounded: { capsize: "unbounded", css2: "Unbounded:wght@200..800", roles: ["display"], tags: ["expressive", "bold", "funky"] },
+  "Darker Grotesque": { capsize: "darkerGrotesque", css2: "Darker+Grotesque:wght@300..700", roles: ["display"], tags: ["expressive", "characterful", "editorial"] },
+  Gabarito: { capsize: "gabarito", css2: "Gabarito:wght@400..900", roles: ["display"], tags: ["friendly", "rounded", "bold"] },
+
+  // ── serif — display + editorial body ─────────────────────────────────────
+  Fraunces: { capsize: "fraunces", css2: "Fraunces:opsz,wght@9..40,100..900", roles: ["display", "body"], tags: ["serif", "editorial", "warm", "characterful"] },
+  Newsreader: { capsize: "newsreader", css2: "Newsreader:opsz,wght@10..72,300..700", roles: ["body", "display"], tags: ["serif", "editorial", "classic", "readable"] },
+  "Source Serif 4": { capsize: "sourceSerif4", css2: "Source+Serif+4:wght@200..800", roles: ["body", "display"], tags: ["serif", "classic", "readable"] },
+  Lora: { capsize: "lora", css2: "Lora:wght@400..700", roles: ["body", "display"], tags: ["serif", "warm", "readable", "classic"] },
+  "Playfair Display": { capsize: "playfairDisplay", css2: "Playfair+Display:wght@400..900", roles: ["display"], tags: ["serif", "elegant", "editorial", "contrast"] },
+  Bitter: { capsize: "bitter", css2: "Bitter:wght@100..900", roles: ["body", "display"], tags: ["serif", "slab", "readable"] },
+  "Crimson Pro": { capsize: "crimsonPro", css2: "Crimson+Pro:wght@200..800", roles: ["body", "display"], tags: ["serif", "classic", "editorial", "readable"] },
+  Cormorant: { capsize: "cormorant", css2: "Cormorant:wght@300..700", roles: ["display"], tags: ["serif", "elegant", "contrast", "editorial"] },
+
+  // ── mono — code / labels ─────────────────────────────────────────────────
+  "JetBrains Mono": { capsize: "jetBrainsMono", css2: "JetBrains+Mono:wght@200..800", roles: ["mono"], tags: ["mono", "technical", "neutral"] },
+  "Geist Mono": { capsize: "geistMono", css2: "Geist+Mono:wght@100..900", roles: ["mono"], tags: ["mono", "minimal", "modern"] },
+  "Roboto Mono": { capsize: "robotoMono", css2: "Roboto+Mono:wght@300..700", roles: ["mono"], tags: ["mono", "neutral", "classic"] },
+  "Source Code Pro": { capsize: "sourceCodePro", css2: "Source+Code+Pro:wght@200..800", roles: ["mono"], tags: ["mono", "neutral", "readable"] },
+  "Fira Code": { capsize: "firaCode", css2: "Fira+Code:wght@300..700", roles: ["mono"], tags: ["mono", "technical", "ligatures"] },
+  "Spline Sans Mono": { capsize: "splineSansMono", css2: "Spline+Sans+Mono:wght@300..700", roles: ["mono"], tags: ["mono", "modern", "friendly"] },
+};
+
+export const families = Object.keys(catalog);
+
+export function inCatalog(family) {
+  return Object.prototype.hasOwnProperty.call(catalog, family);
+}
+
+// Look up a family, throwing a clear error if it isn't a catalog member (curator authoring
+// guard — a typo'd family must fail loudly, not ship a broken bundle).
+export function get(family) {
+  const e = catalog[family];
+  if (!e) throw new Error(`"${family}" is not in the Font Lab catalog (no verified parity bundle)`);
+  return e;
+}

package/codegen.mjs

@@ -0,0 +1,399 @@
+// Font Lab codegen (M2 + M3) — turn .font-lab/selection.json into real, reversible
+// next/font + Tailwind edits, with the analyzer (M3) choosing the branch so codegen never
+// guesses. Strategy per SHIP-SPEC.md:
+//   • ts-morph for the AST-sensitive bits: merge the next/font import, rewrite the <html>
+//     (or <body>) className, and either replace or adopt the consts we're swapping;
+//   • fenced markers for the append-only regions (the generated font consts in layout.tsx
+//     and the @theme block in globals.css) — trivially find/replace/remove, so re-apply is
+//     byte-idempotent and undo is exact;
+//   • backup-first undo that needs nothing of the user (no clean tree, no git).
+//
+// Two wiring shapes, both now handled (the analyzer says which applies per role):
+//   • ROLE-VAR — a font const lives on a role variable (`--font-sans`) or the role is empty.
+//     We replace/create a Font-Lab const on that role var (the M2 path; jack's missing mono).
+//   • ADOPT — a font const lives on the project's own variable (`--font-bricolage`) wired to
+//     a role through `@theme inline`. We rewrite that const's family IN PLACE, keeping its
+//     variable, name, and className token — a minimal diff that leaves the project's own
+//     wiring intact (SHIP-SPEC "adopt an existing variable rather than introduce a competitor").
+//
+// Scope gate: App Router + Tailwind v4 + CSS-variable wiring. The analyzer enforces it.
+
+import { Project, Node, SyntaxKind, QuoteKind } from "ts-morph";
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, existsSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { analyzeProject } from "./analyzer.mjs";
+
+const ROLE_VARS = { display: "--font-display", body: "--font-sans", mono: "--font-mono" };
+const ROLE_VAR_SET = new Set(Object.values(ROLE_VARS));
+const cap = (s) => s[0].toUpperCase() + s.slice(1);
+const constName = (role) => "fontLab" + cap(role);
+const importName = (family) => family.replace(/[^A-Za-z0-9]+/g, "_");
+const sha = (buf) => createHash("sha256").update(buf).digest("hex");
+
+function resolveTargets(projectDir) {
+  const appDir = ["app", "src/app"]
+    .map((d) => path.join(projectDir, d))
+    .find((d) => existsSync(path.join(d, "layout.tsx")));
+  if (!appDir) throw new Error("could not find app/layout.tsx (App Router only for now)");
+  const layout = path.join(appDir, "layout.tsx");
+  const css = ["globals.css", "global.css"].map((f) => path.join(appDir, f)).find(existsSync);
+  if (!css) throw new Error("could not find app/globals.css");
+  return { layout, css };
+}
+
+// ---- layout.tsx: AST bits (import + className + replace/adopt consts) -------
+
+function getStringProp(obj, name) {
+  const p = obj.getProperty(name);
+  if (!p || !Node.isPropertyAssignment(p)) return null;
+  const init = p.getInitializer();
+  if (!init) return null;
+  if (Node.isStringLiteral(init) || Node.isNoSubstitutionTemplateLiteral(init)) return init.getLiteralValue();
+  return init.getText().replace(/^["'`]|["'`]$/g, "");
+}
+
+// Find the element (preferring the analyzer's choice) that wears the font variables.
+function findClassTarget(sf, preferred) {
+  const els = [
+    ...sf.getDescendantsOfKind(SyntaxKind.JsxOpeningElement),
+    ...sf.getDescendantsOfKind(SyntaxKind.JsxSelfClosingElement),
+  ];
+  const byTag = (tag) => els.find((e) => e.getTagNameNode().getText() === tag);
+  return (preferred && byTag(preferred)) || byTag("html") || byTag("body") || null;
+}
+
+function classNameTokens(attr) {
+  const dynamic = [];
+  const statics = [];
+  const init = attr?.getInitializer();
+  if (!init) return { dynamic, statics };
+  if (Node.isJsxExpression(init)) {
+    const expr = init.getExpression();
+    if (!expr) return { dynamic, statics };
+    if (Node.isTemplateExpression(expr)) {
+      statics.push(...expr.getHead().getLiteralText().split(/\s+/).filter(Boolean));
+      for (const span of expr.getTemplateSpans()) {
+        dynamic.push(span.getExpression().getText());
+        statics.push(...span.getLiteral().getLiteralText().split(/\s+/).filter(Boolean));
+      }
+    } else if (Node.isNoSubstitutionTemplateLiteral(expr) || Node.isStringLiteral(expr)) {
+      statics.push(...expr.getLiteralValue().split(/\s+/).filter(Boolean));
+    } else {
+      dynamic.push(expr.getText());
+    }
+  } else if (Node.isStringLiteral(init)) {
+    statics.push(...init.getLiteralValue().split(/\s+/).filter(Boolean));
+  }
+  return { dynamic, statics };
+}
+
+function buildClassNameInit(dynamic, statics) {
+  if (dynamic.length === 0) return `"${statics.join(" ")}"`;
+  const dyn = dynamic.map((d) => "${" + d + "}").join(" ");
+  const stat = statics.length ? " " + statics.join(" ") : "";
+  return "{`" + dyn + stat + "`}";
+}
+
+function editLayoutAst(sf, roles, classTarget) {
+  // 1) ensure the next/font/google import carries every new family.
+  let imp = sf.getImportDeclaration((d) => d.getModuleSpecifierValue() === "next/font/google");
+  if (!imp) imp = sf.addImportDeclaration({ moduleSpecifier: "next/font/google", namedImports: [] });
+  const named = new Set(imp.getNamedImports().map((n) => n.getName()));
+  for (const r of roles)
+    if (!named.has(r.importName)) {
+      imp.addNamedImport(r.importName);
+      named.add(r.importName);
+    }
+
+  const replaced = [];
+  const oldImports = new Set();
+
+  // 2a) ADOPT — rewrite the existing const's family in place, keep its variable/name.
+  for (const r of roles.filter((r) => r.mode === "adopt")) {
+    const vd = sf.getVariableDeclaration(r.constName);
+    const init = vd?.getInitializer();
+    if (!init || !Node.isCallExpression(init)) continue;
+    const callee = init.getExpression();
+    const old = callee.getText();
+    if (old !== r.importName) {
+      replaced.push({ variable: r.adoptVar, font: old });
+      oldImports.add(old);
+      callee.replaceWithText(r.importName);
+    }
+  }
+
+  // 2b) ROLE-VAR — remove existing non-Font-Lab consts sitting on a role var (the ones we
+  //     replace). Font Lab's own consts live in a fenced block managed as text — never here.
+  const removeNames = [];
+  for (const vd of sf.getVariableDeclarations()) {
+    if (vd.getName().startsWith("fontLab")) continue;
+    const init = vd.getInitializer();
+    if (!init || !Node.isCallExpression(init)) continue;
+    const obj = init.getArguments()[0];
+    const varVal = obj && Node.isObjectLiteralExpression(obj) ? getStringProp(obj, "variable") : null;
+    if (varVal && ROLE_VAR_SET.has(varVal)) {
+      removeNames.push(vd.getName());
+      replaced.push({ variable: varVal, font: init.getExpression().getText() });
+      oldImports.add(init.getExpression().getText());
+      vd.getVariableStatementOrThrow().remove();
+    }
+  }
+
+  // 3) className: drop the removed role-var consts' tokens, add a token for every role-var
+  //    role. Adopted roles already carry their token and we leave it untouched.
+  const el = findClassTarget(sf, classTarget);
+  if (!el) throw new Error(`no <${classTarget || "html"}> element in layout.tsx`);
+  const attr = el.getAttribute("className");
+  const { dynamic, statics } = classNameTokens(attr);
+  const kept = dynamic.filter((d) => !removeNames.some((n) => d === n || d.startsWith(n + ".")));
+  for (const r of roles.filter((r) => r.mode === "rolevar")) {
+    const token = `${r.constName}.variable`;
+    if (!kept.includes(token)) kept.push(token);
+  }
+  const initText = buildClassNameInit(kept, statics);
+  if (attr) attr.setInitializer(initText);
+  else el.addAttribute({ name: "className", initializer: initText });
+
+  // 4) drop now-unused imports for replaced/adopted fonts — never one a role still needs.
+  const roleImports = new Set(roles.map((r) => r.importName));
+  for (const callee of oldImports) {
+    if (roleImports.has(callee)) continue;
+    const stillUsed = sf
+      .getDescendantsOfKind(SyntaxKind.Identifier)
+      .some((id) => id.getText() === callee && !Node.isImportSpecifier(id.getParent()));
+    if (!stillUsed) imp.getNamedImports().find((n) => n.getName() === callee)?.remove();
+  }
+
+  return { replaced };
+}
+
+// ---- layout.tsx: fenced const block (text, idempotent) ---------------------
+// Only role-var roles need a generated const; adopted roles are rewritten above.
+
+function setFencedConsts(text, roles) {
+  const rv = roles.filter((r) => r.mode === "rolevar");
+  const strip = (t) => t.replace(/\n*\/\/ font-lab:start[\s\S]*?\/\/ font-lab:end\n*/g, "\n\n");
+  if (!rv.length) return strip(text);
+  const lines = [
+    "// font-lab:start",
+    "// generated — re-run `font-lab apply` to update, `font-lab undo` to revert",
+    ...rv.map(
+      (r) => `const ${r.constName} = ${r.importName}({ subsets: ["latin"], display: "swap", variable: "${r.varName}" });`,
+    ),
+    "// font-lab:end",
+  ];
+  const block = lines.join("\n");
+  text = strip(text);
+  // Match import statements with or without a trailing semicolon (Prettier `semi: false`
+  // projects — e.g. jack-mcgovern.com — write `import x from 'y'` with no `;`).
+  const importRe = /^import\s[^\n]*$/gm;
+  let last = 0;
+  let m;
+  while ((m = importRe.exec(text))) last = m.index + m[0].length;
+  const before = text.slice(0, last).replace(/\s*$/, "");
+  const after = text.slice(last).replace(/^\s*/, "");
+  return `${before}\n\n${block}\n\n${after}`;
+}
+
+function verifyLayout(sf, roles, classTarget) {
+  for (const r of roles) {
+    const vd = sf.getVariableDeclaration(r.constName);
+    if (!vd) throw new Error(`verify: missing const ${r.constName}`);
+    if (r.mode === "adopt") {
+      const callee = vd.getInitializer()?.getExpression?.().getText();
+      if (callee !== r.importName) throw new Error(`verify: ${r.constName} not rewritten to ${r.importName}`);
+    }
+  }
+  const { dynamic } = classNameTokens(findClassTarget(sf, classTarget)?.getAttribute("className"));
+  for (const r of roles) {
+    if (!dynamic.includes(`${r.constName}.variable`)) throw new Error(`verify: <${classTarget}> missing ${r.constName}.variable`);
+  }
+}
+
+// ---- globals.css (fenced markers) ------------------------------------------
+// Only role-var roles need a @theme mapping; adopted roles reuse the project's existing one.
+
+function editCss(cssPath, roles) {
+  const rv = roles.filter((r) => r.mode === "rolevar");
+  let css = readFileSync(cssPath, "utf8");
+  const re = /\/\* font-lab:start \*\/[\s\S]*?\/\* font-lab:end \*\//;
+  if (!rv.length) {
+    if (re.test(css)) writeFileSync(cssPath, css.replace(/\n*\/\* font-lab:start \*\/[\s\S]*?\/\* font-lab:end \*\/\n*/, "\n"));
+    return;
+  }
+  const block = `/* font-lab:start */
+@theme inline {
+${rv.map((r) => `  ${r.varName}: var(${r.varName});`).join("\n")}
+}
+/* font-lab:end */`;
+  if (re.test(css)) css = css.replace(re, block);
+  else if (/@import\s+["']tailwindcss["'];/.test(css)) css = css.replace(/(@import\s+["']tailwindcss["'];\n?)/, `$1\n${block}\n`);
+  else css = `${block}\n${css}`;
+  writeFileSync(cssPath, css);
+}
+
+// ---- backups / apply / undo ------------------------------------------------
+
+function backup(projectDir, files) {
+  const flDir = path.join(projectDir, ".font-lab");
+  const runId = new Date().toISOString().replace(/[:.]/g, "-");
+  const dir = path.join(flDir, "backups", runId);
+  const manifest = { runId, git: null, files: [] };
+  for (const f of files) {
+    const rel = path.relative(projectDir, f);
+    const dest = path.join(dir, rel);
+    mkdirSync(path.dirname(dest), { recursive: true });
+    copyFileSync(f, dest);
+    manifest.files.push({ path: rel, sha256: sha(readFileSync(f)) });
+  }
+  try {
+    manifest.git = execFileSync("git", ["-C", projectDir, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+  } catch {}
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, "manifest.json"), JSON.stringify(manifest, null, 2));
+  writeFileSync(path.join(flDir, "backups", "latest.txt"), runId);
+  return { dir, runId };
+}
+
+function restore(projectDir, backupDir) {
+  const manifest = JSON.parse(readFileSync(path.join(backupDir, "manifest.json"), "utf8"));
+  for (const f of manifest.files) copyFileSync(path.join(backupDir, f.path), path.join(projectDir, f.path));
+}
+
+// Decide per-role whether to adopt the project's existing wiring or write a role-var const.
+function planRoles(selection, analysis) {
+  return ["display", "body", "mono"].map((role) => {
+    const family = selection.roles[role].family;
+    const existing = analysis.roles[role];
+    const adopt = existing && existing.nextFontVar && !ROLE_VAR_SET.has(existing.nextFontVar);
+    return adopt
+      ? {
+          role,
+          family,
+          importName: importName(family),
+          mode: "adopt",
+          constName: existing.constName,
+          adoptVar: existing.nextFontVar,
+        }
+      : {
+          role,
+          family,
+          importName: importName(family),
+          mode: "rolevar",
+          constName: constName(role),
+          varName: ROLE_VARS[role],
+        };
+  });
+}
+
+export function applySelection(projectDir) {
+  const selPath = path.join(projectDir, ".font-lab", "selection.json");
+  if (!existsSync(selPath)) throw new Error(`no selection at ${selPath} — pick one first`);
+  const selection = JSON.parse(readFileSync(selPath, "utf8"));
+
+  // M3: the analyzer picks the branch; codegen refuses anything it can't ship cleanly.
+  const analysis = analyzeProject(projectDir);
+  if (!analysis.supported)
+    throw new Error(`project not supported by codegen yet: ${analysis.reasons.join("; ")}`);
+
+  const { layout, css } = resolveTargets(projectDir);
+  const classTarget = analysis.classNameTarget || "html";
+  const roles = planRoles(selection, analysis);
+
+  const { dir: backupDir, runId } = backup(projectDir, [layout, css]);
+
+  // 1) AST edits (import + className + replace/adopt consts), then save.
+  const project = new Project({ manipulationSettings: { quoteKind: QuoteKind.Double, useTrailingCommas: false } });
+  const sf = project.addSourceFileAtPath(layout);
+  const { replaced } = editLayoutAst(sf, roles, classTarget);
+  sf.saveSync();
+
+  // 2) Fenced const block (text) + the CSS @theme block — role-var roles only.
+  writeFileSync(layout, setFencedConsts(readFileSync(layout, "utf8"), roles));
+  editCss(css, roles);
+
+  // 3) Verify; on failure restore the backup so the tree is never left half-edited.
+  try {
+    const vsf = new Project().addSourceFileAtPath(layout);
+    verifyLayout(vsf, roles, classTarget);
+  } catch (e) {
+    restore(projectDir, backupDir);
+    throw new Error(`apply aborted (${e.message}); restored from backup`);
+  }
+
+  // 4) Record post-apply hashes so undo can warn if the user edited since.
+  const manifestPath = path.join(backupDir, "manifest.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  for (const f of manifest.files) f.appliedSha256 = sha(readFileSync(path.join(projectDir, f.path)));
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  return {
+    runId,
+    direction: selection.direction,
+    roles: roles.map((r) => ({ role: r.role, family: r.family, mode: r.mode })),
+    replaced,
+    classTarget,
+    edited: [path.relative(projectDir, layout), path.relative(projectDir, css)],
+    backupDir: path.relative(projectDir, backupDir),
+  };
+}
+
+// Rewire dead roles — fix a role the analyzer flags as declared-but-not-rendered. Under
+// Tailwind v4 `@theme inline`, a hand-written `font-family: var(--font-display)` resolves to
+// nothing (the theme var isn't published to :root). The fix: point those raw usages at the
+// PUBLISHED leaf var the next/font const actually sets (e.g. var(--font-bricolage)), which is
+// inherited wherever the font is used. Minimal, backup-first, reversible — and it makes both
+// the live preview and the shipped swap visible on that role. Opt-in (we never auto-edit a
+// user's base styles during a normal apply).
+export function rewireCoverage(projectDir) {
+  const analysis = analyzeProject(projectDir);
+  const dead = analysis.coverage?.deadRoles || [];
+  const { css } = resolveTargets(projectDir);
+  if (!dead.length) return { rewired: [], dead, note: "no dead roles to rewire" };
+
+  // protect @theme blocks (their `--font-display: var(--font-x)` definitions stay as-is)
+  let text = readFileSync(css, "utf8");
+  const blocks = [];
+  let work = text.replace(/@theme(\s+inline)?\s*\{[^}]*\}/g, (m) => `__FLTHEME${blocks.push(m) - 1}__`);
+
+  const rewired = [];
+  for (const role of dead) {
+    const roleVar = ROLE_VARS[role];
+    const leaf = analysis.roles[role]?.nextFontVar;
+    if (!leaf) continue;
+    let n = 0;
+    work = work.replace(new RegExp(`var\\(\\s*${roleVar}\\s*\\)`, "g"), () => (n++, `var(${leaf})`));
+    if (n) rewired.push({ role, from: roleVar, to: leaf, count: n });
+  }
+  work = work.replace(/__FLTHEME(\d+)__/g, (_, i) => blocks[Number(i)]);
+  if (!rewired.length) return { rewired: [], dead, note: "dead roles found, but no raw var() usages to rewire" };
+
+  const { dir: backupDir, runId } = backup(projectDir, [css]);
+  writeFileSync(css, work);
+  const manifestPath = path.join(backupDir, "manifest.json");
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  for (const f of manifest.files) f.appliedSha256 = sha(readFileSync(path.join(projectDir, f.path)));
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+
+  return { runId, rewired, edited: [path.relative(projectDir, css)], backupDir: path.relative(projectDir, backupDir) };
+}
+
+export function undo(projectDir) {
+  const flDir = path.join(projectDir, ".font-lab");
+  const latest = path.join(flDir, "backups", "latest.txt");
+  if (!existsSync(latest)) throw new Error("nothing to undo (no backups)");
+  const runId = readFileSync(latest, "utf8").trim();
+  const dir = path.join(flDir, "backups", runId);
+  const manifest = JSON.parse(readFileSync(path.join(dir, "manifest.json"), "utf8"));
+  const warnings = [];
+  for (const f of manifest.files) {
+    const target = path.join(projectDir, f.path);
+    if (f.appliedSha256 && existsSync(target) && sha(readFileSync(target)) !== f.appliedSha256) {
+      warnings.push(`${f.path} was modified since apply — restoring anyway`);
+    }
+  }
+  restore(projectDir, dir);
+  return { runId, restored: manifest.files.map((f) => f.path), warnings };
+}

package/curate.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+// `font-lab curate` — preview the directions Font Lab would offer a project (M4). Read-only.
+//   node cli/curate.mjs [--project <dir>] [--vibe <vibe>] [--count <n>] [--json]
+import path from "node:path";
+import { analyzeProject } from "./analyzer.mjs";
+import { curate } from "./curator.mjs";
+
+const arg = (f, d) => {
+  const i = process.argv.indexOf(f);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : d;
+};
+const project = path.resolve(arg("--project", process.cwd()));
+const analysis = analyzeProject(project);
+const dirs = curate(analysis, { vibe: arg("--vibe", undefined), count: Number(arg("--count", "5")) });
+
+if (process.argv.includes("--json")) {
+  console.log(JSON.stringify(dirs, null, 2));
+} else {
+  const cur = analysis.replaces;
+  console.log(`Font Lab — ${dirs.length} directions for ${path.relative(process.cwd(), project) || "."}`);
+  console.log(`  current: ${cur.display ?? "—"} / ${cur.body ?? "—"} / ${cur.mono ?? "—"}\n`);
+  for (const d of dirs) {
+    console.log(`  ${d.name}  ·  ${d.vibe}`);
+    console.log(`    ${d.roles.display.family} / ${d.roles.body.family} / ${d.roles.mono.family}`);
+    console.log(`    ${d.rationale}\n`);
+  }
+}