@nurix/etna 0.19.10 → 0.19.12

package/data/harnesses/code/skills/design/scripts/scaffold.mjs

@@ -1,769 +0,0 @@
-// skills/design/scripts/scaffold.mjs — generates the non-creative app substrate (routes, nav, per-surface state shells, the theme + chart-colors lib helpers) from docs/design/structure.md
-import { mkdirSync, writeFileSync, readFileSync, existsSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { BUDGETS, BUDGET_STAMPS, stampFor, THEME_ATTR, THEME_VALUES, resolveThemeDefault, MOTION_LIFT_CLASS, MOTION_STAGGER_CLASS, STAGGER_CHILD_CAP } from "./lib/vocabulary.mjs";
-
-const ARCHETYPES = ["list-detail", "dashboard", "entity-detail", "create-edit", "log-stream", "command-center"];
-const LANDING = new Set(["list-detail", "dashboard", "log-stream", "command-center"]);
-// Archetypes whose composition substrate is a row table (rows consume motion-lift) vs a card grid
-// (the grid consumes motion-stagger — brand-forward surfaces only: baseline skips arrival cascades, mot-08).
-const TABLE_ARCHETYPES = new Set(["list-detail", "log-stream", "command-center"]);
-const CARD_GRID_ARCHETYPES = new Set(["dashboard"]);
-// Archetypes whose surfaces typically carry charts — their composition region names the token wiring.
-const CHART_ARCHETYPES = new Set(["dashboard", "command-center"]);
-
-// Print the refusal (problem + exact fix) to stderr and exit non-zero.
-function refuse(problem, fix) {
-  process.stderr.write(`scaffold.mjs: ${problem}\n`);
-  process.stderr.write(`fix: ${fix}\n`);
-  process.exit(1);
-}
-
-// Parse argv into positionals (_) and --flags (supporting --k v and --k=v).
-function parseArgs(argv) {
-  const args = { _: [] };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a.startsWith("--")) {
-      const eq = a.indexOf("=");
-      if (eq !== -1) {
-        args[a.slice(2, eq)] = a.slice(eq + 1);
-      } else {
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith("--")) {
-          args[a.slice(2)] = next;
-          i++;
-        } else {
-          args[a.slice(2)] = true;
-        }
-      }
-    } else {
-      args._.push(a);
-    }
-  }
-  return args;
-}
-
-// Strip a trailing/full-line YAML comment (structure-block values never contain '#').
-function stripComment(line) {
-  const h = line.indexOf("#");
-  if (h === -1) return line;
-  if (h === 0 || /\s/.test(line[h - 1])) return line.slice(0, h).replace(/\s+$/, "");
-  return line;
-}
-
-// Extract the body of the fenced ```yaml structure block by its info-string.
-function extractStructureBlock(text) {
-  const m = text.match(/```yaml structure[^\n]*\n([\s\S]*?)\n```/);
-  return m ? m[1] : null;
-}
-
-// Collapse the block into indent-tagged, comment-free, non-blank lines.
-function toLines(body) {
-  const out = [];
-  for (const raw of body.split(/\r?\n/)) {
-    const noComment = stripComment(raw);
-    if (noComment.trim() === "") continue;
-    out.push({ indent: noComment.length - noComment.trimStart().length, text: noComment.trim() });
-  }
-  return out;
-}
-
-// Parse a scalar, inline flow sequence [a, b], or inline flow mapping {k: v}.
-function parseScalarOrFlow(s) {
-  const t = s.trim();
-  if (t.startsWith("[") && t.endsWith("]")) {
-    const inner = t.slice(1, -1).trim();
-    if (inner === "") return [];
-    return inner.split(",").map((x) => parseScalarOrFlow(x));
-  }
-  if (t.startsWith("{") && t.endsWith("}")) {
-    const inner = t.slice(1, -1).trim();
-    const obj = {};
-    if (inner === "") return obj;
-    for (const pair of inner.split(",")) {
-      const idx = pair.indexOf(":");
-      if (idx === -1) continue;
-      obj[pair.slice(0, idx).trim()] = parseScalarOrFlow(pair.slice(idx + 1));
-    }
-    return obj;
-  }
-  return t;
-}
-
-// Dispatch a contiguous line range [start,end) to a sequence or mapping parse.
-function parseBlock(lines, start, end) {
-  if (start >= end) return null;
-  const base = lines[start].indent;
-  if (lines[start].text.startsWith("- ")) return parseSequence(lines, start, end, base);
-  return parseMapping(lines, start, end, base);
-}
-
-// Parse a YAML sequence: each "- " item, with inline-first-pair mapping items merged with their children.
-function parseSequence(lines, start, end, base) {
-  const items = [];
-  let i = start;
-  while (i < end && lines[i].indent === base && lines[i].text.startsWith("- ")) {
-    const content = lines[i].text.slice(2).trim();
-    let j = i + 1;
-    while (j < end && lines[j].indent > base) j++;
-    if (content.startsWith("{") || content.startsWith("[")) {
-      items.push(parseScalarOrFlow(content));
-    } else if (content.indexOf(":") !== -1) {
-      const map = {};
-      const c = content.indexOf(":");
-      const key = content.slice(0, c).trim();
-      const rest = content.slice(c + 1).trim();
-      map[key] = rest !== "" ? parseScalarOrFlow(rest) : null;
-      if (i + 1 < j) {
-        const child = parseBlock(lines, i + 1, j);
-        if (child && typeof child === "object" && !Array.isArray(child)) Object.assign(map, child);
-      }
-      items.push(map);
-    } else {
-      items.push(parseScalarOrFlow(content));
-    }
-    i = j;
-  }
-  return items;
-}
-
-// Parse a YAML mapping: key/value pairs at one indent, recursing into nested blocks.
-function parseMapping(lines, start, end, base) {
-  const map = {};
-  let i = start;
-  while (i < end && lines[i].indent === base && !lines[i].text.startsWith("- ")) {
-    const line = lines[i].text;
-    const c = line.indexOf(":");
-    if (c === -1) {
-      i++;
-      continue;
-    }
-    const key = line.slice(0, c).trim();
-    const rest = line.slice(c + 1).trim();
-    if (rest !== "") {
-      map[key] = parseScalarOrFlow(rest);
-      i++;
-    } else {
-      let j = i + 1;
-      while (j < end && lines[j].indent > base) j++;
-      map[key] = i + 1 < j ? parseBlock(lines, i + 1, j) : null;
-      i = j;
-    }
-  }
-  return map;
-}
-
-// Split a name into alphanumeric words on any separator.
-function words(s) {
-  return String(s).trim().split(/[^A-Za-z0-9]+/).filter(Boolean);
-}
-
-// PascalCase a name (Support Ticket -> SupportTicket).
-function toPascal(s) {
-  return words(s).map((w) => w[0].toUpperCase() + w.slice(1).toLowerCase()).join("");
-}
-
-// kebab-case a name (Ticket Queue -> ticket-queue).
-function toKebab(s) {
-  return words(s).map((w) => w.toLowerCase()).join("-");
-}
-
-// camelCase a name, preserving already-camel single tokens (created_at -> createdAt, slaMinutes -> slaMinutes).
-function toCamel(s) {
-  const str = String(s).trim();
-  if (/^[A-Za-z0-9]+$/.test(str)) return str[0].toLowerCase() + str.slice(1);
-  const w = words(str);
-  if (!w.length) return "";
-  return w[0].toLowerCase() + w.slice(1).map((x) => x[0].toUpperCase() + x.slice(1).toLowerCase()).join("");
-}
-
-// Naive English pluralization sufficient for entity nouns.
-function pluralize(word) {
-  const w = String(word);
-  if (/[^aeiou]y$/i.test(w)) return w.slice(0, -1) + "ies";
-  if (/(s|x|z|ch|sh)$/i.test(w)) return w + "es";
-  return w + "s";
-}
-
-// Capitalize the first character.
-function cap(s) {
-  return s ? s[0].toUpperCase() + s.slice(1) : s;
-}
-
-// Canonical per-entity identifiers shared with generate-fixtures.mjs (module paths and export names must agree).
-function entityNames(name) {
-  const arrayVar = pluralize(toCamel(name));
-  return {
-    iface: toPascal(name),
-    typeFile: toKebab(name),
-    fixtureFile: pluralize(toKebab(name)),
-    arrayVar,
-    emptyVar: "empty" + cap(arrayVar),
-    degradedVar: "degraded" + cap(arrayVar),
-  };
-}
-
-// Normalize a surface's declared delight budget to a legal enum value, defaulting to the safe floor
-// `baseline` when the map omits it or carries an unknown value (references/structure.md, the delight budget).
-function normalizeBudget(v) {
-  const b = String(v ?? "").trim().toLowerCase();
-  return BUDGETS.includes(b) ? b : "baseline";
-}
-
-// Normalize a surface's declared states to the canonical loading/empty/error/degraded set.
-function normalizeStates(arr) {
-  const alias = { partial: "degraded", degraded: "degraded", loading: "loading", empty: "empty", error: "error" };
-  const order = ["loading", "empty", "error", "degraded"];
-  const set = new Set();
-  for (const s of arr || []) {
-    const n = alias[String(s).trim().toLowerCase()];
-    if (n) set.add(n);
-  }
-  const picked = order.filter((s) => set.has(s));
-  return picked.length ? picked : order.slice();
-}
-
-// Read, parse, and validate docs/design/structure.md into a normalized model, refusing on malformed input.
-function loadStructure(path, { requireSurfaces }) {
-  if (!existsSync(path)) refuse(`structure map not found at ${path}`, "pass the path to docs/design/structure.md as the first argument");
-  const body = extractStructureBlock(readFileSync(path, "utf8"));
-  if (body === null) {
-    refuse(
-      `no fenced \`\`\`yaml structure block in ${path}`,
-      "docs/design/structure.md must carry a fenced ```yaml structure block (see references/structure.md); run the structure phase to produce it",
-    );
-  }
-  const parsed = parseBlock(toLines(body), 0, toLines(body).length) || {};
-  const rawSurfaces = Array.isArray(parsed.surfaces) ? parsed.surfaces : [];
-  const surfaces = rawSurfaces.map((s, idx) => {
-    for (const key of ["name", "archetype", "route", "entity"]) {
-      if (!s || typeof s[key] !== "string" || s[key].trim() === "") {
-        refuse(
-          `surface #${idx + 1} is missing required field "${key}"`,
-          `every surfaces[] entry needs name, archetype, route, entity (structure.md schema)`,
-        );
-      }
-    }
-    const archetype = String(s.archetype).trim();
-    if (!ARCHETYPES.includes(archetype)) {
-      refuse(
-        `surface "${s.name}" has archetype "${archetype}", not one of the closed six`,
-        `set archetype to one of: ${ARCHETYPES.join(", ")} (surface-catalog.md; membership is closed)`,
-      );
-    }
-    let mod = 0;
-    if (s["density-modifier"] !== undefined && s["density-modifier"] !== null && String(s["density-modifier"]).trim() !== "") {
-      mod = Number.parseInt(String(s["density-modifier"]).trim(), 10);
-      if (Number.isNaN(mod)) {
-        refuse(
-          `surface "${s.name}" has a non-integer density-modifier "${s["density-modifier"]}"`,
-          "density-modifier is a signed integer (+1 denser / 0 / -1 looser) per surface-catalog.md",
-        );
-      }
-    }
-    return {
-      name: String(s.name).trim(),
-      archetype,
-      route: String(s.route).trim(),
-      entity: String(s.entity).trim(),
-      densityModifier: mod,
-      budget: normalizeBudget(s.budget),
-      states: normalizeStates(s.states),
-    };
-  });
-  if (requireSurfaces && surfaces.length === 0) {
-    refuse(
-      "the structure map declares no surfaces",
-      "the object pass must assign at least one surface an archetype before scaffold opens (structure.md); an empty pass fails the structure gate",
-    );
-  }
-  return {
-    unitOfWork: typeof parsed["unit-of-work"] === "string" ? parsed["unit-of-work"].trim() : "",
-    coreLoop: typeof parsed["core-loop"] === "string" ? parsed["core-loop"].trim() : "",
-    entities: Array.isArray(parsed.entities) ? parsed.entities : [],
-    temporal: parsed.temporal || {},
-    surfaces,
-  };
-}
-
-// Write a file under the project root, creating parent directories.
-function emit(root, rel, content, written) {
-  const abs = join(root, rel);
-  mkdirSync(dirname(abs), { recursive: true });
-  writeFileSync(abs, content, "utf8");
-  written.push(rel);
-}
-
-// Read the emitted default theme from the artifact payload (payload.theme-default, else derived from
-// look.theme via both → light), returning light when the artifact is absent, unreadable, or silent.
-function readThemeDefault(out) {
-  const artifactPath = join(out, "design.tokens.json");
-  if (!existsSync(artifactPath)) return "light";
-  let tokens;
-  try {
-    tokens = JSON.parse(readFileSync(artifactPath, "utf8"));
-  } catch {
-    return "light";
-  }
-  const payload = tokens && tokens.$extensions && tokens.$extensions["com.nurix.design"];
-  if (!payload || typeof payload !== "object") return "light";
-  if (THEME_VALUES.includes(payload["theme-default"])) return payload["theme-default"];
-  if (payload.look && typeof payload.look === "object") return resolveThemeDefault(payload.look.theme);
-  return "light";
-}
-
-// Render index.html. data-theme is written from the artifact's resolved theme-default; the other
-// <html data-*> personality attributes are placeholders derive-personality.mjs --emit resolves.
-function indexHtml(themeDefault) {
-  return `<!doctype html>
-<!-- Generated by scaffold.mjs. Personality state lives in these <html data-*> attributes (code is the cache).
-     data-theme is written from the project artifact's theme-default; the remaining values are placeholders
-     derive-personality.mjs --emit resolves from the design-tokens artifact (design.tokens.json). -->
-<html
-  lang="en"
-  data-style="app"
-  data-density="standard"
-  data-verbosity="default"
-  data-feedback="subtle"
-  data-theme="${themeDefault}"
->
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Operator UI</title>
-  </head>
-  <body>
-    <div id="root"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>
-`;
-}
-
-// Render src/main.tsx: apply the persisted theme, mount the router app, load the emitted stylesheet.
-function mainTsx() {
-  return `// src/main.tsx — Vite entry: applies the persisted theme, mounts the router app, and loads the emitted global stylesheet (generated by scaffold.mjs; do not hand-edit).
-import { StrictMode } from "react";
-import { createRoot } from "react-dom/client";
-import App from "./App";
-import { initTheme } from "./lib/theme";
-import "./styles/globals.css";
-
-// A stored theme preference overrides the boot attribute before first paint.
-initTheme();
-
-const rootElement = document.getElementById("root");
-if (!rootElement) {
-  throw new Error("Root element #root not found in index.html");
-}
-
-createRoot(rootElement).render(
-  <StrictMode>
-    <App />
-  </StrictMode>,
-);
-`;
-}
-
-// Render src/lib/theme.ts: the data-theme toggle + persistence helper — one attribute convention,
-// four writers (personality.css armor, scaffold's <html>, @custom-variant dark, this helper).
-function themeTs() {
-  const themeUnion = THEME_VALUES.map((v) => `"${v}"`).join(" | ");
-  return `// src/lib/theme.ts — ${THEME_ATTR} toggle + persistence (generated by scaffold.mjs; do not hand-edit).
-// Code is the cache: <html ${THEME_ATTR}> is the single runtime theme state — the same attribute
-// personality.css armors (:root[${THEME_ATTR}="dark"]) and globals.css's @custom-variant dark follows.
-// index.html carries the artifact's theme-default as the boot value; a stored preference overrides it.
-
-export type Theme = ${themeUnion};
-
-const THEME_ATTRIBUTE = "${THEME_ATTR}";
-const THEME_STORAGE_KEY = "theme";
-const THEMES: Theme[] = [${THEME_VALUES.map((v) => `"${v}"`).join(", ")}];
-
-// The active theme, read from the attribute (the cache), defaulting to light.
-export function getTheme(): Theme {
-  const value = document.documentElement.getAttribute(THEME_ATTRIBUTE);
-  return THEMES.includes(value as Theme) ? (value as Theme) : "light";
-}
-
-// Set the theme: write the attribute (the cascade flips) and persist the preference.
-export function setTheme(theme: Theme): void {
-  document.documentElement.setAttribute(THEME_ATTRIBUTE, theme);
-  try {
-    localStorage.setItem(THEME_STORAGE_KEY, theme);
-  } catch {
-    // storage unavailable (private mode) — the attribute still flips for this session
-  }
-}
-
-// Flip between light and dark, returning the new theme.
-export function toggleTheme(): Theme {
-  const next: Theme = getTheme() === "dark" ? "light" : "dark";
-  setTheme(next);
-  return next;
-}
-
-// Apply a stored preference over the boot attribute; called once by main.tsx before mount.
-export function initTheme(): void {
-  let stored: string | null = null;
-  try {
-    stored = localStorage.getItem(THEME_STORAGE_KEY);
-  } catch {
-    return;
-  }
-  if (stored !== null && THEMES.includes(stored as Theme)) {
-    document.documentElement.setAttribute(THEME_ATTRIBUTE, stored as Theme);
-  }
-}
-`;
-}
-
-// Render src/lib/chart-colors.ts: token-backed chart palettes so the identity survives to the pixel.
-function chartColorsTs() {
-  return `// src/lib/chart-colors.ts — chart color wiring over the emitted tokens (generated by scaffold.mjs; do not hand-edit).
-// @nurix/components charts accept color props (probed at 0.14.0): LineGraph/PieGraph take a series
-// list, BarGraph takes a status map (success | degraded | error | info | empty). Always pass these
-// exports — never literals — so every chart inherits the theme through the emitted tokens; chart
-// chrome (gridlines, axis labels) stays library-internal, a known substrate limit.
-
-// Series palette for LineGraph / PieGraph \`colors\` — the artifact's five chart tokens, in order.
-export const SERIES_COLORS = [
-  "var(--chart-1)",
-  "var(--chart-2)",
-  "var(--chart-3)",
-  "var(--chart-4)",
-  "var(--chart-5)",
-];
-
-// Status map for BarGraph \`colors\`. info/empty ride accent / muted-foreground: the 36-role
-// artifact carries no dedicated info or empty token, and those two are their closest semantic homes.
-export const STATUS_COLORS = {
-  success: "var(--success)",
-  degraded: "var(--warning)",
-  error: "var(--destructive)",
-  info: "var(--accent)",
-  empty: "var(--muted-foreground)",
-};
-`;
-}
-
-// Render src/App.tsx: one route per surface, wrapped in the persistent operator shell.
-function appTsx(surfaces) {
-  const imports = surfaces
-    .map((s) => `import { ${toPascal(s.name)} } from "./routes/${toKebab(s.name)}/${toPascal(s.name)}";`)
-    .join("\n");
-  const routes = surfaces
-    .map((s) => `          <Route path="${s.route}" element={<${toPascal(s.name)} />} />`)
-    .join("\n");
-  return `// src/App.tsx — application routes and layout wiring (generated from docs/design/structure.md; do not hand-edit).
-import { BrowserRouter, Routes, Route, Outlet } from "react-router-dom";
-import { AppNav } from "./components/nav/AppNav";
-${imports}
-
-// Persistent operator shell: the navigation rail beside the routed surface.
-function AppLayout() {
-  return (
-    <div className="flex min-h-[100dvh] bg-background text-foreground">
-      <AppNav />
-      <main className="flex min-h-0 flex-1 flex-col overflow-auto">
-        <Outlet />
-      </main>
-    </div>
-  );
-}
-
-// Router: one route per surface in the entity/surface map.
-export default function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        <Route element={<AppLayout />}>
-${routes}
-        </Route>
-      </Routes>
-    </BrowserRouter>
-  );
-}
-`;
-}
-
-// Render src/components/nav/AppNav.tsx: top-level entries derived from the object model, secondary surfaces reached by drilling in.
-function navTsx(surfaces) {
-  const navItems = surfaces.filter(
-    (s) => LANDING.has(s.archetype) && !s.route.includes(":") && !/\/new$/.test(s.route),
-  );
-  const items = navItems
-    .map((s) => `  { label: "${s.name}", route: "${s.route}" },`)
-    .join("\n");
-  return `// src/components/nav/AppNav.tsx — top-level navigation derived from the object model (generated; do not hand-edit).
-import { NavLink } from "react-router-dom";
-
-interface NavItem {
-  label: string;
-  route: string;
-}
-
-// Top-level entries are the primary entities' home surfaces; detail and create surfaces are reached by drilling in.
-const NAV_ITEMS: NavItem[] = [
-${items}
-];
-
-// Left navigation rail: one entry per top-level operator surface.
-export function AppNav() {
-  return (
-    <nav
-      aria-label="Primary"
-      className="flex w-56 shrink-0 flex-col gap-1 border-r border-sidebar-border bg-sidebar p-3 text-sidebar-foreground"
-    >
-      {NAV_ITEMS.map((item) => (
-        <NavLink
-          key={item.route}
-          to={item.route}
-          end
-          className={({ isActive }) =>
-            [
-              "rounded-md px-3 py-2 text-sm font-medium transition-colors",
-              isActive
-                ? "bg-sidebar-accent text-sidebar-accent-foreground"
-                : "text-sidebar-foreground hover:bg-sidebar-accent/60",
-            ].join(" ")
-          }
-        >
-          {item.label}
-        </NavLink>
-      ))}
-    </nav>
-  );
-}
-`;
-}
-
-// Composition region for one surface, per archetype: table archetypes get a substrate row table
-// (rows consume motion-lift — hover feedback, budget-free); card-grid archetypes get a substrate
-// grid (motion-stagger on brand-forward surfaces only — baseline skips arrival cascades, mot-08);
-// chart archetypes carry the token wiring instruction; the rest keep the compose-here placeholder.
-function compositionFn(surface, en) {
-  const comp = toPascal(surface.name);
-  const chartNote = CHART_ARCHETYPES.has(surface.archetype)
-    ? `
-      {/* Charts: import { SERIES_COLORS, STATUS_COLORS } from "../../lib/chart-colors" and pass
-          colors={SERIES_COLORS} to LineGraph/PieGraph, colors={STATUS_COLORS} to BarGraph —
-          token-backed palettes only; chart chrome is library-internal (a substrate limit). */}`
-    : "";
-
-  if (TABLE_ARCHETYPES.has(surface.archetype)) {
-    return `// Composition region: the surfaces phase composes the ${surface.archetype} archetype here, following its exemplar and the emitted tokens.
-function ${comp}Composition({ rows, degraded = false }: { rows: ${en.iface}[]; degraded?: boolean }) {
-  const columns = rows.length > 0 ? Object.keys(rows[0] as unknown as Record<string, unknown>).slice(0, 5) : [];
-  return (
-    <div className="flex flex-1 flex-col rounded-lg border border-border bg-card text-card-foreground">
-      <div className="flex items-center justify-between border-b border-border px-4 py-3">
-        <p className="text-sm font-medium text-foreground">${surface.name}</p>
-        <p className="text-xs text-muted-foreground tabular-nums">
-          {rows.length} records{degraded ? " (partial)" : ""}
-        </p>
-      </div>
-      <div className="overflow-x-auto">
-        <table className="w-full table-fixed text-sm">
-          <thead>
-            <tr className="border-b border-border text-left">
-              {columns.map((column) => (
-                <th key={column} scope="col" className="truncate px-4 py-2 text-xs font-medium text-muted-foreground">
-                  {column}
-                </th>
-              ))}
-            </tr>
-          </thead>
-          <tbody>
-            {rows.map((row, index) => (
-              <tr key={index} className="${MOTION_LIFT_CLASS} border-b border-border">
-                {columns.map((column) => (
-                  <td key={column} className="truncate px-4 py-2">
-                    {String((row as unknown as Record<string, unknown>)[column] ?? "")}
-                  </td>
-                ))}
-              </tr>
-            ))}
-          </tbody>
-        </table>
-      </div>${chartNote}
-      <p className="border-t border-border px-4 py-3 text-xs text-muted-foreground">
-        Substrate table: compose the ${surface.archetype} surface for ${surface.entity} here.
-      </p>
-    </div>
-  );
-}`;
-  }
-
-  if (CARD_GRID_ARCHETYPES.has(surface.archetype)) {
-    const staggerClass = surface.budget === "brand-forward" ? ` ${MOTION_STAGGER_CLASS}` : "";
-    return `// Composition region: the surfaces phase composes the ${surface.archetype} archetype here, following its exemplar and the emitted tokens.
-function ${comp}Composition({ rows, degraded = false }: { rows: ${en.iface}[]; degraded?: boolean }) {
-  return (
-    <div className="flex flex-1 flex-col gap-3">
-      <div className="flex items-center justify-between">
-        <p className="text-sm font-medium text-foreground">${surface.name}</p>
-        <p className="text-xs text-muted-foreground tabular-nums">
-          {rows.length} records{degraded ? " (partial)" : ""}
-        </p>
-      </div>
-      <div className="grid auto-rows-min grid-cols-1 gap-4 md:grid-cols-2 xl:grid-cols-3${staggerClass}">
-        {rows.slice(0, ${STAGGER_CHILD_CAP}).map((row, index) => (
-          <article key={index} className="flex flex-col gap-2 rounded-lg border border-border bg-card p-4 text-card-foreground shadow-sm">
-            {Object.entries(row as unknown as Record<string, unknown>).slice(0, 4).map(([field, value]) => (
-              <div key={field} className="flex items-baseline justify-between gap-3">
-                <span className="truncate text-xs text-muted-foreground">{field}</span>
-                <span className="truncate text-sm font-medium">{String(value ?? "")}</span>
-              </div>
-            ))}
-          </article>
-        ))}
-      </div>${chartNote}
-      <p className="text-xs text-muted-foreground">
-        Substrate card grid: compose the ${surface.archetype} surface for ${surface.entity} here.
-      </p>
-    </div>
-  );
-}`;
-  }
-
-  return `// Composition region: the surfaces phase composes the ${surface.archetype} archetype here, following its exemplar and the emitted tokens.
-function ${comp}Composition({ rows, degraded = false }: { rows: ${en.iface}[]; degraded?: boolean }) {
-  return (
-    <div className="flex flex-1 flex-col rounded-lg border border-border bg-card text-card-foreground">
-      <div className="flex items-center justify-between border-b border-border px-4 py-3">
-        <p className="text-sm font-medium text-foreground">${surface.name}</p>
-        <p className="text-xs text-muted-foreground tabular-nums">
-          {rows.length} records{degraded ? " (partial)" : ""}
-        </p>
-      </div>${chartNote}
-      <p className="px-4 py-6 text-sm text-muted-foreground">
-        Compose the ${surface.archetype} surface for ${surface.entity} here.
-      </p>
-    </div>
-  );
-}`;
-}
-
-// Render one surface shell: typed props, fixture wiring, pre-created lifecycle state shells, and the density-step root.
-function surfaceShell(surface) {
-  const comp = toPascal(surface.name);
-  const slug = toKebab(surface.name);
-  const en = entityNames(surface.entity);
-  const states = surface.states;
-  const hasEmpty = states.includes("empty");
-  const hasDegraded = states.includes("degraded");
-  const union = [...states, "ready"].map((s) => `"${s}"`).join(" | ");
-  const densityAttr =
-    surface.densityModifier > 0 ? ' data-density-step="tighter"' : surface.densityModifier < 0 ? ' data-density-step="looser"' : "";
-
-  const named = [en.arrayVar];
-  if (hasEmpty) named.push(en.emptyVar);
-  if (hasDegraded) named.push(en.degradedVar);
-
-  const branches = [];
-  if (states.includes("loading")) {
-    branches.push(`      {state === "loading" && (
-        <div className="flex flex-1 items-center justify-center py-12" aria-busy="true">
-          <p className="text-sm text-muted-foreground">Loading ${surface.name}</p>
-        </div>
-      )}`);
-  }
-  if (hasEmpty) {
-    branches.push(`      {state === "empty" && (
-        <div className="flex flex-1 flex-col items-center justify-center gap-1 py-12 text-center">
-          <p className="text-sm font-medium text-foreground">Nothing here yet</p>
-          <p className="max-w-sm text-sm text-muted-foreground">
-            ${surface.name} has no records yet. New records appear here as the operator creates them.
-          </p>
-        </div>
-      )}`);
-  }
-  if (states.includes("error")) {
-    branches.push(`      {state === "error" && (
-        <div role="alert" className="flex flex-1 flex-col items-center justify-center gap-1 py-12 text-center">
-          <p className="text-sm font-medium text-destructive">Could not load ${surface.name}</p>
-          <p className="max-w-sm text-sm text-muted-foreground">The request failed. Retry to reload this surface.</p>
-        </div>
-      )}`);
-  }
-  if (hasDegraded) {
-    branches.push(`      {state === "degraded" && (
-        <div className="flex flex-1 flex-col gap-2">
-          <p className="text-sm text-warning">Showing partial data. Some records are stale or failed to enrich.</p>
-          <${comp}Composition rows={rows} degraded />
-        </div>
-      )}`);
-  }
-  branches.push(`      {state === "ready" && <${comp}Composition rows={rows} />}`);
-
-  const pickBody = [];
-  if (hasDegraded) pickBody.push(`  if (state === "degraded") return ${en.degradedVar};`);
-  if (hasEmpty) pickBody.push(`  if (state === "empty") return ${en.emptyVar};`);
-  pickBody.push(`  return ${en.arrayVar};`);
-
-  const stamp = stampFor(surface.budget) || BUDGET_STAMPS.baseline;
-  const content = `${stamp}
-// src/routes/${slug}/${comp}.tsx — ${surface.name} surface shell (${surface.archetype}; generated by scaffold.mjs; do not hand-edit).
-import type { ${en.iface} } from "../../types/${en.typeFile}";
-import { ${named.join(", ")} } from "../../fixtures/${en.fixtureFile}";
-
-type SurfaceState = ${union};
-
-interface ${comp}Props {
-  state?: SurfaceState;
-}
-
-// ${surface.name}: the ${surface.archetype} surface; scaffold pre-creates every lifecycle shell for the surfaces phase to fill.
-export function ${comp}({ state = "ready" }: ${comp}Props) {
-  const rows: ${en.iface}[] = pickRows(state);
-  return (
-    <section${densityAttr} aria-label="${surface.name}" className="flex h-full min-h-0 flex-col gap-4 p-6">
-      <header className="flex items-center justify-between border-b border-border pb-3">
-        <div className="flex flex-col gap-1">
-          <h1 className="text-base font-semibold tracking-tight text-foreground">${surface.name}</h1>
-          <p className="text-xs text-muted-foreground">${surface.archetype} - ${surface.entity}</p>
-        </div>
-        <span className="text-xs text-muted-foreground tabular-nums">{rows.length} records</span>
-      </header>
-${branches.join("\n")}
-    </section>
-  );
-}
-
-${compositionFn(surface, en)}
-
-// Select the fixture set backing the requested lifecycle state.
-function pickRows(state: SurfaceState): ${en.iface}[] {
-${pickBody.join("\n")}
-}
-`;
-  return { rel: `src/routes/${slug}/${comp}.tsx`, content };
-}
-
-// Entry point: load the map, emit the substrate, and report what was written.
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const structurePath = args._[0];
-  const out = typeof args.out === "string" ? args.out : null;
-  if (!structurePath || !out) {
-    refuse("missing arguments", "usage: scaffold.mjs <docs/design/structure.md> --out <project-root-dir>");
-  }
-  const model = loadStructure(structurePath, { requireSurfaces: true });
-  const written = [];
-  emit(out, "index.html", indexHtml(readThemeDefault(out)), written);
-  emit(out, "src/main.tsx", mainTsx(), written);
-  emit(out, "src/lib/theme.ts", themeTs(), written);
-  emit(out, "src/lib/chart-colors.ts", chartColorsTs(), written);
-  emit(out, "src/App.tsx", appTsx(model.surfaces), written);
-  emit(out, "src/components/nav/AppNav.tsx", navTsx(model.surfaces), written);
-  for (const surface of model.surfaces) {
-    const shell = surfaceShell(surface);
-    emit(out, shell.rel, shell.content, written);
-  }
-  process.stdout.write(`scaffold.mjs: wrote ${written.length} files under ${out}\n`);
-  for (const rel of written) process.stdout.write(`  ${rel}\n`);
-}
-
-main();