makersclaw 0.1.0

package/templates/next/files/check/run.mjs

@@ -0,0 +1,683 @@
+#!/usr/bin/env node
+// `npm run check` — does this app hold? One command, one line per rule,
+// exit 1 on the first thing that does not. No dependency: node's own fs,
+// crypto, fetch and child_process.
+//
+// Static rules read the source; the smoke test builds the app and loads
+// every surface. Every static rule exists because the failure it names
+// was seen in a real build: a hex in a surface (the app stopped following
+// the workspace theme), a hand-rolled <select> that could not be used, an
+// example INSERTed into a shared table, a manifest entry whose file was
+// never written, an icon name that rendered nothing, a tweet card painted
+// in the workspace's tokens (unrecognisable as a tweet — the one thing
+// the app was for), a kit file "improved" per app.
+//
+//   npm run check               static rules, then smoke
+//   npm run check -- --static   static rules only
+//
+// The smoke test builds for itself, and only when a source file is newer
+// than its last build. Where: in the sandbox the app folder is
+// `ubuntu:claw 2755` — the terminal user can read it, not write in it —
+// so the sources are copied to a folder of its own (`~/.claw-check/<app>`,
+// node_modules symlinked back) and built there. On a writable checkout
+// (local dev) it builds in place, into `.next-check` (CLAW_DIST_DIR,
+// next.config.mjs). Never into `.next`: that is the dev server's, and a
+// second build there dies with EACCES on .next/trace. The founder's live
+// preview keeps running, untouched, while the check runs beside it.
+//
+// Output is meant to be read by the platform agent in one glance: keep
+// it under twenty lines, name file:line, say what to do instead.
+
+import { accessSync, constants, cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, symlinkSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { spawn, spawnSync } from "node:child_process";
+import { createServer } from "node:net";
+import { basename, dirname, join, relative } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { fileURLToPath } from "node:url";
+
+// The app dir: this file's parent, unless the platform runs a canonical
+// copy of it from elsewhere against an app (CLAW_APP_DIR).
+const ROOT = process.env.CLAW_APP_DIR || join(fileURLToPath(import.meta.url), "..", "..");
+const STATIC_ONLY = process.argv.includes("--static");
+
+// The kit, by exact file: what the template ships under components/ui and
+// components/parts. Anything else in those folders is the agent's, and the
+// `kit` rule refuses it (a shared piece goes in components/, a picture in
+// components/depictions/). The list is the template's; `makersclaw
+// update` lays both folders again.
+// Exact names AND extensions: Next resolves .js before .jsx, so a
+// components/ui/depiction.js beside depiction.jsx would win unseen.
+const KIT = /^components\/(?:ui\/(?:cx|index)\.js|ui\/(?:button|depiction|field|icon|menu|notice|sheet|tabs)\.jsx|parts\/index\.js|parts\/(?:fixture|record-switcher)\.jsx)$/;
+
+// The pins: sha256 of every fixed file, written by `makersclaw init` and
+// `makersclaw add` (check/pins.json). Read first, because a BLOCK is
+// fixed only while it is pinned: `makersclaw add <name>` lays a block
+// under components/blocks/<name>/ and pins each of its files, so the
+// rules below skip it the way they skip the kit (a block owns native
+// elements — a canvas draws its links in <svg>). A file there that no
+// pin names was not installed; the `kit` rule refuses it.
+const PINS = (() => {
+  try {
+    return JSON.parse(readFileSync(join(ROOT, "check", "pins.json"), "utf8"));
+  } catch {
+    return null;
+  }
+})();
+const BLOCK = /^components\/blocks\/[a-z0-9]+(?:-[a-z0-9]+)*\/[a-z0-9]+(?:-[a-z0-9]+)*\.(?:jsx|js)$/;
+const pinnedBlock = (path) => BLOCK.test(path) && PINS !== null && Object.prototype.hasOwnProperty.call(PINS, path);
+/** A depiction: a picture of something that exists elsewhere (README §3c). */
+const DEPICTION = /^components\/depictions\//;
+/** Where a depiction may be framed: a surface, or the agent's own
+ *  component (the client component that holds the draft is where a
+ *  preview can follow typing). Never the shell, the kit or lib/. */
+const FRAME_HOST = /^(?:surfaces\/[^/]+\.jsx|components\/[^/]+\.jsx)$/;
+
+// Files the rules skip: the kit (it owns the native elements and the
+// fallback colours), the fixed template files, machine folders. Depiction
+// files are NOT skipped — the `depictions` rule reads them.
+const SKIP = [
+  /^node_modules\//,
+  /^\.next(-check)?\//,
+  /^check\//,
+  KIT,
+  /^app\/globals\.css$/,
+  /^lib\/(db|data|actions|claw|platform|hooks|sample)\.js$/,
+  /^app\/(layout|page|error|global-error|not-found|error-relay|auto-refresh)\.jsx$/,
+  /^app\/s\/\[key\]\/page\.jsx$/,
+  /^middleware\.js$/,
+  /^next\.config\.mjs$/,
+  /^postcss\.config\.mjs$/,
+  /^public\//,
+  /\.(md|sql|json|lock)$/,
+];
+
+// Only the build's own folders are skipped: a dot-named module
+// (components/.pictures.js) is a module Next bundles all the same.
+function walk(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    if (name === "node_modules" || name === ".git" || name === ".next" || name === ".next-check") continue;
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) walk(full, out);
+    else out.push(full);
+  }
+  return out;
+}
+
+const files = walk(ROOT)
+  .map((f) => ({ path: relative(ROOT, f), text: null }))
+  .filter((f) => /\.(jsx?|mjs|cjs|tsx?|mts|cts|css|svg)$/.test(f.path) && !SKIP.some((re) => re.test(f.path)) && !pinnedBlock(f.path))
+  .map((f) => ({ ...f, text: readFileSync(join(ROOT, f.path), "utf8") }))
+  .map((f) => ({ ...f, code: stripComments(f.text) }));
+const depictionFiles = files.filter((f) => DEPICTION.test(f.path));
+const appFiles = files.filter((f) => !DEPICTION.test(f.path));
+// A folder file another depiction imports with ./ is a helper (glyphs, a
+// mode table): the inside rules apply to it, the header and dead rules do
+// not, and it is not a picture in its own right.
+const helpers = new Set();
+for (const f of depictionFiles) {
+  for (const m of f.code.matchAll(/^\s*import\b[^"']*\bfrom\s*["']\.\/([^"']+?)(?:\.jsx?)?["']/gm)) helpers.add(m[1]);
+}
+const pictures = depictionFiles.length - helpers.size;
+
+const failures = [];
+const lines = [];
+function ok(rule, detail) {
+  lines.push(`ok    ${rule.padEnd(10)} ${detail}`);
+}
+function fail(rule, where, detail) {
+  failures.push(rule);
+  lines.push(`FAIL  ${rule.padEnd(10)} ${where} — ${detail}`);
+}
+function lineOf(text, index) {
+  return text.slice(0, index).split("\n").length;
+}
+/** Every match of `re` in every file (or in `over`), with its line. Reads
+ *  the code, never the prose beside it (f.code: comments blanked). */
+function scan(re, onHit, over = appFiles) {
+  for (const f of over) {
+    const g = new RegExp(re.source, re.flags.includes("g") ? re.flags : `${re.flags}g`);
+    let m;
+    while ((m = g.exec(f.code))) onHit(f, m, lineOf(f.code, m.index));
+  }
+}
+/** A rule's FAIL lines, capped and deduped, so the report stays short. */
+function limiter(rule, cap = 4) {
+  const seen = new Set();
+  let hits = 0;
+  return {
+    hit(where, what, detail) {
+      const key = `${where.replace(/:\d+$/, "")} ${what}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      if (hits++ < cap) fail(rule, where, detail);
+    },
+    get count() {
+      return hits;
+    },
+  };
+}
+
+const HUES = "slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose|white|black";
+const TOKEN_SLOTS = "background|foreground|card|popover|primary|secondary|muted|accent|destructive|success|warning|info|border|input|ring";
+const COLOUR_PREFIXES = "bg|text|border(?:-[xytrbles])?|ring(?:-offset)?|inset-ring|inset-shadow|text-shadow|from|to|via|fill|stroke|outline|decoration|accent|caret|divide(?:-[xy])?|placeholder|shadow";
+
+/** Source without its comments, newlines kept so line numbers hold: a
+ *  rule reads code, not the prose beside it (a header that says
+ *  "window." or names <a> is not browser access or a link). */
+function stripComments(text) {
+  const blank = (m) => m.replace(/[^\n]/g, " ");
+  return text
+    .replace(/\{\/\*[\s\S]*?\*\/\}/g, blank)
+    .replace(/\/\*[\s\S]*?\*\//g, blank)
+    .replace(/(^|[^:\\])\/\/[^\n]*/g, (m, lead) => lead + blank(m.slice(lead.length)));
+}
+/** JSX attributes up to the tag's `>`: strings and balanced braces may hold a `>` or `=>`. */
+const ATTRS = String.raw`(?:"[^"]*"|'[^']*'|\{(?:[^{}]|\{[^{}]*\})*\}|[^>"'{])*`;
+
+// 1. Colour lives in the workspace theme, nowhere in the app — except a
+//    depiction, which wears the colours of the place it depicts (rule 7).
+{
+  const L = limiter("colours");
+  const RULES = [
+    [/(?:#|\\x23|\\u0023|%23)(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})(?![\w-])/, "a hex colour"],
+    [/\b(?:rgba?|hsla?|hwb|lab|lch|oklch|oklab|color|color-mix|light-dark|device-cmyk)\(/i, "a colour function"],
+    [new RegExp(`\\b(?:${COLOUR_PREFIXES})-(?:${HUES})(?:-\\d{2,3})?\\b`), "a raw Tailwind hue"],
+    [new RegExp(`\\b(?:${COLOUR_PREFIXES})-\\[(?!(?:length|size|position|image|url|--|var\\()|\\d)[a-zA-Z#][^\\]]*\\]`), "an arbitrary colour"],
+    // A value through a colour property, or a custom property set here and
+    // read back (text-(--x)), bypasses the theme whatever it spells.
+    [/\[(?:--[\w-]+|[a-z-]*(?:color|background|shadow|decoration|outline|fill|stroke|filter|caret|accent)|border(?:-(?:top|right|bottom|left|inline|block|[xysetlrb]))?(?:-(?:start|end))?)\s*:[^\]]*\]/, "an arbitrary property (CSS the theme cannot reach)"],
+    [/<style\b/, "a <style> tag (CSS the theme cannot reach)"],
+    [/dangerouslySetInnerHTML|\[data-depiction|\[&_\[data-depiction/, "markup or selectors that reach past the theme"],
+  ];
+  for (const [re, what] of RULES) {
+    scan(re, (f, m, line) => L.hit(`${f.path}:${line}`, what, `${what} (${m[0]}); use a token: bg-card, text-muted-foreground, border-border, text-primary… (a picture of a tweet or a post goes in components/depictions/, README §3c)`));
+  }
+  // A filter recolours whatever the theme painted.
+  scan(/(?<=[\s"'`:])(?:backdrop-)?(?:hue-rotate|invert|sepia|saturate|grayscale)(?:-(?:\d+|\[[^\]]+\]|\([^)]+\)))?(?=[\s"'`])/, (f, m, line) => L.hit(`${f.path}:${line}`, "filter", `a filter (${m[0]}) recolours the theme; use tokens for every state`));
+  // The only stylesheet is app/globals.css (pinned). Another one can pin
+  // the workspace's slots (--primary: …) with no hex in sight.
+  for (const f of appFiles) if (/\.css$/.test(f.path)) L.hit(f.path, "sheet", "the only stylesheet is app/globals.css (fixed); design goes in the shell and the surfaces, with tokens");
+  if (!L.count) ok("colours", `no colour outside the workspace theme${pictures ? ` (${pictures} depiction${pictures === 1 ? "" : "s"} excepted)` : ""}`);
+}
+
+// 2. Controls come from the kit; the browser supplies their behaviour.
+//    A depiction may draw its own <svg> glyphs (the X mark looks like
+//    nothing in the sprite) but still has no app controls.
+{
+  const L = limiter("controls");
+  const RULES = [
+    [/<select\b/, "Select from components/ui, or RecordSwitcher from components/parts", files],
+    [/<dialog\b/, "Sheet or Confirm from components/ui", files],
+    [/<details\b/, "Menu or Sheet from components/ui", files],
+    [/role=["']tab(?:list)?["']/, "Tabs from components/ui", files],
+    [/role=["']menu(?:item)?["']/, "Menu from components/ui", files],
+    [/role=["']dialog["']/, "Sheet from components/ui", files],
+    [/\bpopover=/, "Menu from components/ui", files],
+    [/window\.confirm\(/, "Confirm from components/ui", files],
+    [/<svg\b/, "Icon from components/ui (add a glyph there if it is missing)", appFiles],
+  ];
+  for (const [re, use, over] of RULES) {
+    scan(re, (f, m, line) => L.hit(`${f.path}:${line}`, use, `${m[0]} by hand; use ${use}`), over);
+  }
+  if (!L.count) ok("controls", "every control is a kit part");
+}
+
+// 3. The example is a fixture in code — never a row in the shared database.
+{
+  const L = limiter("examples");
+  scan(/\bINSERT\s+INTO\b/i, (f, m, line) => L.hit(`${f.path}:${line}`, "insert", "SQL INSERT outside lib/actions.js; insertRow() is the write door, and a fixture is never inserted"), files);
+  for (const f of files) {
+    const decl = /\b(?:const|let)\s+((?:[A-Z][A-Z0-9_]*_)?(?:SAMPLE|EXAMPLE|FIXTURE|DEMO)S?(?:_[A-Z0-9_]+)?)\s*=\s*[\[{]/.exec(f.code);
+    if (!decl) continue;
+    // A data-only module (no JSX) may hold the rows; the file that renders
+    // them is the one that must run them through useFixture(). A depiction
+    // never holds one: its rows arrive as props from the surface.
+    const renders = /<\/|\/>/.test(f.code);
+    const uses = /\buseFixture\(|\bmarkSample\(/.test(f.code);
+    const server = /from\s*["']\.\.?\/lib\/data["']/.test(f.code);
+    if (renders && !uses) L.hit(`${f.path}:${lineOf(f.code, decl.index)}`, "fixture", `${decl[1]} is rendered without useFixture() — the example shows only while the table is empty, and is never saved${DEPICTION.test(f.path) ? " (a depiction takes its rows as props; the surface holds the fixture)" : server ? " (a server surface cannot call it: pass the rows down and let the client component run useFixture)" : ""}`);
+  }
+  if (!L.count) ok("examples", "fixtures stay in code (useFixture), nothing INSERTs one");
+}
+
+// 4. The manifest names surfaces that exist, once each, under keys that are free.
+const surfaceKeys = [];
+{
+  // Comments hold the worked example; only code counts.
+  const manifest = readFileSync(join(ROOT, "surfaces.js"), "utf8").replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, "");
+  const problems = [];
+  const imports = new Map();
+  for (const m of manifest.matchAll(/import\s+(\w+)\s+from\s+["'](\.\/surfaces\/[^"']+)["']/g)) {
+    const target = m[2].replace(/^\.\//, "");
+    const candidates = [target, `${target}.jsx`, `${target}.js`, `${target}/index.jsx`];
+    if (!candidates.some((c) => existsSync(join(ROOT, c)))) problems.push(`${m[1]} imports ${m[2]}, which is not there`);
+    imports.set(m[1], target);
+  }
+  for (const m of manifest.matchAll(/key:\s*["']([^"']+)["']/g)) surfaceKeys.push(m[1]);
+  const seen = new Set();
+  for (const k of surfaceKeys) {
+    if (seen.has(k)) problems.push(`key "${k}" appears twice`);
+    seen.add(k);
+    if (["agent", "runs", "activity", "settings"].includes(k)) problems.push(`key "${k}" is reserved (the OS draws that tab)`);
+  }
+  for (const m of manifest.matchAll(/component:\s*(\w+)/g)) {
+    if (!imports.has(m[1])) problems.push(`component ${m[1]} is not imported`);
+  }
+  if (surfaceKeys.length === 0) problems.push("no surfaces listed — the manifest is empty");
+  if (problems.length) for (const p of problems.slice(0, 4)) fail("manifest", "surfaces.js", p);
+  else ok("manifest", `${surfaceKeys.length} surface${surfaceKeys.length === 1 ? "" : "s"}: ${surfaceKeys.join(", ")}`);
+}
+
+// 5. Every icon named exists in the sprite (a depiction's own glyphs are
+//    not sprite names).
+{
+  const sprite = readFileSync(join(ROOT, "components/ui/icon.jsx"), "utf8");
+  const names = new Set([...sprite.matchAll(/^\s+"?([a-z][a-z0-9-]*)"?:\s*"/gm)].map((m) => m[1]));
+  const missing = new Map();
+  const check = (f, name, line) => {
+    if (!names.has(name) && !missing.has(name)) missing.set(name, `${f.path}:${line}`);
+  };
+  scan(/<Icon\b[^>]*\bname=["']([a-z][a-z0-9-]*)["']/, (f, m, line) => check(f, m[1], line));
+  scan(/\bicon(?:=|:\s*)["']([a-z][a-z0-9-]*)["']/, (f, m, line) => check(f, m[1], line));
+  if (missing.size) {
+    const where = [...missing].map(([n, at]) => `"${n}" (${at})`).join(", ");
+    fail("icons", "sprite", `not in components/ui/icon.jsx: ${where}. Add the glyph there, or pick one of: ${[...names].join(" ")}`);
+  } else ok("icons", "every icon name exists");
+}
+
+// 6. The kit is fixed. Its folders hold the template's files and nothing
+//    else; the template's other fixed files are pinned by hash
+//    (check/pins.json, written by makersclaw init) so a colour slipped
+//    into app/globals.css is caught even though rule 1 skips that file.
+//    Blocks are fixed the same way: components/blocks/<name>/ holds what
+//    `makersclaw add <name>` laid and pinned, and nothing else.
+{
+  const L = limiter("kit");
+  for (const dir of ["components/ui", "components/parts"]) {
+    const full = join(ROOT, dir);
+    if (!existsSync(full)) continue;
+    for (const f of walk(full)) {
+      const rel = relative(ROOT, f);
+      if (!KIT.test(rel)) L.hit(rel, "extra", "the kit is fixed; a shared piece goes in components/, a picture in components/depictions/");
+    }
+  }
+  if (existsSync(join(ROOT, "components", "blocks"))) {
+    for (const f of walk(join(ROOT, "components", "blocks"))) {
+      const rel = relative(ROOT, f);
+      if (!pinnedBlock(rel)) L.hit(rel, "extra", "blocks come from `makersclaw add <name>` and are fixed; your own piece goes in components/");
+    }
+  }
+  // components/ui.js beside components/ui/ wins module resolution: every
+  // `../components/ui` import would get a fake kit. Whatever the
+  // extension — a file so named has no other purpose.
+  if (existsSync(join(ROOT, "components"))) {
+    for (const e of readdirSync(join(ROOT, "components"), { withFileTypes: true })) {
+      if (e.isFile() && /^(?:ui|parts|depictions|blocks)\.[^.]+$/.test(e.name)) L.hit(`components/${e.name}`, "shadow", `a file beside the components/${e.name.replace(/\..*$/, "")}/ folder wins module resolution over it; delete it`);
+    }
+  }
+  // check/ is this script and its pins; a module hidden there is bundled
+  // by Next and read by no rule.
+  if (existsSync(join(ROOT, "check"))) {
+    for (const e of readdirSync(join(ROOT, "check"))) {
+      if (e !== "run.mjs" && e !== "pins.json") L.hit(`check/${e}`, "extra", "check/ holds run.mjs and pins.json only; a module goes in components/ or lib/");
+    }
+  }
+  for (const f of files) {
+    if (/\.(tsx?|mts|cts|cjs)$/.test(f.path)) L.hit(f.path, "ext", "the template is JSX and ships no TypeScript; write .jsx / .js");
+  }
+  let pinned = 0;
+  const blocks = new Set();
+  for (const [path, sha] of Object.entries(PINS ?? {})) {
+    const block = BLOCK.test(path) ? path.split("/")[2] : null;
+    if (block) blocks.add(block);
+    const full = join(ROOT, path);
+    if (!existsSync(full)) {
+      L.hit(path, "missing", block ? `a file of the ${block} block is missing; \`makersclaw add ${block}\` restores it` : "a template file is missing; `makersclaw update` restores it");
+      continue;
+    }
+    const have = createHash("sha256").update(readFileSync(full)).digest("hex");
+    if (have !== sha) {
+      L.hit(
+        path,
+        "changed",
+        block
+          ? `differs from the ${block} block — blocks are fixed: compose it through its props, or write your own in components/; \`makersclaw add ${block}\` restores it`
+          : "differs from the template — fixed files are not yours to edit (design goes in app/shell.jsx and the surfaces); `makersclaw update` restores it",
+      );
+    }
+    pinned++;
+  }
+  const blockNote = blocks.size ? ` (blocks: ${[...blocks].sort().join(", ")})` : "";
+  if (!L.count) ok("kit", pinned ? `${pinned} fixed files match the template${blockNote}` : "kit folders hold the template's files (no pins)");
+}
+
+// 7. Depictions: a picture of something that exists elsewhere wears THAT
+//    place's colours, face and widths — and nothing of the workspace. It
+//    is a file in components/depictions/, inert, framed by the kit's
+//    <Depiction> on a surface or in the component that holds the draft.
+//    Both directions are checked: the workspace must not leak in, the
+//    picture must not leak out.
+{
+  const L = limiter("depictions");
+  const rendered = new Map(); // slug → files framing it
+  const claimed = new Set(); // slugs a file imported wrongly — that line already points at them
+  const ok7 = (msg) => (L.count ? null : ok("depictions", msg));
+  const slugOf = (path) => basename(path).replace(/\.jsx?$/, "");
+  const depDir = join(ROOT, "components", "depictions");
+
+  // (a) inside the folder — read raw, so a .json or a subfolder no rule
+  //     would open is seen too.
+  if (existsSync(depDir)) {
+    for (const e of readdirSync(depDir, { withFileTypes: true })) {
+      if (e.isDirectory()) L.hit(`components/depictions/${e.name}/`, "ext", "no folders here: one .jsx per picture, a helper beside it (./glyphs.jsx)");
+      else if (!/\.jsx$/.test(e.name)) L.hit(`components/depictions/${e.name}`, "ext", /\.js$/.test(e.name) ? "rename to .jsx: a depiction is a component" : "only .jsx here: colour goes on the element (style, bg-[#…]); a stylesheet or a data file reaches past the rules");
+      else if (!/^[a-z0-9-]+\.jsx$/.test(e.name)) L.hit(`components/depictions/${e.name}`, "name", `rename it ${e.name.replace(/\.jsx$/, "").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[^A-Za-z0-9]+/g, "-").toLowerCase()}.jsx: a depiction file is a lowercase-kebab slug, the same word as of="…" on its frame`);
+    }
+  }
+  for (const f of depictionFiles) {
+    const raw = f.text;
+    const code = f.code;
+    const at = (m) => `${f.path}:${lineOf(code, m.index)}`;
+    const helper = helpers.has(slugOf(f.path));
+    if (!/^[a-z0-9-]+\.jsx$/.test(basename(f.path))) continue; // reported above
+    if (!helper && !(/Exact:/.test(raw.slice(0, 8000)) && /Approximate:/.test(raw.slice(0, 8000)))) {
+      L.hit(f.path, "header", "open with a header comment: the target, the date traced, its column widths in px, its modes, then a line starting `Exact:` (colours, sizes, radii, the fold) and one starting `Approximate:` (a proprietary face, the emoji set) — that spelling and case");
+    }
+    for (const m of code.matchAll(/^\s*import\b[^"']*\bfrom\s*["']([^"']+)["']|\bimport\(\s*["']([^"']+)|\brequire\(\s*["']([^"']+)|^\s*export\b[^"']*\bfrom\s*["']([^"']+)["']/gm)) {
+      const spec = m[1] ?? m[2] ?? m[3] ?? m[4];
+      // A sibling is one path segment that IS a .jsx in the folder: an
+      // extensionless ./palette would resolve to palette.json unseen.
+      const sibling = /^\.\/[a-z0-9-]+(?:\.jsx)?$/.test(spec) && existsSync(join(depDir, `${spec.slice(2).replace(/\.jsx$/, "")}.jsx`));
+      if (!(spec === "react" || spec === "../ui/cx" || sibling)) L.hit(at(m), "import", `imports ${spec} — a depiction imports react, ../ui/cx and a sibling .jsx that exists (./glyphs) only; data comes in as props, the app's verbs stay in the chrome`);
+    }
+    let m;
+    if ((m = /^\s*export\s+(?!default\b)/m.exec(code))) L.hit(at(m), "export", "one default export, a component; a colour, a font or a class string never leaves the folder");
+    if ((m = /^[A-Z]\w*\.\w+\s*=|\bglobalThis\b|\bmodule\.exports\b/m.exec(code))) L.hit(at(m), "export", "nothing leaves the folder but the component: no property on it, no global");
+    if ((m = new RegExp(`\\b(?:${COLOUR_PREFIXES})-(?:${TOKEN_SLOTS})(?:-foreground)?(?:\\/\\d+)?\\b`).exec(code))) L.hit(at(m), "token", `the workspace's colour inside a depiction (${m[0]}); paint it in the target's: bg-[#ffffff], style={{ color: "#536471" }}`);
+    if ((m = new RegExp(`\\b(?:${COLOUR_PREFIXES})-(?:${HUES})(?:-\\d{2,3})?\\b`).exec(code))) L.hit(at(m), "hue", `${m[0]}: Tailwind's palette is not the target's; write the traced value: bg-[#ffffff], style={{ color: "#536471" }}`);
+    // Every form Tailwind turns into a live var(): inline var(--x),
+    // bg-(--x), bg-(color:--x), theme(--x), [prop:var(--x)].
+    if ((m = /var\(\s*--|\((?:[a-z-]+:)?--[a-z][\w-]+\)/.exec(code))) L.hit(at(m), "var", `a workspace variable inside a depiction (${m[0].trim()}); paint the target's own value`);
+    if ((m = /\bfont-(?:sans|mono|display)\b/.exec(code))) L.hit(at(m), "face", `the workspace's face (${m[0]}); write the target's stack in style={{ fontFamily }}`);
+    if ((m = /\bdark:(?=[a-z!\[-])|prefers-color-scheme|data-theme/.exec(code))) L.hit(at(m), "dark", `${m[0]} keys on the workspace's <html data-theme>; a depiction keys on its own mode prop`);
+    // Path data (d="M3 6h-2…") looks like utilities; blank it first.
+    const noPaths = code.replace(/\b(?:d|points)=(["'])[^"']*\1/g, (a) => a.replace(/[^\n]/g, " "));
+    if ((m = /\b-?(?:[mp][xytrbl]?|gap(?:-[xy])?|space-[xy]|w|h|size|min-w|max-w|min-h|max-h|inset(?:-[xy])?|top|right|bottom|left|leading|indent)-(?!0\b)\d+(?:\.\d+)?(?!\/)\b|\bmax-w-(?:xs|sm|md|lg|\d?xl|prose)\b|\btext-(?:2xs|xs|sm|base|lg|\d?xl)\b|\brounded(?:-[trbl]{1,2})?-(?:sm|md|lg|\d?xl)\b|\[[\d.]+r?em\]/.exec(noPaths))) L.hit(at(m), "rem", `${m[0]} is scaled by the workspace (rem × density × radius); inside a depiction write px: text-[15px] p-[12px] rounded-[16px]`);
+    if ((m = /<style\b|<link\b|dangerouslySetInnerHTML|\[(?:html|body|:root)\b|:has\(/.exec(code))) L.hit(at(m), "leak", "a depiction paints itself, never the page; put the colour on the element");
+    if ((m = /<(?:form|input|textarea|select|a|iframe|script|dialog|details)\b|contentEditable|role=["'](?:button|textbox|switch|checkbox|listbox|option|tab|menu)|\btabIndex=/.exec(code))) L.hit(at(m), "inert", `${m[0]}: a depiction is a picture — a link there is a <span> that looks like one; the founder's controls sit beside the frame`);
+    const handlers = [...code.matchAll(/\bon[A-Z]\w*=\{/g)];
+    if (handlers.length > 1) L.hit(at(handlers[1]), "handler", "one toggle at most (the target's own \"…more\"); more than one handler is a control, and controls sit beside the frame");
+    if ((m = /\bon[A-Z]\w*=\{(?!\s*\(\s*\w*\s*\)\s*=>)/.exec(code))) L.hit(at(m), "handler", "one toggle at most, written in place: onClick={() => setOpen(true)}");
+    // The default export's parameter list, whether it is written in place
+    // or `export default XPost;` names a function declared above.
+    const SIG = String.raw`(?:function\s*\w*\s*\(\s*(?:\{([^}]*)\}|(\w+))?\s*\)|(?:\(\s*(?:\{([^}]*)\}|(\w+))?\s*\)|(\w+))\s*=>)`;
+    let main = new RegExp(String.raw`export\s+default\s+${SIG}`).exec(code);
+    const byName = /export\s+default\s+([A-Za-z_$][\w$]*)\s*;/.exec(code);
+    if (!main && byName) main = new RegExp(String.raw`(?:function\s+${byName[1]}\s*\(\s*(?:\{([^}]*)\}|(\w+))?\s*\)|(?:const|let|var)\s+${byName[1]}\s*=\s*(?:\(\s*(?:\{([^}]*)\}|(\w+))?\s*\)|(\w+))\s*=>)`).exec(code);
+    const destructured = main?.[1] ?? main?.[3] ?? "";
+    const bag = main?.[2] ?? main?.[4] ?? main?.[5];
+    if (/\b(?:on[A-Z]\w*|className|style|children|render)\b/.test(destructured)) L.hit(at(main), "props", "props are data (text, name, avatar, mode) — never a verb, a class, a style or children");
+    if (/\.\.\./.test(destructured)) L.hit(at(main), "props", "name every prop ({ text, name, mode }); a rest bag is how a class or a style would get in");
+    if (bag && (m = new RegExp(`\\b${bag}\\.(?:on[A-Z]\\w*|className|style|children|render)\\b`).exec(code))) L.hit(at(m), "props", "props are data (text, name, avatar, mode) — never a verb, a class, a style or children");
+    // A helper inside the file may take children (it gets JSX from this
+    // file); the default export never does, and never hands its props on
+    // whole — a spread is how children or a class would reach a helper.
+    if ((m = /\{\s*\.\.\.[\w.]+\s*\}/.exec(code))) L.hit(at(m), "props", "no spread: pass a depiction's data by name (text={text}), never {...props}");
+    if ((m = /\buse(?!State\b|Memo\b|Id\b)[A-Z]\w*\(/.exec(code))) L.hit(at(m), "hook", "a depiction is a pure function of its props (useState for one toggle, useMemo, useId at most)");
+    if (/\buse(?:State|Memo|Id)\(/.test(code) && !/^\s*["']use client["']/.test(raw)) L.hit(f.path, "client", 'a hook needs "use client" on the first line');
+    if ((m = /\bfetch\(|\bwindow\.|\bdocument\.(?![\w-]+["'\s])|localStorage|sessionStorage|getComputedStyle|matchMedia|\bref=\{|"use server"|revalidate/.exec(code))) L.hit(at(m), "io", "no reads, no writes, no browser: the surface does that beside the frame");
+  }
+
+  // (b) where it is framed. The folder has one door: a static default
+  //     import under a Capitalised name. Any other string that names the
+  //     folder (import(), require(), a re-export, a split path) is a way
+  //     round the frame, wherever it sits.
+  const DOOR = /(?<!^\s*import\s+[\w$]+\s+from\s*)["'`][^"'`\n]*\bdepictions\b[^"'`\n]*["'`]/m;
+  scan(DOOR, (f, m, line) => {
+    const slug = /depictions\/([a-z0-9-]+)/.exec(m[0])?.[1];
+    if (slug) claimed.add(slug);
+    L.hit(`${f.path}:${line}`, "door", `${m[0]}: a depiction is reached by one door — import XPost from "…/depictions/x-post" at the top of the file that frames it`);
+  });
+  scan(/\bimport\s*\(|\brequire\s*\(/, (f, m, line) => L.hit(`${f.path}:${line}`, "dynamic", `${m[0].trim()} — the app is one static bundle; write import X from "…" at the top of the file`));
+  const IMPORT = /^\s*import\s+([^;]*?)\s+from\s*["']([^"']*depictions\/([^"']+?))(?:\.jsx?)?["']/gm;
+  const FRAME = new RegExp(String.raw`<Depiction\b(${ATTRS})>\s*<([A-Z]\w*)\b${ATTRS}\/>\s*<\/Depiction>`, "g");
+  for (const f of appFiles) {
+    const code = f.code;
+    const importsHere = [...code.matchAll(IMPORT)];
+    const opened = [...code.matchAll(/<Depiction\b/g)];
+    if (/data-depiction=|(?:function|const)\s+Depiction\b|\bas\s+Depiction\b/.test(code)) L.hit(f.path, "frame", "the frame is the kit's (components/ui/depiction.jsx)");
+    if (!importsHere.length && !opened.length) continue;
+    if (!FRAME_HOST.test(f.path)) {
+      L.hit(f.path, "place", "a depiction is framed on a surface or in the component that holds the draft (components/<X>.jsx), never in the shell, the kit or lib/");
+      continue;
+    }
+    if (!/^\s*import\s*\{[^}]*\bDepiction\b[^}]*\}\s*from\s*["'](?:\.\.\/components\/ui|\.\/ui)(?:\/depiction)?["']/m.test(code)) L.hit(f.path, "wrap", 'wrap it: import { Depiction } from "../components/ui" (a surface) or "./ui" (a component)');
+    // Code with its strings blanked too (same length, so indices hold),
+    // and the names this file binds to JSX (const look = <b/>).
+    const bare = code.replace(/(["'`])(?:(?!\1)[^\\\n]|\\.)*\1/g, (str) => str.replace(/[^\n]/g, " "));
+    const bound = [...bare.matchAll(/\b(?:const|let|var)\s+(\w+)\s*=\s*\(?\s*</g)].map((m) => m[1]);
+    const names = new Map(); // component name → slug
+    let named = false;
+    for (const m of importsHere) {
+      const what = (m[1] ?? "").trim();
+      const slug = m[3];
+      if (!/^[A-Z]\w*$/.test(what)) {
+        named = true;
+        claimed.add(slug);
+        L.hit(`${f.path}:${lineOf(code, m.index)}`, "named", `import the picture under a Capitalised name and nothing else: import ${slug.replace(/(^|-)(\w)/g, (_, __, c) => c.toUpperCase())} from "…/depictions/${slug}"`);
+        continue;
+      }
+      if (!existsSync(join(ROOT, "components", "depictions", `${slug}.jsx`))) L.hit(`${f.path}:${lineOf(code, m.index)}`, "missing", `components/depictions/${slug}.jsx is not there`);
+      names.set(what, slug);
+    }
+    if (named) continue;
+    const wrapped = [...code.matchAll(FRAME)];
+    if (opened.length !== wrapped.length) {
+      const bad = opened.find((o) => !wrapped.some((w) => w.index === o.index)) ?? opened[0];
+      L.hit(`${f.path}:${lineOf(code, bad.index)}`, "one", "inside <Depiction> goes exactly one depiction, self-closing; the chrome around it is the app");
+    }
+    const framed = new Map();
+    for (const fr of wrapped) {
+      const [, attrs, name] = fr;
+      const where = `${f.path}:${lineOf(code, fr.index)}`;
+      const slug = names.get(name);
+      if (!slug) {
+        L.hit(where, "one", `<${name}> inside <Depiction> is not a depiction; the frame holds one imported picture`);
+        continue;
+      }
+      const of = /\bof=(?:["']([a-z0-9-]+)["']|\{["']([a-z0-9-]+)["']\})/.exec(attrs);
+      const ofSlug = of?.[1] ?? of?.[2];
+      if (!of) L.hit(where, "of", `of must be a plain string naming the file: of="${slug}"`);
+      else if (ofSlug !== slug) L.hit(where, "of", `of="${slug}" names the file it frames`);
+      if (!/\bscheme=["'](?:light|dark)["']/.test(attrs) || !/\bwidth=\{\d+\}/.test(attrs)) L.hit(where, "frame-props", 'the frame needs scheme="light|dark" (the TARGET\'s) and width={<px from the header>}');
+      // Data goes through the frame; an element, an object, an array, a
+      // function or a spread does not, whatever the prop is called.
+      const tag = fr[0].slice(fr[0].indexOf(`<${name}`));
+      if (/\{\s*\.\.\.|=\{\s*[<{\[(`]|=>|=\{\s*(?:async\s+)?function\b/.test(tag) || bound.some((b) => new RegExp(`=\\{\\s*${b}\\b`).test(tag))) L.hit(where, "one", "the picture takes data props only (text={draft.text}, name=\"…\"); no element, object, array, function or spread goes through the frame");
+      framed.set(name, (framed.get(name) ?? 0) + 1);
+      rendered.set(slug, [...(rendered.get(slug) ?? []), f.path]);
+    }
+    // Every reference to the name but the import must be a framed tag: an
+    // alias (const P = XPost), a prop or a bare render is a leak. A string
+    // may name it (a caption); only code counts. An escaped identifier
+    // (\u0058Post) is the same binding spelled past the regex: refused.
+    let esc;
+    if ((esc = /\\u(?:\{[0-9a-fA-F]+\}|[0-9a-fA-F]{4})/.exec(bare))) L.hit(`${f.path}:${lineOf(code, esc.index)}`, "escape", "an escaped identifier; write the name as it is imported");
+    for (const [name] of names) {
+      const imp = importsHere.find((m) => (m[1] ?? "").trim() === name);
+      const inside = (i) => (imp && i >= imp.index && i < imp.index + imp[0].length) || wrapped.some((fr) => fr[2] === name && i >= fr.index && i < fr.index + fr[0].length);
+      const stray = [...bare.matchAll(new RegExp(`\\b${name}\\b`, "g"))].filter((m) => !inside(m.index));
+      if (!stray.length) {
+        if (!framed.get(name)) L.hit(f.path, `outside-${name}`, `${name} is imported and never framed`);
+        continue;
+      }
+      const where = `${f.path}:${lineOf(code, stray[0].index)}`;
+      if (bare[stray[0].index - 1] === "<") L.hit(where, `outside-${name}`, `<${name}> rendered outside its frame — it inherits the workspace; wrap it in <Depiction of= scheme= width=>`);
+      else L.hit(where, `alias-${name}`, `${name} used as a value here (aliased, called or passed along) — a depiction is written as <${name} …/> directly inside <Depiction> and nowhere else`);
+    }
+  }
+
+  // (c) nothing in the folder is dead
+  for (const f of depictionFiles) {
+    const slug = slugOf(f.path);
+    if (!rendered.has(slug) && !helpers.has(slug) && !claimed.has(slug)) L.hit(f.path, "dead", "dead depiction — frame it on a surface or in the component that holds the draft, or delete it");
+  }
+
+  const hosts = new Set([...rendered.values()].flat()).size;
+  if (!depictionFiles.length) ok7("none");
+  else ok7(`${pictures} picture${pictures === 1 ? "" : "s"} of elsewhere, framed in ${hosts} file${hosts === 1 ? "" : "s"}: ${[...rendered.keys()].join(", ")}`);
+}
+
+// 6. Smoke: the app, built and started, answers every surface.
+
+/** Newest mtime among the app's own sources (what a build reads). */
+function newestSource() {
+  let newest = 0;
+  for (const f of walk(ROOT)) {
+    const rel = relative(ROOT, f);
+    if (/^(node_modules|\.next|\.next-check|check)\//.test(rel)) continue;
+    newest = Math.max(newest, statSync(f).mtimeMs);
+  }
+  return newest;
+}
+
+function writable(dir) {
+  try {
+    accessSync(dir, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Where the build goes: { dir, dist } — in place when the app folder is
+ *  ours to write, else a copy of the sources under a folder that is. */
+function buildSite() {
+  if (writable(ROOT)) return { dir: ROOT, dist: ".next-check", copied: false };
+  const name = basename(dirname(ROOT)) || "app"; // plays/<name>/app
+  const home = writable(homedir()) ? homedir() : tmpdir();
+  return { dir: join(home, ".claw-check", name), dist: ".next", copied: true };
+}
+
+/** Copy the app's sources (never node_modules or a build) to `dir`, and
+ *  point its node_modules back at the app's. */
+function copySources(dir) {
+  for (const stale of readdirSync(dir, { withFileTypes: true }).filter((e) => e.name !== "node_modules" && e.name !== ".next")) {
+    rmSync(join(dir, stale.name), { recursive: true, force: true });
+  }
+  cpSync(ROOT, dir, {
+    recursive: true,
+    dereference: false,
+    filter: (src) => {
+      const rel = relative(ROOT, src);
+      return !/^(node_modules|\.next|\.next-check|check)(\/|$)/.test(rel);
+    },
+  });
+  const link = join(dir, "node_modules");
+  if (!existsSync(link)) symlinkSync(join(ROOT, "node_modules"), link, "dir");
+}
+
+function buildForCheck(site, env) {
+  const stamp = join(site.dir, site.dist, "BUILD_ID");
+  if (existsSync(stamp) && statSync(stamp).mtimeMs >= newestSource()) return { ok: true, reused: true };
+  const started = Date.now();
+  if (site.copied) {
+    mkdirSync(site.dir, { recursive: true });
+    copySources(site.dir);
+  }
+  const r = spawnSync(join(site.dir, "node_modules", ".bin", "next"), ["build"], { cwd: site.dir, env, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) {
+    const tail = `${r.stdout ?? ""}\n${r.stderr ?? ""}`.trim().split("\n").filter(Boolean).slice(-8).join("\n");
+    return { ok: false, tail };
+  }
+  return { ok: true, reused: false, seconds: ((Date.now() - started) / 1000).toFixed(0) };
+}
+
+async function smoke() {
+  const site = buildSite();
+  const base = { ...process.env, ...dotenv(join(ROOT, ".env")), NODE_ENV: "production", HOSTNAME: "127.0.0.1", CLAW_DIST_DIR: site.dist };
+  delete base.CLAW_PRODUCT_TOKEN; // the check is not the proxy; the middleware would 401 it
+  const built = buildForCheck(site, base);
+  if (!built.ok) {
+    fail("smoke", "build", `next build failed:\n${built.tail}`);
+    return;
+  }
+  const buildNote = built.reused ? "build reused" : `built in ${built.seconds}s${site.copied ? ` (copy at ${site.dir})` : ""}`;
+  const manifest = join(site.dir, site.dist, "required-server-files.json");
+  const basePath = existsSync(manifest) ? (JSON.parse(readFileSync(manifest, "utf8"))?.config?.basePath ?? "") : "";
+  const env = { ...base, CLAW_BASE_PATH: basePath };
+  const port = await freePort();
+  env.PORT = String(port);
+  const child = spawn(join(site.dir, "node_modules", ".bin", "next"), ["start"], { cwd: site.dir, env, stdio: ["ignore", "pipe", "pipe"] });
+  let log = "";
+  child.stdout.on("data", (d) => (log += d));
+  child.stderr.on("data", (d) => (log += d));
+  const origin = `http://127.0.0.1:${port}${basePath}`;
+  const started = Date.now();
+  try {
+    const up = await waitFor(() => fetch(`${origin}/`, { redirect: "manual" }).then((r) => r.status < 500), 60_000);
+    if (!up) {
+      fail("smoke", origin, `did not start in 60s. Last log lines:\n${log.trim().split("\n").slice(-6).join("\n")}`);
+      return;
+    }
+    const results = [];
+    const home = await fetch(`${origin}/`, { redirect: "manual" });
+    results.push(`/ → ${home.status}`);
+    if (!(home.status === 200 || (home.status >= 300 && home.status < 400))) fail("smoke", "/", `answered ${home.status}`);
+    for (const key of surfaceKeys) {
+      const res = await fetch(`${origin}/s/${encodeURIComponent(key)}`);
+      const body = await res.text();
+      const broke = /Something broke on this surface|The page could not render|Application error: a (client|server)-side exception/.test(body);
+      results.push(`/s/${key} ${res.status}${broke ? " BROKE" : ""}`);
+      if (res.status !== 200) fail("smoke", `/s/${key}`, `answered ${res.status}`);
+      else if (broke) fail("smoke", `/s/${key}`, `rendered the error boundary. Last log lines:\n${log.trim().split("\n").slice(-6).join("\n")}`);
+    }
+    const errors = log.split("\n").filter((l) => /\b(Error|TypeError|ReferenceError)\b/.test(l) && !/ECONNREFUSED|DATABASE_URL/.test(l));
+    if (errors.length) fail("smoke", "server log", errors.slice(0, 3).join(" | "));
+    if (!failures.includes("smoke")) ok("smoke", `${buildNote} · ${results.join(" · ")} (${((Date.now() - started) / 1000).toFixed(1)}s)`);
+  } finally {
+    child.kill("SIGTERM");
+  }
+}
+
+function dotenv(path) {
+  if (!existsSync(path)) return {};
+  const out = {};
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    const m = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)\s*$/.exec(line);
+    if (!m) continue;
+    out[m[1]] = m[2].replace(/^(['"])(.*)\1$/, "$2");
+  }
+  return out;
+}
+
+function freePort() {
+  return new Promise((resolve, reject) => {
+    const s = createServer();
+    s.listen(0, "127.0.0.1", () => {
+      const { port } = s.address();
+      s.close(() => resolve(port));
+    });
+    s.on("error", reject);
+  });
+}
+
+async function waitFor(probe, ms) {
+  const until = Date.now() + ms;
+  while (Date.now() < until) {
+    try {
+      if (await probe()) return true;
+    } catch {}
+    await new Promise((r) => setTimeout(r, 500));
+  }
+  return false;
+}
+
+if (!STATIC_ONLY) await smoke();
+
+console.log(`check: ${files.length} files · ${surfaceKeys.length} surface${surfaceKeys.length === 1 ? "" : "s"}${STATIC_ONLY ? " · static only" : ""}`);
+for (const l of lines) console.log(l);
+const failed = new Set(failures).size;
+console.log(failed ? `${failed} rule${failed === 1 ? "" : "s"} failed` : "all clear");
+process.exit(failed ? 1 : 0);