font-lab 0.1.0

package/curator.mjs

@@ -0,0 +1,92 @@
+// Font Lab curator (M4) — turns `analysis + vibe` into ~5 concrete directions via a
+// deterministic lookup over the catalog. **No runtime LLM**: the agent driving Font Lab is
+// the LLM; this package stays dumb, instant, free, and reproducible (same inputs → same
+// directions, every time). Each direction is a hand-authored pairing with a pre-written
+// rationale; `curate()` selects among them.
+//
+// Selection rules (all deterministic):
+//   • drop any direction that wouldn't change the current site (display+body == current),
+//     so we always move *away* from the baseline;
+//   • if a vibe is given, rank exact-vibe and tag matches first;
+//   • otherwise return a fixed, diverse spread in authored order;
+//   • always validate every referenced family is a catalog member (authoring guard).
+
+import { get, catalog } from "./catalog.mjs";
+
+const D = (id, name, vibe, rationale, display, body, mono, weights = {}) => ({
+  id,
+  name,
+  vibe,
+  rationale,
+  roles: {
+    display: { family: display, weights: weights.display || [400, 700] },
+    body: { family: body, weights: weights.body || [400, 600] },
+    mono: { family: mono, weights: weights.mono || [400, 700] },
+  },
+});
+
+// The curated set — diverse across vibe, each a real pairing of catalog fonts.
+export const directions = [
+  D("editorial-serif", "Editorial", "editorial", "Warm high-contrast serif headlines over a clean grotesque body.", "Fraunces", "Libre Franklin", "JetBrains Mono"),
+  D("modern-grotesque", "Modern Grotesque", "technical", "A characterful display grotesque over a quiet geometric body.", "Bricolage Grotesque", "Figtree", "JetBrains Mono"),
+  D("clean-geometric", "Clean Geometric", "minimal", "One geometric family throughout — calm, precise, contemporary.", "Geist", "Geist", "Geist Mono"),
+  D("warm-humanist", "Warm Humanist", "warm", "Friendly humanist shapes, soft and highly readable end to end.", "Bricolage Grotesque", "Hanken Grotesk", "Spline Sans Mono"),
+  D("classic-editorial", "Classic Editorial", "classic", "High-drama display serif over a steady text serif — magazine feel.", "Playfair Display", "Source Serif 4", "Roboto Mono"),
+  D("technical", "Technical", "technical", "Engineered grotesque headings, a neutral geometric body, code-first mono.", "Space Grotesk", "Sora", "Fira Code"),
+  D("elegant-contrast", "Elegant Contrast", "elegant", "Delicate high-contrast serif display against a plain grotesque body.", "Cormorant", "Work Sans", "JetBrains Mono"),
+  D("expressive", "Expressive", "bold", "A loud, rounded display voice balanced by a minimal geometric body.", "Unbounded", "Manrope", "Geist Mono"),
+  D("modern-serif", "Modern Serif", "editorial", "A contemporary text serif headline over a neutral UI sans.", "Newsreader", "Inter", "Geist Mono"),
+  D("bold-editorial", "Bold Editorial", "bold", "An expressive editorial display over a crisp modern sans.", "Syne", "Albert Sans", "Spline Sans Mono"),
+  D("friendly-rounded", "Friendly Rounded", "friendly", "Rounded, approachable display with a soft geometric body.", "Gabarito", "Plus Jakarta Sans", "Roboto Mono"),
+  D("quiet-minimal", "Quiet Minimal", "minimal", "Understated geometric sans throughout — gets out of the way.", "Manrope", "Manrope", "Geist Mono"),
+];
+
+// Validate authoring once at import: every referenced family must be a catalog member.
+for (const d of directions) for (const r of ["display", "body", "mono"]) get(d.roles[r].family);
+
+const norm = (s) => (s || "").toLowerCase().trim();
+
+function scoreForVibe(d, vibe) {
+  const v = norm(vibe);
+  if (!v) return 0;
+  if (norm(d.vibe) === v) return 3;
+  // tag match across the direction's fonts
+  const tags = new Set(["display", "body", "mono"].flatMap((r) => catalog[d.roles[r].family].tags));
+  return tags.has(v) ? 1 : 0;
+}
+
+/**
+ * Deterministically pick ~`count` directions for a project.
+ * @param analysis  output of analyzeProject (or null) — used to skip no-op directions.
+ * @param opts      { vibe?: string, count?: number }
+ */
+export function curate(analysis, opts = {}) {
+  const count = opts.count ?? 5;
+  const cur = analysis?.replaces || {};
+  const isNoop = (d) => norm(d.roles.display.family) === norm(cur.display) && norm(d.roles.body.family) === norm(cur.body);
+
+  const pool = directions.filter((d) => !isNoop(d));
+  // stable sort by vibe score (desc), preserving authored order for ties.
+  const ranked = pool
+    .map((d, i) => ({ d, i, s: scoreForVibe(d, opts.vibe) }))
+    .sort((a, b) => b.s - a.s || a.i - b.i)
+    .map((x) => x.d);
+
+  const picked = ranked.slice(0, count);
+  return picked.map((d) => ({ ...d, rationale: rationaleFor(d, cur) }));
+}
+
+// Make the rationale concrete about what it replaces, when we know the current fonts.
+function rationaleFor(d, cur) {
+  if (cur.display && norm(cur.display) !== norm(d.roles.display.family)) {
+    return `${d.rationale} (replaces ${cur.display}${cur.body && cur.body !== cur.display ? " / " + cur.body : ""}.)`;
+  }
+  return d.rationale;
+}
+
+// Unique catalog families needed to render a set of directions (for self-hosting).
+export function fontsForDirections(dirs) {
+  const set = new Set();
+  for (const d of dirs) for (const r of ["display", "body", "mono"]) set.add(d.roles[r].family);
+  return [...set];
+}

package/engine.mjs

@@ -0,0 +1,343 @@
+// Font Lab engine (M5) — the stable programmatic facade the MCP server and CLIs wrap. One
+// import surface over the whole pipeline so the agent can drive the loop:
+//
+//   analyze → (curate  OR  listCatalog + composeDirections) → preparePreview → readSelection → apply
+//
+// The taste split is enforced here, not just documented:
+//   • the HUMAN makes the final pick (we only ever prepare a preview; we never auto-select);
+//   • the AGENT may take the wheel on the *menu* — compose its own directions — but every
+//     font it chooses must be a catalog member, so the parity / ship guarantee always holds.
+//   • the curator is the strong default the agent gets for free.
+
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { readFileSync, writeFileSync, copyFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { catalog, get as catalogGet, inCatalog } from "./catalog.mjs";
+import { curate as curateDirections } from "./curator.mjs";
+import { analyzeProject, toTarget, wiringFor } from "./analyzer.mjs";
+import { generateCatalog } from "./catalog-build.mjs";
+import { applySelection, undo as undoApply, rewireCoverage } from "./codegen.mjs";
+
+const PANEL_TEMPLATE = fileURLToPath(new URL("./templates/font-lab-panel.tsx", import.meta.url));
+
+const ROLES = ["display", "body", "mono"];
+const slugId = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+
+// ── read ────────────────────────────────────────────────────────────────────
+
+export function analyze(projectDir) {
+  return analyzeProject(path.resolve(projectDir));
+}
+
+// Browse the catalog so the agent can compose its own directions. Filter by role/tag.
+export function listCatalog({ role, tag } = {}) {
+  return Object.entries(catalog)
+    .filter(([, e]) => (!role || e.roles.includes(role)) && (!tag || e.tags.includes(tag)))
+    .map(([family, e]) => ({ family, roles: e.roles, tags: e.tags }));
+}
+
+// The default menu: ~5 deterministic directions for this project.
+export function curate(projectDir, opts = {}) {
+  const analysis = analyzeProject(path.resolve(projectDir));
+  return { analysis, directions: curateDirections(analysis, opts) };
+}
+
+// ── option 3: the agent composes its own directions ──────────────────────────
+// specs: [{ name, vibe?, rationale?, display, body, mono, weights? }]
+// Parity guard: every family must be a catalog member; otherwise throw with suggestions.
+export function composeDirections(specs) {
+  if (!Array.isArray(specs) || !specs.length) throw new Error("composeDirections: provide a non-empty array of directions");
+  const warnings = [];
+  const directions = specs.map((s, i) => {
+    if (!s || !s.display || !s.body || !s.mono) throw new Error(`direction[${i}]: needs display, body, and mono families`);
+    for (const role of ROLES) {
+      const fam = s[role];
+      if (!inCatalog(fam)) {
+        const near = suggest(fam, role);
+        throw new Error(`direction[${i}].${role}: "${fam}" is not in the Font Lab catalog${near ? ` — did you mean ${near}?` : ""}`);
+      }
+      if (!catalogGet(fam).roles.includes(role)) warnings.push(`"${fam}" isn't a typical ${role} font (allowed, but check it reads well)`);
+    }
+    const name = s.name || `${s.display} / ${s.body}`;
+    return {
+      id: s.id || slugId(name),
+      name,
+      vibe: s.vibe || "custom",
+      rationale: s.rationale || `${s.display} headings over ${s.body}.`,
+      roles: {
+        display: { family: s.display, weights: s.weights?.display || [400, 700] },
+        body: { family: s.body, weights: s.weights?.body || [400, 600] },
+        mono: { family: s.mono, weights: s.weights?.mono || [400, 700] },
+      },
+    };
+  });
+  return { directions, warnings };
+}
+
+function suggest(fam, role) {
+  const f = (fam || "").toLowerCase();
+  const hit = Object.keys(catalog).find((k) => k.toLowerCase().includes(f) || f.includes(k.toLowerCase()));
+  if (hit) return `"${hit}"`;
+  const someInRole = Object.entries(catalog).filter(([, e]) => e.roles.includes(role)).slice(0, 3).map(([k]) => `"${k}"`);
+  return someInRole.length ? someInRole.join(", ") : null;
+}
+
+// ── prepare the live preview (build parity bundles into the project) ──────────
+// directions: optional agent-composed/curated directions; if omitted, curate for the project.
+export async function preparePreview(projectDir, { directions, vibe, count, fetch = true, log } = {}) {
+  const dir = path.resolve(projectDir);
+  const analysis = analyzeProject(dir);
+  const dirs = directions && directions.length ? directions : curateDirections(analysis, { vibe, count });
+  const meta = { target: toTarget(analysis), replaces: analysis.replaces };
+  const result = await generateCatalog(dir, dirs, meta, { fetch, log });
+  return { analysis, prepared: result.fonts, directions: result.directions, outPath: result.outPath };
+}
+
+// ── the human's pick, and shipping it ────────────────────────────────────────
+
+export function readSelection(projectDir) {
+  const p = path.join(path.resolve(projectDir), ".font-lab", "selection.json");
+  if (!existsSync(p)) return null;
+  try {
+    return JSON.parse(readFileSync(p, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function apply(projectDir) {
+  return applySelection(path.resolve(projectDir));
+}
+
+// Fix a role the analyzer flags as dead (declared but not actually rendered). Reversible.
+export function rewire(projectDir) {
+  return rewireCoverage(path.resolve(projectDir));
+}
+
+// ── install / uninstall the live panel (the agent's "setup" step) ────────────
+
+const INIT_START = "// font-lab:init:start";
+const INIT_END = "// font-lab:init:end";
+
+function resolveAppDir(projectDir) {
+  const d = ["app", "src/app"].map((x) => path.join(projectDir, x)).find((x) => existsSync(path.join(x, "layout.tsx")));
+  if (!d) throw new Error("could not find app/layout.tsx (App Router only)");
+  return d;
+}
+function insertAfterImports(text, snippet) {
+  const re = /^import\s[^\n]*$/gm;
+  let last = 0, m;
+  while ((m = re.exec(text))) last = m.index + m[0].length;
+  return `${text.slice(0, last).replace(/\s*$/, "")}\n\n${snippet}\n\n${text.slice(last).replace(/^\s*/, "")}`;
+}
+function mountPanel(layoutPath) {
+  let src = readFileSync(layoutPath, "utf8");
+  if (src.includes(INIT_START)) return false;
+  if (!/from\s+["']next\/dynamic["']/.test(src)) src = insertAfterImports(src, `import dynamic from "next/dynamic"`);
+  const block = [
+    INIT_START,
+    `const FontLabDevPanel =`,
+    `  process.env.NODE_ENV === "development"`,
+    `    ? dynamic(() => import("./_fontlab/FontLabDevPanel").then((m) => m.FontLabDevPanel))`,
+    `    : () => null;`,
+    INIT_END,
+  ].join("\n");
+  src = insertAfterImports(src, block);
+  if (!/<FontLabDevPanel\s*\/>/.test(src)) src = src.replace(/<\/body>/, `  {process.env.NODE_ENV === "development" && <FontLabDevPanel />}\n      </body>`);
+  writeFileSync(layoutPath, src);
+  return true;
+}
+
+// Set the project up so the human can preview live: self-host the parity bundles, drop in the
+// portable dev panel, and mount it (dev-only) in the layout. Idempotent + reversible (uninit).
+export async function init(projectDir, { vibe, count, fetch = true, log } = {}) {
+  const dir = path.resolve(projectDir);
+  const analysis = analyzeProject(dir);
+  if (!analysis.supported) throw new Error(`project not supported yet: ${analysis.reasons.join("; ")}`);
+  const appDir = resolveAppDir(dir);
+  const layout = path.join(appDir, "layout.tsx");
+
+  const backupDir = path.join(dir, ".font-lab", "init-backup");
+  mkdirSync(backupDir, { recursive: true });
+  const backupLayout = path.join(backupDir, "layout.tsx");
+  if (!existsSync(backupLayout)) copyFileSync(layout, backupLayout); // never clobber the original
+
+  const directions = curateDirections(analysis, { vibe, count });
+  const meta = { target: toTarget(analysis), replaces: analysis.replaces, wiring: wiringFor(analysis) };
+  const built = await generateCatalog(dir, directions, meta, { fetch, log });
+
+  mkdirSync(path.join(appDir, "_fontlab"), { recursive: true });
+  copyFileSync(PANEL_TEMPLATE, path.join(appDir, "_fontlab", "FontLabDevPanel.tsx"));
+  const mounted = mountPanel(layout);
+
+  return {
+    analysis,
+    directions: directions.map((d) => ({ id: d.id, name: d.name, vibe: d.vibe })),
+    wiring: meta.wiring,
+    deadRoles: analysis.coverage?.deadRoles || [],
+    otherSubsystems: analysis.coverage?.otherSubsystems || [],
+    prepared: built.fonts,
+    mounted,
+    layout: path.relative(dir, layout),
+    nextStep: "Start your dev server, then have the human flip fonts in the panel (bottom-right) and Pick. Then read_pick → apply.",
+  };
+}
+
+export function uninit(projectDir) {
+  const dir = path.resolve(projectDir);
+  const appDir = resolveAppDir(dir);
+  const layout = path.join(appDir, "layout.tsx");
+  const backupLayout = path.join(dir, ".font-lab", "init-backup", "layout.tsx");
+  if (existsSync(backupLayout)) copyFileSync(backupLayout, layout);
+  rmSync(path.join(appDir, "_fontlab"), { recursive: true, force: true });
+  rmSync(path.join(dir, "public", "fontlab"), { recursive: true, force: true });
+  rmSync(path.join(dir, ".font-lab", "init-backup"), { recursive: true, force: true });
+  return { restored: path.relative(dir, layout), removed: ["app/_fontlab", "public/fontlab"] };
+}
+
+export function undo(projectDir) {
+  return undoApply(path.resolve(projectDir));
+}
+
+// ── headless pick mode ────────────────────────────────────────────────────────
+// When there's no live browser for the human to flip in (web/cloud sessions, phones), the
+// agent screenshots the site in each direction, shows the images, the human picks by id, and
+// we record that pick — the SAME selection.json the panel writes, so `apply` ships it
+// identically. The taste decision still belongs to the human; only the surface changes.
+
+// Record the human's pick from a chosen direction id — no panel click needed. Supports a mixed
+// pick: each role can be sourced from a different direction (heading from one, body from another).
+export function selectDirection(projectDir, { directionId, directions, vibe, count, roles: roleSrc } = {}) {
+  const dir = path.resolve(projectDir);
+  const analysis = analyzeProject(dir);
+  const dirs = directions && directions.length ? directions : curateDirections(analysis, { vibe, count });
+  const byId = (id) => dirs.find((d) => d.id === id || slugId(d.name) === id);
+  const chosen = byId(directionId);
+  if (!chosen) throw new Error(`no direction "${directionId}" — available: ${dirs.map((d) => d.id).join(", ")}`);
+  const roles = {};
+  for (const role of ROLES) {
+    const src = roleSrc?.[role] ? byId(roleSrc[role]) : chosen;
+    if (!src) throw new Error(`no direction "${roleSrc[role]}" for role ${role}`);
+    roles[role] = src.roles[role];
+  }
+  const selection = {
+    direction: { id: chosen.id, name: chosen.name, vibe: chosen.vibe },
+    roles,
+    pickedAt: new Date().toISOString(),
+    via: "headless",
+  };
+  const flDir = path.join(dir, ".font-lab");
+  mkdirSync(flDir, { recursive: true });
+  writeFileSync(path.join(flDir, "selection.json"), JSON.stringify(selection, null, 2) + "\n");
+  return selection;
+}
+
+// Ready-to-run commands to launch the FULL live editor (flip / mix / compare in a real browser),
+// for when the screenshots aren't enough. Detects the project's dev command + package manager.
+export function liveInstructions(projectDir) {
+  const dir = path.resolve(projectDir);
+  let devCmd = "npm run dev";
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(dir, "package.json"), "utf8"));
+    if (pkg.scripts?.dev) {
+      const pm = existsSync(path.join(dir, "pnpm-lock.yaml"))
+        ? "pnpm"
+        : existsSync(path.join(dir, "yarn.lock"))
+          ? "yarn"
+          : existsSync(path.join(dir, "bun.lockb"))
+            ? "bun"
+            : "npm run";
+      devCmd = `${pm} dev`;
+    }
+  } catch {}
+  return {
+    note: "Run these in a local terminal — your Mac/Linux terminal, or the integrated terminal in VS Code / Cursor / the Claude Code IDE extension — to flip, mix, and compare the directions live on your real site.",
+    steps: [
+      "npx font-lab init --project .          # scaffold the live panel + parity bundles (reversible)",
+      `${devCmd}                              # start your dev server`,
+      "npx font-lab --project . &             # the pick endpoint on :7777 (records your choice)",
+      "# open your site (e.g. http://localhost:3000): ← → flip · [ ] mix a role · B before/after · Pick",
+      "npx font-lab-apply --project .         # the agent ships exactly what you picked",
+    ],
+    teardown: "npx font-lab init --project . --undo   # remove the panel scaffolding when done",
+  };
+}
+
+// Headless capture: drive the REAL live panel through each direction and screenshot the site, so
+// the images are faithful to what ships. Requires init() done and a dev server running at baseUrl.
+// Makes no project edits — it only reads the running site. Returns a manifest the agent shows.
+export async function captureDirections(projectDir, { baseUrl, routes = ["/"], outDir, directions, viewport, fullPage = true } = {}) {
+  if (!baseUrl) throw new Error("captureDirections: baseUrl is required (your running dev server, e.g. http://localhost:3000)");
+  let chromium;
+  try {
+    ({ chromium } = await import("playwright"));
+  } catch {
+    throw new Error(
+      "Playwright/Chromium isn't available for screenshots. Install it (`npm i -D playwright && npx playwright install chromium`), or use the live editor instead — see liveInstructions().",
+    );
+  }
+  const dir = path.resolve(projectDir);
+  const analysis = analyzeProject(dir);
+  const dirs = directions && directions.length ? directions : curateDirections(analysis, {});
+  const out = outDir ? path.resolve(outDir) : path.join(dir, ".font-lab", "previews");
+  mkdirSync(out, { recursive: true });
+  const base = baseUrl.replace(/\/+$/, "");
+  const route = routes[0] || "/";
+
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage({ viewport: viewport || { width: 1280, height: 900 }, deviceScaleFactor: 2 });
+    await page.goto(base + route, { waitUntil: "networkidle" });
+    await page.waitForSelector("#fontlab-panel-host", { timeout: 20000 });
+    await page.evaluate(async () => {
+      await document.fonts.ready;
+    });
+
+    const setPanel = (v) =>
+      page.evaluate((vis) => {
+        const h = document.getElementById("fontlab-panel-host");
+        if (h) h.style.visibility = vis;
+      }, v);
+
+    const shots = [];
+    // current / before
+    await setPanel("hidden");
+    const curPath = path.join(out, "current.png");
+    await page.screenshot({ path: curPath, fullPage });
+    await setPanel("visible");
+    shots.push({ id: "current", name: "Current (before)", vibe: "—", rationale: "the site as it is today", screenshot: curPath });
+
+    for (const d of dirs) {
+      const clicked = await page.evaluate((id) => {
+        const host = document.getElementById("fontlab-panel-host");
+        const btn = host?.shadowRoot?.querySelector(`button[data-fl-id="${id}"]`);
+        if (!btn) return false;
+        btn.click();
+        return true;
+      }, d.id);
+      if (!clicked) {
+        shots.push({ id: d.id, name: d.name, vibe: d.vibe, rationale: d.rationale, error: "no panel chip — direction not in the preview build (re-run init/preparePreview with these directions)" });
+        continue;
+      }
+      await page.evaluate(async () => {
+        await document.fonts.ready;
+      });
+      await page.waitForTimeout(350);
+      await setPanel("hidden");
+      const file = path.join(out, `${d.id}.png`);
+      await page.screenshot({ path: file, fullPage });
+      await setPanel("visible");
+      shots.push({
+        id: d.id,
+        name: d.name,
+        vibe: d.vibe,
+        rationale: d.rationale,
+        fonts: { display: d.roles.display.family, body: d.roles.body.family, mono: d.roles.mono.family },
+        screenshot: file,
+      });
+    }
+    return { baseUrl: base, route, outDir: out, shots, live: liveInstructions(dir) };
+  } finally {
+    await browser.close();
+  }
+}

package/font-lab.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Font Lab CLI — entry point.
+//
+// Subcommands:
+//   install            wire Font Lab into your machine + project (skill + MCP server)
+//   uninstall          undo the above
+//   mcp                run the MCP server (stdio) — what `.mcp.json` launches
+//   serve  (default)   run the localhost write-back endpoint the dev panel POSTs a pick to,
+//                      persist it to `.font-lab/selection.json` (+ append picks.log.jsonl).
+//                      This is the seam where codegen hooks in: pick lands here -> agent ships it.
+//
+// Usage:
+//   npx font-lab install [--project <dir>] [--no-mcp] [--local] [--dry-run]
+//   npx font-lab uninstall [--project <dir>]
+//   node cli/font-lab.mjs [serve] [--project <dir>] [--port <n>] [--apply]
+
+import http from "node:http";
+import path from "node:path";
+import { writeFileSync, appendFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+
+// ---- subcommand dispatch ---------------------------------------------------
+// The first non-flag arg selects a subcommand. Anything else (or a leading flag)
+// falls through to `serve`, preserving the original `--project/--port` invocation.
+const SUB = process.argv[2] && !process.argv[2].startsWith("-") ? process.argv[2] : "serve";
+if (SUB === "install" || SUB === "uninstall") {
+  const { runInstall, runUninstall } = await import("./install.mjs");
+  if (SUB === "install") runInstall();
+  else runUninstall();
+} else if (SUB === "mcp") {
+  await import("./mcp.mjs"); // self-runs the stdio server on import
+} else if (SUB === "help" || SUB === "--help" || SUB === "-h") {
+  console.log(
+    [
+      "Font Lab",
+      "  font-lab install [--project <dir>] [--no-mcp] [--no-skill] [--local] [--dry-run]",
+      "  font-lab uninstall [--project <dir>]",
+      "  font-lab mcp                      run the MCP server (stdio)",
+      "  font-lab serve [--project <dir>] [--port <n>] [--apply]   pick write-back endpoint",
+    ].join("\n"),
+  );
+} else {
+  runServe();
+}
+
+function runServe() {
+
+const arg = (flag, def) => {
+  const i = process.argv.indexOf(flag);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : def;
+};
+const PORT = Number(arg("--port", "7777"));
+const PROJECT = path.resolve(arg("--project", process.cwd()));
+const AUTO_APPLY = process.argv.includes("--apply"); // pick -> ship, in one step
+const FLDIR = path.join(PROJECT, ".font-lab");
+const SELECTION = path.join(FLDIR, "selection.json");
+const PICKLOG = path.join(FLDIR, "picks.log.jsonl");
+
+const cors = (res) => {
+  res.setHeader("Access-Control-Allow-Origin", "*");
+  res.setHeader("Access-Control-Allow-Methods", "GET,POST,OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", "content-type");
+};
+
+function printPick(sel) {
+  const r = sel.roles || {};
+  const fam = (x) => (x && x.family) || "?";
+  console.log(`\n  ✓ picked "${sel.direction?.name ?? "?"}" (${sel.direction?.vibe ?? "?"})`);
+  console.log(`      display ${fam(r.display)}   body ${fam(r.body)}   mono ${fam(r.mono)}`);
+  console.log(`      wrote ${path.relative(process.cwd(), SELECTION)}`);
+  console.log(`      → next milestone (M4) turns this into next/font + Tailwind edits.\n`);
+}
+
+const server = http.createServer((req, res) => {
+  cors(res);
+  if (req.method === "OPTIONS") {
+    res.writeHead(204);
+    return res.end();
+  }
+  if (req.method === "GET" && req.url === "/health") {
+    res.writeHead(200, { "content-type": "application/json" });
+    return res.end('{"ok":true}');
+  }
+  if (req.method === "GET" && req.url === "/selection") {
+    const cur = existsSync(SELECTION) ? readFileSync(SELECTION, "utf8") : "{}";
+    res.writeHead(200, { "content-type": "application/json" });
+    return res.end(cur);
+  }
+  if (req.method === "POST" && req.url === "/select") {
+    let body = "";
+    req.on("data", (c) => (body += c));
+    req.on("end", () => {
+      try {
+        const sel = JSON.parse(body);
+        mkdirSync(FLDIR, { recursive: true });
+        writeFileSync(SELECTION, JSON.stringify(sel, null, 2) + "\n");
+        appendFileSync(
+          PICKLOG,
+          JSON.stringify({ at: sel.pickedAt, direction: sel.direction?.id, roles: sel.roles }) + "\n",
+        );
+        printPick(sel);
+        if (AUTO_APPLY) {
+          import("./codegen.mjs")
+            .then(({ applySelection }) => {
+              const r = applySelection(PROJECT);
+              console.log(`  → applied to project: ${r.edited.join(", ")} (\`font-lab undo\` to revert)\n`);
+            })
+            .catch((e) => console.error(`  apply failed: ${e.message}\n`));
+        }
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end('{"ok":true}');
+      } catch (e) {
+        res.writeHead(400, { "content-type": "application/json" });
+        res.end(JSON.stringify({ ok: false, error: String(e) }));
+      }
+    });
+    return;
+  }
+  res.writeHead(404);
+  res.end();
+});
+
+  server.listen(PORT, () => {
+    console.log(`Font Lab — walking skeleton`);
+    console.log(`  endpoint  http://localhost:${PORT}  (POST /select, GET /selection)`);
+    console.log(`  project   ${PROJECT}`);
+    console.log(`  Open your dev site, flip directions in the panel (← →), and hit Pick.`);
+    console.log(`  Waiting for a pick…`);
+  });
+}

package/gen-catalog.mjs

@@ -0,0 +1,32 @@
+// `font-lab gen` — build the parity catalog the dev panel previews from. Thin CLI over the
+// full analyzer → curator → generateCatalog pipeline:
+//   1. analyze the project (M3) → target + the real current fonts;
+//   2. curate ~5 directions for it (M4, deterministic, no LLM);
+//   3. self-host each font's variable woff2 + compute next/font's exact adjusted fallback
+//      (M0-proven parity) and write app/_fontlab/catalog.generated.ts.
+//
+// Uses curl (which honors the sandbox HTTPS proxy) to fetch from Google.
+
+import { fileURLToPath } from "node:url";
+import { curate } from "./curator.mjs";
+import { analyzeProject, toTarget, wiringFor } from "./analyzer.mjs";
+import { generateCatalog } from "./catalog-build.mjs";
+
+const arg = (flag, def) => {
+  const i = process.argv.indexOf(flag);
+  return i !== -1 && process.argv[i + 1] ? process.argv[i + 1] : def;
+};
+const APP = arg("--project", fileURLToPath(new URL("../examples/sample-next-site/", import.meta.url))).replace(/\/+$/, "");
+
+const analysis = analyzeProject(APP);
+const target = toTarget(analysis);
+const replaces = analysis.replaces;
+const directions = curate(analysis, { vibe: arg("--vibe", undefined), count: Number(arg("--count", "5")) });
+console.log(
+  `  analyzed ${analysis.router}/${target.framework} · tailwind v${target.tailwindVersion} · ${target.fontWiring}` +
+    ` · current: ${replaces.display ?? "—"} / ${replaces.body ?? "—"} / ${replaces.mono ?? "—"}`,
+);
+console.log(`  curated ${directions.length} directions: ${directions.map((d) => d.name).join(", ")}`);
+
+const r = await generateCatalog(APP, directions, { target, replaces, wiring: wiringFor(analysis) }, { log: (m) => console.log(m) });
+console.log(`\nwrote app/_fontlab/catalog.generated.ts (${r.fonts.length} fonts, ${r.directions.length} directions)`);

package/init-test.mjs

@@ -0,0 +1,52 @@
+// init verification — `font-lab init` scaffolds a real project (panel + parity module +
+// dev-only mount) and `--undo` restores it byte-for-byte. Offline (--no-fetch).
+
+import { execFileSync } from "node:child_process";
+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 + ".init-tmp/";
+mkdirSync(OUT, { recursive: true });
+const CLEAN = path.join(ROOT, "examples/clean-next-site");
+
+const results = [];
+const assert = (n, c, e = "") => { results.push({ name: n, pass: !!c }); console.log((c ? "PASS" : "FAIL").padEnd(5), n, e && !c ? `(${e})` : ""); };
+
+try {
+  rmSync(TMP, { recursive: true, force: true });
+  const dir = path.join(TMP, "proj");
+  mkdirSync(path.join(dir, "app"), { recursive: true });
+  for (const f of ["package.json", "app/layout.tsx", "app/globals.css"]) cpSync(path.join(CLEAN, f), path.join(dir, f));
+  const layoutPath = path.join(dir, "app/layout.tsx");
+  const orig = readFileSync(layoutPath, "utf8");
+
+  execFileSync("node", [HERE + "init.mjs", "--project", dir, "--no-fetch"], { stdio: "pipe" });
+  const layout = readFileSync(layoutPath, "utf8");
+  assert("init: catalog.generated.ts written", existsSync(path.join(dir, "app/_fontlab/catalog.generated.ts")));
+  assert("init: generated module carries wiring", /export const wiring/.test(readFileSync(path.join(dir, "app/_fontlab/catalog.generated.ts"), "utf8")));
+  assert("init: portable panel copied", existsSync(path.join(dir, "app/_fontlab/FontLabDevPanel.tsx")));
+  assert("init: layout imports next/dynamic", /from\s+["']next\/dynamic["']/.test(layout));
+  assert("init: layout declares the dev-only panel", /font-lab:init:start/.test(layout) && /NODE_ENV === "development"/.test(layout));
+  assert("init: panel mounted in <body>", /<FontLabDevPanel \/>/.test(layout));
+
+  // idempotent: re-init doesn't double-mount
+  execFileSync("node", [HERE + "init.mjs", "--project", dir, "--no-fetch"], { stdio: "pipe" });
+  const layout2 = readFileSync(layoutPath, "utf8");
+  assert("init: re-init doesn't duplicate the mount", (layout2.match(/font-lab:init:start/g) || []).length === 1);
+
+  execFileSync("node", [HERE + "init.mjs", "--project", dir, "--undo"], { stdio: "pipe" });
+  assert("undo: layout restored byte-identical", readFileSync(layoutPath, "utf8") === orig);
+  assert("undo: _fontlab removed", !existsSync(path.join(dir, "app/_fontlab")));
+} finally {
+  rmSync(TMP, { recursive: true, force: true });
+}
+
+const failed = results.filter((r) => !r.pass);
+writeFileSync(OUT + "init-report.json", JSON.stringify({ results }, null, 2));
+console.log(`\ninit: ${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("init PASS");