font-lab 0.1.0

package/m4-test.mjs

@@ -0,0 +1,92 @@
+// M4 verification — the parity catalog and the curator. Offline (no network): the gate that
+// matters most, capsize coverage, is checked by actually importing each font's metrics; the
+// curator's determinism and selection rules are pure logic.
+
+import { catalog, families, get } from "./catalog.mjs";
+import { directions, curate, fontsForDirections } from "./curator.mjs";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+const OUT = fileURLToPath(new URL("./out/", import.meta.url));
+mkdirSync(OUT, { recursive: true });
+
+const results = [];
+const assert = (name, cond, extra = "") => {
+  results.push({ name, pass: !!cond });
+  console.log((cond ? "PASS" : "FAIL").padEnd(5), name, extra && !cond ? `(${extra})` : "");
+};
+const ROLES = ["display", "body", "mono"];
+const deep = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+
+// ===================================================================== //
+//  Part 1 — the catalog: every member is a verified parity bundle       //
+// ===================================================================== //
+
+assert("catalog is ~40 fonts", families.length >= 36, String(families.length));
+
+let coverageOk = 0;
+for (const family of families) {
+  const e = catalog[family];
+  let metrics = null;
+  try {
+    metrics = (await import("@capsizecss/metrics/" + e.capsize)).default;
+  } catch {}
+  const covered = !!(metrics && metrics.familyName);
+  if (covered) coverageOk++;
+  else assert(`capsize coverage: ${family}`, false, `no metrics for slug "${e.capsize}"`);
+  const validRoles = Array.isArray(e.roles) && e.roles.length && e.roles.every((r) => ROLES.includes(r));
+  if (!validRoles) assert(`roles valid: ${family}`, false, JSON.stringify(e.roles));
+  if (!(e.css2 && /wght@/.test(e.css2))) assert(`css2 weight-range: ${family}`, false, e.css2);
+  if (!(Array.isArray(e.tags) && e.tags.length)) assert(`has tags: ${family}`, false, JSON.stringify(e.tags));
+}
+assert("every catalog font has verified capsize coverage", coverageOk === families.length, `${coverageOk}/${families.length}`);
+assert("every catalog font: valid roles / css2 / tags", results.every((r) => r.pass));
+assert("mono fonts exist for the mono role", families.some((f) => catalog[f].roles.includes("mono")));
+
+// ===================================================================== //
+//  Part 2 — the curator: deterministic, valid, moves off the baseline   //
+// ===================================================================== //
+
+// every authored direction references only catalog fonts, with role-appropriate fonts
+for (const d of directions) {
+  for (const r of ROLES) {
+    const fam = d.roles[r].family;
+    assert(`${d.id}: ${r} "${fam}" in catalog`, (() => { try { get(fam); return true; } catch { return false; } })());
+    assert(`${d.id}: ${fam} suits role ${r}`, catalog[fam].roles.includes(r), catalog[fam].roles.join(","));
+  }
+  assert(`${d.id}: has name/vibe/rationale`, !!(d.name && d.vibe && d.rationale));
+}
+
+const fresh = { replaces: { display: "Inter", body: "Inter", mono: "JetBrains Mono" } };
+
+const a = curate(fresh);
+const b = curate(fresh);
+assert("curate is deterministic (same input → same output)", deep(a, b));
+assert("curate returns 5 by default", a.length === 5, String(a.length));
+assert("curate respects count", curate(fresh, { count: 3 }).length === 3);
+
+// excludes no-op directions (display+body already current)
+const onGeist = { replaces: { display: "Geist", body: "Geist", mono: "Geist Mono" } };
+assert("curate drops a direction that wouldn't change the site", !curate(onGeist, { count: 12 }).some((d) => d.id === "clean-geometric"));
+
+// vibe ranking puts the matching vibe first
+const ed = curate(fresh, { vibe: "editorial" });
+assert("vibe=editorial ranks an editorial direction first", ed[0].vibe === "editorial", ed[0].vibe);
+const minimal = curate(fresh, { vibe: "minimal" });
+assert("vibe=minimal ranks a minimal direction first", minimal[0].vibe === "minimal", minimal[0].vibe);
+
+// rationale becomes concrete about what it replaces
+assert("rationale names the replaced font when known", a.some((d) => /replaces Inter/.test(d.rationale)));
+
+// fontsForDirections returns catalog members only
+const used = fontsForDirections(a);
+assert("fontsForDirections returns catalog members", used.length > 0 && used.every((f) => !!catalog[f]));
+
+const failed = results.filter((r) => !r.pass);
+writeFileSync(OUT + "m4-report.json", JSON.stringify({ catalogSize: families.length, directions: directions.length, results }, null, 2));
+console.log(`\nM4: ${results.length - failed.length}/${results.length} assertions passed  (catalog ${families.length} fonts, ${directions.length} authored directions)`);
+if (failed.length) {
+  console.error("FAILED:", failed.map((f) => f.name).join(", "));
+  process.exit(5);
+}
+console.log("M4 PASS");

package/m5-test.mjs

@@ -0,0 +1,142 @@
+// M5 verification — the engine facade and the MCP server. The engine logic is offline; the
+// MCP server is exercised over real stdio (spawn → initialize → tools/list → tools/call).
+// Option 3 is the heart of it: the agent can compose its own directions, but only from the
+// catalog, and the human is always the one who picks (we only ever prepare a preview).
+
+import * as engine from "./engine.mjs";
+import { spawn } from "node:child_process";
+import { writeFileSync, mkdirSync, rmSync, cpSync, existsSync } 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 + ".m5-tmp/";
+mkdirSync(OUT, { recursive: true });
+const CLEAN = path.join(ROOT, "examples/clean-next-site");
+
+const results = [];
+const assert = (name, cond, extra = "") => {
+  results.push({ name, pass: !!cond });
+  console.log((cond ? "PASS" : "FAIL").padEnd(5), name, extra && !cond ? `(${extra})` : "");
+};
+
+try {
+  rmSync(TMP, { recursive: true, force: true });
+
+  // ===================================================================== //
+  //  Part 1 — the engine facade                                           //
+  // ===================================================================== //
+
+  const a = engine.analyze(CLEAN);
+  assert("analyze returns target + current", a.framework === "next" && "replaces" in a);
+
+  const cat = engine.listCatalog({ role: "mono" });
+  assert("listCatalog filters by role (mono)", cat.length > 0 && cat.every((f) => f.roles.includes("mono")));
+  assert("listCatalog filters by tag (serif)", engine.listCatalog({ tag: "serif" }).every((f) => f.tags.includes("serif")));
+
+  const { directions: curated } = engine.curate(CLEAN);
+  assert("curate returns the default menu (~5)", curated.length === 5);
+
+  // option 3: agent composes its own directions from the catalog
+  const composed = engine.composeDirections([
+    { name: "My Pick", vibe: "editorial", display: "Playfair Display", body: "Inter", mono: "Geist Mono" },
+  ]);
+  assert("composeDirections accepts catalog fonts", composed.directions.length === 1 && composed.directions[0].roles.display.family === "Playfair Display");
+  assert("composeDirections normalizes id + weights", !!composed.directions[0].id && Array.isArray(composed.directions[0].roles.body.weights));
+
+  // option 3 guard: a non-catalog font is refused with a helpful error
+  let refused = false, msg = "";
+  try {
+    engine.composeDirections([{ display: "Comic Sans MS", body: "Inter", mono: "Geist Mono" }]);
+  } catch (e) {
+    refused = true;
+    msg = e.message;
+  }
+  assert("composeDirections refuses non-catalog fonts", refused && /not in the Font Lab catalog/.test(msg), msg);
+
+  // preparePreview without network (fetch:false) builds the generated module from composed dirs
+  const proj = path.join(TMP, "clean");
+  mkdirSync(path.join(proj, "app/_fontlab"), { recursive: true });
+  for (const f of ["package.json", "app/layout.tsx", "app/globals.css"]) cpSync(path.join(CLEAN, f), path.join(proj, f));
+  const prep = await engine.preparePreview(proj, { directions: composed.directions, fetch: false });
+  assert("preparePreview writes catalog.generated.ts", existsSync(prep.outPath));
+  assert("preparePreview reports prepared fonts", prep.prepared.includes("Playfair Display"));
+
+  // readSelection: null before a pick, the object after
+  assert("readSelection is null before a pick", engine.readSelection(proj) === null);
+  mkdirSync(path.join(proj, ".font-lab"), { recursive: true });
+  writeFileSync(path.join(proj, ".font-lab/selection.json"), JSON.stringify({ version: 1, direction: { id: "x" } }));
+  assert("readSelection returns the pick after one exists", engine.readSelection(proj)?.direction?.id === "x");
+
+  // ===================================================================== //
+  //  Part 2 — the MCP server over real stdio                              //
+  // ===================================================================== //
+
+  const server = spawn("node", [HERE + "mcp.mjs"], { stdio: ["pipe", "pipe", "inherit"] });
+  const pending = new Map();
+  let sbuf = "";
+  server.stdout.setEncoding("utf8");
+  server.stdout.on("data", (chunk) => {
+    sbuf += chunk;
+    let nl;
+    while ((nl = sbuf.indexOf("\n")) !== -1) {
+      const line = sbuf.slice(0, nl).trim();
+      sbuf = sbuf.slice(nl + 1);
+      if (!line) continue;
+      const msg = JSON.parse(line);
+      if (msg.id && pending.has(msg.id)) {
+        pending.get(msg.id)(msg);
+        pending.delete(msg.id);
+      }
+    }
+  });
+  let nextId = 1;
+  const rpc = (method, params) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, resolve);
+      server.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+      setTimeout(() => reject(new Error(`timeout: ${method}`)), 15000);
+    });
+
+  try {
+    const init = await rpc("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "test", version: "0" } });
+    assert("MCP initialize returns serverInfo", init.result?.serverInfo?.name === "font-lab");
+    assert("MCP initialize advertises tools capability", !!init.result?.capabilities?.tools);
+    server.stdin.write(JSON.stringify({ jsonrpc: "2.0", method: "notifications/initialized" }) + "\n");
+
+    const list = await rpc("tools/list", {});
+    const names = list.result.tools.map((t) => t.name);
+    for (const t of ["font_lab_analyze", "font_lab_list_catalog", "font_lab_curate", "font_lab_compose_directions", "font_lab_init", "font_lab_uninit", "font_lab_prepare_preview", "font_lab_read_pick", "font_lab_apply", "font_lab_rewire_dead_roles", "font_lab_undo"])
+      assert(`MCP exposes ${t}`, names.includes(t));
+    assert("MCP tool descriptions mention the human keeps the pick", list.result.tools.some((t) => /human/i.test(t.description)));
+
+    const an = await rpc("tools/call", { name: "font_lab_analyze", arguments: { projectDir: CLEAN } });
+    const anObj = JSON.parse(an.result.content[0].text);
+    assert("MCP analyze call returns analysis", anObj.framework === "next");
+
+    const cu = await rpc("tools/call", { name: "font_lab_curate", arguments: { projectDir: CLEAN, count: 3 } });
+    assert("MCP curate call returns 3 directions", JSON.parse(cu.result.content[0].text).length === 3);
+
+    const bad = await rpc("tools/call", { name: "font_lab_compose_directions", arguments: { directions: [{ display: "Nope", body: "Inter", mono: "Geist Mono" }] } });
+    assert("MCP surfaces tool errors in-band (isError)", bad.result.isError === true && /not in the Font Lab catalog/.test(bad.result.content[0].text));
+
+    const unknown = await rpc("tools/call", { name: "font_lab_nope", arguments: {} });
+    assert("MCP rejects unknown tool", !!unknown.error);
+  } finally {
+    server.kill();
+  }
+} finally {
+  rmSync(TMP, { recursive: true, force: true });
+}
+
+const failed = results.filter((r) => !r.pass);
+writeFileSync(OUT + "m5-report.json", JSON.stringify({ results }, null, 2));
+console.log(`\nM5: ${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("M5 PASS");

package/m6-test.mjs

@@ -0,0 +1,119 @@
+// M6 verification — drive the polished choosing moment in a real browser and prove the new
+// powers actually work on the running fixture: mixed picks (display from A, body from B),
+// before/after, pin-two-to-compare, and multi-route persistence. Spawns the CLI endpoint;
+// expects the fixture 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:4332";
+const HERE = fileURLToPath(new URL("./", import.meta.url));
+const APP = fileURLToPath(new URL("../examples/sample-next-site/", import.meta.url));
+const SEL = path.join(APP, ".font-lab", "selection.json");
+mkdirSync(HERE + "out", { recursive: true });
+rmSync(path.join(APP, ".font-lab"), { recursive: true, force: true });
+
+const cli = spawn("node", [HERE + "font-lab.mjs", "--project", APP, "--port", "7777"], { stdio: "inherit" });
+for (let i = 0; i < 40; i++) {
+  try { if ((await fetch("http://localhost:7777/health")).ok) break; } catch {}
+  await new Promise((r) => setTimeout(r, 250));
+}
+
+const results = [];
+const assert = (name, cond, extra = "") => {
+  results.push({ name, pass: !!cond });
+  console.log((cond ? "PASS" : "FAIL").padEnd(5), name, extra && !cond ? `(${extra})` : "");
+};
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 1000 } });
+
+const SHADOW = `document.getElementById("fontlab-panel-host").shadowRoot`;
+const click = (sel) => page.evaluate((s) => eval(s.host).querySelector(s.sel).click(), { host: SHADOW, sel });
+const famRow = (role) => page.evaluate((s) => eval(s.host).querySelector(`[data-fl-fam="${s.role}"]`).textContent, { host: SHADOW, role });
+const activeId = () => page.evaluate(() => document.documentElement.getAttribute("data-fontlab-active"));
+const bodyFont = () => page.evaluate(() => getComputedStyle(document.body).fontFamily);
+const dispFont = () => page.evaluate(() => getComputedStyle(document.querySelector("h1")).fontFamily);
+const settle = async () => { await page.evaluate(async () => { await document.fonts.ready; }); await page.waitForTimeout(180); };
+const readSel = () => (existsSync(SEL) ? JSON.parse(readFileSync(SEL, "utf8")) : null);
+const blur = () => page.mouse.click(3, 3);
+
+try {
+  await page.goto(BASE + "/", { waitUntil: "domcontentloaded" });
+  await settle();
+  await blur();
+  assert("starts on current (Inter)", (await activeId()) === "current" && /Inter/i.test(await bodyFont()), await bodyFont());
+
+  // ---- Mixed pick: display from Editorial, body swapped to another direction's font ----
+  await click('button[data-fl-id="editorial-serif"]');
+  await settle();
+  assert("editorial: display Fraunces", /FL Fraunces/i.test(await dispFont()), await dispFont());
+  assert("editorial: body Libre Franklin", /FL Libre Franklin/i.test(await bodyFont()), await bodyFont());
+
+  await click('[data-fl-inc="body"]'); // cycle just the body role
+  await settle();
+  const mixedBody = await bodyFont();
+  assert("mixed: body changed independently", !/Libre Franklin/i.test(mixedBody) && /FL /.test(mixedBody), mixedBody);
+  assert("mixed: display still Fraunces", /FL Fraunces/i.test(await dispFont()), await dispFont());
+  assert("mixed: active flips to 'mixed'", (await activeId()) === "mixed", await activeId());
+  const bodyFam = await famRow("body");
+
+  await click('[data-fl-action="pick"]');
+  let sel = null;
+  for (let i = 0; i < 40; i++) { sel = readSel(); if (sel) break; await page.waitForTimeout(150); }
+  assert("mixed pick written", !!sel);
+  assert("mixed pick: direction id = mixed", sel?.direction?.id === "mixed", sel?.direction?.id);
+  assert("mixed pick: display = Fraunces", sel?.roles?.display?.family === "Fraunces");
+  assert("mixed pick: body = the swapped font", sel?.roles?.body?.family === bodyFam, `${sel?.roles?.body?.family} vs ${bodyFam}`);
+  assert("mixed pick: display ≠ body (it's a real mix)", sel?.roles?.display?.family !== sel?.roles?.body?.family);
+
+  // ---- Before / after ----
+  await click('[data-fl-action="compare"]');
+  await settle();
+  assert("before/after shows current", (await activeId()) === "current" && /Inter/i.test(await bodyFont()), await bodyFont());
+  await click('[data-fl-action="compare"]');
+  await settle();
+  assert("before/after restores the build", (await activeId()) === "mixed");
+
+  // ---- Pin two to compare ----
+  await click('[data-fl-action="pin"]'); // pin A (the mix)
+  await click('button[data-fl-id="clean-geometric"]'); // build B
+  await settle();
+  await click('[data-fl-action="pin"]'); // pin B
+  await blur();
+  await page.keyboard.press(" ");
+  await settle();
+  const firstShown = await bodyFont();
+  await blur();
+  await page.keyboard.press(" ");
+  await settle();
+  const secondShown = await bodyFont();
+  assert("pin compare toggles between A and B", firstShown !== secondShown, `${firstShown} / ${secondShown}`);
+  assert("one of the pinned views is Geist (clean-geometric)", /FL Geist/i.test(firstShown) || /FL Geist/i.test(secondShown));
+
+  // ---- Multi-route: re-establish a mix, navigate, confirm it persists ----
+  await click('button[data-fl-id="editorial-serif"]');
+  await click('[data-fl-inc="body"]');
+  await settle();
+  const homeBody = await bodyFont();
+  await page.goto(BASE + "/dense", { waitUntil: "domcontentloaded" });
+  await settle();
+  assert("panel persists across route nav (multi-route)", (await bodyFont()) === homeBody, `${await bodyFont()} vs ${homeBody}`);
+  assert("dense route renders the mixed display too", /FL Fraunces/i.test(await dispFont()), await dispFont());
+  await page.screenshot({ path: HERE + "out/m6-dense.png" });
+} finally {
+  await browser.close();
+  cli.kill();
+}
+
+const failed = results.filter((r) => !r.pass);
+writeFileSync(HERE + "out/m6-report.json", JSON.stringify({ results, finalSelection: readSel() }, null, 2));
+console.log(`\nM6: ${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("M6 PASS");

package/mcp.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+// Font Lab MCP server (M5) — wraps the engine so an agent can drive the whole loop:
+//   analyze → (curate OR list_catalog + compose_directions) → prepare_preview → read_pick → apply
+//
+// Minimal, dependency-free JSON-RPC 2.0 over stdio (newline-delimited messages, per the MCP
+// stdio transport). Protocol on stdout; all logging on stderr.
+//
+// Discoverability ("SEO for agents") lives in the tool descriptions below: they're written so
+// an agent reaches for Font Lab the moment a user wants to choose, change, or improve fonts —
+// and so it understands the contract (the HUMAN picks; the agent curates and ships).
+
+import * as engine from "./engine.mjs";
+
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER = { name: "font-lab", version: "0.7.0" };
+const log = (...a) => process.stderr.write("[font-lab mcp] " + a.join(" ") + "\n");
+
+const proj = { type: "string", description: "Absolute path to the user's Next.js + Tailwind project root." };
+
+const TOOLS = [
+  {
+    name: "font_lab_analyze",
+    description:
+      "Audit a Next.js + Tailwind project's CURRENT typography before changing it: framework, App/Pages router, Tailwind version, the current display/body/mono fonts, how they're wired, and coverage warnings (e.g. a font that's declared but not actually rendered). ALWAYS run this first when a user wants to pick, change, or improve fonts.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.analyze(a.projectDir),
+  },
+  {
+    name: "font_lab_list_catalog",
+    description:
+      "Browse Font Lab's curated catalog of ship-ready variable Google fonts (each verified for capsize/CLS-safe parity). Filter by role ('display'|'body'|'mono') or vibe tag (e.g. 'editorial','geometric','serif','technical'). Use this to compose your OWN font directions when the default curation isn't what the user asked for.",
+    inputSchema: {
+      type: "object",
+      properties: { role: { type: "string", enum: ["display", "body", "mono"] }, tag: { type: "string" } },
+    },
+    handler: (a) => engine.listCatalog({ role: a.role, tag: a.tag }),
+  },
+  {
+    name: "font_lab_curate",
+    description:
+      "Get ~5 tasteful, ready-to-preview font directions for a project (display+body+mono pairings with a name, vibe, and rationale). Deterministic, no LLM — a strong DEFAULT menu that moves off the project's current fonts. Pass an optional 'vibe' to steer it. You can also ignore this and compose your own with list_catalog + compose_directions.",
+    inputSchema: {
+      type: "object",
+      properties: { projectDir: proj, vibe: { type: "string" }, count: { type: "number" } },
+      required: ["projectDir"],
+    },
+    handler: (a) => engine.curate(a.projectDir, { vibe: a.vibe, count: a.count }).directions,
+  },
+  {
+    name: "font_lab_compose_directions",
+    description:
+      "Assemble your OWN font directions from catalog fonts when you want to tailor the options to the user's request (this is how the agent takes the wheel on the menu). Each direction needs display, body, and mono families. Every family MUST be a catalog member (run list_catalog) — that's what guarantees the preview matches what ships. Returns validated, preview-ready directions (and warnings for unusual role choices).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        directions: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              vibe: { type: "string" },
+              rationale: { type: "string" },
+              display: { type: "string" },
+              body: { type: "string" },
+              mono: { type: "string" },
+            },
+            required: ["display", "body", "mono"],
+          },
+        },
+      },
+      required: ["directions"],
+    },
+    handler: (a) => engine.composeDirections(a.directions),
+  },
+  {
+    name: "font_lab_init",
+    description:
+      "SET UP Font Lab in the project so the human can preview live — self-hosts the parity bundles, installs the dev panel, and mounts it (dev-only) in the layout. This is the one-shot setup: run it after font_lab_analyze, then start the dev server and tell the human to flip fonts in the panel (bottom-right) and Pick. Idempotent and reversible (font_lab_uninit). Reports any dead roles (offer font_lab_rewire_dead_roles).",
+    inputSchema: {
+      type: "object",
+      properties: { projectDir: proj, vibe: { type: "string" }, count: { type: "number" } },
+      required: ["projectDir"],
+    },
+    handler: (a) => engine.init(a.projectDir, { vibe: a.vibe, count: a.count, log }),
+  },
+  {
+    name: "font_lab_uninit",
+    description: "Remove Font Lab's panel scaffolding from the project (restores the layout, removes the generated panel + self-hosted fonts). Use to clean up if the user doesn't want to keep previewing.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.uninit(a.projectDir),
+  },
+  {
+    name: "font_lab_prepare_preview",
+    description:
+      "Build the LIVE preview bundle (self-hosted woff2 + exact next/font fallbacks) into the user's project so the HUMAN can flip through the directions on their real running site and pick one. Pass either curated/composed 'directions' or a 'vibe'. Font Lab keeps the taste decision with the human — this never auto-selects. (Fetches fonts from Google.)",
+    inputSchema: {
+      type: "object",
+      properties: { projectDir: proj, directions: { type: "array", items: { type: "object" } }, vibe: { type: "string" }, count: { type: "number" } },
+      required: ["projectDir"],
+    },
+    handler: (a) => engine.preparePreview(a.projectDir, { directions: a.directions, vibe: a.vibe, count: a.count, log }),
+  },
+  {
+    name: "font_lab_read_pick",
+    description:
+      "Read the human's pick (.font-lab/selection.json). Returns null until they've chosen in the panel. Poll this after prepare_preview; ship it with font_lab_apply once present.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.readSelection(a.projectDir),
+  },
+  {
+    name: "font_lab_apply",
+    description:
+      "Ship the human's pick: apply the exact next/font + Tailwind edits to the project, idempotently and reversibly (backup-first). Refuses out-of-branch projects with a clear reason. Run after read_pick returns a selection.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.apply(a.projectDir),
+  },
+  {
+    name: "font_lab_rewire_dead_roles",
+    description:
+      "Fix a role that font_lab_analyze flags as DEAD — declared but not actually rendered (common with Tailwind v4 @theme inline + a hand-written `font-family: var(--font-display)`, which resolves to nothing). Points those raw usages at the published leaf variable so the font renders, making the swap visible. Reversible via font_lab_undo. Offer this when analyze reports dead roles and the user wants that role to actually change.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.rewire(a.projectDir),
+  },
+  {
+    name: "font_lab_undo",
+    description: "Revert Font Lab's last apply or rewire, restoring the edited files byte-for-byte from the backup.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.undo(a.projectDir),
+  },
+  {
+    name: "font_lab_screenshot_directions",
+    description:
+      "HEADLESS pick mode — when the human has no live browser to flip in (a web/cloud session, or they're on a phone), screenshot the running site in each curated direction so they can pick from IMAGES instead of a live panel. Requires font_lab_init done and the project's dev server running; pass its baseUrl (e.g. http://localhost:3000). Returns a manifest of {id, name, vibe, rationale, fonts, screenshot path} per direction (plus a 'current' before-shot) — SHOW these images to the human and ask them to pick an id. The screenshots are driven through the real preview panel, so they are faithful to what ships. Makes no edits.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectDir: proj,
+        baseUrl: { type: "string", description: "The running dev server URL, e.g. http://localhost:3000." },
+        routes: { type: "array", items: { type: "string" }, description: "Route(s) to capture; defaults to ['/']." },
+        outDir: { type: "string", description: "Where to write PNGs; defaults to <project>/.font-lab/previews." },
+      },
+      required: ["projectDir", "baseUrl"],
+    },
+    handler: (a) => engine.captureDirections(a.projectDir, { baseUrl: a.baseUrl, routes: a.routes, outDir: a.outDir }),
+  },
+  {
+    name: "font_lab_select",
+    description:
+      "Record the human's pick by direction id — the HEADLESS counterpart to clicking Pick in the panel. Use AFTER the human has chosen from the screenshots (you must still let the HUMAN make the call — never auto-select). Writes the same selection.json the panel writes, so font_lab_apply ships it identically. Supports a mixed pick: pass roles {display, body, mono} as direction ids to take each role from a different direction.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        projectDir: proj,
+        directionId: { type: "string", description: "The id the human picked (from curate/screenshots)." },
+        roles: {
+          type: "object",
+          description: "Optional mixed pick — per-role direction ids, e.g. {display:'editorial-serif', body:'modern-grotesque'}.",
+          properties: { display: { type: "string" }, body: { type: "string" }, mono: { type: "string" } },
+        },
+      },
+      required: ["projectDir", "directionId"],
+    },
+    handler: (a) => engine.selectDirection(a.projectDir, { directionId: a.directionId, roles: a.roles }),
+  },
+  {
+    name: "font_lab_live_instructions",
+    description:
+      "Get ready-to-run commands to launch the FULL live editor (flip / mix / compare directions in a real browser) — for when the headless screenshots aren't enough and the human wants to drive it themselves. Detects the project's dev command. These run in a local terminal: a Mac/Linux terminal or the integrated terminal in VS Code / Cursor / the Claude Code IDE extension.",
+    inputSchema: { type: "object", properties: { projectDir: proj }, required: ["projectDir"] },
+    handler: (a) => engine.liveInstructions(a.projectDir),
+  },
+];
+
+const send = (msg) => process.stdout.write(JSON.stringify(msg) + "\n");
+const reply = (id, result) => send({ jsonrpc: "2.0", id, result });
+const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+
+async function handle(msg) {
+  const { id, method, params } = msg;
+  const isNotification = id === undefined || id === null;
+  try {
+    if (method === "initialize") {
+      return reply(id, { protocolVersion: PROTOCOL_VERSION, capabilities: { tools: {} }, serverInfo: SERVER });
+    }
+    if (method === "notifications/initialized" || method === "notifications/cancelled") return; // notifications
+    if (method === "ping") return reply(id, {});
+    if (method === "tools/list") {
+      return reply(id, { tools: TOOLS.map(({ name, description, inputSchema }) => ({ name, description, inputSchema })) });
+    }
+    if (method === "tools/call") {
+      const tool = TOOLS.find((t) => t.name === params?.name);
+      if (!tool) return fail(id, -32602, `unknown tool: ${params?.name}`);
+      try {
+        const out = await tool.handler(params.arguments || {});
+        return reply(id, { content: [{ type: "text", text: JSON.stringify(out, null, 2) }] });
+      } catch (e) {
+        // tool-level errors are reported in-band so the agent can react
+        return reply(id, { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true });
+      }
+    }
+    if (!isNotification) fail(id, -32601, `method not found: ${method}`);
+  } catch (e) {
+    if (!isNotification) fail(id, -32603, e.message);
+  }
+}
+
+let buf = "";
+process.stdin.setEncoding("utf8");
+process.stdin.on("data", (chunk) => {
+  buf += chunk;
+  let nl;
+  while ((nl = buf.indexOf("\n")) !== -1) {
+    const line = buf.slice(0, nl).trim();
+    buf = buf.slice(nl + 1);
+    if (!line) continue;
+    let msg;
+    try {
+      msg = JSON.parse(line);
+    } catch {
+      log("parse error:", line.slice(0, 120));
+      continue;
+    }
+    handle(msg);
+  }
+});
+process.stdin.on("end", () => process.exit(0));
+log(`ready — ${TOOLS.length} tools, protocol ${PROTOCOL_VERSION}`);

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "font-lab",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Font Lab — a decision surface for typography in Next.js + Tailwind apps. Curate tasteful font directions on your real running site, let a human pick, and ship the exact next/font + Tailwind code. Installs as an agent skill + MCP server.",
+  "keywords": [
+    "fonts",
+    "typography",
+    "nextjs",
+    "next-font",
+    "tailwindcss",
+    "claude",
+    "claude-code",
+    "mcp",
+    "agent",
+    "skill"
+  ],
+  "license": "MIT",
+  "author": "jmg698",
+  "homepage": "https://github.com/jmg698/Font-Lab#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jmg698/Font-Lab.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/jmg698/Font-Lab/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "font-lab": "./font-lab.mjs",
+    "font-lab-install": "./install.mjs",
+    "font-lab-apply": "./apply.mjs",
+    "font-lab-undo": "./undo.mjs",
+    "font-lab-rewire": "./rewire.mjs",
+    "font-lab-analyze": "./analyze.mjs",
+    "font-lab-curate": "./curate.mjs",
+    "font-lab-init": "./init.mjs",
+    "font-lab-screenshots": "./screenshots.mjs",
+    "font-lab-select": "./select.mjs",
+    "font-lab-mcp": "./mcp.mjs"
+  },
+  "files": [
+    "*.mjs",
+    "templates/",
+    "skill/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "gen": "node gen-catalog.mjs",
+    "start": "node font-lab.mjs",
+    "setup": "node install.mjs",
+    "analyze": "node analyze.mjs",
+    "curate": "node curate.mjs",
+    "apply": "node apply.mjs",
+    "undo": "node undo.mjs",
+    "rewire": "node rewire.mjs",
+    "mcp": "node mcp.mjs",
+    "prepack": "node bundle-skill.mjs",
+    "m1": "bash run-m1.sh",
+    "m2": "bash run-m2.sh",
+    "m3": "bash run-m3.sh",
+    "m4": "bash run-m4.sh",
+    "m5": "bash run-m5.sh",
+    "m6": "bash run-m6.sh"
+  },
+  "dependencies": {
+    "@capsizecss/metrics": "^3.4.0",
+    "ts-morph": "^28.0.0"
+  },
+  "devDependencies": {
+    "playwright": "1.56.1"
+  }
+}