@loworbitstudio/visor 1.2.0 → 1.3.0

package/dist/CHANGELOG.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-05-20T04:45:51.978Z",
+  "generated_at": "2026-05-21T04:13:27.641Z",
   "components": {
     "accessibility-specimen": {
       "changeType": "current",

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync26 } from "fs";
-import { dirname as dirname10, join as join24 } from "path";
+import { readFileSync as readFileSync27 } from "fs";
+import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
 
@@ -5779,8 +5779,8 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
 }
 
 // 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 { existsSync as existsSync21, mkdirSync as mkdirSync9, readFileSync as readFileSync24, rmSync as rmSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join22, resolve as resolve15, dirname as dirname9 } from "path";
 import { fileURLToPath as fileURLToPath3 } from "url";
 import * as childProcess2 from "child_process";
 
@@ -6022,11 +6022,18 @@ function tsconfigTemplate() {
 }
 function nextConfigTemplate() {
   return `import type { NextConfig } from "next"
+import path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
 const nextConfig: NextConfig = {
   reactStrictMode: true,
   // Sandbox is local-only \u2014 disable production telemetry and image opt to keep startup fast.
   images: { unoptimized: true },
+  // Anchor turbopack root to the sandbox dir so a parent-repo package-lock.json
+  // doesn't pull the workspace root upstream (VI-440).
+  turbopack: { root: __dirname },
 }
 
 export default nextConfig
@@ -6160,6 +6167,43 @@ export default async function ScreenPage({ params }: { params: Promise<Params> }
 }
 `;
 }
+function prototypeScreenRouteTemplate(screenMap) {
+  const mapLiteral = JSON.stringify(screenMap, null, 2);
+  return `import { notFound } from "next/navigation"
+import { manifest } from "@/lib/sandbox-manifest"
+import { ScreenSample } from "@/components/sandbox-sample"
+
+const SCREEN_HTML: Record<string, string> = ${mapLiteral}
+
+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()
+  const htmlFile = SCREEN_HTML[entry.name]
+  return (
+    <main style={{ padding: "32px", maxWidth: "1440px", margin: "0 auto" }}>
+      <h1>{entry.title}</h1>
+      {entry.route ? <p style={{ color: "var(--text-secondary, #555)" }}><code>{entry.route}</code></p> : null}
+      {htmlFile ? (
+        <iframe
+          src={\`/prototype/\${htmlFile}\`}
+          title={entry.title}
+          style={{ width: "100%", height: "calc(100vh - 160px)", border: "1px solid var(--border-default, #e5e7eb)", borderRadius: "8px", background: "var(--bg-surface, #f7f7f8)" }}
+        />
+      ) : (
+        <ScreenSample name={entry.name} />
+      )}
+    </main>
+  )
+}
+`;
+}
 function sandboxManifestModule(manifest) {
   const payload = {
     pattern: manifest.pattern,
@@ -6173,7 +6217,8 @@ function sandboxManifestModule(manifest) {
     screens: manifest.screens.map((s) => ({
       name: s.name,
       title: s.title,
-      route: s.route ?? null
+      route: s.route ?? null,
+      kind: s.kind ?? "named"
     }))
   };
   return `export const manifest = ${JSON.stringify(payload, null, 2)} as const
@@ -6312,8 +6357,10 @@ function readmeTemplate(manifest, port) {
 }
 function captureScriptTemplate() {
   return `// Auto-generated by 'visor sandbox approve'. Do not edit by hand \u2014 rewrite via approve.
+// Always captures to captures/pending/ and pixel-diffs against captures/approved/ if a baseline exists.
+// Promotion of pending \u2192 approved happens via 'visor sandbox approve --approve' (operator review gate).
 import { chromium } from "@playwright/test"
-import { readFile, writeFile, mkdir, readdir } from "node:fs/promises"
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises"
 import { existsSync } from "node:fs"
 import { join, dirname } from "node:path"
 import { fileURLToPath } from "node:url"
@@ -6324,7 +6371,6 @@ 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}\`
 
@@ -6333,9 +6379,11 @@ const routes = ["/", ...config.primitives.map((p) => \`/primitives/\${p.name}\`)
 const approvedDir = join(sandboxDir, "captures", "approved")
 const pendingDir = join(sandboxDir, "captures", "pending")
 const diffsDir = join(sandboxDir, "captures", "diffs")
+await rm(pendingDir, { recursive: true, force: true })
+await rm(diffsDir, { recursive: true, force: true })
 await mkdir(approvedDir, { recursive: true })
 await mkdir(pendingDir, { recursive: true })
-if (diffMode) await mkdir(diffsDir, { recursive: true })
+await mkdir(diffsDir, { recursive: true })
 
 function slugify(route) {
   if (route === "/") return "index"
@@ -6343,56 +6391,56 @@ function slugify(route) {
 }
 
 const browser = await chromium.launch()
-const context = await browser.newContext({ viewport: { width: 1280, height: 800 } })
+const context = await browser.newContext({ viewport: { width: 1280, height: 800 }, deviceScaleFactor: 2 })
 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\`)
+  const pngPath = join(pendingDir, \`\${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 })
+  const entry = { route, png: pngPath }
+  results.push(entry)
 
-  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
-    }
+  const baselinePath = join(approvedDir, \`\${slug}.png\`)
+  if (!existsSync(baselinePath)) {
+    entry.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)
+    entry.diff = diffPath
+    entry.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))
+    entry.diff = diffPath
+    entry.changedPixels = pixels
+  } else {
+    entry.diff = "clean"
   }
 }
 
 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))
+await writeFile(join(sandboxDir, "captures", "last-run.json"), JSON.stringify({ baseUrl, routes: results }, null, 2))
+console.log(JSON.stringify({ ok: true, mode: "pending", routes: results }, null, 2))
 `;
 }
 function toPascalCase(s) {
@@ -6400,7 +6448,7 @@ function toPascalCase(s) {
 }
 
 // src/commands/sandbox/scaffold.ts
-function writeScaffold(sandboxDir, manifest, port) {
+function writeScaffold(sandboxDir, manifest, port, options = {}) {
   mkdirSync7(sandboxDir, { recursive: true });
   const created = [];
   const writeIfNew = (rel, contents) => {
@@ -6419,7 +6467,10 @@ function writeScaffold(sandboxDir, manifest, port) {
   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(
+    "app/screens/[name]/page.tsx",
+    options.prototypeImport ? prototypeScreenRouteTemplate(options.prototypeImport.screenMap) : screenRouteTemplate()
+  );
   writeIfNew("components/sandbox-sample.tsx", sandboxSampleComponent());
   writeIfNew("lib/sandbox-manifest.ts", sandboxManifestModule(manifest));
   writeIfNew("lib/sandbox-mocks.ts", sandboxMocksModule(manifest.mockShapes));
@@ -6447,9 +6498,21 @@ function writeSandboxConfig(sandboxDir, manifest, port, options) {
     primitives: manifest.primitives.map((p) => ({
       name: p.name,
       status: p.status,
-      viTicket: p.viTicket ?? null
+      viTicket: p.viTicket ?? null,
+      kind: p.kind ?? null
     })),
-    screens: manifest.screens.map((s) => ({ name: s.name, title: s.title, route: s.route ?? null }))
+    screens: manifest.screens.map((s) => ({
+      name: s.name,
+      title: s.title,
+      route: s.route ?? null,
+      kind: s.kind ?? "named"
+    })),
+    fromHtmlPrototype: options.prototypeImport ? {
+      sourceDir: options.prototypeImport.sourceDir,
+      screenMap: options.prototypeImport.screenMap,
+      stateCoverageScreens: options.prototypeImport.stateCoverageScreens,
+      stripChromeSelectors: options.prototypeImport.stripChromeSelectors
+    } : null
   };
   writeFileSync12(join20(sandboxDir, "sandbox.json"), JSON.stringify(config, null, 2) + "\n", "utf-8");
 }
@@ -6462,6 +6525,278 @@ function sandboxIsEmpty(sandboxDir) {
   }
 }
 
+// src/commands/sandbox/html-prototype.ts
+import { mkdirSync as mkdirSync8, readdirSync as readdirSync13, readFileSync as readFileSync23, statSync as statSync9, writeFileSync as writeFileSync13 } from "fs";
+import { join as join21 } from "path";
+
+// src/commands/sandbox/strip-chrome.ts
+var DEFAULT_STRIP_SELECTORS = [
+  ".state-callout",
+  ".state-section__header",
+  ".proto-nav",
+  "[data-documentary-chrome]",
+  '[style*="mint"]'
+];
+var CLASS_SELECTOR = /^\.([a-zA-Z_][\w-]*)$/;
+var ATTR_SUBSTRING_SELECTOR = /^\[([a-zA-Z_][\w-]*)\*=(?:"([^"]*)"|'([^']*)')\]$/;
+var ATTR_PRESENCE_SELECTOR = /^\[([a-zA-Z_][\w-]*)\]$/;
+function parseSelector(selector) {
+  const trimmed = selector.trim();
+  let m;
+  if (m = trimmed.match(CLASS_SELECTOR)) {
+    return { kind: "class", name: m[1] };
+  }
+  if (m = trimmed.match(ATTR_SUBSTRING_SELECTOR)) {
+    return { kind: "attr-substring", attr: m[1], value: m[2] ?? m[3] ?? "" };
+  }
+  if (m = trimmed.match(ATTR_PRESENCE_SELECTOR)) {
+    return { kind: "attr-presence", attr: m[1] };
+  }
+  return { kind: "unknown" };
+}
+var VOID_ELEMENTS = /* @__PURE__ */ new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr"
+]);
+function findOpenTagEnd(html, openTagStart) {
+  let i = openTagStart;
+  let quote = null;
+  while (i < html.length) {
+    const ch = html[i];
+    if (quote) {
+      if (ch === quote) quote = null;
+    } else {
+      if (ch === '"' || ch === "'") quote = ch;
+      else if (ch === ">") return i + 1;
+    }
+    i++;
+  }
+  return -1;
+}
+function findMatchingCloseTag(html, tagName, searchFrom) {
+  const openRe = new RegExp(`<${tagName}(?=[\\s/>])`, "gi");
+  const closeRe = new RegExp(`</${tagName}\\s*>`, "gi");
+  let depth = 1;
+  let pos = searchFrom;
+  while (pos < html.length) {
+    openRe.lastIndex = pos;
+    closeRe.lastIndex = pos;
+    const openMatch = openRe.exec(html);
+    const closeMatch = closeRe.exec(html);
+    if (!closeMatch) return -1;
+    if (openMatch && openMatch.index < closeMatch.index) {
+      depth++;
+      const past = findOpenTagEnd(html, openMatch.index);
+      pos = past === -1 ? openMatch.index + tagName.length + 1 : past;
+      continue;
+    }
+    depth--;
+    if (depth === 0) return closeMatch.index;
+    pos = closeMatch.index + closeMatch[0].length;
+  }
+  return -1;
+}
+function openTagMatches(openTag, selector) {
+  if (selector.kind === "class") {
+    const classAttr = /\sclass\s*=\s*(?:"([^"]*)"|'([^']*)')/i.exec(openTag);
+    if (!classAttr) return false;
+    const value = classAttr[1] ?? classAttr[2] ?? "";
+    return value.split(/\s+/).some((token) => token === selector.name);
+  }
+  if (selector.kind === "attr-substring") {
+    const attrRe = new RegExp(
+      `\\s${escapeRegex2(selector.attr)}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`,
+      "i"
+    );
+    const m = openTag.match(attrRe);
+    if (!m) return false;
+    const value = m[1] ?? m[2] ?? "";
+    return value.includes(selector.value);
+  }
+  if (selector.kind === "attr-presence") {
+    const attrRe = new RegExp(
+      `\\s${escapeRegex2(selector.attr)}(?:\\s*=|\\s|/?>)`,
+      "i"
+    );
+    return attrRe.test(openTag);
+  }
+  return false;
+}
+function escapeRegex2(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+var TAG_NAME_RE = /^<([a-zA-Z][a-zA-Z0-9-]*)/;
+function stripOnce(html, selectors) {
+  const tagRe = /<([a-zA-Z][a-zA-Z0-9-]*)\b/g;
+  let m;
+  while (m = tagRe.exec(html)) {
+    const openTagStart = m.index;
+    const tagNameMatch = html.slice(openTagStart, openTagStart + 200).match(TAG_NAME_RE);
+    if (!tagNameMatch) continue;
+    const tagName = tagNameMatch[1].toLowerCase();
+    const openTagEnd = findOpenTagEnd(html, openTagStart);
+    if (openTagEnd === -1) continue;
+    const openTag = html.slice(openTagStart, openTagEnd);
+    const matched = selectors.some((sel) => openTagMatches(openTag, sel));
+    if (!matched) continue;
+    let elementEnd;
+    if (VOID_ELEMENTS.has(tagName) || /\/\s*>$/.test(openTag)) {
+      elementEnd = openTagEnd;
+    } else {
+      const closeStart = findMatchingCloseTag(html, tagName, openTagEnd);
+      if (closeStart === -1) continue;
+      const closeRe = new RegExp(`</${tagName}\\s*>`, "i");
+      const closeMatch = html.slice(closeStart).match(closeRe);
+      if (!closeMatch) continue;
+      elementEnd = closeStart + closeMatch[0].length;
+    }
+    let cutEnd = elementEnd;
+    if (html[cutEnd] === "\n") cutEnd++;
+    let cutStart = openTagStart;
+    while (cutStart > 0 && (html[cutStart - 1] === " " || html[cutStart - 1] === "	")) {
+      cutStart--;
+    }
+    if (cutStart > 0 && html[cutStart - 1] === "\n" && cutEnd <= html.length && (html[cutEnd - 1] === "\n" || cutEnd === html.length)) {
+      cutStart--;
+    }
+    return {
+      html: html.slice(0, cutStart) + html.slice(cutEnd),
+      changed: true
+    };
+  }
+  return { html, changed: false };
+}
+function resolveStripSelectors(stripChrome, additional) {
+  if (stripChrome === void 0 || stripChrome === false) {
+    if (additional && additional.trim() !== "") {
+      return [...DEFAULT_STRIP_SELECTORS, ...parseList(additional)];
+    }
+    return [];
+  }
+  const base = stripChrome === true || typeof stripChrome === "string" && stripChrome.trim() === "" ? [...DEFAULT_STRIP_SELECTORS] : parseList(stripChrome);
+  if (additional && additional.trim() !== "") {
+    return [...base, ...parseList(additional)];
+  }
+  return base;
+}
+function parseList(input) {
+  return input.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function stripDocumentaryChrome(html, selectors) {
+  if (selectors.length === 0) return html;
+  const parsed = selectors.map(parseSelector).filter((s) => s.kind !== "unknown");
+  if (parsed.length === 0) return html;
+  let current = html;
+  for (let i = 0; i < 1e3; i++) {
+    const { html: next, changed } = stripOnce(current, parsed);
+    if (!changed) break;
+    current = next;
+  }
+  return current;
+}
+
+// src/commands/sandbox/html-prototype.ts
+var SCREEN_FILE_PATTERN = /^screen-(\d+)-([^/.]+)\.html$/i;
+function copyHtmlPrototype(sourceDir, sandboxDir, manifest, options = {}) {
+  const warnings = [];
+  const destAbs = join21(sandboxDir, "public", "prototype");
+  mkdirSync8(destAbs, { recursive: true });
+  const stripChromeSelectors = options.stripChromeSelectors ?? [];
+  const copiedFiles = copyTreeRelative(sourceDir, destAbs, "", stripChromeSelectors);
+  const screenFiles = listOrderedScreenFiles(sourceDir);
+  if (screenFiles.length === 0) {
+    warnings.push(
+      `HTML prototype at ${sourceDir} has no 'screen-N-*.html' files \u2014 screen routes will fall back to placeholder.`
+    );
+  }
+  const screenMap = {};
+  manifest.screens.forEach((screen, idx) => {
+    const file = screenFiles[idx];
+    if (file) {
+      screenMap[screen.name] = file;
+    } else {
+      warnings.push(
+        `Manifest screen '${screen.name}' has no matching prototype HTML at position ${idx + 1} \u2014 route will use placeholder.`
+      );
+    }
+  });
+  const stateCoverageScreens = [];
+  if (screenFiles.length > manifest.screens.length) {
+    const extras = screenFiles.slice(manifest.screens.length);
+    const existingNames = new Set(manifest.screens.map((s) => s.name));
+    for (const file of extras) {
+      const entry = deriveStateCoverageScreen(file, existingNames);
+      manifest.screens.push(entry);
+      existingNames.add(entry.name);
+      screenMap[entry.name] = file;
+      stateCoverageScreens.push(entry.name);
+    }
+  }
+  return {
+    sourceDir,
+    destDir: "public/prototype",
+    copiedFiles,
+    screenMap,
+    stateCoverageScreens,
+    stripChromeSelectors,
+    warnings
+  };
+}
+function deriveStateCoverageScreen(file, existingNames) {
+  const m = file.match(SCREEN_FILE_PATTERN);
+  const idx = m ? m[1] : "0";
+  const suffix = m ? m[2].toLowerCase() : "extra";
+  let slug2 = `state-coverage-${suffix}`;
+  if (existingNames.has(slug2)) slug2 = `${slug2}-${idx}`;
+  const title = `State coverage: ${suffix.replace(/-/g, " ")}`;
+  return { name: slug2, title, kind: "state-coverage" };
+}
+function copyTreeRelative(srcDir, destDir, relDir = "", stripChromeSelectors = []) {
+  const out = [];
+  const entries = readdirSync13(join21(srcDir, relDir));
+  for (const name of entries) {
+    if (name.startsWith(".")) continue;
+    const srcPath = join21(srcDir, relDir, name);
+    const destPath = join21(destDir, relDir, name);
+    const stat = statSync9(srcPath);
+    if (stat.isDirectory()) {
+      mkdirSync8(destPath, { recursive: true });
+      out.push(...copyTreeRelative(srcDir, destDir, join21(relDir, name), stripChromeSelectors));
+    } else if (stat.isFile()) {
+      if (stripChromeSelectors.length > 0 && name.toLowerCase().endsWith(".html")) {
+        const html = readFileSync23(srcPath, "utf-8");
+        const stripped = stripDocumentaryChrome(html, stripChromeSelectors);
+        writeFileSync13(destPath, stripped);
+      } else {
+        writeFileSync13(destPath, readFileSync23(srcPath));
+      }
+      out.push(join21("public", "prototype", relDir, name).replace(/\\/g, "/"));
+    }
+  }
+  return out;
+}
+function listOrderedScreenFiles(srcDir) {
+  const names = readdirSync13(srcDir).filter((n) => SCREEN_FILE_PATTERN.test(n));
+  names.sort((a, b) => {
+    const na = Number(a.match(SCREEN_FILE_PATTERN)?.[1] ?? 0);
+    const nb = Number(b.match(SCREEN_FILE_PATTERN)?.[1] ?? 0);
+    return na - nb;
+  });
+  return names;
+}
+
 // src/commands/sandbox/init.ts
 async function sandboxInitCommand(name, cwd, options) {
   const json = options.json ?? false;
@@ -6509,7 +6844,7 @@ async function runInit(name, cwd, options) {
       `Handoff has no primitives \u2014 refusing to scaffold an empty sandbox. Check the manifest at ${handoffPath}`
     );
   }
-  const sandboxDir = join21(cwd, ".lo", "sandbox", name);
+  const sandboxDir = join22(cwd, ".lo", "sandbox", name);
   if (!sandboxIsEmpty(sandboxDir)) {
     if (!options.overwrite) {
       throw new Error(
@@ -6518,23 +6853,48 @@ async function runInit(name, cwd, options) {
     }
     rmSync2(sandboxDir, { recursive: true, force: true });
   }
-  mkdirSync8(sandboxDir, { recursive: true });
+  mkdirSync9(sandboxDir, { recursive: true });
   const port = await findOpenPort();
-  writeScaffold(sandboxDir, manifest, port);
+  let prototypeImport;
+  if (options.fromHtmlPrototype) {
+    const prototypeDir = isAbsolute2(options.fromHtmlPrototype) ? options.fromHtmlPrototype : resolve15(cwd, options.fromHtmlPrototype);
+    if (!existsSync21(prototypeDir)) {
+      throw new Error(`HTML prototype directory not found: ${prototypeDir}`);
+    }
+    const stripChromeSelectors = resolveStripSelectors(
+      options.stripChrome,
+      options.stripChromeAdditional
+    );
+    prototypeImport = copyHtmlPrototype(prototypeDir, sandboxDir, manifest, {
+      stripChromeSelectors
+    });
+    for (const w of prototypeImport.warnings) manifest.warnings.push(w);
+  }
+  const known = loadKnownPrimitives();
+  for (const p of manifest.primitives) {
+    if (p.status !== "shipped" && p.status !== "gap-inflight") continue;
+    if (known.has(p.name)) continue;
+    p.status = "compose-recipe";
+    p.viTicket = void 0;
+    manifest.warnings.push(
+      `'${p.name}' declared shipped in the handoff but absent from the registry \u2014 reclassified as compose-recipe`
+    );
+  }
+  writeScaffold(sandboxDir, manifest, port, { prototypeImport });
   if (!options.skipInstall) {
     runNpmInstall(sandboxDir, options.json ?? false);
   }
-  applyThemeIfPossible(sandboxDir, manifest, options.theme, cwd, options.json ?? false);
-  const known = loadKnownPrimitives();
+  applyThemeIfPossible(
+    sandboxDir,
+    manifest,
+    options.theme,
+    cwd,
+    options.json ?? false,
+    options.themeFile
+  );
   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);
   }
@@ -6542,34 +6902,50 @@ async function runInit(name, cwd, options) {
   writeSandboxConfig(sandboxDir, manifest, port, {
     handoffPath,
     theme: options.theme,
-    visorVersion: readCliVersion()
+    visorVersion: readCliVersion(),
+    prototypeImport
   });
   return {
     success: true,
     sandboxDir,
     port,
     primitives: { shipped, gaps },
+    prototypeImport,
     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`)
-  ];
+function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json, themeFile) {
+  const candidates = [];
+  if (themeFile) {
+    candidates.push(isAbsolute2(themeFile) ? themeFile : resolve15(cwd, themeFile));
+  }
+  candidates.push(isAbsolute2(theme2) ? theme2 : resolve15(cwd, theme2));
+  const privateRoot = process.env.VISOR_THEMES_PRIVATE_PATH;
+  if (privateRoot && privateRoot.length > 0) {
+    candidates.push(join22(privateRoot, "themes", theme2, "theme.visor.yaml"));
+  }
+  candidates.push(
+    join22(cwd, "themes", `${theme2}.visor.yaml`),
+    join22(cwd, "custom-themes", `${theme2}.visor.yaml`)
+  );
   const yamlPath = candidates.find((p) => existsSync21(p));
   if (!yamlPath) {
+    const searched = candidates.join(", ");
     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.`
+      `Theme '${theme2}' not found (searched: ${searched}) \u2014 sandbox uses placeholder globals.css. Run 'npx visor theme apply <path-to-theme.visor.yaml> --adapter nextjs -o ${join22(sandboxDir, "app", "globals.css")}' manually, or re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH to a directory containing themes/${theme2}/theme.visor.yaml.`
     );
     if (!json) {
       logger.warn(`Theme '${theme2}' not found \u2014 leaving placeholder globals.css.`);
+      logger.item(
+        `Re-run with --theme-file <path>, or set VISOR_THEMES_PRIVATE_PATH=<dir-containing-themes/${theme2}/theme.visor.yaml>.`
+      );
+      logger.item(
+        `Or apply manually: npx visor theme apply <path> --adapter nextjs -o ${join22(sandboxDir, "app", "globals.css")}`
+      );
     }
     return;
   }
-  const globalsOut = join21(sandboxDir, "app", "globals.css");
+  const globalsOut = join22(sandboxDir, "app", "globals.css");
   try {
     themeApplyCommand(yamlPath, sandboxDir, {
       output: globalsOut,
@@ -6625,9 +7001,9 @@ function readCliVersion() {
     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");
+      const candidate = join22(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync23(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync24(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) return pkg2.version;
       } catch {
       }
@@ -6638,13 +7014,13 @@ function readCliVersion() {
 }
 
 // src/commands/sandbox/dev.ts
-import { existsSync as existsSync22, readFileSync as readFileSync24 } from "fs";
-import { join as join22 } from "path";
+import { existsSync as existsSync22, readFileSync as readFileSync25 } from "fs";
+import { join as join23 } 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");
+  const sandboxDir = join23(cwd, ".lo", "sandbox", options.name);
+  const configPath = join23(sandboxDir, "sandbox.json");
   if (!existsSync22(configPath)) {
     fail(
       json,
@@ -6654,7 +7030,7 @@ function sandboxDevCommand(cwd, options) {
   }
   let config;
   try {
-    config = JSON.parse(readFileSync24(configPath, "utf-8"));
+    config = JSON.parse(readFileSync25(configPath, "utf-8"));
   } catch (err) {
     fail(json, `Invalid sandbox.json at ${configPath}: ${err.message}`);
     return;
@@ -6710,13 +7086,21 @@ function fail(json, message) {
 }
 
 // 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 {
+  copyFileSync as copyFileSync2,
+  existsSync as existsSync23,
+  mkdirSync as mkdirSync10,
+  readFileSync as readFileSync26,
+  readdirSync as readdirSync14,
+  rmSync as rmSync3,
+  writeFileSync as writeFileSync14
+} from "fs";
+import { basename as basename6, join as join24 } 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");
+  const sandboxDir = join24(cwd, ".lo", "sandbox", options.name);
+  const configPath = join24(sandboxDir, "sandbox.json");
   if (!existsSync23(configPath)) {
     fail2(
       json,
@@ -6724,18 +7108,27 @@ function sandboxApproveCommand(cwd, options) {
     );
     return;
   }
-  const config = JSON.parse(readFileSync25(configPath, "utf-8"));
-  const captureScriptPath = join23(sandboxDir, "playwright.capture.mjs");
-  writeFileSync13(captureScriptPath, captureScriptTemplate(), "utf-8");
+  if (options.approve) {
+    runPromotion(sandboxDir, options.name, json);
+    return;
+  }
+  runCapture(sandboxDir, configPath, options.name, json);
+}
+function runCapture(sandboxDir, configPath, sandboxName, json) {
+  const config = JSON.parse(readFileSync26(configPath, "utf-8"));
+  const captureScriptPath = join24(sandboxDir, "playwright.capture.mjs");
+  writeFileSync14(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"
-  });
+  const result = childProcess4.spawnSync(
+    "npx",
+    ["--no-install", "node", "playwright.capture.mjs"],
+    {
+      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;
@@ -6745,20 +7138,24 @@ function sandboxApproveCommand(cwd, options) {
 ${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) : [];
+  const pendingDir = join24(sandboxDir, "captures", "pending");
+  const diffsDir = join24(sandboxDir, "captures", "diffs");
+  const approvedDir = join24(sandboxDir, "captures", "approved");
+  const pendingFiles = safeListPngs(pendingDir);
+  const diffFiles = safeListPngs(diffsDir);
+  const hasBaseline = safeListPngs(approvedDir).length > 0;
   if (json) {
     console.log(
       JSON.stringify(
         {
           success: true,
-          mode: options.diff ? "diff" : "approve",
+          mode: "pending",
+          pendingDir,
+          diffsDir,
           approvedDir,
-          diffsDir: options.diff ? diffsDir : null,
-          approved: approvedFiles,
+          pending: pendingFiles,
           diffs: diffFiles,
+          hasBaseline,
           captureOutput: tryParseJson(result.stdout)
         },
         null,
@@ -6767,34 +7164,75 @@ ${result.stderr}`);
     );
   } else {
     logger.success(
-      options.diff ? `Pixel-diff complete. ${diffFiles.length} diff PNGs in ${diffsDir}` : `Captured ${approvedFiles.length} PNGs in ${approvedDir}`
+      `Captured ${pendingFiles.length} PNGs in ${pendingDir}` + (hasBaseline ? ` (${diffFiles.length} differ from approved baseline)` : " (no prior baseline \u2014 first capture)")
     );
-    if (options.diff && diffFiles.length > 0) {
-      logger.blank();
+    logger.blank();
+    if (diffFiles.length > 0) {
       logger.info("Changed routes:");
       for (const f of diffFiles) logger.item(f);
+      logger.blank();
     }
+    logger.info("Review captures/pending/ (and captures/diffs/), then promote with:");
+    logger.item(`npx visor sandbox approve --name ${sandboxName} --approve`);
+  }
+}
+function runPromotion(sandboxDir, sandboxName, json) {
+  const pendingDir = join24(sandboxDir, "captures", "pending");
+  const approvedDir = join24(sandboxDir, "captures", "approved");
+  const diffsDir = join24(sandboxDir, "captures", "diffs");
+  const pendingFiles = safeListPngs(pendingDir);
+  if (pendingFiles.length === 0) {
+    fail2(
+      json,
+      `No pending captures found at ${pendingDir}. Run 'visor sandbox approve --name ${sandboxName}' (without --approve) first to capture and review.`
+    );
+    return;
+  }
+  mkdirSync10(approvedDir, { recursive: true });
+  const promoted = [];
+  for (const src of pendingFiles) {
+    const dest = join24(approvedDir, basename6(src));
+    copyFileSync2(src, dest);
+    promoted.push(dest);
+  }
+  rmSync3(pendingDir, { recursive: true, force: true });
+  rmSync3(diffsDir, { recursive: true, force: true });
+  if (json) {
+    console.log(
+      JSON.stringify(
+        { success: true, mode: "approve", approvedDir, promoted },
+        null,
+        2
+      )
+    );
+  } else {
+    logger.success(`Promoted ${promoted.length} pending captures \u2192 ${approvedDir}`);
+    logger.info("Pending and diff directories cleared.");
   }
 }
 function ensurePlaywrightInstalled(sandboxDir, json) {
-  const markerPath = join23(sandboxDir, ".playwright-installed");
+  const markerPath = join24(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"
-  });
+  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");
+  writeFileSync14(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));
+  return readdirSync14(dir).filter((f) => f.endsWith(".png")).map((f) => join24(dir, f));
 }
 function tryParseJson(s) {
   try {
@@ -6815,7 +7253,7 @@ function fail2(json, message) {
 // src/index.ts
 var __dirname2 = dirname10(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync26(join24(__dirname2, "..", "package.json"), "utf-8")
+  readFileSync27(join25(__dirname2, "..", "package.json"), "utf-8")
 );
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version(pkg.version);
@@ -6970,7 +7408,19 @@ 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(
+).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(
+  "--theme-file <path>",
+  "explicit path to a theme.visor.yaml \u2014 bypasses name resolution and the VISOR_THEMES_PRIVATE_PATH env var"
+).option(
+  "--from-html-prototype <path>",
+  "import a Phase 1.5 HTML prototype directory (its screen-N-*.html files become screen routes via iframe)"
+).option(
+  "--strip-chrome [selectors]",
+  "strip Phase 1.5 documentary chrome from imported prototype HTML (no arg = defaults; comma list = replace defaults)"
+).option(
+  "--strip-chrome-additional <selectors>",
+  "extra selectors to merge with the strip-chrome base list (comma-separated)"
+).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);
   }
@@ -6978,7 +7428,19 @@ sandbox.command("init").description(
 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);
-});
+sandbox.command("approve").description(
+  "Capture sandbox routes into captures/pending/ (with auto-diff vs the approved baseline). Pass --approve to promote pending \u2192 approved."
+).requiredOption("--name <name>", "sandbox name (created via 'sandbox init')").option(
+  "--approve",
+  "promote captures/pending/ \u2192 captures/approved/ (skips capture; assumes prior run populated pending)",
+  false
+).option(
+  "--diff",
+  "[deprecated, no-op] default behavior already captures to pending and diffs against approved",
+  false
+).option("--json", "output structured JSON (for AI agents)").action(
+  (options) => {
+    sandboxApproveCommand(process.cwd(), options);
+  }
+);
 program.parse();

package/dist/visor-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-05-20T04:45:51.975Z",
+  "generated_at": "2026-05-21T04:13:27.636Z",
   "components": {
     "accessibility-specimen": {
       "category": "specimen",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI for the Visor design system — add components, hooks, and utilities to your project.",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1021.0",
     "@babel/parser": "^7.26.0",
-    "@loworbitstudio/visor-theme-engine": "^0.8.1",
+    "@loworbitstudio/visor-theme-engine": "^0.9.0",
     "commander": "^13.1.0",
     "diff": "^8.0.4",
     "picocolors": "^1.1.1",