@struq/skill 0.3.0 → 0.4.0

package/skills/struq/scripts/blocks.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+// Struq blocks, offline: the skill's own copy of Struq's admitted blocks (blocks/, catalog.json), installed into a
+// Next.js App Router project. The same files the MCP's struq_blok returns.
+//
+//   node <skill-dir>/scripts/blocks.mjs list [kind]          the catalogue, one line per block with its variants
+//   node <skill-dir>/scripts/blocks.mjs init                 the kit, the app shell (on a starter) and the base packages
+//   node <skill-dir>/scripts/blocks.mjs add <slug> [<slug>]  a block and every file it imports, plus its packages
+//   flags: --dir <project>, --force (replace files you already have), --no-install
+//
+// Everything lands under components/struq/ in the layout of Struq's blocks/ (kit/, heroes/, sections/ ...), so the
+// relative imports between them hold. A layout or stylesheet you wrote yourself is never overwritten.
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendLog } from "./log.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const BLOCKS = join(here, "..", "blocks");
+const RECIPES = join(here, "..", "recipes");
+const CATALOG = JSON.parse(readFileSync(join(BLOCKS, "catalog.json"), "utf8")).blocks;
+
+const args = process.argv.slice(2);
+const dirAt = args.indexOf("--dir");
+const root = resolve(dirAt >= 0 ? args[dirAt + 1] : process.cwd());
+const force = args.includes("--force");
+const install = !args.includes("--no-install");
+const [cmd, ...rest] = args.filter((x, i) => !x.startsWith("--") && (dirAt < 0 || i !== dirAt + 1));
+
+const src = existsSync(join(root, "src", "app")) ? "src" : "";
+const target = (...p) => join(root, src, "components", "struq", ...p);
+const copied = [];
+const kept = [];
+const notes = [];
+
+function place(from, to, overwrite = force) {
+  if (existsSync(to) && !overwrite) return kept.push(relative(root, to));
+  mkdirSync(dirname(to), { recursive: true });
+  copyFileSync(from, to);
+  copied.push(relative(root, to).split("\\").join("/"));
+}
+
+function walk(dir) {
+  return readdirSync(dir).flatMap((n) => (statSync(join(dir, n)).isDirectory() ? walk(join(dir, n)) : [join(dir, n)]));
+}
+
+function project() {
+  const pkgPath = join(root, "package.json");
+  if (!existsSync(pkgPath)) {
+    console.error(`FAIL no package.json in ${root}. Scaffold first: npx create-next-app@latest . --ts --tailwind --app --eslint --yes`);
+    process.exit(2);
+  }
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  if (!deps.next) {
+    console.error("FAIL not a Next.js project. The blocks use next/image and next/link; for Vite read references/stack-targets.md.");
+    process.exit(2);
+  }
+  return deps;
+}
+
+function installMissing(deps, wanted) {
+  const need = [...wanted].filter((d) => !deps[d]);
+  const dev = need.filter((d) => d.startsWith("@types/"));
+  const runtime = need.filter((d) => !d.startsWith("@types/"));
+  for (const [list, flag] of [[runtime, ""], [dev, "-D "]]) {
+    if (!list.length) continue;
+    const line = `npm install ${flag}${list.join(" ")}`;
+    if (!install) {
+      notes.push(`Run: ${line}`);
+      continue;
+    }
+    console.log(`> ${line}`);
+    if (spawnSync(line, { cwd: root, stdio: "inherit", shell: true }).status !== 0) notes.push(`The install failed. Run it yourself: ${line}`);
+  }
+}
+
+function report(step, what) {
+  console.log(`\nCopied ${copied.length} file(s)${copied.length ? ":" : "."}`);
+  for (const f of copied) console.log(`  ${f}`);
+  if (kept.length) console.log(`Kept ${kept.length} existing file(s) (--force replaces them).`);
+  for (const n of notes) console.log(`NOTE ${n}`);
+  appendLog(root, step, [what, ...(notes.length ? [`Notes: ${notes.join(" ")}`] : [])]);
+}
+
+const commands = {
+  list() {
+    const kind = rest[0];
+    const rows = CATALOG.filter((b) => !kind || b.kind === kind);
+    if (!rows.length) throw new Error(`No blocks of kind "${kind}". Kinds: ${[...new Set(CATALOG.map((b) => b.kind))].join(", ")}`);
+    for (const b of rows) {
+      console.log(`${b.kind.padEnd(16)} ${b.slug.padEnd(24)} ${b.title}${b.variants.length ? `  [${b.variants.map((v) => v.id).join(", ")}]` : ""}`);
+    }
+    console.log(`\n${rows.length} block(s). What each does and its variants: blocks/CATALOG.md.`);
+  },
+
+  init() {
+    const deps = project();
+    // The kit, minus the WebGL hero layer: HeroCanvas and its scenes need three, so they come with hero-opener.
+    for (const f of walk(join(BLOCKS, "kit"))) {
+      const r = relative(join(BLOCKS, "kit"), f).split("\\").join("/");
+      if (r === "HeroCanvas.tsx" || r.startsWith("scenes/")) continue;
+      place(f, target("kit", r));
+    }
+    const appDir = join(root, src, "app");
+    const read = (p) => (existsSync(p) ? readFileSync(p, "utf8") : "");
+    const layout = read(join(appDir, "layout.tsx"));
+    if (!layout || /Create Next App|Geist/.test(layout) || force) place(join(RECIPES, "app", "layout.tsx"), join(appDir, "layout.tsx"), true);
+    else if (!/data-blocks/.test(layout)) {
+      notes.push("app/layout.tsx is your own: add the sq-js script, the font links, data-blocks on <body> and <SmoothScroll> (recipes/app/layout.tsx).");
+    }
+    const css = read(join(appDir, "globals.css"));
+    if (!css || (!css.includes("STRUQ TOKENS") && /--background|--foreground|Arial|prefers-color-scheme/.test(css)) || force) {
+      place(join(RECIPES, "app", "globals.css"), join(appDir, "globals.css"), true);
+    } else if (!css.includes("STRUQ TOKENS")) notes.push("app/globals.css is your own: add the kit import and the STRUQ TOKENS block from recipes/app/globals.css.");
+    place(join(RECIPES, "app", "fonts.ts"), join(appDir, "fonts.ts"));
+    for (const starter of ["next.svg", "vercel.svg", "file.svg", "globe.svg", "window.svg"]) rmSync(join(root, "public", starter), { force: true });
+    installMissing(deps, ["gsap", "@gsap/react", "lenis"]);
+    report("Step 1 Project", `blocks.mjs init copied the kit and ${copied.length} file(s) in all, kept ${kept.length}.`);
+    console.log("OK init ready");
+  },
+
+  add() {
+    if (!rest.length) throw new Error("Usage: blocks.mjs add <slug> [<slug> ...]. The slugs: blocks.mjs list");
+    const deps = project();
+    const wanted = new Set();
+    const added = [];
+    for (const slug of rest) {
+      const b = CATALOG.find((x) => x.slug === slug);
+      if (!b) throw new Error(`Unknown block "${slug}". Run: blocks.mjs list`);
+      for (const f of b.files) place(join(BLOCKS, f), target(f));
+      for (const p of b.packages) wanted.add(p);
+      added.push(b);
+    }
+    installMissing(deps, wanted);
+    for (const b of added) {
+      const from = `@/components/struq/${b.file.replace(/\.tsx?$/, "")}`;
+      console.log(`\n${b.slug}: import { ${b.exports.join(", ")} } from "${from}";`);
+      if (b.variants.length) console.log(`  variant: ${b.variants.map((v) => `"${v.id}"`).join(" | ")} (default "${b.variants[0].id}")`);
+    }
+    report("Step 5 Blocks", `blocks.mjs added ${added.map((b) => b.slug).join(", ")}.`);
+    console.log("OK blocks added");
+  },
+};
+
+const run = commands[cmd];
+if (!run) {
+  console.error("Usage: blocks.mjs list [kind] | init | add <slug> [<slug> ...]   [--dir <project>] [--force] [--no-install]");
+  process.exit(2);
+}
+try {
+  run();
+} catch (e) {
+  console.error(`FAIL ${e.message}`);
+  process.exitCode = 1;
+}

package/skills/struq/scripts/canon.mjs

@@ -1,309 +1,134 @@
 #!/usr/bin/env node
-// Struq canon: Struq's own palettes, type pairings and design systems, written into the project.
-// This is what keeps a Struq build off the defaults every AI falls back on.
+// Struq canon, offline: Struq's palettes and type pairings, written into the project as the one token block the
+// blocks read. The same block, derivation and font requests as Struq's block lab and the MCP's struq_richting
+// (scripts/tokens.mjs), from the snapshot in canon/canon.json that the skill's release copies from Struq.
 //
-//   node <skill-dir>/scripts/canon.mjs list                 every palette, pairing, system and pack
-//   node <skill-dir>/scripts/canon.mjs palette <slug>       writes the STRUQ TOKENS block in globals.css
-//   node <skill-dir>/scripts/canon.mjs type <slug>          writes app/fonts.ts (Google or Fontshare)
-//   node <skill-dir>/scripts/canon.mjs type --display "Fraunces" --body "Urbanist"
-//   node <skill-dir>/scripts/canon.mjs system <slug>        prints the section order and its refs
+//   node <skill-dir>/scripts/canon.mjs list                       every palette and pairing
+//   node <skill-dir>/scripts/canon.mjs palette <id>               writes the STRUQ TOKENS block in app/globals.css
+//   node <skill-dir>/scripts/canon.mjs type <id>                  the same block with the pairing, and app/fonts.ts
+//   node <skill-dir>/scripts/canon.mjs print <palette> <pairing>  prints the block and the font URLs, writes nothing
 //   add --dir <project> to run from elsewhere
 //
-// Public API, no account: https://struq.nl/api/assets?filter=palette|typography|design_system
-// Node 18 or later, no dependencies. Google faces load through next/font/google (checked against the
-// project's own next/font data); faces that are not on Google come from Fontshare as local woff2.
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join, resolve } from "node:path";
-import { googleName } from "./font-names.mjs";
+// Node 18 or later, no network, no dependencies.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { appendLog } from "./log.mjs";
+import { fontHrefs, headFamily, lightness, paletteTokens } from "./tokens.mjs";
 
-// STRUQ_API_BASE points a test run at another Struq environment (for example https://staging.struq.nl).
-// Real users never set it: the default is production.
-const API = `${(process.env.STRUQ_API_BASE || "https://struq.nl").replace(/\/+$/, "")}/api`;
+const here = dirname(fileURLToPath(import.meta.url));
+const CANON = JSON.parse(readFileSync(join(here, "..", "canon", "canon.json"), "utf8"));
 const args = process.argv.slice(2);
-const opt = (name) => {
-  const i = args.indexOf(name);
-  return i >= 0 ? args[i + 1] : undefined;
-};
-const root = resolve(opt("--dir") ?? process.cwd());
-const [cmd, slugArg] = args.filter((a, i) => !a.startsWith("--") && !["--dir", "--display", "--body", "--accent"].includes(args[i - 1]));
-
-// Struq's own rules win over a canon entry: these faces never ship (SKILL.md, the tell list).
-const BANNED = new Set(["Inter", "Roboto", "Arial", "Helvetica", "Open Sans", "Poppins", "Montserrat", "Lato", "Geist", "Space Grotesk", "Geist Mono", "JetBrains Mono", "Space Mono", "IBM Plex Mono", "Roboto Mono"]);
-// The text face that replaces a banned one, by the display face it sits under.
-const BODY_FOR = { Fraunces: "Urbanist", Newsreader: "Manrope", Sora: "Instrument Sans", Syne: "Hanken Grotesk", Manrope: "Figtree" };
-// Commercial faces in the canon, and their free stand-ins.
-const STAND_IN = { "Neue Haas Grotesk Text": "General Sans", "Neue Haas Grotesk": "General Sans", "PP Neue Montreal": "General Sans", "Söhne": "General Sans", Canela: "Newsreader", "PP Editorial New": "Instrument Serif", "GT Sectra": "Fraunces" };
+const dirAt = args.indexOf("--dir");
+const root = resolve(dirAt >= 0 ? args[dirAt + 1] : process.cwd());
+const [cmd, a, b] = args.filter((_, i) => dirAt < 0 || (i !== dirAt && i !== dirAt + 1));
 
-async function getJson(url) {
-  const res = await fetch(url, { signal: AbortSignal.timeout(20000), headers: { accept: "application/json" } });
-  if (!res.ok) throw new Error(`${url} answered ${res.status}`);
-  return res.json();
-}
-async function canon(filter) {
-  const all = [];
-  for (let page = 1; page <= 10; page++) {
-    const d = await getJson(`${API}/assets?filter=${filter}&page=${page}`);
-    all.push(...(d.items ?? []));
-    if (!d.hasMore) break;
-  }
-  return all;
-}
-
-function parseOklch(v) {
-  const m = String(v).match(/oklch\(\s*([\d.]+%?)\s+([\d.]+)\s+([\d.]+)/i);
-  if (!m) return null;
-  const L = m[1].endsWith("%") ? parseFloat(m[1]) / 100 : parseFloat(m[1]);
-  return { L, C: parseFloat(m[2]), H: parseFloat(m[3]) };
-}
-function hexLightness(v) {
-  const m = String(v).match(/^#([0-9a-f]{6})$/i);
-  if (!m) return null;
-  const [r, g, b] = [0, 2, 4].map((i) => parseInt(m[1].slice(i, i + 2), 16) / 255);
-  return (Math.max(r, g, b) + Math.min(r, g, b)) / 2;
-}
-const lightness = (v) => parseOklch(v)?.L ?? hexLightness(v) ?? 0.5;
-const isCool = (v) => {
-  const o = parseOklch(v);
-  return o ? o.C > 0.06 && o.H >= 220 && o.H <= 320 : false;
+const palette = (id) => {
+  const p = CANON.palettes.find((x) => x.id === id);
+  if (!p) throw new Error(`Unknown palette "${id}". Run: canon.mjs list`);
+  return p;
 };
+const pairing = (id) => {
+  const t = CANON.pairings.find((x) => x.id === id);
+  if (!t) throw new Error(`Unknown pairing "${id}". Run: canon.mjs list`);
+  return t;
+};
+const faces = (t) => [t.display, t.body, t.accentItalic].filter(Boolean).map(headFamily);
 
-/* ------------------------------------------------------------------ list */
-async function list() {
-  const [palettes, types, systems] = await Promise.all([canon("palette"), canon("typography"), canon("design_system")]);
-  console.log(`PALETTES (${palettes.length}): slug, mood, ground, accent`);
-  for (const p of palettes) {
-    const c = p.data?.colors ?? {};
-    const ground = lightness(c.background) > 0.5 ? "light" : "dark";
-    const note = isCool(c.accent) ? "  (blue or purple accent: only for a brand that is that colour)" : "";
-    console.log(`  ${p.slug.padEnd(38)} ${(p.data?.mood ?? "").padEnd(36)} ${ground.padEnd(6)}${note}`);
-  }
-  console.log(`\nPAIRINGS (${types.length}): slug, display + body as Struq builds them`);
-  for (const t of types) {
-    const plan = planType(t.data.display.name, t.data.body.name);
-    console.log(`  ${t.slug.padEnd(28)} ${plan.display} + ${plan.body}${plan.notes.length ? `  (${plan.notes.join("; ")})` : ""}`);
-  }
-  console.log(`\nDESIGN SYSTEMS (${systems.length}): slug, section order`);
-  for (const s of systems) console.log(`  ${s.slug.padEnd(22)} ${(s.data?.silhouette?.sectionOrder ?? []).join(" > ")}`);
-  try {
-    const packs = await getJson(`${API}/media/packs`);
-    console.log(`\nBEELDBANK PACKS (${packs.packCount}): use with images.mjs`);
-    for (const p of packs.packs) console.log(`  ${p.slug.padEnd(10)} ${p.description.slice(0, 100)}`);
-  } catch (e) {
-    console.log(`\nBEELDBANK: ${e.message}`);
-  }
-}
-
-/* --------------------------------------------------------------- palette */
-async function palette(slug) {
-  const items = await canon("palette");
-  const p = items.find((i) => i.slug === slug);
-  if (!p) throw new Error(`Unknown palette "${slug}". Run: canon.mjs list`);
-  const c = p.data.colors;
-  const dark = lightness(c.background) < 0.5;
-  const accentInk = lightness(c.accent) > 0.62 ? (dark ? c.background : c.text) : dark ? c.text : c.background;
-  const cssPath = ["app/globals.css", "src/app/globals.css"].map((f) => join(root, f)).find(existsSync);
-  if (!cssPath) throw new Error("No app/globals.css. Run recipes.mjs first.");
-  let css = readFileSync(cssPath, "utf8");
-  const weight = css.match(/--display-weight:\s*(\d{3})/)?.[1] ?? "300";
-  const block = `:root {
-  /* canon palette: ${p.slug} (${p.data.mood}) */
-  --surface-0: ${c.background}; /* the page */
-  --surface-1: ${c.surface}; /* one step: panels, the showpiece ground */
-  --surface-2: color-mix(in oklch, var(--surface-1), var(--ink) ${dark ? 9 : 7}%); /* image wells, hover grounds */
-  --surface-3: color-mix(in oklch, var(--surface-1), var(--ink) ${dark ? 18 : 16}%); /* hairline accents, never text */
-  --ink: ${c.text};
-  --ink-muted: color-mix(in oklch, var(--ink) ${dark ? 70 : 66}%, var(--surface-0)); /* secondary text */
-  --accent: ${c.accent}; /* the one accent: the key CTA, one highlight per screen */
-  --accent-ink: ${accentInk}; /* text on the accent */
-  --accent-2: ${c.accentAlt ?? c.surface}; /* a second ground, never a second highlight colour */
-  --line: color-mix(in oklch, var(--ink) 13%, transparent); /* hairlines */
-  --on-photo: ${dark ? c.text : c.background}; /* type over a photo, with a scrim */
-  /* the contrast scene: the palette's inverse and field roles when it has them, else text and ground swapped */
-  --inverse: ${c.inverse ?? (dark ? c.surface : c.text)};
-  --on-inverse: ${c.onInverse ?? c.inverseText ?? (dark ? c.text : c.background)};
-  --field: ${c.field ?? c.accent};
-  --on-field: ${c.onField ?? c.fieldText ?? accentInk};
-  --display-weight: ${weight};
-}`;
-  const re = /(STRUQ TOKENS[\s\S]*?\*\/\s*):root\s*\{[\s\S]*?\n\}/;
-  if (!re.test(css)) throw new Error(`No STRUQ TOKENS block in ${cssPath}. Run recipes.mjs, or merge the block from recipes/app/globals.css.`);
-  css = css.replace(re, `$1${block}`);
-  if (!css.includes("--color-accent-2")) css = css.replace("  --color-line: var(--line);", "  --color-line: var(--line);\n  --color-accent-2: var(--accent-2);");
-  // Projects started before the contrast scene existed get its colour tokens too.
-  if (!css.includes("--color-inverse")) {
-    css = css.replace("  --color-line: var(--line);", "  --color-line: var(--line);\n  --color-inverse: var(--inverse);\n  --color-on-inverse: var(--on-inverse);\n  --color-field: var(--field);\n  --color-on-field: var(--on-field);");
-  }
-  writeFileSync(cssPath, css);
-  console.log(`Wrote palette ${p.slug} to ${cssPath.replace(root, ".")}`);
-  if (isCool(c.accent)) console.log('NOTE blue or purple accent: write "Cool hue: declared because <the brand colour>" in STRUQ.md, or pick a warmer palette.');
-  console.log(`STRUQ.md line:  Palette: ${p.slug} (${p.data.mood})`);
-  appendLog(root, "Step 4 Canon palette", [
-    `canon.mjs wrote palette ${p.slug} (${p.data.mood}) into the STRUQ TOKENS block.`,
-    `Ground ${dark ? "dark" : "light"}, accent ${c.accent}.${isCool(c.accent) ? " Blue or purple accent: needs a Cool hue declaration." : ""}`,
-  ]);
-  console.log("OK palette written");
+export function tokenBlock(p, t) {
+  const lines = paletteTokens(p, t).map(([k, v]) => `  ${k}: ${v};`);
+  return `/* STRUQ TOKENS: palette ${p.id}, type ${t.id}. Written by canon.mjs, the block Struq's lab and struq_richting give. */\n[data-blocks] {\n${lines.join("\n")}\n}`;
 }
 
-/* ------------------------------------------------------------------ type */
-function planType(display, body) {
-  const notes = [];
-  let d = display;
-  let b = body;
-  if (STAND_IN[d]) notes.push(`${d} is commercial, ${STAND_IN[d]} stands in`), (d = STAND_IN[d]);
-  if (STAND_IN[b]) notes.push(`${b} is commercial, ${STAND_IN[b]} stands in`), (b = STAND_IN[b]);
-  if (BANNED.has(d)) notes.push(`${d} is off the Struq list: pick another pairing`), (d = null);
-  if (BANNED.has(b)) {
-    const swap = BODY_FOR[d] ?? "Urbanist";
-    notes.push(`${b} is off the Struq list, ${swap} replaces it`);
-    b = swap;
-  }
-  return { display: d ?? "(none)", body: b, notes, ok: Boolean(d) };
-}
+const BLOCK = /\/\* STRUQ TOKENS[^*]*\*\/\s*\[data-blocks\]\s*\{[\s\S]*?\n\}/;
 
-function googleData() {
-  const p = join(root, "node_modules", "next", "dist", "compiled", "@next", "font", "dist", "google", "font-data.json");
-  return existsSync(p) ? JSON.parse(readFileSync(p, "utf8")) : null;
+function cssFile() {
+  const path = ["app/globals.css", "src/app/globals.css"].map((f) => join(root, f)).find(existsSync);
+  if (!path) throw new Error("No app/globals.css. Run blocks.mjs init first.");
+  return path;
 }
 
-async function fontshare(name, weights) {
-  const slug = name.toLowerCase().replace(/\s+/g, "-");
-  const css = await fetch(`https://api.fontshare.com/v2/css?f[]=${slug}@${weights.join(",")}&display=swap`, { signal: AbortSignal.timeout(20000) }).then((r) => (r.ok ? r.text() : ""));
-  const faces = [...css.matchAll(/@font-face\s*\{([\s\S]*?)\}/g)].map((m) => ({
-    url: m[1].match(/url\('([^']+\.woff2)'\)/)?.[1],
-    weight: m[1].match(/font-weight:\s*(\d+)/)?.[1],
-    style: m[1].match(/font-style:\s*(\w+)/)?.[1] ?? "normal",
-  })).filter((f) => f.url && f.weight);
-  if (!faces.length) return null;
-  const dir = join(root, existsSync(join(root, "src", "app")) ? "src/app" : "app", "fonts");
-  mkdirSync(dir, { recursive: true });
-  const src = [];
-  for (const f of faces) {
-    const file = `${slug}-${f.weight}${f.style === "italic" ? "-italic" : ""}.woff2`;
-    const res = await fetch(f.url.startsWith("//") ? `https:${f.url}` : f.url, { signal: AbortSignal.timeout(30000) });
-    if (!res.ok) continue;
-    writeFileSync(join(dir, file), Buffer.from(await res.arrayBuffer()));
-    src.push({ path: `./fonts/${file}`, weight: f.weight, style: f.style });
-  }
-  return src.length ? src : null;
+function write(p, t) {
+  const path = cssFile();
+  const css = readFileSync(path, "utf8");
+  if (!BLOCK.test(css)) throw new Error(`No STRUQ TOKENS block in ${path}. Run blocks.mjs init, or copy the block from recipes/app/globals.css.`);
+  writeFileSync(path, css.replace(BLOCK, tokenBlock(p, t)));
+  return path;
 }
 
-async function faceCode(canonName, role, google) {
-  const variable = `--face-${role}`;
-  const id = role;
-  // The canon's name ("Big Shoulders Display") may be listed by Google under its family ("Big Shoulders").
-  const name = googleName(canonName, google) ?? canonName;
-  const g = google?.[name];
-  if (g) {
-    const ident = name.replace(/\s+/g, "_");
-    const parts = [`subsets: ["latin"]`];
-    const italicOnly = role === "accent";
-    if (!g.weights.includes("variable")) {
-      const wanted = g.weights.filter((w) => ["300", "400", "500"].includes(w));
-      parts.push(`weight: ${JSON.stringify(wanted.length ? wanted : [g.weights[0]])}`);
-    }
-    const axes = (g.axes ?? []).map((a) => a.tag).filter((t) => ["opsz", "SOFT"].includes(t));
-    if (axes.length && g.weights.includes("variable")) parts.push(`axes: ${JSON.stringify(axes)}`);
-    if (italicOnly && g.styles.includes("italic")) parts.push(`style: ["italic"]`);
-    else if (role === "display" && g.styles.includes("italic")) parts.push(`style: ["normal", "italic"]`);
-    parts.push(`variable: "${variable}"`, `display: "swap"`);
-    const light = g.weights.includes("300") ? 300 : g.axes?.find((a) => a.tag === "wght")?.min <= 300 ? 300 : 400;
-    return { kind: "google", id, ident, family: name, code: `export const ${id} = ${ident}({ ${parts.join(", ")} });`, light };
-  }
-  const local = await fontshare(canonName, role === "accent" ? ["400"] : ["300", "400", "500"]);
-  if (local) {
-    const light = local.some((s) => s.weight === "300") ? 300 : 400;
-    const src = local.map((s) => `{ path: "${s.path}", weight: "${s.weight}", style: "${s.style}" }`).join(", ");
-    return { kind: "local", id, family: canonName, code: `export const ${id} = localFont({ src: [${src}], variable: "${variable}", display: "swap" });`, light };
-  }
-  return null;
+function current() {
+  const css = readFileSync(cssFile(), "utf8");
+  const m = css.match(/STRUQ TOKENS: palette (\S+), type (\S+?)\./);
+  return { palette: m?.[1] ?? CANON.palettes[0].id, type: m?.[2] ?? CANON.pairings[0].id };
 }
 
-async function type(slug) {
-  let display = opt("--display");
-  let body = opt("--body");
-  let accent = opt("--accent");
-  let label = "custom";
-  if (slug) {
-    const items = await canon("typography");
-    const t = items.find((i) => i.slug === slug);
-    if (!t) throw new Error(`Unknown pairing "${slug}". Run: canon.mjs list`);
-    display = t.data.display.name;
-    body = t.data.body.name;
-    accent = t.data.accent?.name;
-    label = t.slug;
-  }
-  if (!display || !body) throw new Error('Usage: canon.mjs type <slug>, or type --display "Name" --body "Name" [--accent "Name"]');
-  const plan = planType(display, body);
-  for (const n of plan.notes) console.log(`NOTE ${n}`);
-  if (!plan.ok) throw new Error("The display face is off the Struq list. Pick another pairing (canon.mjs list).");
-  const google = googleData();
-  if (!google) console.log("NOTE next is not installed here, so Google faces cannot be checked; install first for a sure result.");
-  const d = await faceCode(plan.display, "display", google);
-  const b = await faceCode(plan.body, "body", google);
-  if (!d || !b) throw new Error(`Could not load ${!d ? plan.display : plan.body} from Google Fonts or Fontshare. Pick another pairing.`);
-  // The italic accent: its own face when the canon names one apart from display and body; the
-  // display face's italic otherwise (font-accent falls back to it in globals.css).
-  const accentName = accent && !BANNED.has(accent) && accent !== plan.display && accent !== plan.body ? accent : null;
-  const a = accentName ? await faceCode(accentName, "accent", google) : null;
-  if (accentName && !a) console.log(`NOTE the accent face ${accentName} could not be loaded; the display italic carries the accent word.`);
-  const faces = [d, b, a].filter(Boolean);
-  const imports = [];
-  const gIdents = faces.filter((f) => f.kind === "google").map((f) => f.ident);
-  if (gIdents.length) imports.push(`import { ${[...new Set(gIdents)].join(", ")} } from "next/font/google";`);
-  if (faces.some((f) => f.kind === "local")) imports.push(`import localFont from "next/font/local";`);
+function writeFonts(t) {
+  const hrefs = fontHrefs(t, CANON);
   const file = join(root, existsSync(join(root, "src", "app")) ? "src/app" : "app", "fonts.ts");
   writeFileSync(
     file,
-    `// app/fonts.ts: written by the Struq skill (scripts/canon.mjs type). Pairing: ${label}, ${d.family} + ${b.family}${a ? `, accent ${a.family} italic` : ""}.
-// Display and body, plus at most the one italic accent face. globals.css maps --face-display to
-// font-display, --face-body to font-body and --face-accent to font-accent (the display italic when absent).
-${imports.join("\n")}
-
-${faces.map((f) => f.code).join("\n\n")}
-
-/** Every face's CSS variable, for the <html> className in app/layout.tsx. */
-export const fontVariables = [${faces.map((f) => f.id).join(", ")}].map((f) => f.variable).join(" ");
+    `// app/fonts.ts: written by the Struq skill (canon.mjs type ${t.id}): ${faces(t).join(", ")}.
+// Each Google face is asked for its real weight range, then as the bare family as a fallback, because Google refuses a
+// request for a weight the family lacks. The layout puts one <link> per URL in <head>; the token block in globals.css
+// names the faces (--face-display, --face-body, --face-accent), so the blocks measure with the real face.
+export const fontHrefs: string[] = ${JSON.stringify(hrefs, null, 2)};
 `,
   );
-  const cssPath = ["app/globals.css", "src/app/globals.css"].map((f) => join(root, f)).find(existsSync);
-  if (cssPath) {
-    let css = readFileSync(cssPath, "utf8").replace(/--display-weight:\s*\d{3}/, `--display-weight: ${d.light}`);
-    if (!css.includes("--font-accent")) {
-      css = css.replace(/(\s*--font-body:[^\n]*\n)/, `$1  --font-accent: var(--face-accent, var(--face-display)), ui-serif, Georgia, serif;\n`);
-    }
-    writeFileSync(cssPath, css);
-  }
-  console.log(`Wrote ${file.replace(root, ".")}: ${d.family} (${d.kind}) + ${b.family} (${b.kind})${a ? ` + accent ${a.family} italic (${a.kind})` : ""}, display weight ${d.light}`);
-  console.log(`STRUQ.md line:  Type: ${label}: ${d.family} + ${b.family}${a ? `, accent ${a.family}` : ""}`);
-  appendLog(root, "Step 4 Canon type", [
-    `canon.mjs wrote app/fonts.ts: ${d.family} (${d.kind}) over ${b.family} (${b.kind})${a ? `, accent ${a.family} italic` : ""}, pairing ${label}.`,
-    `Display weight ${d.light}.${plan.notes.length ? ` Overrides: ${plan.notes.join("; ")}.` : ""}`,
-  ]);
-  console.log("OK type written");
+  return { file, hrefs };
 }
 
-/* ---------------------------------------------------------------- system */
-async function system(slug) {
-  const items = await canon("design_system");
-  const s = items.find((i) => i.slug === slug);
-  if (!s) throw new Error(`Unknown design system "${slug}". Run: canon.mjs list`);
-  const order = s.data?.silhouette?.sectionOrder ?? [];
-  console.log(`${s.slug}: ${order.join(" > ")}`);
-  console.log(`refs: palette ${s.data.paletteRef}, typography ${s.data.typographyRef} (your own palette and type picks win when the brief fits them better)`);
-  console.log("Struq adds to every order: the hero canvas in the hero, one showpiece at the act break, the designed footer.");
-  console.log("proof and story-proof hold only real facts from the brief; faq only questions the brief answers. Drop a section that would need invented content.");
-  console.log(`STRUQ.md line:  System: ${s.slug} (${order.join(" > ")})`);
-  appendLog(root, "Step 2 Canon system", [`canon.mjs read design system ${s.slug}: ${order.join(" > ")}.`]);
-  console.log("OK system read");
-}
+const commands = {
+  list() {
+    console.log(`PALETTES (${CANON.palettes.length}): id, mood, ground. "kept out" means kept for a brand that asks, never picked unasked.`);
+    for (const p of CANON.palettes) {
+      const ground = lightness(p.colors.background) < 0.5 ? "dark" : "light";
+      console.log(`  ${p.id.padEnd(40)} ${(p.mood ?? "").padEnd(44)} ${ground}${p.autoPick === false ? "  kept out" : ""}`);
+    }
+    console.log(`\nPAIRINGS (${CANON.pairings.length}): id, display + body (+ italic accent), display weight`);
+    for (const t of CANON.pairings) {
+      const [d, bo, ac] = [t.display, t.body, t.accentItalic].map((s) => (s ? headFamily(s) : null));
+      console.log(`  ${t.id.padEnd(26)} ${d} + ${bo}${ac ? ` (+ ${ac} italic)` : ""}, ${t.displayScale?.weight ?? 300}${t.autoPick === false ? "  kept out" : ""}`);
+    }
+    console.log(`\nSnapshot: Struq ${CANON.source.ref} ${CANON.source.commit}.`);
+  },
+  palette() {
+    const p = palette(a);
+    const t = pairing(current().type);
+    const path = write(p, t);
+    console.log(`Wrote palette ${p.id} (${p.mood}) to ${path.replace(root, ".")}, with type ${t.id}.`);
+    console.log(`STRUQ.md line:  Palette: ${p.id} (${p.mood})`);
+    appendLog(root, "Step 3 Canon palette", [`canon.mjs wrote palette ${p.id} (${p.mood}) into the STRUQ TOKENS block.`]);
+    console.log("OK palette written");
+  },
+  type() {
+    const t = pairing(a);
+    const p = palette(current().palette);
+    const path = write(p, t);
+    const { file, hrefs } = writeFonts(t);
+    console.log(`Wrote type ${t.id} (${faces(t).join(" + ")}) to ${path.replace(root, ".")} and ${file.replace(root, ".")} (${hrefs.length} font URLs).`);
+    console.log(`STRUQ.md line:  Type: ${t.id}: ${faces(t).join(" + ")}`);
+    appendLog(root, "Step 3 Canon type", [`canon.mjs wrote type ${t.id}: ${faces(t).join(" + ")}, display weight ${t.displayScale?.weight ?? 300}.`]);
+    console.log("OK type written");
+  },
+  print() {
+    const p = palette(a);
+    const t = pairing(b ?? CANON.pairings[0].id);
+    console.log(tokenBlock(p, t));
+    console.log("");
+    for (const h of fontHrefs(t, CANON)) console.log(h);
+  },
+};
 
-const run = { list, palette: () => palette(slugArg), type: () => type(slugArg), system: () => system(slugArg) }[cmd];
-if (!run) {
-  console.error("Usage: canon.mjs list | palette <slug> | type <slug> | system <slug>   [--dir <project>]");
-  process.exit(2);
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const run = commands[cmd];
+  if (!run || (cmd !== "list" && !a)) {
+    console.error("Usage: canon.mjs list | palette <id> | type <id> | print <palette> [pairing]   [--dir <project>]");
+    process.exit(2);
+  }
+  try {
+    run();
+  } catch (e) {
+    console.error(`FAIL ${e.message}`);
+    process.exitCode = 1;
+  }
 }
-run().catch((e) => {
-  console.error(`FAIL ${e.message}`);
-  process.exitCode = 1;
-});