@loworbitstudio/visor 0.10.2 → 1.2.0

package/dist/index.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync22 } from "fs";
-import { dirname as dirname8, join as join20 } from "path";
-import { fileURLToPath as fileURLToPath3 } from "url";
+import { readFileSync as readFileSync26 } from "fs";
+import { dirname as dirname10, join as join24 } from "path";
+import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
 
 // src/commands/check.ts
@@ -3843,7 +3843,7 @@ import {
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-import { join as join15, basename as basename3, resolve as resolve11, sep } from "path";
+import { join as join15, basename as basename3, resolve as resolve11, sep, relative as relative2 } from "path";
 import { parse as parseYaml2 } from "yaml";
 import { generateThemeData as generateThemeData4, validateFontCoverage, formatFontCoverageError } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
@@ -3939,6 +3939,32 @@ function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
   }
   return { files: [...merged.values()], deprecationWarnings };
 }
+function emitFailureSummary({
+  failures,
+  succeeded,
+  options,
+  cwd
+}) {
+  if (options.json) {
+    console.log(
+      JSON.stringify({
+        success: false,
+        themes: succeeded,
+        failures: failures.map((f) => ({ filePath: f.filePath, error: f.error }))
+      })
+    );
+    return;
+  }
+  const lines2 = [
+    `Theme sync: ${succeeded} succeeded, ${failures.length} failed.`,
+    "",
+    "Failed:",
+    ...failures.map((f) => `  ${relative2(cwd, f.filePath)} \u2014 ${f.error}`),
+    "",
+    "Re-run after fixing the failed themes."
+  ];
+  logger.error(lines2.join("\n"));
+}
 function reportBrokenSymlink(err, options) {
   const msg = `Broken symlink in theme source: ${err.path} \u2192 ${err.target}`;
   if (options.json) {
@@ -4220,20 +4246,23 @@ function themeSyncCommand(cwd, options) {
     for (const w of discoveryWarnings) logger.warn(w);
   }
   const manifest = [];
-  const errors = [];
+  const failures = [];
   const processFile = (filePath, isCustom, slugOverride) => {
     let yamlContent;
     try {
       yamlContent = readFileSync16(filePath, "utf-8");
     } catch {
-      errors.push(`Could not read: ${filePath}`);
+      failures.push({ filePath, error: `Could not read: ${filePath}` });
       return;
     }
     let data;
     try {
       data = generateThemeData4(yamlContent);
     } catch (err) {
-      errors.push(`Failed to parse ${basename3(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`);
+      failures.push({
+        filePath,
+        error: `Failed to parse ${basename3(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
+      });
       return;
     }
     const slug2 = slugOverride ?? toSlug(data.config.name);
@@ -4244,7 +4273,10 @@ function themeSyncCommand(cwd, options) {
     const coverage = validateFontCoverage(css);
     if (coverage.errors.length > 0) {
       for (const e of coverage.errors) {
-        errors.push(formatFontCoverageError(basename3(filePath), e.declaredAt, e.family));
+        failures.push({
+          filePath,
+          error: formatFontCoverageError(basename3(filePath), e.declaredAt, e.family)
+        });
       }
       return;
     }
@@ -4256,12 +4288,8 @@ function themeSyncCommand(cwd, options) {
     const isNested = c.origin !== "legacy";
     processFile(c.filePath, true, isNested ? c.slug : void 0);
   }
-  if (errors.length > 0) {
-    if (options.json) {
-      console.log(JSON.stringify({ success: false, errors }));
-    } else {
-      errors.forEach((e) => logger.error(e));
-    }
+  if (manifest.length === 0) {
+    emitFailureSummary({ failures, succeeded: 0, options, cwd });
     process.exit(1);
     return;
   }
@@ -4297,6 +4325,7 @@ function themeSyncCommand(cwd, options) {
   const newPublicYamlSet = new Set(manifest.map((e) => `${e.yamlFilename}.visor.yaml`));
   const stalePublicYamls = existingPublicYamls.filter((f) => !newPublicYamlSet.has(f));
   if (options.dryRun) {
+    const dryRunHasFailures = failures.length > 0;
     const changes = {
       themesDiscovered: manifest.map((e) => ({ slug: e.slug, group: e.group, isCustom: e.isCustom })),
       cssFilesGenerated: allSlugs.map((s) => `packages/docs/app/${s}-theme.css`),
@@ -4309,13 +4338,25 @@ function themeSyncCommand(cwd, options) {
       publicYamlsDeleted: stalePublicYamls.map((f) => `packages/docs/public/themes/${f}`)
     };
     if (options.json) {
-      console.log(JSON.stringify({ success: true, dryRun: true, changes }));
+      console.log(JSON.stringify({
+        success: !dryRunHasFailures,
+        dryRun: true,
+        changes,
+        ...dryRunHasFailures ? { failures: failures.map((f) => ({ filePath: f.filePath, error: f.error })) } : {}
+      }));
     } else {
       logger.info("Dry run \u2014 no files written");
       logger.item(`Themes discovered: ${manifest.length} (${stockManifest.length} stock, ${customManifest.length} custom)`);
       manifest.forEach((e) => logger.item(`  ${e.slug} \u2014 group: ${e.group}`));
       if (staleCssFiles.length > 0) logger.item(`CSS files to delete: ${staleCssFiles.join(", ")}`);
       if (stalePublicYamls.length > 0) logger.item(`Public YAMLs to delete: ${stalePublicYamls.join(", ")}`);
+      if (dryRunHasFailures) {
+        emitFailureSummary({ failures, succeeded: manifest.length, options, cwd });
+      }
+    }
+    if (dryRunHasFailures) {
+      process.exit(1);
+      return;
     }
     return;
   }
@@ -4353,20 +4394,28 @@ function themeSyncCommand(cwd, options) {
     process.exit(2);
     return;
   }
+  const hasFailures = failures.length > 0;
   if (options.json) {
     const warnings = [...deprecationWarnings, ...discoveryWarnings];
     console.log(JSON.stringify({
-      success: true,
+      success: !hasFailures,
       themes: manifest.length,
       stock: stockManifest.length,
       custom: customManifest.length,
       staleCssDeleted: staleCssFiles.length,
       staleYamlsDeleted: stalePublicYamls.length,
       slugs: allSlugs,
-      ...warnings.length > 0 ? { warnings } : {}
+      ...warnings.length > 0 ? { warnings } : {},
+      ...hasFailures ? {
+        failures: failures.map((f) => ({ filePath: f.filePath, error: f.error }))
+      } : {}
     }));
   } else {
-    logger.success(`Theme sync complete \u2014 ${manifest.length} themes registered`);
+    if (hasFailures) {
+      logger.info(`Theme sync partial \u2014 ${manifest.length} themes registered`);
+    } else {
+      logger.success(`Theme sync complete \u2014 ${manifest.length} themes registered`);
+    }
     logger.item(`Stock: ${stockManifest.map((e) => e.slug).join(", ")}`);
     if (customManifest.length > 0) {
       logger.item(`Custom: ${customManifest.map((e) => e.slug).join(", ")}`);
@@ -4374,6 +4423,13 @@ function themeSyncCommand(cwd, options) {
     if (staleCssFiles.length > 0) {
       logger.item(`Removed stale CSS: ${staleCssFiles.join(", ")}`);
     }
+    if (hasFailures) {
+      emitFailureSummary({ failures, succeeded: manifest.length, options, cwd });
+    }
+  }
+  if (hasFailures) {
+    process.exit(1);
+    return;
   }
 }
 
@@ -5486,7 +5542,7 @@ Visor Tokens (${categoryLabel}) \u2014 ${tokens2.length} tokens
 
 // src/commands/migrate-token-substitution.ts
 import { readFileSync as readFileSync21, writeFileSync as writeFileSync11, readdirSync as readdirSync11, statSync as statSync8, existsSync as existsSync18 } from "fs";
-import { resolve as resolve13, join as join19, relative as relative3 } from "path";
+import { resolve as resolve13, join as join19, relative as relative4 } from "path";
 import { parse as parseYaml3 } from "yaml";
 import pc4 from "picocolors";
 var V7_ENTR_SUBSTITUTION_MAP = {
@@ -5679,7 +5735,7 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
     process.exit(0);
     return;
   }
-  const relTarget = relative3(cwd, targetPath) || ".";
+  const relTarget = relative4(cwd, targetPath) || ".";
   if (dryRun) {
     logger.heading(`visor migrate token-substitution \u2014 dry run`);
     logger.blank();
@@ -5690,7 +5746,7 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
     logger.heading(`Proposed changes (${result.filesChanged} file(s), ${result.totalSubstitutions} substitution(s)):`);
     logger.blank();
     for (const f of result.files) {
-      const relFile = relative3(cwd, f.file);
+      const relFile = relative4(cwd, f.file);
       logger.info(pc4.bold(`  ${relFile}`));
       for (const sub of f.substitutions) {
         logger.info(
@@ -5711,7 +5767,7 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
     logger.info(`  Scanned: ${result.filesScanned} file(s)`);
     logger.blank();
     for (const f of result.files) {
-      const relFile = relative3(cwd, f.file);
+      const relFile = relative4(cwd, f.file);
       logger.success(`  ${relFile} (${f.substitutions.length} substitution(s))`);
     }
     logger.blank();
@@ -5722,10 +5778,1044 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
   process.exit(0);
 }
 
+// src/commands/sandbox/init.ts
+import { existsSync as existsSync21, mkdirSync as mkdirSync8, readFileSync as readFileSync23, rmSync as rmSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join21, resolve as resolve15, dirname as dirname9 } from "path";
+import { fileURLToPath as fileURLToPath3 } from "url";
+import * as childProcess2 from "child_process";
+
+// src/commands/sandbox/parse-handoff.ts
+import { readFileSync as readFileSync22, existsSync as existsSync19 } from "fs";
+import { dirname as dirname8, resolve as resolve14, isAbsolute } from "path";
+function parseHandoff(handoffPath) {
+  const text = readFileSync22(handoffPath, "utf-8");
+  const lines2 = text.split("\n");
+  const warnings = [];
+  const pattern2 = extractPatternSlug(lines2, warnings);
+  const theme2 = extractMetaField(lines2, "Theme");
+  const recipePath = extractRecipePath(text, handoffPath, warnings);
+  const primitives = extractPrimitives(text, warnings);
+  const { screens, mockShapes } = recipePath && existsSync19(recipePath) ? extractRecipeArtifacts(recipePath, warnings) : { screens: [], mockShapes: [] };
+  return { pattern: pattern2, theme: theme2, recipePath, primitives, screens, mockShapes, warnings };
+}
+function extractPatternSlug(lines2, warnings) {
+  const h1 = lines2.find((l) => /^#\s/.test(l));
+  if (!h1) {
+    warnings.push("Handoff has no H1 \u2014 pattern slug fell back to 'sandbox'");
+    return "sandbox";
+  }
+  const m = h1.match(/^#\s+(?:Design\s+handoff\s+[—-]\s+)?(.+?)\s*$/i);
+  if (!m) {
+    warnings.push(`Could not parse pattern from H1: ${h1}`);
+    return "sandbox";
+  }
+  return m[1].trim().toLowerCase().replace(/\s+/g, "-");
+}
+function extractMetaField(lines2, field) {
+  const re = new RegExp(`^\\*\\*${field}:\\*\\*\\s+([^\\s(*]+)`, "i");
+  for (const l of lines2) {
+    const m = l.match(re);
+    if (m) return m[1].trim();
+  }
+  return void 0;
+}
+function extractRecipePath(text, handoffPath, warnings) {
+  const m = text.match(/##\s+Recipe[\s\S]*?\[`?([^\]`]+)`?\]\(([^)]+)\)/i);
+  if (!m) {
+    warnings.push("Could not locate Recipe link in handoff");
+    return void 0;
+  }
+  const href = m[2].trim();
+  if (isAbsolute(href)) return href;
+  return resolve14(dirname8(handoffPath), href);
+}
+var STATUS_PATTERNS = [
+  { re: /NEW\s+gap/i, status: "gap-new" },
+  { re: /blocked-by/i, status: "gap-new" },
+  { re: /in\s+flight/i, status: "gap-inflight" },
+  { re: /shipped/i, status: "shipped" }
+];
+function classifyStatus(cell) {
+  for (const { re, status } of STATUS_PATTERNS) {
+    if (re.test(cell)) return status;
+  }
+  return "shipped";
+}
+function extractVITicket(cell) {
+  const m = cell.match(/VI-(\d+)/i);
+  return m ? `VI-${m[1]}` : void 0;
+}
+function extractPrimitives(text, warnings) {
+  const primitives = [];
+  const seen = /* @__PURE__ */ new Set();
+  const tableMatches = text.matchAll(/\|\s*Component\s*\|[^\n]*\n\|[^\n]*\n((?:\|[^\n]*\n?)+)/gi);
+  for (const tm of tableMatches) {
+    const rows = tm[1].split("\n").map((r) => r.trim()).filter((r) => r.startsWith("|"));
+    for (const row of rows) {
+      const cells = row.split("|").map((c) => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+      if (cells.length < 2) continue;
+      const rawName = cells[0].replace(/`/g, "").trim();
+      const nameCell = rawName.replace(/\s*\([^)]*\)\s*/g, "").trim();
+      if (!nameCell || nameCell.includes("---") || nameCell === "Component") continue;
+      if (seen.has(nameCell)) continue;
+      seen.add(nameCell);
+      const joined = cells.slice(1).join(" | ");
+      const status = classifyStatus(joined);
+      const viTicket = status === "shipped" ? void 0 : extractVITicket(joined);
+      const kindCell = cells[1] || "";
+      const annotation = rawName.match(/\(([^)]+)\)/)?.[1] ?? "";
+      const kind = /block/i.test(kindCell) || /block/i.test(annotation) ? "block" : /primitive/i.test(kindCell) || /primitive/i.test(annotation) ? "primitive" : void 0;
+      primitives.push({ name: nameCell, status, viTicket, kind });
+    }
+  }
+  if (primitives.length === 0) {
+    warnings.push("Handoff has no Component inventory rows \u2014 sandbox will be empty");
+  }
+  return primitives;
+}
+function extractRecipeArtifacts(recipePath, warnings) {
+  const text = readFileSync22(recipePath, "utf-8");
+  const screens = extractScreens(text);
+  const mockShapes = extractMockFields(text, warnings);
+  return { screens, mockShapes };
+}
+function extractScreens(text) {
+  const out = [];
+  const matches = text.matchAll(/^###\s+Screen\s+\d+:\s+(.+?)(?:\s*\(`([^`]+)`\))?\s*$/gim);
+  let idx = 1;
+  for (const m of matches) {
+    const title = m[1].trim();
+    const route = m[2]?.trim();
+    const slug2 = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const name = slug2 || `screen-${idx}`;
+    out.push({ name, title, route });
+    idx++;
+  }
+  return out;
+}
+function extractMockFields(text, warnings) {
+  const m = text.match(/##\s+Inputs[^\n]*\n+([\s\S]*?)(?=\n##\s|\n$)/i);
+  if (!m) {
+    warnings.push(
+      "Recipe has no 'Inputs from generation skill' section \u2014 mock data will be empty"
+    );
+    return [];
+  }
+  const rows = m[1].split("\n").filter((r) => r.startsWith("|"));
+  if (rows.length < 2) return [];
+  const out = [];
+  for (const row of rows.slice(2)) {
+    const cells = row.split("|").map((c) => c.trim()).filter((_, i, arr) => i > 0 && i < arr.length - 1);
+    if (cells.length < 2) continue;
+    const field = cells[0].replace(/`/g, "").trim();
+    if (!field) continue;
+    const type = cells[1].replace(/`/g, "").trim();
+    const description = cells[2]?.trim();
+    out.push({ field, type, description });
+  }
+  return out;
+}
+
+// src/commands/sandbox/ports.ts
+import { createServer } from "net";
+var RESERVED_PORTS = /* @__PURE__ */ new Set([3e3]);
+var MAX_PORT_PROBES = 50;
+var DEFAULT_START_PORT = 4060;
+async function findOpenPort(start = DEFAULT_START_PORT) {
+  let port = start;
+  for (let i = 0; i < MAX_PORT_PROBES; i++) {
+    if (RESERVED_PORTS.has(port)) {
+      port++;
+      continue;
+    }
+    const free = await tryPort(port);
+    if (free) return port;
+    port++;
+  }
+  throw new Error(
+    `Could not find an open port between ${start} and ${start + MAX_PORT_PROBES} (port 3000 excluded)`
+  );
+}
+function tryPort(port) {
+  return new Promise((resolveProbe) => {
+    const server = createServer();
+    server.once("error", () => resolveProbe(false));
+    server.once("listening", () => {
+      server.close(() => resolveProbe(true));
+    });
+    server.listen(port, "127.0.0.1");
+  });
+}
+
+// src/commands/sandbox/scaffold.ts
+import { mkdirSync as mkdirSync7, writeFileSync as writeFileSync12, existsSync as existsSync20, readdirSync as readdirSync12 } from "fs";
+import { join as join20 } from "path";
+
+// src/commands/sandbox/templates.ts
+var SANDBOX_PACKAGE_VERSION = "16.2.6";
+var SANDBOX_REACT_VERSION = "19.0.0";
+var SANDBOX_REACT_DOM_VERSION = "19.0.0";
+var SANDBOX_PLAYWRIGHT_VERSION = "1.49.0";
+var SANDBOX_PIXELMATCH_VERSION = "6.0.0";
+var SANDBOX_PNGJS_VERSION = "7.0.0";
+function packageJsonTemplate(name) {
+  return `${JSON.stringify(
+    {
+      name: `sandbox-${name}`,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      scripts: {
+        dev: "next dev",
+        build: "next build",
+        start: "next start"
+      },
+      dependencies: {
+        next: SANDBOX_PACKAGE_VERSION,
+        react: SANDBOX_REACT_VERSION,
+        "react-dom": SANDBOX_REACT_DOM_VERSION,
+        "@loworbitstudio/visor-core": "*",
+        "@loworbitstudio/visor-theme-engine": "*"
+      },
+      devDependencies: {
+        "@types/node": "^22.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        typescript: "^5.7.2",
+        "@playwright/test": `^${SANDBOX_PLAYWRIGHT_VERSION}`,
+        pixelmatch: `^${SANDBOX_PIXELMATCH_VERSION}`,
+        pngjs: `^${SANDBOX_PNGJS_VERSION}`
+      }
+    },
+    null,
+    2
+  )}
+`;
+}
+function tsconfigTemplate() {
+  return `${JSON.stringify(
+    {
+      compilerOptions: {
+        target: "ES2022",
+        lib: ["dom", "dom.iterable", "esnext"],
+        allowJs: false,
+        skipLibCheck: true,
+        strict: true,
+        noEmit: true,
+        esModuleInterop: true,
+        module: "esnext",
+        moduleResolution: "bundler",
+        resolveJsonModule: true,
+        isolatedModules: true,
+        jsx: "preserve",
+        incremental: true,
+        plugins: [{ name: "next" }],
+        paths: { "@/*": ["./*"] }
+      },
+      include: ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
+      exclude: ["node_modules", "captures", ".next"]
+    },
+    null,
+    2
+  )}
+`;
+}
+function nextConfigTemplate() {
+  return `import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  // Sandbox is local-only \u2014 disable production telemetry and image opt to keep startup fast.
+  images: { unoptimized: true },
+}
+
+export default nextConfig
+`;
+}
+function nextEnvDtsTemplate() {
+  return `/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+`;
+}
+function gitignoreTemplate() {
+  return [
+    "node_modules",
+    ".next",
+    "out",
+    "captures/pending",
+    "captures/diffs",
+    "*.log",
+    ""
+  ].join("\n");
+}
+function rootLayoutTemplate(pattern2) {
+  return `import "./globals.css"
+import { FOWT_SCRIPT } from "@loworbitstudio/visor-theme-engine/fowt"
+import type { Metadata } from "next"
+import type { ReactNode } from "react"
+
+export const metadata: Metadata = {
+  title: "Sandbox \u2014 ${pattern2}",
+  description: "Visor sandbox for in-vivo primitive iteration.",
+}
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <script>{FOWT_SCRIPT}</script>
+      </head>
+      <body>{children}</body>
+    </html>
+  )
+}
+`;
+}
+function globalsCssPlaceholder() {
+  return `/* This file is overwritten by 'visor theme apply' during sandbox init. */
+:root {
+  --bg-surface: #f7f7f8;
+  --text-primary: #111827;
+}
+body { background: var(--bg-surface); color: var(--text-primary); margin: 0; font-family: system-ui, -apple-system, "Segoe UI", sans-serif; }
+`;
+}
+function indexPageTemplate() {
+  return `import Link from "next/link"
+import { manifest } from "@/lib/sandbox-manifest"
+
+export default function SandboxIndex() {
+  return (
+    <main style={{ padding: "32px", maxWidth: "880px", margin: "0 auto" }}>
+      <h1>Sandbox: {manifest.pattern}</h1>
+      <p style={{ color: "var(--text-secondary, #555)" }}>{manifest.primitives.length} primitives \xB7 {manifest.screens.length} screens</p>
+      <section>
+        <h2>Primitives</h2>
+        <ul>
+          {manifest.primitives.map((p) => (
+            <li key={p.name}><Link href={\`/primitives/\${p.name}\`}>{p.name}</Link> <small>({p.status}{p.viTicket ? " \xB7 " + p.viTicket : ""})</small></li>
+          ))}
+        </ul>
+      </section>
+      <section>
+        <h2>Screens</h2>
+        <ul>
+          {manifest.screens.map((s) => (
+            <li key={s.name}><Link href={\`/screens/\${s.name}\`}>{s.title}</Link></li>
+          ))}
+        </ul>
+      </section>
+    </main>
+  )
+}
+`;
+}
+function primitiveRouteTemplate() {
+  return `import { notFound } from "next/navigation"
+import { manifest } from "@/lib/sandbox-manifest"
+import { PrimitiveSample } from "@/components/sandbox-sample"
+
+interface Params { name: string }
+
+export function generateStaticParams() {
+  return manifest.primitives.map((p) => ({ name: p.name }))
+}
+
+export default async function PrimitivePage({ params }: { params: Promise<Params> }) {
+  const { name } = await params
+  const entry = manifest.primitives.find((p) => p.name === name)
+  if (!entry) notFound()
+  return (
+    <main style={{ padding: "32px", maxWidth: "880px", margin: "0 auto" }}>
+      <h1>{entry.name}</h1>
+      <p style={{ color: "var(--text-secondary, #555)" }}>{entry.status}{entry.viTicket ? " \xB7 " + entry.viTicket : ""}</p>
+      <PrimitiveSample name={entry.name} />
+    </main>
+  )
+}
+`;
+}
+function screenRouteTemplate() {
+  return `import { notFound } from "next/navigation"
+import { manifest } from "@/lib/sandbox-manifest"
+import { ScreenSample } from "@/components/sandbox-sample"
+
+interface Params { name: string }
+
+export function generateStaticParams() {
+  return manifest.screens.map((s) => ({ name: s.name }))
+}
+
+export default async function ScreenPage({ params }: { params: Promise<Params> }) {
+  const { name } = await params
+  const entry = manifest.screens.find((s) => s.name === name)
+  if (!entry) notFound()
+  return (
+    <main style={{ padding: "32px", maxWidth: "1280px", margin: "0 auto" }}>
+      <h1>{entry.title}</h1>
+      {entry.route ? <p style={{ color: "var(--text-secondary, #555)" }}><code>{entry.route}</code></p> : null}
+      <ScreenSample name={entry.name} />
+    </main>
+  )
+}
+`;
+}
+function sandboxManifestModule(manifest) {
+  const payload = {
+    pattern: manifest.pattern,
+    theme: manifest.theme ?? null,
+    primitives: manifest.primitives.map((p) => ({
+      name: p.name,
+      status: p.status,
+      viTicket: p.viTicket ?? null,
+      kind: p.kind ?? null
+    })),
+    screens: manifest.screens.map((s) => ({
+      name: s.name,
+      title: s.title,
+      route: s.route ?? null
+    }))
+  };
+  return `export const manifest = ${JSON.stringify(payload, null, 2)} as const
+
+export type ManifestPrimitive = (typeof manifest)["primitives"][number]
+export type ManifestScreen = (typeof manifest)["screens"][number]
+`;
+}
+function sandboxMocksModule(fields) {
+  if (fields.length === 0) {
+    return `// No mock fields declared in recipe. Hand-edit this file to add fixtures consumed by screens/<name>/page.tsx.
+export const mocks: Record<string, unknown> = {}
+`;
+  }
+  const lines2 = [
+    "// Auto-generated mock fixtures from the recipe's 'Inputs from generation skill' table.",
+    "// Hand-edit values to provide realistic data for screens. The shapes below are TODO stubs.",
+    "",
+    "export const mocks = {"
+  ];
+  for (const f of fields) {
+    const isArray = /\[\]\s*$/.test(f.type);
+    const stub = isArray ? "[]" : f.field === "currentUser" ? '{ id: "u1", role: "owner" }' : '""';
+    const safeKey = /^[a-zA-Z_$][\w$]*$/.test(f.field) ? f.field : `["${f.field.replace(/"/g, '\\"')}"]`;
+    const desc = f.description ? ` // ${f.description.slice(0, 80)}` : "";
+    lines2.push(`  ${safeKey}: ${stub} as unknown,${desc}`);
+  }
+  lines2.push("} satisfies Record<string, unknown>", "");
+  return lines2.join("\n");
+}
+function sandboxSampleComponent() {
+  return `import { manifest, type ManifestPrimitive } from "@/lib/sandbox-manifest"
+import { mocks } from "@/lib/sandbox-mocks"
+
+void mocks
+
+/** Dynamic primitive sample. v1 shows the primitive name in a frame; operator hand-edits routes for richer compositions. */
+export function PrimitiveSample({ name }: { name: string }) {
+  const entry = manifest.primitives.find((p) => p.name === name) as ManifestPrimitive | undefined
+  if (!entry) return null
+  return (
+    <section data-sandbox-primitive={entry.name} style={{ padding: "24px", border: "1px solid var(--border-default, #e5e7eb)", borderRadius: "12px", marginTop: "16px" }}>
+      <p style={{ margin: 0, fontFamily: "var(--font-mono, monospace)", fontSize: "var(--text-sm, 13px)", color: "var(--text-secondary, #555)" }}>
+        Operator: hand-edit <code>app/primitives/[name]/page.tsx</code> to render this primitive in real states.
+      </p>
+    </section>
+  )
+}
+
+export function ScreenSample({ name }: { name: string }) {
+  const entry = manifest.screens.find((s) => s.name === name)
+  if (!entry) return null
+  return (
+    <section data-sandbox-screen={entry.name} style={{ padding: "24px", border: "1px solid var(--border-default, #e5e7eb)", borderRadius: "12px", marginTop: "16px" }}>
+      <p style={{ margin: 0, fontFamily: "var(--font-mono, monospace)", fontSize: "var(--text-sm, 13px)", color: "var(--text-secondary, #555)" }}>
+        Operator: hand-edit <code>app/screens/[name]/page.tsx</code> to assemble the {entry.title} composition.
+      </p>
+    </section>
+  )
+}
+`;
+}
+function stubTemplate(entry) {
+  const componentName = toPascalCase(entry.name);
+  const ticket = entry.viTicket ?? "VI-???";
+  return `// GAP STUB \u2014 ${ticket}. Hand-edit this file to sketch the primitive in place.
+import type { ReactNode } from "react"
+
+export interface ${componentName}Props {
+  children?: ReactNode
+  [key: string]: unknown
+}
+
+export function ${componentName}(props: ${componentName}Props) {
+  return (
+    <div
+      role="img"
+      aria-label="GAP: ${ticket} \u2014 ${entry.name}"
+      data-stub-component="${entry.name}"
+      style={{
+        border: "2px dashed var(--border-strong, #888)",
+        padding: "var(--spacing-4, 16px)",
+        borderRadius: "var(--radius-md, 8px)",
+        color: "var(--text-secondary, #555)",
+        fontFamily: "var(--font-mono, monospace)",
+        fontSize: "var(--text-sm, 12px)",
+        display: "inline-flex",
+        flexDirection: "column",
+        gap: "4px",
+        minWidth: "120px",
+        textAlign: "center",
+      }}
+    >
+      <strong>GAP: ${ticket}</strong>
+      <span>${entry.name}</span>
+      <span style={{ opacity: 0.7 }}>see visual spec</span>
+      {props.children}
+    </div>
+  )
+}
+`;
+}
+function readmeTemplate(manifest, port) {
+  const shipped = manifest.primitives.filter((p) => p.status === "shipped" || p.status === "gap-inflight");
+  const gaps = manifest.primitives.filter((p) => p.status === "gap-new");
+  return [
+    `# Sandbox: ${manifest.pattern}`,
+    "",
+    "Scaffolded by `visor sandbox init`. Iterate visually here, then capture approved states with `visor sandbox approve`.",
+    "",
+    "## Running",
+    "",
+    "```bash",
+    `npx visor sandbox dev --name ${manifest.pattern}`,
+    "```",
+    "",
+    `Dev server on **port ${port}** (port 3000 is reserved).`,
+    "",
+    `## Primitives (${shipped.length} shipped / ${gaps.length} gaps)`,
+    "",
+    ...shipped.map((p) => `- \`${p.name}\` \u2014 shipped`),
+    ...gaps.map((p) => `- \`${p.name}\` \u2014 **GAP** (${p.viTicket ?? "VI-???"}) \u2014 stub at \`components/stubs/${p.name}.tsx\``),
+    "",
+    "## Screens",
+    "",
+    ...manifest.screens.length === 0 ? ["- (none declared in recipe)"] : manifest.screens.map((s) => `- \`/screens/${s.name}\` \u2014 ${s.title}${s.route ? ` (target route: \`${s.route}\`)` : ""}`),
+    "",
+    "## Capturing",
+    "",
+    "```bash",
+    `npx visor sandbox approve --name ${manifest.pattern}            # writes captures/approved/*.png`,
+    `npx visor sandbox approve --name ${manifest.pattern} --diff     # pixel-diff vs prior approved`,
+    "```",
+    ""
+  ].join("\n");
+}
+function captureScriptTemplate() {
+  return `// Auto-generated by 'visor sandbox approve'. Do not edit by hand \u2014 rewrite via approve.
+import { chromium } from "@playwright/test"
+import { readFile, writeFile, mkdir, readdir } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import { join, dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+import pixelmatch from "pixelmatch"
+import { PNG } from "pngjs"
+
+const sandboxDir = dirname(fileURLToPath(import.meta.url))
+const configPath = join(sandboxDir, "sandbox.json")
+const config = JSON.parse(await readFile(configPath, "utf-8"))
+
+const diffMode = process.argv.includes("--diff")
+const port = Number(process.env.SANDBOX_PORT ?? config.port)
+const baseUrl = \`http://localhost:\${port}\`
+
+const routes = ["/", ...config.primitives.map((p) => \`/primitives/\${p.name}\`), ...config.screens.map((s) => \`/screens/\${s.name}\`)]
+
+const approvedDir = join(sandboxDir, "captures", "approved")
+const pendingDir = join(sandboxDir, "captures", "pending")
+const diffsDir = join(sandboxDir, "captures", "diffs")
+await mkdir(approvedDir, { recursive: true })
+await mkdir(pendingDir, { recursive: true })
+if (diffMode) await mkdir(diffsDir, { recursive: true })
+
+function slugify(route) {
+  if (route === "/") return "index"
+  return route.replace(/^\\//, "").replace(/\\//g, "__")
+}
+
+const browser = await chromium.launch()
+const context = await browser.newContext({ viewport: { width: 1280, height: 800 } })
+const page = await context.newPage()
+const results = []
+
+for (const route of routes) {
+  const slug = slugify(route)
+  const targetDir = diffMode ? pendingDir : approvedDir
+  const pngPath = join(targetDir, \`\${slug}.png\`)
+  await page.goto(baseUrl + route, { waitUntil: "networkidle" })
+  const buf = await page.screenshot({ fullPage: true })
+  await writeFile(pngPath, buf)
+  results.push({ route, png: pngPath })
+
+  if (diffMode) {
+    const baselinePath = join(approvedDir, \`\${slug}.png\`)
+    if (!existsSync(baselinePath)) {
+      results[results.length - 1].diff = "no-baseline"
+      continue
+    }
+    const baselineBuf = await readFile(baselinePath)
+    const baseline = PNG.sync.read(baselineBuf)
+    const candidate = PNG.sync.read(buf)
+    if (baseline.width !== candidate.width || baseline.height !== candidate.height) {
+      const diffPath = join(diffsDir, \`\${slug}.diff.png\`)
+      await writeFile(diffPath, buf)
+      results[results.length - 1].diff = diffPath
+      results[results.length - 1].dimensionsMismatch = true
+      continue
+    }
+    const diffPng = new PNG({ width: baseline.width, height: baseline.height })
+    const pixels = pixelmatch(
+      baseline.data,
+      candidate.data,
+      diffPng.data,
+      baseline.width,
+      baseline.height,
+      { threshold: 0.1 }
+    )
+    if (pixels > 0) {
+      const diffPath = join(diffsDir, \`\${slug}.diff.png\`)
+      await writeFile(diffPath, PNG.sync.write(diffPng))
+      results[results.length - 1].diff = diffPath
+      results[results.length - 1].changedPixels = pixels
+    }
+  }
+}
+
+await browser.close()
+await writeFile(join(sandboxDir, "captures", "last-run.json"), JSON.stringify({ diffMode, baseUrl, routes: results }, null, 2))
+console.log(JSON.stringify({ ok: true, diffMode, routes: results }, null, 2))
+`;
+}
+function toPascalCase(s) {
+  return s.split(/[^a-zA-Z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+
+// src/commands/sandbox/scaffold.ts
+function writeScaffold(sandboxDir, manifest, port) {
+  mkdirSync7(sandboxDir, { recursive: true });
+  const created = [];
+  const writeIfNew = (rel, contents) => {
+    const full = join20(sandboxDir, rel);
+    mkdirSync7(dirOf(full), { recursive: true });
+    writeFileSync12(full, contents, "utf-8");
+    created.push(rel);
+  };
+  writeIfNew("package.json", packageJsonTemplate(manifest.pattern));
+  writeIfNew("tsconfig.json", tsconfigTemplate());
+  writeIfNew("next.config.ts", nextConfigTemplate());
+  writeIfNew("next-env.d.ts", nextEnvDtsTemplate());
+  writeIfNew(".gitignore", gitignoreTemplate());
+  writeIfNew("README.md", readmeTemplate(manifest, port));
+  writeIfNew("app/layout.tsx", rootLayoutTemplate(manifest.pattern));
+  writeIfNew("app/globals.css", globalsCssPlaceholder());
+  writeIfNew("app/page.tsx", indexPageTemplate());
+  writeIfNew("app/primitives/[name]/page.tsx", primitiveRouteTemplate());
+  writeIfNew("app/screens/[name]/page.tsx", screenRouteTemplate());
+  writeIfNew("components/sandbox-sample.tsx", sandboxSampleComponent());
+  writeIfNew("lib/sandbox-manifest.ts", sandboxManifestModule(manifest));
+  writeIfNew("lib/sandbox-mocks.ts", sandboxMocksModule(manifest.mockShapes));
+  for (const p of manifest.primitives) {
+    if (p.status === "gap-new") {
+      writeIfNew(`components/stubs/${p.name}.tsx`, stubTemplate(p));
+    }
+  }
+  writeIfNew("playwright.capture.mjs", captureScriptTemplate());
+  mkdirSync7(join20(sandboxDir, "captures", "approved"), { recursive: true });
+  return { created };
+}
+function dirOf(p) {
+  const idx = p.lastIndexOf("/");
+  return idx === -1 ? "." : p.slice(0, idx);
+}
+function writeSandboxConfig(sandboxDir, manifest, port, options) {
+  const config = {
+    pattern: manifest.pattern,
+    handoffPath: options.handoffPath,
+    theme: options.theme,
+    port,
+    visorVersion: options.visorVersion,
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    primitives: manifest.primitives.map((p) => ({
+      name: p.name,
+      status: p.status,
+      viTicket: p.viTicket ?? null
+    })),
+    screens: manifest.screens.map((s) => ({ name: s.name, title: s.title, route: s.route ?? null }))
+  };
+  writeFileSync12(join20(sandboxDir, "sandbox.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
+}
+function sandboxIsEmpty(sandboxDir) {
+  if (!existsSync20(sandboxDir)) return true;
+  try {
+    return readdirSync12(sandboxDir).filter((f) => !f.startsWith(".")).length === 0;
+  } catch {
+    return false;
+  }
+}
+
+// src/commands/sandbox/init.ts
+async function sandboxInitCommand(name, cwd, options) {
+  const json = options.json ?? false;
+  try {
+    const result = await runInit(name, cwd, options);
+    if (json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    logger.blank();
+    logger.success(`Sandbox ready at ${result.sandboxDir}`);
+    logger.info(`Port: ${result.port} (port 3000 reserved)`);
+    logger.info(`Shipped primitives added: ${result.primitives?.shipped.length ?? 0}`);
+    logger.info(`Gap stubs generated: ${result.primitives?.gaps.length ?? 0}`);
+    if (result.warnings && result.warnings.length > 0) {
+      logger.blank();
+      logger.warn("Warnings:");
+      for (const w of result.warnings) logger.item(w);
+    }
+    logger.blank();
+    logger.info("Next:");
+    logger.item(`npx visor sandbox dev --name ${name}`);
+    logger.item(`npx visor sandbox approve --name ${name}`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: message }, null, 2));
+    } else {
+      logger.error(message);
+    }
+    process.exit(1);
+  }
+}
+async function runInit(name, cwd, options) {
+  if (!name || !/^[a-z0-9][a-z0-9-_]*$/i.test(name)) {
+    throw new Error(`Invalid sandbox name '${name}'. Use letters, digits, '-' or '_'.`);
+  }
+  const handoffPath = isAbsolute2(options.handoff) ? options.handoff : resolve15(cwd, options.handoff);
+  if (!existsSync21(handoffPath)) {
+    throw new Error(`Handoff manifest not found: ${handoffPath}`);
+  }
+  const manifest = parseHandoff(handoffPath);
+  if (manifest.primitives.length === 0) {
+    throw new Error(
+      `Handoff has no primitives \u2014 refusing to scaffold an empty sandbox. Check the manifest at ${handoffPath}`
+    );
+  }
+  const sandboxDir = join21(cwd, ".lo", "sandbox", name);
+  if (!sandboxIsEmpty(sandboxDir)) {
+    if (!options.overwrite) {
+      throw new Error(
+        `Sandbox directory not empty: ${sandboxDir}. Pass --overwrite to replace it.`
+      );
+    }
+    rmSync2(sandboxDir, { recursive: true, force: true });
+  }
+  mkdirSync8(sandboxDir, { recursive: true });
+  const port = await findOpenPort();
+  writeScaffold(sandboxDir, manifest, port);
+  if (!options.skipInstall) {
+    runNpmInstall(sandboxDir, options.json ?? false);
+  }
+  applyThemeIfPossible(sandboxDir, manifest, options.theme, cwd, options.json ?? false);
+  const known = loadKnownPrimitives();
+  const shipped = [];
+  for (const p of manifest.primitives) {
+    if (p.status !== "shipped" && p.status !== "gap-inflight") continue;
+    if (!known.has(p.name)) {
+      manifest.warnings.push(
+        `'${p.name}' is declared shipped in the handoff but is not in the registry \u2014 skipped`
+      );
+      continue;
+    }
+    const ok = tryAddPrimitive(p, sandboxDir, options.json ?? false);
+    if (ok) shipped.push(p.name);
+  }
+  const gaps = manifest.primitives.filter((p) => p.status === "gap-new").map((p) => p.name);
+  writeSandboxConfig(sandboxDir, manifest, port, {
+    handoffPath,
+    theme: options.theme,
+    visorVersion: readCliVersion()
+  });
+  return {
+    success: true,
+    sandboxDir,
+    port,
+    primitives: { shipped, gaps },
+    warnings: manifest.warnings
+  };
+}
+function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json) {
+  const directPath = isAbsolute2(theme2) ? theme2 : resolve15(cwd, theme2);
+  const candidates = [
+    directPath,
+    join21(cwd, "themes", `${theme2}.visor.yaml`),
+    join21(cwd, "custom-themes", `${theme2}.visor.yaml`)
+  ];
+  const yamlPath = candidates.find((p) => existsSync21(p));
+  if (!yamlPath) {
+    manifest.warnings.push(
+      `Theme '${theme2}' not found in themes/ or custom-themes/ \u2014 sandbox uses placeholder globals.css. Run 'visor theme apply <path> --adapter nextjs -o app/globals.css' manually.`
+    );
+    if (!json) {
+      logger.warn(`Theme '${theme2}' not found \u2014 leaving placeholder globals.css.`);
+    }
+    return;
+  }
+  const globalsOut = join21(sandboxDir, "app", "globals.css");
+  try {
+    themeApplyCommand(yamlPath, sandboxDir, {
+      output: globalsOut,
+      adapter: "nextjs",
+      json: false
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    manifest.warnings.push(`Theme apply failed: ${msg}`);
+    if (!json) logger.warn(`Theme apply failed: ${msg}`);
+  }
+}
+function tryAddPrimitive(primitive, sandboxDir, json) {
+  try {
+    addCommand([primitive.name], sandboxDir, {
+      overwrite: true,
+      target: "react",
+      json: false
+    });
+    return true;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (!json) {
+      logger.warn(`Skipped '${primitive.name}': ${msg}`);
+    }
+    return false;
+  }
+}
+function runNpmInstall(sandboxDir, json) {
+  if (!json) logger.info("Installing sandbox dependencies...");
+  const result = childProcess2.spawnSync("npm", ["install", "--no-audit", "--no-fund"], {
+    cwd: sandboxDir,
+    stdio: json ? "ignore" : "inherit"
+  });
+  if (result.error) {
+    throw new Error(`npm install failed to start: ${result.error.message}`);
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    throw new Error(`npm install exited with code ${result.status}`);
+  }
+}
+function loadKnownPrimitives() {
+  try {
+    const reg = loadRegistry();
+    const items = filterItemsByTarget(reg.items, "react");
+    return new Set(items.map((i) => i.name));
+  } catch {
+    return /* @__PURE__ */ new Set();
+  }
+}
+function readCliVersion() {
+  try {
+    const here = dirname9(fileURLToPath3(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+      const segments = new Array(i).fill("..");
+      const candidate = join21(here, ...segments, "package.json");
+      try {
+        const pkg2 = JSON.parse(readFileSync23(candidate, "utf-8"));
+        if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) return pkg2.version;
+      } catch {
+      }
+    }
+  } catch {
+  }
+  return "0.0.0-dev";
+}
+
+// src/commands/sandbox/dev.ts
+import { existsSync as existsSync22, readFileSync as readFileSync24 } from "fs";
+import { join as join22 } from "path";
+import * as childProcess3 from "child_process";
+function sandboxDevCommand(cwd, options) {
+  const json = options.json ?? false;
+  const sandboxDir = join22(cwd, ".lo", "sandbox", options.name);
+  const configPath = join22(sandboxDir, "sandbox.json");
+  if (!existsSync22(configPath)) {
+    fail(
+      json,
+      `Sandbox '${options.name}' not found at ${sandboxDir}. Run 'visor sandbox init ${options.name} --handoff ... --theme ...' first.`
+    );
+    return;
+  }
+  let config;
+  try {
+    config = JSON.parse(readFileSync24(configPath, "utf-8"));
+  } catch (err) {
+    fail(json, `Invalid sandbox.json at ${configPath}: ${err.message}`);
+    return;
+  }
+  const baseUrl = `http://localhost:${config.port}`;
+  const routes = [
+    "/",
+    ...config.primitives.map((p) => `/primitives/${p.name}`),
+    ...config.screens.map((s) => `/screens/${s.name}`)
+  ];
+  if (json) {
+    console.log(
+      JSON.stringify({ success: true, baseUrl, port: config.port, routes }, null, 2)
+    );
+  } else {
+    logger.info(`Sandbox: ${config.pattern}`);
+    logger.info(`Dev server on port ${config.port}`);
+    logger.info(`Base URL: ${baseUrl}`);
+    logger.blank();
+    logger.info("Routes:");
+    for (const r of routes) logger.item(`${baseUrl}${r}`);
+    logger.blank();
+  }
+  spawnNextDev(sandboxDir, config.port, json);
+}
+function spawnNextDev(sandboxDir, port, json) {
+  const child = childProcess3.spawn(
+    "npx",
+    ["--no-install", "next", "dev", "--port", String(port)],
+    {
+      cwd: sandboxDir,
+      stdio: json ? "ignore" : "inherit"
+    }
+  );
+  child.on("exit", (code) => {
+    if (typeof code === "number" && code !== 0 && !json) {
+      logger.warn(`next dev exited with code ${code}`);
+    }
+  });
+  const stop = () => {
+    if (!child.killed) child.kill("SIGINT");
+  };
+  process.on("SIGINT", stop);
+  process.on("SIGTERM", stop);
+}
+function fail(json, message) {
+  if (json) {
+    console.log(JSON.stringify({ success: false, error: message }, null, 2));
+  } else {
+    logger.error(message);
+  }
+  process.exit(1);
+}
+
+// src/commands/sandbox/approve.ts
+import { existsSync as existsSync23, readFileSync as readFileSync25, writeFileSync as writeFileSync13, readdirSync as readdirSync13 } from "fs";
+import { join as join23 } from "path";
+import * as childProcess4 from "child_process";
+function sandboxApproveCommand(cwd, options) {
+  const json = options.json ?? false;
+  const sandboxDir = join23(cwd, ".lo", "sandbox", options.name);
+  const configPath = join23(sandboxDir, "sandbox.json");
+  if (!existsSync23(configPath)) {
+    fail2(
+      json,
+      `Sandbox '${options.name}' not found at ${sandboxDir}. Run 'visor sandbox init' first.`
+    );
+    return;
+  }
+  const config = JSON.parse(readFileSync25(configPath, "utf-8"));
+  const captureScriptPath = join23(sandboxDir, "playwright.capture.mjs");
+  writeFileSync13(captureScriptPath, captureScriptTemplate(), "utf-8");
+  ensurePlaywrightInstalled(sandboxDir, json);
+  const args = ["--no-install", "node", "playwright.capture.mjs"];
+  if (options.diff) args.push("--diff");
+  const result = childProcess4.spawnSync("npx", args, {
+    cwd: sandboxDir,
+    stdio: "pipe",
+    env: { ...process.env, SANDBOX_PORT: String(config.port) },
+    encoding: "utf-8"
+  });
+  if (result.error) {
+    fail2(json, `Capture failed to start: ${result.error.message}`);
+    return;
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    fail2(json, `Capture script exited with code ${result.status}
+${result.stderr}`);
+    return;
+  }
+  const approvedDir = join23(sandboxDir, "captures", "approved");
+  const diffsDir = join23(sandboxDir, "captures", "diffs");
+  const approvedFiles = safeListPngs(approvedDir);
+  const diffFiles = options.diff ? safeListPngs(diffsDir) : [];
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          mode: options.diff ? "diff" : "approve",
+          approvedDir,
+          diffsDir: options.diff ? diffsDir : null,
+          approved: approvedFiles,
+          diffs: diffFiles,
+          captureOutput: tryParseJson(result.stdout)
+        },
+        null,
+        2
+      )
+    );
+  } else {
+    logger.success(
+      options.diff ? `Pixel-diff complete. ${diffFiles.length} diff PNGs in ${diffsDir}` : `Captured ${approvedFiles.length} PNGs in ${approvedDir}`
+    );
+    if (options.diff && diffFiles.length > 0) {
+      logger.blank();
+      logger.info("Changed routes:");
+      for (const f of diffFiles) logger.item(f);
+    }
+  }
+}
+function ensurePlaywrightInstalled(sandboxDir, json) {
+  const markerPath = join23(sandboxDir, ".playwright-installed");
+  if (existsSync23(markerPath)) return;
+  if (!json) logger.info("Installing Playwright Chromium (one-time)...");
+  const result = childProcess4.spawnSync("npx", ["--no-install", "playwright", "install", "chromium"], {
+    cwd: sandboxDir,
+    stdio: json ? "ignore" : "inherit"
+  });
+  if (result.error) {
+    throw new Error(`playwright install failed to start: ${result.error.message}`);
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    throw new Error(`playwright install exited with code ${result.status}`);
+  }
+  writeFileSync13(markerPath, (/* @__PURE__ */ new Date()).toISOString(), "utf-8");
+}
+function safeListPngs(dir) {
+  if (!existsSync23(dir)) return [];
+  return readdirSync13(dir).filter((f) => f.endsWith(".png")).map((f) => join23(dir, f));
+}
+function tryParseJson(s) {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s.trim();
+  }
+}
+function fail2(json, message) {
+  if (json) {
+    console.log(JSON.stringify({ success: false, error: message }, null, 2));
+  } else {
+    logger.error(message);
+  }
+  process.exit(1);
+}
+
 // src/index.ts
-var __dirname2 = dirname8(fileURLToPath3(import.meta.url));
+var __dirname2 = dirname10(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync22(join20(__dirname2, "..", "package.json"), "utf-8")
+  readFileSync26(join24(__dirname2, "..", "package.json"), "utf-8")
 );
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version(pkg.version);
@@ -5877,4 +6967,18 @@ migrate.command("token-substitution").description(
     });
   }
 );
+var sandbox = program.command("sandbox").description("Scaffold and iterate on a Next.js sandbox for new primitives");
+sandbox.command("init").description(
+  "Scaffold a Next.js sandbox at .lo/sandbox/<name>/ from a design-handoff manifest"
+).argument("<name>", "sandbox name (used as directory and pattern slug)").requiredOption("--handoff <path>", "path to design-handoff.md manifest").requiredOption("--theme <theme>", "theme slug (e.g. 'space') or path to .visor.yaml").option("--overwrite", "replace an existing sandbox at this name", false).option("--skip-install", "skip npm install (test fixture mode)", false).option("--json", "output structured JSON (for AI agents)").action(
+  async (name, options) => {
+    await sandboxInitCommand(name, process.cwd(), options);
+  }
+);
+sandbox.command("dev").description("Boot the Next.js dev server for a sandbox on its allocated port").requiredOption("--name <name>", "sandbox name (created via 'sandbox init')").option("--json", "output structured JSON (for AI agents)").action((options) => {
+  sandboxDevCommand(process.cwd(), options);
+});
+sandbox.command("approve").description("Capture Playwright screenshots of every sandbox route as the visual spec").requiredOption("--name <name>", "sandbox name (created via 'sandbox init')").option("--diff", "pixel-diff against the prior approved baseline", false).option("--json", "output structured JSON (for AI agents)").action((options) => {
+  sandboxApproveCommand(process.cwd(), options);
+});
 program.parse();