font-lab 0.1.0

package/init.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// `font-lab init` — make a real project previewable: scaffold the dev panel + parity bundles
+// and mount the panel (dev-only) in the layout. Reversible with `--undo`. Thin CLI over
+// engine.init / engine.uninit (the same code the MCP server's font_lab_init tool uses).
+//
+//   node cli/init.mjs --project <dir> [--vibe <v>] [--count <n>] [--no-fetch]
+//   node cli/init.mjs --project <dir> --undo
+
+import path from "node:path";
+import * as engine from "./engine.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 rel = (p) => path.relative(process.cwd(), p) || ".";
+
+try {
+  if (process.argv.includes("--undo")) {
+    const r = engine.uninit(PROJECT);
+    console.log(`Font Lab — uninstalled (restored ${r.restored}, removed ${r.removed.join(" + ")})`);
+  } else {
+    const r = await engine.init(PROJECT, {
+      vibe: arg("--vibe", undefined),
+      count: Number(arg("--count", "5")),
+      fetch: !process.argv.includes("--no-fetch"),
+      log: (m) => console.log(m),
+    });
+    console.log(`\nFont Lab — initialized ${rel(PROJECT)}`);
+    console.log(`  directions  ${r.directions.map((d) => d.name).join(", ")}`);
+    console.log(`  wiring      ${["display", "body", "mono"].map((role) => `${role}:${r.wiring[role] ? r.wiring[role].var + "@" + r.wiring[role].el : "—"}`).join("  ")}`);
+    if (r.deadRoles.length) console.log(`  note        ${r.deadRoles.join(", ")} won't preview (dead on this site — \`font-lab rewire\` fixes it)`);
+    console.log(`  panel       ${r.mounted ? "mounted in" : "already in"} ${r.layout} (dev only)`);
+    console.log(`\n  next:  run your dev server, then \`node cli/font-lab.mjs --project ${rel(PROJECT)}\` — flip, Pick, then \`node cli/apply.mjs\`.`);
+    console.log(`         undo:  \`node cli/init.mjs --project ${rel(PROJECT)} --undo\``);
+  }
+} catch (e) {
+  console.error("init failed:", e.message);
+  process.exit(1);
+}

package/install.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+// `font-lab install` — the one-command setup that makes Font Lab self-installing, the way
+// `npx impeccable install` works. Two wiring actions, mirroring impeccable's pattern:
+//
+//   1. Copy the `font-lab` SKILL into the global skills dir (~/.claude/skills/font-lab) so the
+//      agent DISCOVERS it in every session — you just say "pick new fonts" and it reaches for it.
+//   2. Register the `font-lab` MCP server into the target project's `.mcp.json` so the agent has
+//      the font_lab_* tools to actually drive the loop.
+//
+// Both steps are idempotent (re-running is a no-op) and reversible (`font-lab uninstall`).
+//
+//   npx font-lab install [--project <dir>] [--no-mcp] [--no-skill] [--local] [--dry-run]
+//   npx font-lab uninstall [--project <dir>]
+//
+// Flags:
+//   --project <dir>   project to wire the MCP server into (default: cwd)
+//   --no-mcp          skip the .mcp.json registration (skill only)
+//   --no-skill        skip the global skill copy (MCP only)
+//   --local           register the MCP server as `node <this-checkout>/mcp.mjs` instead of the
+//                     published `npx` form — use this to test from a git clone before publishing
+//   --skills-dir <d>  override the skills dir (default: $CLAUDE_CONFIG_DIR/skills or ~/.claude/skills)
+//   --dry-run         print what would change, write nothing
+
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { cpSync, rmSync, mkdirSync, readFileSync, writeFileSync, existsSync, statSync } from "node:fs";
+
+const PKG_NAME = "font-lab"; // single source of truth for the published name
+const SKILL_NAME = "font-lab";
+const MCP_KEY = "font-lab";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url)); // the `cli/` dir
+const arg = (flag, def) => {
+  const i = process.argv.indexOf(flag);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : def;
+};
+const has = (flag) => process.argv.includes(flag);
+const rel = (p) => path.relative(process.cwd(), p) || ".";
+
+// ---- shared resolution -----------------------------------------------------
+
+// The SKILL source: bundled inside the package (cli/skill/font-lab, created by `prepack`)
+// when installed via npm, or the repo's top-level skill/font-lab when run from a git checkout.
+function resolveSkillSource() {
+  const candidates = [
+    path.join(HERE, "skill", SKILL_NAME),
+    path.join(HERE, "..", "skill", SKILL_NAME),
+  ];
+  for (const c of candidates) {
+    if (existsSync(path.join(c, "SKILL.md"))) return c;
+  }
+  return null;
+}
+
+function skillsDir() {
+  const override = arg("--skills-dir", null);
+  if (override) return path.resolve(override);
+  const base = process.env.CLAUDE_CONFIG_DIR
+    ? path.resolve(process.env.CLAUDE_CONFIG_DIR)
+    : path.join(os.homedir(), ".claude");
+  return path.join(base, "skills");
+}
+
+// The command the agent's host will run to launch the MCP server.
+//   published (default):  npx -y font-lab mcp
+//   --local (dev/test):   node <abs>/cli/mcp.mjs
+function mcpServerEntry() {
+  if (has("--local")) {
+    return { command: "node", args: [path.join(HERE, "mcp.mjs")] };
+  }
+  return { command: "npx", args: ["-y", PKG_NAME, "mcp"] };
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(readFileSync(file, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+// ---- install ---------------------------------------------------------------
+
+export function runInstall() {
+  const dry = has("--dry-run");
+  const doSkill = !has("--no-skill");
+  const doMcp = !has("--no-mcp");
+  const project = path.resolve(arg("--project", process.cwd()));
+  const tag = dry ? " (dry-run, nothing written)" : "";
+  const steps = [];
+
+  console.log(`Font Lab — install${tag}`);
+
+  if (doSkill) {
+    const src = resolveSkillSource();
+    if (!src) {
+      console.error(
+        `  ✗ skill source not found (looked in cli/skill/${SKILL_NAME} and ../skill/${SKILL_NAME}).`,
+      );
+      console.error(`    If you're running from a git clone, run from the repo root; if from npm,`);
+      console.error(`    this is a packaging bug (the skill wasn't bundled).`);
+      process.exit(1);
+    }
+    const dest = path.join(skillsDir(), SKILL_NAME);
+    if (!dry) {
+      mkdirSync(path.dirname(dest), { recursive: true });
+      rmSync(dest, { recursive: true, force: true }); // clean copy so updates fully replace
+      cpSync(src, dest, { recursive: true });
+    }
+    steps.push(`skill   → ${dest}`);
+  }
+
+  if (doMcp) {
+    const mcpFile = path.join(project, ".mcp.json");
+    const entry = mcpServerEntry();
+    const existing = existsSync(mcpFile) ? readJson(mcpFile) || {} : {};
+    const servers = existing.mcpServers && typeof existing.mcpServers === "object" ? existing.mcpServers : {};
+    const before = JSON.stringify(servers[MCP_KEY] || null);
+    const after = JSON.stringify(entry);
+    const changed = before !== after;
+    if (!dry && changed) {
+      const next = { ...existing, mcpServers: { ...servers, [MCP_KEY]: entry } };
+      writeFileSync(mcpFile, JSON.stringify(next, null, 2) + "\n");
+    }
+    steps.push(
+      `mcp     → ${rel(mcpFile)}  ["${MCP_KEY}"] = ${entry.command} ${entry.args.join(" ")}` +
+        (changed ? "" : "  (already set)"),
+    );
+  }
+
+  for (const s of steps) console.log(`  ${s}`);
+  console.log();
+  if (doMcp) {
+    console.log(`  Note: a newly registered MCP server is picked up when the agent/session reloads`);
+    console.log(`        its config — restart the session (or reconnect MCP) if the tools aren't live yet.`);
+  }
+  console.log(`  Then just ask: "use Font Lab to pick new fonts". Undo with \`font-lab uninstall\`.`);
+}
+
+// ---- uninstall -------------------------------------------------------------
+
+export function runUninstall() {
+  const dry = has("--dry-run");
+  const project = path.resolve(arg("--project", process.cwd()));
+  const tag = dry ? " (dry-run, nothing written)" : "";
+  console.log(`Font Lab — uninstall${tag}`);
+
+  // 1. remove the global skill
+  const dest = path.join(skillsDir(), SKILL_NAME);
+  if (existsSync(dest)) {
+    if (!dry) rmSync(dest, { recursive: true, force: true });
+    console.log(`  removed skill   ${dest}`);
+  } else {
+    console.log(`  skill           not installed (${dest})`);
+  }
+
+  // 2. drop the MCP server entry (leave any others untouched)
+  const mcpFile = path.join(project, ".mcp.json");
+  if (existsSync(mcpFile) && statSync(mcpFile).isFile()) {
+    const json = readJson(mcpFile);
+    if (json && json.mcpServers && json.mcpServers[MCP_KEY]) {
+      if (!dry) {
+        delete json.mcpServers[MCP_KEY];
+        // If we left the file empty (no other servers and no other top-level keys), remove
+        // it — install likely created it, so a bare `{"mcpServers":{}}` shouldn't linger.
+        const otherKeys = Object.keys(json).filter((k) => k !== "mcpServers");
+        const emptied = Object.keys(json.mcpServers).length === 0 && otherKeys.length === 0;
+        if (emptied) rmSync(mcpFile, { force: true });
+        else writeFileSync(mcpFile, JSON.stringify(json, null, 2) + "\n");
+        console.log(`  removed mcp     ${rel(mcpFile)} ["${MCP_KEY}"]${emptied ? " (removed empty .mcp.json)" : ""}`);
+      } else {
+        console.log(`  removed mcp     ${rel(mcpFile)} ["${MCP_KEY}"]`);
+      }
+    } else {
+      console.log(`  mcp             entry not present in ${rel(mcpFile)}`);
+    }
+  } else {
+    console.log(`  mcp             no .mcp.json in ${rel(project)}`);
+  }
+}
+
+// Allow running directly as a bin (`font-lab-install`) in addition to the
+// `font-lab install` subcommand dispatched from font-lab.mjs.
+if (path.resolve(fileURLToPath(import.meta.url)) === path.resolve(process.argv[1] || "")) {
+  if (process.argv.includes("uninstall")) runUninstall();
+  else runInstall();
+}

package/loop-test.mjs

@@ -0,0 +1,119 @@
+// M1 verification — drive the whole loop in a real browser and prove the pick lands on
+// disk: flip directions (arrow keys + click), swap fonts live, Pick (button + Enter), and
+// assert .font-lab/selection.json + picks.log.jsonl. Spawns the CLI endpoint itself;
+// expects the fixture's dev server already running at BASE_URL.
+
+import { chromium } from "playwright";
+import { spawn } from "node:child_process";
+import { readFileSync, existsSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const BASE = process.env.BASE_URL || process.argv[2] || "http://localhost:4331";
+const HERE = fileURLToPath(new URL("./", import.meta.url));
+const APP = fileURLToPath(new URL("../examples/sample-next-site/", import.meta.url));
+const FLDIR = path.join(APP, ".font-lab");
+const SEL = path.join(FLDIR, "selection.json");
+const LOG = path.join(FLDIR, "picks.log.jsonl");
+mkdirSync(HERE + "out", { recursive: true });
+
+rmSync(FLDIR, { recursive: true, force: true });
+
+const cli = spawn("node", [HERE + "font-lab.mjs", "--project", APP, "--port", "7777"], { stdio: "inherit" });
+const waitHealth = async () => {
+  for (let i = 0; i < 40; i++) {
+    try {
+      if ((await fetch("http://localhost:7777/health")).ok) return;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  throw new Error("CLI endpoint never became healthy");
+};
+await waitHealth();
+
+const results = [];
+const assert = (name, cond, extra = "") => {
+  results.push({ name, pass: !!cond, extra });
+  console.log((cond ? "PASS" : "FAIL").padEnd(5), name, extra ? `(${extra})` : "");
+};
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 1000 } });
+const bodyFont = () => page.evaluate(() => getComputedStyle(document.body).fontFamily);
+const displayFont = () => page.evaluate(() => getComputedStyle(document.querySelector("h1")).fontFamily);
+const activeId = () => page.evaluate(() => document.documentElement.getAttribute("data-fontlab-active"));
+const clickDir = (id) =>
+  page.evaluate((id) => document.getElementById("fontlab-panel-host").shadowRoot.querySelector(`button[data-fl-id="${id}"]`).click(), id);
+const clickPick = () =>
+  page.evaluate(() => document.getElementById("fontlab-panel-host").shadowRoot.querySelector('[data-fl-action="pick"]').click());
+const readSel = () => (existsSync(SEL) ? JSON.parse(readFileSync(SEL, "utf8")) : null);
+
+await page.goto(BASE + "/", { waitUntil: "domcontentloaded" });
+await page.evaluate(async () => {
+  await document.fonts.ready;
+  return true;
+});
+await page.waitForTimeout(600);
+await page.mouse.click(2, 2); // focus the document for keyboard nav
+
+assert("starts on current state", (await activeId()) === "current");
+assert("current body is Inter", /Inter/i.test(await bodyFont()), await bodyFont());
+
+// ← → flips to the first direction and swaps the body live.
+await page.keyboard.press("ArrowRight");
+await page.waitForTimeout(250);
+assert("ArrowRight selects editorial-serif", (await activeId()) === "editorial-serif", await activeId());
+assert("body swapped to Libre Franklin", /FL Libre Franklin/i.test(await bodyFont()), await bodyFont());
+
+// Click the second direction; display + body both swap.
+await clickDir("modern-grotesque");
+await page.evaluate(async () => {
+  await document.fonts.ready;
+  return true;
+});
+await page.waitForTimeout(300);
+assert("click selects modern-grotesque", (await activeId()) === "modern-grotesque");
+assert("body swapped to Figtree", /FL Figtree/i.test(await bodyFont()), await bodyFont());
+assert("display swapped to Bricolage", /FL Bricolage/i.test(await displayFont()), await displayFont());
+
+// Pick via button -> selection.json written.
+await clickPick();
+let sel = null;
+for (let i = 0; i < 40; i++) {
+  sel = readSel();
+  if (sel) break;
+  await page.waitForTimeout(150);
+}
+assert("selection.json written", !!sel);
+assert("direction id = modern-grotesque", sel?.direction?.id === "modern-grotesque");
+assert("body family = Figtree", sel?.roles?.body?.family === "Figtree");
+assert("display family = Bricolage Grotesque", sel?.roles?.display?.family === "Bricolage Grotesque");
+assert("mono family = JetBrains Mono", sel?.roles?.mono?.family === "JetBrains Mono");
+assert("target tailwind v4", sel?.target?.tailwindVersion === 4);
+assert("records replaces (Inter)", sel?.replaces?.body === "Inter");
+
+// Re-pick a different direction via Enter -> overwrites selection.json, appends to log.
+await clickDir("editorial-serif");
+await page.waitForTimeout(200);
+await page.keyboard.press("Enter");
+let sel2 = null;
+for (let i = 0; i < 40; i++) {
+  sel2 = readSel();
+  if (sel2?.direction?.id === "editorial-serif") break;
+  await page.waitForTimeout(150);
+}
+assert("Enter re-picks editorial-serif", sel2?.direction?.id === "editorial-serif");
+const logLines = existsSync(LOG) ? readFileSync(LOG, "utf8").trim().split("\n").filter(Boolean) : [];
+assert("picks.log appended (2 entries)", logLines.length === 2, `lines=${logLines.length}`);
+
+await browser.close();
+cli.kill();
+
+const failed = results.filter((r) => !r.pass);
+writeFileSync(HERE + "out/m1-report.json", JSON.stringify({ results, finalSelection: readSel() }, null, 2));
+console.log(`\nM1 loop: ${results.length - failed.length}/${results.length} assertions passed`);
+if (failed.length) {
+  console.error("FAILED:", failed.map((f) => f.name).join(", "));
+  process.exit(5);
+}
+console.log("M1 PASS");

package/m3-test.mjs

@@ -0,0 +1,255 @@
+// M3 verification — the analyzer reads real projects correctly, and codegen consumes that
+// analysis to ship BOTH wiring shapes: the role-var path (our fixture) and the adopt path
+// (the real jack-mcgovern.com site, whose fonts ride project-named variables on <body>).
+//
+// Structural only — no build. It applies into throwaway copies so it never touches the
+// source repos, and asserts the produced code, idempotency, and byte-exact reversibility.
+
+import { analyzeProject } from "./analyzer.mjs";
+import { applySelection, undo } from "./codegen.mjs";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+  cpSync,
+} from "node:fs";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+
+const HERE = fileURLToPath(new URL("./", import.meta.url));
+const ROOT = path.resolve(HERE, "..");
+const OUT = HERE + "out/";
+const TMP = HERE + ".m3-tmp/";
+mkdirSync(OUT, { recursive: true });
+
+const SAMPLE = path.join(ROOT, "examples/sample-next-site");
+const CLEAN = path.join(ROOT, "examples/clean-next-site");
+const JACK = path.resolve(ROOT, "../jack-mcgovern-site");
+
+const results = [];
+const assert = (name, cond, extra = "") => {
+  results.push({ name, pass: !!cond });
+  console.log((cond ? "PASS" : "FAIL").padEnd(5), name, extra && !cond ? `(got: ${extra})` : "");
+};
+
+// Build a throwaway copy carrying just what the analyzer/codegen read.
+function stage(srcDir, label) {
+  const dst = path.join(TMP, label);
+  rmSync(dst, { recursive: true, force: true });
+  mkdirSync(path.join(dst, "app"), { recursive: true });
+  for (const f of ["package.json", "app/layout.tsx", "app/globals.css"]) {
+    const s = path.join(srcDir, f);
+    if (existsSync(s)) cpSync(s, path.join(dst, f));
+  }
+  for (const cfg of ["tailwind.config.ts", "tailwind.config.js"]) {
+    const s = path.join(srcDir, cfg);
+    if (existsSync(s)) cpSync(s, path.join(dst, cfg));
+  }
+  return dst;
+}
+
+const SELECTION = {
+  version: 1,
+  pickedAt: "2026-06-25T00:00:00.000Z",
+  direction: { id: "editorial-serif", name: "Editorial", vibe: "editorial", rationale: "Warm serif headlines over a clean grotesque body." },
+  roles: {
+    display: { family: "Fraunces", source: "google", weights: [400, 700] },
+    body: { family: "Libre Franklin", source: "google", weights: [400, 600] },
+    mono: { family: "JetBrains Mono", source: "google", weights: [400, 700] },
+  },
+};
+function writeSelection(dir, replaces, target) {
+  mkdirSync(path.join(dir, ".font-lab"), { recursive: true });
+  writeFileSync(path.join(dir, ".font-lab/selection.json"), JSON.stringify({ ...SELECTION, replaces, target }, null, 2));
+}
+
+try {
+  rmSync(TMP, { recursive: true, force: true });
+
+  // ===================================================================== //
+  //  Part 1 — the analyzer reads each project correctly                   //
+  // ===================================================================== //
+
+  const aSample = analyzeProject(SAMPLE);
+  assert("sample: framework next", aSample.framework === "next");
+  assert("sample: App Router", aSample.router === "app");
+  assert("sample: Tailwind v4", aSample.tailwindVersion === 4, String(aSample.tailwindVersion));
+  assert("sample: css-variable wiring", aSample.fontWiring === "css-variables", aSample.fontWiring);
+  assert("sample: class target <html>", aSample.classNameTarget === "html", String(aSample.classNameTarget));
+  assert("sample: current display Inter", aSample.replaces.display === "Inter", String(aSample.replaces.display));
+  assert("sample: current mono JetBrains Mono", aSample.replaces.mono === "JetBrains Mono", String(aSample.replaces.mono));
+  assert("sample: supported", aSample.supported === true, aSample.reasons.join("; "));
+
+  const aClean = analyzeProject(CLEAN);
+  assert("clean: no display font wired", aClean.replaces.display === null, String(aClean.replaces.display));
+  assert("clean: body Inter via --font-sans", aClean.replaces.body === "Inter", String(aClean.replaces.body));
+  assert("clean: supported", aClean.supported === true, aClean.reasons.join("; "));
+  assert("clean: no dead roles (no false positives)", aClean.coverage.deadRoles.length === 0, aClean.coverage.deadRoles.join(","));
+  assert("sample: no dead roles (no false positives)", aSample.coverage.deadRoles.length === 0, aSample.coverage.deadRoles.join(","));
+
+  const haveJack = existsSync(JACK);
+  let aJack = null;
+  if (haveJack) {
+    aJack = analyzeProject(JACK);
+    assert("jack: framework next", aJack.framework === "next");
+    assert("jack: App Router", aJack.router === "app");
+    assert("jack: Tailwind v4", aJack.tailwindVersion === 4, String(aJack.tailwindVersion));
+    assert("jack: css-variable wiring", aJack.fontWiring === "css-variables", aJack.fontWiring);
+    assert("jack: class target <body>", aJack.classNameTarget === "body", String(aJack.classNameTarget));
+    assert("jack: display = Bricolage Grotesque", aJack.replaces.display === "Bricolage Grotesque", String(aJack.replaces.display));
+    assert("jack: body = Hanken Grotesk", aJack.replaces.body === "Hanken Grotesk", String(aJack.replaces.body));
+    assert("jack: no mono font wired", aJack.replaces.mono === null, String(aJack.replaces.mono));
+    assert("jack: display rides --font-bricolage", aJack.roles.display?.nextFontVar === "--font-bricolage", String(aJack.roles.display?.nextFontVar));
+    assert("jack: body rides --font-hanken", aJack.roles.body?.nextFontVar === "--font-hanken", String(aJack.roles.body?.nextFontVar));
+    assert("jack: supported", aJack.supported === true, aJack.reasons.join("; "));
+    // Coverage diagnostics — the foolproofing: detect a swap that won't be visible.
+    assert("jack: flags display as a dead role", aJack.coverage.deadRoles.includes("display"), aJack.coverage.deadRoles.join(","));
+    assert("jack: does NOT flag body as dead", !aJack.coverage.deadRoles.includes("body"));
+    assert("jack: reports other font subsystems (/gus, /fonts)", aJack.coverage.otherSubsystems.length >= 2, String(aJack.coverage.otherSubsystems.length));
+  } else {
+    console.log("note: jack-mcgovern-site not found alongside Font-Lab — skipping its assertions");
+  }
+
+  // ===================================================================== //
+  //  Part 2 — codegen ROLE-VAR path on the clean fixture                  //
+  // ===================================================================== //
+
+  const cleanTarget = { framework: "next", router: "app", styling: "tailwind", tailwindVersion: 4, fontWiring: "css-variables" };
+  {
+    const dir = stage(CLEAN, "clean");
+    const origLayout = readFileSync(path.join(dir, "app/layout.tsx"), "utf8");
+    const origCss = readFileSync(path.join(dir, "app/globals.css"), "utf8");
+    writeSelection(dir, aClean.replaces, cleanTarget);
+    const r = applySelection(dir);
+    const layout = readFileSync(path.join(dir, "app/layout.tsx"), "utf8");
+    const css = readFileSync(path.join(dir, "app/globals.css"), "utf8");
+
+    assert("clean: imports Fraunces + Libre_Franklin", /\bFraunces\b/.test(layout) && /\bLibre_Franklin\b/.test(layout));
+    assert("clean: fontLabDisplay on --font-display", /const fontLabDisplay = Fraunces\([^)]*--font-display/.test(layout));
+    assert("clean: fontLabBody on --font-sans", /const fontLabBody = Libre_Franklin\([^)]*--font-sans/.test(layout));
+    assert("clean: fontLabMono on --font-mono", /const fontLabMono = JetBrains_Mono\([^)]*--font-mono/.test(layout));
+    assert("clean: removed old `const inter`", !/const inter =/.test(layout));
+    assert("clean: html has all 3 role vars", ["fontLabDisplay", "fontLabBody", "fontLabMono"].every((c) => layout.includes(`${c}.variable`)));
+    assert("clean: css fenced @theme has 3 role vars", /\/\* font-lab:start \*\/[\s\S]*--font-display[\s\S]*--font-sans[\s\S]*--font-mono[\s\S]*\/\* font-lab:end \*\//.test(css));
+
+    const layout2 = (applySelection(dir), readFileSync(path.join(dir, "app/layout.tsx"), "utf8"));
+    assert("clean: idempotent re-apply", layout === layout2);
+    assert("clean: replaced reported (inter)", r.replaced.some((x) => /Inter/.test(x.font)));
+
+    // Reversibility on a fresh copy (single apply, like M2).
+    const rev = stage(CLEAN, "clean-rev");
+    writeSelection(rev, aClean.replaces, cleanTarget);
+    applySelection(rev);
+    undo(rev);
+    assert("clean: undo restores layout byte-identical", readFileSync(path.join(rev, "app/layout.tsx"), "utf8") === origLayout);
+    assert("clean: undo restores globals byte-identical", readFileSync(path.join(rev, "app/globals.css"), "utf8") === origCss);
+  }
+
+  // ===================================================================== //
+  //  Part 3 — codegen ADOPT path on the real jack-mcgovern.com site       //
+  // ===================================================================== //
+
+  if (haveJack) {
+    const jackTarget = { framework: "next", router: "app", styling: "tailwind", tailwindVersion: 4, fontWiring: "css-variables" };
+    const dir = stage(JACK, "jack");
+    const origLayout = readFileSync(path.join(dir, "app/layout.tsx"), "utf8");
+    const origCss = readFileSync(path.join(dir, "app/globals.css"), "utf8");
+    writeSelection(dir, aJack.replaces, jackTarget);
+
+    const r = applySelection(dir);
+    const layout = readFileSync(path.join(dir, "app/layout.tsx"), "utf8");
+    const css = readFileSync(path.join(dir, "app/globals.css"), "utf8");
+    writeFileSync(OUT + "jack-applied.layout.tsx", layout);
+    writeFileSync(OUT + "jack-applied.globals.css", css);
+    const fenced = (css.match(/\/\* font-lab:start \*\/[\s\S]*?\/\* font-lab:end \*\//) || [""])[0];
+
+    assert("jack: adopts display const (bricolage = Fraunces)", /const bricolage = Fraunces\(/.test(layout));
+    assert("jack: display keeps --font-bricolage", /Fraunces\(\{[^}]*--font-bricolage/.test(layout.replace(/\n/g, " ")));
+    assert("jack: adopts body const (hanken = Libre_Franklin)", /const hanken = Libre_Franklin\(/.test(layout));
+    assert("jack: body keeps --font-hanken", /Libre_Franklin\(\{[^}]*--font-hanken/.test(layout.replace(/\n/g, " ")));
+    assert("jack: dropped Bricolage_Grotesque import", !/Bricolage_Grotesque/.test(layout));
+    assert("jack: dropped Hanken_Grotesk import", !/Hanken_Grotesk/.test(layout));
+    assert("jack: creates fontLabMono on --font-mono", /const fontLabMono = JetBrains_Mono\([^)]*--font-mono/.test(layout));
+    assert("jack: <body> keeps bricolage.variable + hanken.variable", /bricolage\.variable/.test(layout) && /hanken\.variable/.test(layout));
+    assert("jack: <body> gains fontLabMono.variable", /fontLabMono\.variable/.test(layout));
+    assert("jack: fenced @theme maps only --font-mono", /--font-mono/.test(fenced) && !/--font-display/.test(fenced) && !/--font-sans/.test(fenced), fenced.replace(/\n/g, " "));
+    assert("jack: project's own @theme (--font-display: var(--font-bricolage)) intact", /--font-display:\s*var\(--font-bricolage\)/.test(css));
+    assert("jack: replaces reports Bricolage Grotesque", r.replaced.some((x) => /Bricolage_Grotesque/.test(x.font)));
+    assert("jack: class target reported as body", r.classTarget === "body");
+
+    const layout2 = (applySelection(dir), readFileSync(path.join(dir, "app/layout.tsx"), "utf8"));
+    assert("jack: idempotent re-apply", layout === layout2);
+
+    // Reversibility on a fresh copy (single apply, like M2).
+    const rev = stage(JACK, "jack-rev");
+    writeSelection(rev, aJack.replaces, jackTarget);
+    applySelection(rev);
+    undo(rev);
+    assert("jack: undo restores layout byte-identical", readFileSync(path.join(rev, "app/layout.tsx"), "utf8") === origLayout);
+    assert("jack: undo restores globals byte-identical", readFileSync(path.join(rev, "app/globals.css"), "utf8") === origCss);
+  }
+  // ===================================================================== //
+  //  Part 4 — branch selection: the analyzer gates what codegen ships     //
+  // ===================================================================== //
+
+  // Synthesize minimal projects the analyzer should flag as out-of-branch.
+  function synth(label, { pkg, layoutPath, layout, css }) {
+    const dir = path.join(TMP, label);
+    rmSync(dir, { recursive: true, force: true });
+    mkdirSync(path.dirname(path.join(dir, layoutPath)), { recursive: true });
+    mkdirSync(path.join(dir, "app"), { recursive: true });
+    writeFileSync(path.join(dir, "package.json"), JSON.stringify(pkg, null, 2));
+    writeFileSync(path.join(dir, layoutPath), layout);
+    writeFileSync(path.join(dir, "app/globals.css"), css);
+    return dir;
+  }
+  const refuses = (dir, needle) => {
+    writeSelection(dir, { display: null, body: null, mono: null }, {});
+    try {
+      applySelection(dir);
+      return false;
+    } catch (e) {
+      return new RegExp(needle, "i").test(e.message);
+    }
+  };
+
+  const v3 = synth("v3", {
+    pkg: { dependencies: { next: "^15", react: "^19" }, devDependencies: { tailwindcss: "^3.4.0" } },
+    layoutPath: "app/layout.tsx",
+    layout: `import { Inter } from "next/font/google";\nconst inter = Inter({ subsets: ["latin"], variable: "--font-sans" });\nexport default function RootLayout({ children }) { return (<html className={inter.variable}><body>{children}</body></html>); }`,
+    css: `@tailwind base;\n@tailwind components;\n@tailwind utilities;\n@theme inline { --font-sans: var(--font-sans); }`,
+  });
+  assert("v3: analyzer reports Tailwind v3", analyzeProject(v3).tailwindVersion === 3, String(analyzeProject(v3).tailwindVersion));
+  assert("v3: codegen refuses (need v4)", refuses(v3, "tailwind v3"));
+
+  const pages = synth("pages", {
+    pkg: { dependencies: { next: "^15", react: "^19", tailwindcss: "^4.2.0" }, devDependencies: { "@tailwindcss/postcss": "^4" } },
+    layoutPath: "pages/_app.tsx",
+    layout: `import { Inter } from "next/font/google";\nconst inter = Inter({ subsets: ["latin"], variable: "--font-sans" });\nexport default function App({ Component, pageProps }) { return (<div className={inter.variable}><Component {...pageProps} /></div>); }`,
+    css: `@import "tailwindcss";\n@theme inline { --font-sans: var(--font-sans); }`,
+  });
+  assert("pages: analyzer reports Pages Router", analyzeProject(pages).router === "pages", String(analyzeProject(pages).router));
+  assert("pages: codegen refuses (need app)", refuses(pages, "router is pages"));
+
+  const hard = synth("hardcoded", {
+    pkg: { dependencies: { next: "^15", react: "^19", tailwindcss: "^4.2.0" }, devDependencies: { "@tailwindcss/postcss": "^4" } },
+    layoutPath: "app/layout.tsx",
+    layout: `export default function RootLayout({ children }) { return (<html><body>{children}</body></html>); }`,
+    css: `@import "tailwindcss";\nbody { font-family: "Times New Roman", serif; }`,
+  });
+  assert("hardcoded: analyzer reports hardcoded wiring", analyzeProject(hard).fontWiring === "hardcoded", analyzeProject(hard).fontWiring);
+  assert("hardcoded: codegen refuses (need css-variables)", refuses(hard, "hardcoded"));
+} finally {
+  rmSync(TMP, { recursive: true, force: true });
+}
+
+const failed = results.filter((r) => !r.pass);
+writeFileSync(OUT + "m3-report.json", JSON.stringify({ results }, null, 2));
+console.log(`\nM3: ${results.length - failed.length}/${results.length} assertions passed`);
+if (failed.length) {
+  console.error("FAILED:", failed.map((f) => f.name).join(", "));
+  process.exit(5);
+}
+console.log("M3 PASS");