@loworbitstudio/visor 1.13.0 → 1.14.0

package/README.md

@@ -175,6 +175,52 @@ Rules in `disabledRules` are skipped entirely — useful when a project intentio
   run: npx visor check design ./src --json
 ```
 
+## visor check theme-mode
+
+Deterministic theme-mode gate. Reads a theme's declared `color-scheme` (`dark-only | light-only | adaptive`) and asserts that the app-root background (`--surface-page`) luminance matches the declared mode — catching the failure class where a `dark-only` brand ships a light app root (or vice versa), which structural oracle/freeze gates cannot see.
+
+- `dark-only` → the dark-scope app-root background must be **dark** (luminance `< 0.2`)
+- `light-only` → the light-scope app-root background must be **light** (luminance `>= 0.2`)
+- `adaptive` (or no `color-scheme`) → **skipped** — no single mode to assert
+
+The gate is fully deterministic and dependency-light: it reuses the theme engine's own resolution to compute the host page background the emitted CSS would carry, then reuses `getLuminance()`. No browser required.
+
+```bash
+# Human-readable terminal output
+npx visor check theme-mode ./my-theme.visor.yaml
+
+# JSON output for pipeline wiring
+npx visor check theme-mode ./my-theme.visor.yaml --json
+
+# Advisory mode — report without failing CI
+npx visor check theme-mode ./my-theme.visor.yaml --no-fail
+```
+
+### Output schema (--json)
+
+```json
+{
+  "success": true,
+  "pass": false,
+  "skipped": false,
+  "mode": "dark-only",
+  "theme": "my-theme",
+  "computed_bg": "#ffffff",
+  "luminance": 1,
+  "threshold": 0.2,
+  "reason": "theme declares dark-only but app-root background \"#ffffff\" renders light (luminance 1.0000, threshold 0.2) — expected dark"
+}
+```
+
+On failure, `computed_bg` is the offending computed background color.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Mode matches, or `adaptive`/no-scheme (skipped), or `--no-fail` mode |
+| `1` | Rendered mode does not match the declared `color-scheme` |
+
 ## Documentation
 
 Full docs at [visor.loworbit.studio](https://visor.loworbit.studio).

package/dist/CHANGELOG.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-06-25T19:22:02.086Z",
+  "generated_at": "2026-07-02T17:50:48.092Z",
   "components": {
     "accessibility-specimen": {
       "changeType": "current",

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync27 } from "fs";
+import { readFileSync as readFileSync28 } from "fs";
 import { dirname as dirname10, join as join25 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
@@ -9,7 +9,7 @@ import { Command as Command2 } from "commander";
 // src/commands/check.ts
 import { Command } from "commander";
 import { statSync as statSync3 } from "fs";
-import { resolve as resolve3, dirname as dirname2 } from "path";
+import { resolve as resolve4, dirname as dirname2 } from "path";
 
 // src/registry/resolve.ts
 import { readFileSync } from "fs";
@@ -867,6 +867,62 @@ function scanDesign(pathArg, options = {}) {
   };
 }
 
+// src/check/theme-mode.ts
+import { readFileSync as readFileSync4 } from "fs";
+import { resolve as resolve3 } from "path";
+import {
+  generateThemeData,
+  parseColor,
+  getLuminance
+} from "@loworbitstudio/visor-theme-engine";
+var LUMINANCE_THRESHOLD = 0.2;
+function checkThemeModeSource(yamlSource, threshold = LUMINANCE_THRESHOLD) {
+  const data = generateThemeData(yamlSource);
+  const mode = data.config["color-scheme"];
+  const theme2 = data.config.name;
+  if (mode === "adaptive") {
+    return {
+      pass: true,
+      skipped: true,
+      mode,
+      theme: theme2,
+      computed_bg: null,
+      luminance: null,
+      threshold,
+      reason: "adaptive theme \u2014 supports both modes, no single background to assert"
+    };
+  }
+  const page = data.tokens.surface.page;
+  const computed_bg = mode === "dark-only" ? page.dark : page.light;
+  const parsed = parseColor(computed_bg);
+  if (!parsed) {
+    throw new Error(
+      `Could not parse app-root background color "${computed_bg}" for theme "${theme2}".`
+    );
+  }
+  const luminance = getLuminance(parsed.rgb[0], parsed.rgb[1], parsed.rgb[2]);
+  const isDark = luminance < threshold;
+  const pass = mode === "dark-only" ? isDark : !isDark;
+  const declaredWord = mode === "dark-only" ? "dark" : "light";
+  const actualWord = isDark ? "dark" : "light";
+  const reason = pass ? `theme declares ${mode}; app-root background renders ${actualWord} (luminance ${luminance.toFixed(4)}) \u2014 matches` : `theme declares ${mode} but app-root background "${computed_bg}" renders ${actualWord} (luminance ${luminance.toFixed(4)}, threshold ${threshold}) \u2014 expected ${declaredWord}`;
+  return {
+    pass,
+    skipped: false,
+    mode,
+    theme: theme2,
+    computed_bg,
+    luminance,
+    threshold,
+    reason
+  };
+}
+function checkThemeModeFile(filePath, threshold = LUMINANCE_THRESHOLD) {
+  const abs = resolve3(filePath);
+  const source = readFileSync4(abs, "utf-8");
+  return checkThemeModeSource(source, threshold);
+}
+
 // src/utils/logger.ts
 import pc from "picocolors";
 var logger = {
@@ -1026,7 +1082,7 @@ async function checkDiffCommand(pathArg, options) {
   if (options.failOnHits) process.exit(1);
 }
 function checkDesignCommand(pathArg, options) {
-  const absPath = resolve3(pathArg);
+  const absPath = resolve4(pathArg);
   const rcDir = statSync3(absPath).isDirectory() ? absPath : dirname2(absPath);
   const rc = loadVisorRc(rcDir);
   const result = scanDesign(absPath, {
@@ -1077,6 +1133,43 @@ function checkDesignCommand(pathArg, options) {
   logger.blank();
   if (!options.noFail && summary.errorCount > 0) process.exit(1);
 }
+function checkThemeModeCommand(pathArg, options) {
+  let result;
+  try {
+    result = checkThemeModeFile(pathArg);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const useJson2 = options.json || options.format === "json";
+    if (useJson2) {
+      console.log(JSON.stringify({ success: false, error: message }, null, 2));
+    } else {
+      logger.error(message);
+    }
+    process.exit(1);
+    return;
+  }
+  const useJson = options.json || options.format === "json";
+  const shouldFail = options.fail !== false;
+  if (useJson) {
+    console.log(JSON.stringify({ success: true, ...result }, null, 2));
+    if (shouldFail && !result.pass) process.exit(1);
+    process.exit(0);
+    return;
+  }
+  if (result.skipped) {
+    logger.info(`\u20DD  skipped \u2014 ${result.theme}: ${result.reason}`);
+    process.exit(0);
+    return;
+  }
+  if (result.pass) {
+    logger.success(`${result.theme} \u2014 ${result.reason}`);
+    process.exit(0);
+    return;
+  }
+  logger.error(`${result.theme} \u2014 ${result.reason}`);
+  logger.item(`  offending background: ${pc2.cyan(result.computed_bg ?? "unknown")} (luminance ${result.luminance?.toFixed(4)})`);
+  if (shouldFail) process.exit(1);
+}
 function checkCommand() {
   const check = new Command("check").description("Check Visor catalog \u2014 list items, test existence, scan JSX for native HTML");
   check.command("list").description("List all catalog items (components, blocks, hooks, patterns)").option("--type <type>", "filter by type: ui, blocks, hooks, patterns, all (default: all)").option("--json", "output structured JSON (for AI agents)").action((options) => {
@@ -1091,17 +1184,20 @@ function checkCommand() {
   check.command("design").description("Scan frontend code for Borealis design anti-patterns (deterministic, no LLM)").argument("<path>", "file path or directory to scan").option("--format <format>", "output format: json or human (default: human when TTY, json otherwise)").option("--errors-only", "report only error-severity rules (skip warnings)").option("--no-fail", "do not exit 1 on errors (advisory mode)").option("--json", "shorthand for --format json").action((pathArg, options) => {
     checkDesignCommand(pathArg, options);
   });
+  check.command("theme-mode").description("Assert a theme's rendered app-root background matches its declared color-scheme (dark-only/light-only/adaptive)").argument("<path>", "path to a .visor.yaml theme file").option("--format <format>", "output format: json or human (default: human)").option("--no-fail", "do not exit 1 on a mode mismatch (advisory mode)").option("--json", "shorthand for --format json").action((pathArg, options) => {
+    checkThemeModeCommand(pathArg, options);
+  });
   return check;
 }
 
 // src/commands/init.ts
-import { existsSync as existsSync4, writeFileSync as writeFileSync2, mkdirSync, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync4, writeFileSync as writeFileSync2, mkdirSync, readFileSync as readFileSync7 } from "fs";
 import { join as join6, dirname as dirname3 } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 import * as childProcess from "child_process";
 
 // src/config/config.ts
-import { readFileSync as readFileSync4, writeFileSync, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync5, writeFileSync, existsSync as existsSync2 } from "fs";
 import { join as join4 } from "path";
 
 // src/config/defaults.ts
@@ -1131,7 +1227,7 @@ function loadConfig(cwd) {
       `No ${CONFIG_FILE} found. Run "visor init" first.`
     );
   }
-  const raw = readFileSync4(configPath, "utf-8");
+  const raw = readFileSync5(configPath, "utf-8");
   const parsed = JSON.parse(raw);
   const knownKeys = /* @__PURE__ */ new Set(["paths"]);
   for (const key of Object.keys(parsed)) {
@@ -1168,12 +1264,12 @@ function writeConfig(cwd, config) {
 
 // src/utils/packages.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync3, readFileSync as readFileSync5 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync6 } from "fs";
 import { join as join5 } from "path";
 function readPackageJson(cwd) {
   const pkgPath = join5(cwd, "package.json");
   if (!existsSync3(pkgPath)) return null;
-  return JSON.parse(readFileSync5(pkgPath, "utf-8"));
+  return JSON.parse(readFileSync6(pkgPath, "utf-8"));
 }
 function isPackageInstalled(packageName, cwd) {
   const pkg2 = readPackageJson(cwd);
@@ -1198,6 +1294,7 @@ function installPackages(packages, cwd, dev = false) {
 }
 
 // src/commands/templates/nextjs.ts
+import { parse as parseYaml } from "yaml";
 var NEXTJS_PINNED_VERSION = "15.1.6";
 var CREATE_NEXT_APP_FLAGS = [
   "--ts",
@@ -1211,11 +1308,24 @@ var CREATE_NEXT_APP_FLAGS = [
 ];
 var NEXTJS_STARTER_YAML = `name: my-app
 version: 1
+# color-scheme controls the mode the scaffold applies at the root <html>:
+#   adaptive   \u2014 follow the OS via prefers-color-scheme (default)
+#   dark-only  \u2014 always dark (adds className="dark" + color-scheme: dark)
+#   light-only \u2014 always light
+color-scheme: adaptive
 colors:
   primary: "#2563EB"
 `;
-function generateNextjsLayout() {
-  return `import "./globals.css";
+function extractColorScheme(yamlContent) {
+  const parsed = parseYaml(yamlContent);
+  const v = parsed?.["color-scheme"];
+  if (v === "dark-only" || v === "light-only" || v === "adaptive") return v;
+  return void 0;
+}
+function generateNextjsLayout(colorScheme) {
+  const forcedMode = colorScheme === "dark-only" ? "dark" : colorScheme === "light-only" ? "light" : void 0;
+  if (forcedMode === void 0) {
+    return `import "./globals.css";
 import { FOWT_SCRIPT } from "@loworbitstudio/visor-theme-engine/fowt";
 import type { Metadata } from "next";
 import type { ReactNode } from "react";
@@ -1235,11 +1345,41 @@ export default function RootLayout({ children }: { children: ReactNode }) {
     </html>
   );
 }
+`;
+  }
+  return `import "./globals.css";
+import { generateFowtScript } from "@loworbitstudio/visor-theme-engine/fowt";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = {
+  title: "My Visor App",
+  description: "Built with Visor \u2014 Low Orbit Studio's design system.",
+};
+
+// Theme declares \`color-scheme: ${colorScheme}\` \u2014 force ${forcedMode} at the root.
+const FOWT_SCRIPT = generateFowtScript({ defaultTheme: "${forcedMode}" });
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html
+      lang="en"
+      className="${forcedMode}"
+      style={{ colorScheme: "${forcedMode}" }}
+      suppressHydrationWarning
+    >
+      <head>
+        <script>{FOWT_SCRIPT}</script>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
 `;
 }
 
 // src/commands/init.ts
-import { generateThemeData } from "@loworbitstudio/visor-theme-engine";
+import { generateThemeData as generateThemeData2 } from "@loworbitstudio/visor-theme-engine";
 import { nextjsAdapter } from "@loworbitstudio/visor-theme-engine/adapters";
 function initCommand(cwd, options) {
   const json = options?.json ?? false;
@@ -1346,7 +1486,7 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
       logger.success("Created .visor.yaml");
     }
   }
-  const data = generateThemeData(NEXTJS_STARTER_YAML);
+  const data = generateThemeData2(NEXTJS_STARTER_YAML);
   const css = nextjsAdapter({
     primitives: data.primitives,
     tokens: data.tokens,
@@ -1366,7 +1506,8 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
     logger.success("Created app/globals.css with theme tokens");
   }
   const layoutPath = join6(cwd, "app", "layout.tsx");
-  writeFileSync2(layoutPath, generateNextjsLayout(), "utf-8");
+  const colorScheme = extractColorScheme(NEXTJS_STARTER_YAML);
+  writeFileSync2(layoutPath, generateNextjsLayout(colorScheme), "utf-8");
   filesCreated.push("app/layout.tsx");
   if (!json) {
     logger.success("Wired app/layout.tsx with FOWT prevention and theme tokens");
@@ -1442,7 +1583,7 @@ function readVisorCliVersion() {
       const segments = new Array(i).fill("..");
       const candidate = join6(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync6(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync7(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) {
           return pkg2.version;
         }
@@ -1457,7 +1598,7 @@ function readVisorCliVersion() {
 // src/utils/fs.ts
 import {
   writeFileSync as writeFileSync3,
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync8,
   existsSync as existsSync5,
   mkdirSync as mkdirSync2
 } from "fs";
@@ -1499,7 +1640,7 @@ function writeFile(filePath, content) {
 }
 function readFile(filePath) {
   if (!existsSync5(filePath)) return null;
-  return readFileSync7(filePath, "utf-8");
+  return readFileSync8(filePath, "utf-8");
 }
 function fileExists(filePath) {
   return existsSync5(filePath);
@@ -1643,7 +1784,7 @@ function listCommand(cwd, options = {}) {
 }
 
 // src/utils/pubspec.ts
-import { existsSync as existsSync6, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync4 } from "fs";
 import { join as join8 } from "path";
 import { parseDocument, YAMLMap } from "yaml";
 function mergePubspec(pubspecText, deps) {
@@ -1673,7 +1814,7 @@ function pubspecExists(cwd) {
 }
 function isPubPackageInstalled(packageName, cwd) {
   if (!pubspecExists(cwd)) return false;
-  const text = readFileSync8(pubspecPath(cwd), "utf-8");
+  const text = readFileSync9(pubspecPath(cwd), "utf-8");
   const doc = parseDocument(text);
   const depsNode = doc.get("dependencies");
   if (!(depsNode instanceof YAMLMap)) return false;
@@ -1689,7 +1830,7 @@ function addPubDependencies(deps, cwd) {
       `No pubspec.yaml found at ${path2}. Run this command from a Flutter project root.`
     );
   }
-  const text = readFileSync8(path2, "utf-8");
+  const text = readFileSync9(path2, "utf-8");
   const result = mergePubspec(text, deps);
   if (result.added.length > 0) {
     writeFileSync4(path2, result.text, "utf-8");
@@ -2398,9 +2539,9 @@ function infoCommand(name, cwd, options = {}) {
 }
 
 // src/commands/theme-apply.ts
-import { readFileSync as readFileSync9, writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
-import { resolve as resolve4, dirname as dirname5, join as join10 } from "path";
-import { generateTheme, generateThemeData as generateThemeData2 } from "@loworbitstudio/visor-theme-engine";
+import { readFileSync as readFileSync10, writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
+import { resolve as resolve5, dirname as dirname5, join as join10 } from "path";
+import { generateTheme, generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
 import {
   nextjsAdapter as nextjsAdapter2,
   fumadocsAdapter,
@@ -2429,10 +2570,10 @@ function defaultOutputPath(adapter, themeName) {
   }
 }
 function themeApplyCommand(file, cwd, options) {
-  const filePath = resolve4(cwd, file);
+  const filePath = resolve5(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync9(filePath, "utf-8");
+    yamlContent = readFileSync10(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2453,7 +2594,7 @@ function themeApplyCommand(file, cwd, options) {
   let sections;
   try {
     if (options.adapter) {
-      const data = generateThemeData2(yamlContent);
+      const data = generateThemeData3(yamlContent);
       themeName = data.config.name;
       const adapterInput = {
         primitives: data.primitives,
@@ -2511,7 +2652,7 @@ function themeApplyCommand(file, cwd, options) {
     process.exit(1);
   }
   const outputTarget = options.output ?? defaultOutputPath(options.adapter, themeName);
-  const outputPath = resolve4(cwd, outputTarget);
+  const outputPath = resolve5(cwd, outputTarget);
   if (fileMap) {
     try {
       mkdirSync3(outputPath, { recursive: true });
@@ -2600,8 +2741,8 @@ function formatSize(bytes) {
 }
 
 // src/commands/theme-export.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { resolve as resolve5 } from "path";
+import { readFileSync as readFileSync11 } from "fs";
+import { resolve as resolve6 } from "path";
 import {
   parseConfig,
   resolveConfig,
@@ -2609,10 +2750,10 @@ import {
   exportTheme
 } from "@loworbitstudio/visor-theme-engine";
 function themeExportCommand(file, cwd, options) {
-  const filePath = resolve5(cwd, file ?? ".visor.yaml");
+  const filePath = resolve6(cwd, file ?? ".visor.yaml");
   let yamlContent;
   try {
-    yamlContent = readFileSync10(filePath, "utf-8");
+    yamlContent = readFileSync11(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2664,16 +2805,16 @@ function themeExportCommand(file, cwd, options) {
 }
 
 // src/commands/theme-validate.ts
-import { readFileSync as readFileSync11 } from "fs";
-import { resolve as resolve6 } from "path";
-import { parse as parseYaml } from "yaml";
+import { readFileSync as readFileSync12 } from "fs";
+import { resolve as resolve7 } from "path";
+import { parse as parseYaml2 } from "yaml";
 import { validate } from "@loworbitstudio/visor-theme-engine";
 import pc3 from "picocolors";
 function themeValidateCommand(file, cwd, options) {
-  const filePath = resolve6(cwd, file);
+  const filePath = resolve7(cwd, file);
   let fileContent;
   try {
-    fileContent = readFileSync11(filePath, "utf-8");
+    fileContent = readFileSync12(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -2697,7 +2838,7 @@ function themeValidateCommand(file, cwd, options) {
   }
   let parsed;
   try {
-    parsed = parseYaml(fileContent);
+    parsed = parseYaml2(fileContent);
   } catch (err) {
     const message = err instanceof Error ? err.message : "Invalid YAML syntax";
     if (options.json) {
@@ -2763,7 +2904,7 @@ function printIssue(issue) {
 // src/commands/theme-verify.ts
 import { spawnSync as _spawnSync } from "child_process";
 import { existsSync as existsSync8 } from "fs";
-import { resolve as resolve7 } from "path";
+import { resolve as resolve8 } from "path";
 function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
   const target = options.target ?? "flutter";
   if (target !== "flutter") {
@@ -2785,7 +2926,7 @@ function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
     }
     process.exit(1);
   }
-  const dirPath = resolve7(cwd, dir);
+  const dirPath = resolve8(cwd, dir);
   if (!existsSync8(dirPath)) {
     if (options.json) {
       console.log(
@@ -2873,8 +3014,8 @@ function themeVerifyCommand(dir, cwd, options, _spawnFn = _spawnSync) {
 }
 
 // src/commands/theme-extract.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync6, existsSync as existsSync9, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
-import { resolve as resolve8, join as join11, basename as basename2, extname as extname3, relative } from "path";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync6, existsSync as existsSync9, readdirSync as readdirSync4, statSync as statSync5 } from "fs";
+import { resolve as resolve9, join as join11, basename as basename2, extname as extname3, relative } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import {
   extractFromCSS,
@@ -2903,7 +3044,7 @@ var CSS_DIRS = [
   "packages/design-tokens"
 ];
 function themeExtractCommand(cwd, options) {
-  const targetDir = resolve8(cwd, options.from ?? ".");
+  const targetDir = resolve9(cwd, options.from ?? ".");
   if (!existsSync9(targetDir)) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Directory not found: ${targetDir}` }));
@@ -2975,11 +3116,11 @@ function collectCSSFiles(targetDir) {
   return files;
 }
 function addFileIfExists(filePath, files, seen) {
-  const resolved = resolve8(filePath);
+  const resolved = resolve9(filePath);
   if (seen.has(resolved)) return;
   if (!existsSync9(resolved)) return;
   try {
-    const content = readFileSync12(resolved, "utf-8");
+    const content = readFileSync13(resolved, "utf-8");
     if (content.includes("--")) {
       files.push({ path: resolved, content });
       seen.add(resolved);
@@ -3095,7 +3236,7 @@ function parseNextFontFromLayouts(targetDir) {
     const fullPath = join11(targetDir, relPath);
     if (!existsSync9(fullPath)) continue;
     try {
-      const content = readFileSync12(fullPath, "utf-8");
+      const content = readFileSync13(fullPath, "utf-8");
       parseNextFontDeclarations(content, fontMap);
     } catch {
     }
@@ -3183,7 +3324,7 @@ function extractFontHints(targetDir) {
   const pkgPath = join11(targetDir, "package.json");
   if (!existsSync9(pkgPath)) return void 0;
   try {
-    const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+    const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
     const allDeps = { ...pkg2.dependencies, ...pkg2.devDependencies };
     const fonts2 = [];
     for (const [dep, _] of Object.entries(allDeps)) {
@@ -3222,7 +3363,7 @@ function inferThemeName(targetDir) {
   const pkgPath = join11(targetDir, "package.json");
   if (existsSync9(pkgPath)) {
     try {
-      const pkg2 = JSON.parse(readFileSync12(pkgPath, "utf-8"));
+      const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
       if (pkg2.name) {
         const name = pkg2.name.replace(/^@[\w-]+\//, "");
         return `${name}-theme`;
@@ -3259,7 +3400,7 @@ function outputJSON(result, validationResult) {
 }
 function outputYAML(result, outputPath, cwd, validationResult) {
   const yamlStr = buildAnnotatedYAML(result);
-  const outFile = resolve8(cwd, outputPath ?? ".visor.yaml");
+  const outFile = resolve9(cwd, outputPath ?? ".visor.yaml");
   const high = result.tokens.filter((t) => t.confidence === "high").length;
   const med = result.tokens.filter((t) => t.confidence === "medium").length;
   const low = result.tokens.filter((t) => t.confidence === "low").length;
@@ -3345,14 +3486,14 @@ function buildAnnotatedYAML(result) {
 }
 
 // src/commands/theme-register.ts
-import { readFileSync as readFileSync14, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync11 } from "fs";
-import { resolve as resolve10, join as join13 } from "path";
-import { generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
+import { readFileSync as readFileSync15, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync11 } from "fs";
+import { resolve as resolve11, join as join13 } from "path";
+import { generateThemeData as generateThemeData4 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/utils/theme-helpers.ts
-import { existsSync as existsSync10, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync13, readlinkSync, realpathSync, statSync as statSync6 } from "fs";
-import { resolve as resolve9, dirname as dirname6, join as join12 } from "path";
+import { existsSync as existsSync10, lstatSync, readdirSync as readdirSync5, readFileSync as readFileSync14, readlinkSync, realpathSync, statSync as statSync6 } from "fs";
+import { resolve as resolve10, dirname as dirname6, join as join12 } from "path";
 import { execFileSync as execFileSync3 } from "child_process";
 function toSlug(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
@@ -3361,7 +3502,7 @@ function toLabel(name) {
   return name.split(/[\s-]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function findRepoRoot(startDir) {
-  let current = resolve9(startDir);
+  let current = resolve10(startDir);
   while (true) {
     if (existsSync10(join12(current, "packages", "docs"))) {
       return current;
@@ -3380,7 +3521,7 @@ function findMainRepoRoot(startDir) {
       stdio: ["ignore", "pipe", "ignore"]
     }).trim();
     if (commonDir) {
-      const absoluteCommonDir = resolve9(startDir, commonDir);
+      const absoluteCommonDir = resolve10(startDir, commonDir);
       const candidate = dirname6(absoluteCommonDir);
       if (existsSync10(join12(candidate, "packages", "docs"))) {
         return candidate;
@@ -3449,12 +3590,12 @@ function scanNestedThemeDir(dir) {
   return out;
 }
 function detectVisorWorkspace(cwd) {
-  let current = resolve9(cwd);
+  let current = resolve10(cwd);
   while (true) {
     const pkgPath = join12(current, "package.json");
     if (existsSync10(pkgPath)) {
       try {
-        const pkg2 = JSON.parse(readFileSync13(pkgPath, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync14(pkgPath, "utf-8"));
         const workspaces = pkg2.workspaces ?? [];
         const hasCli = workspaces.some((w) => w.includes("packages/cli"));
         const hasEngine = workspaces.some((w) => w.includes("packages/theme-engine"));
@@ -3478,12 +3619,12 @@ function isLocalVisorBinary(workspaceRoot, scriptPath) {
   try {
     resolvedScript = realpathSync(scriptPath);
   } catch {
-    resolvedScript = resolve9(scriptPath);
+    resolvedScript = resolve10(scriptPath);
   }
   try {
     resolvedPrefix = realpathSync(expectedPrefix);
   } catch {
-    resolvedPrefix = resolve9(expectedPrefix);
+    resolvedPrefix = resolve10(expectedPrefix);
   }
   return resolvedScript.startsWith(resolvedPrefix + "/") || resolvedScript === resolvedPrefix;
 }
@@ -3573,10 +3714,10 @@ ${indent}${newEntry},
   return { updated, changed: true };
 }
 function themeRegisterCommand(file, cwd, options) {
-  const filePath = resolve10(cwd, file);
+  const filePath = resolve11(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync14(filePath, "utf-8");
+    yamlContent = readFileSync15(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Could not read file: ${filePath}` }));
@@ -3588,7 +3729,7 @@ function themeRegisterCommand(file, cwd, options) {
   }
   let data;
   try {
-    data = generateThemeData3(yamlContent);
+    data = generateThemeData4(yamlContent);
   } catch (err) {
     const message = err instanceof Error ? err.message : "Unknown error parsing theme";
     if (options.json) {
@@ -3636,8 +3777,8 @@ function themeRegisterCommand(file, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync14(globalsPath, "utf-8");
-    themeConfigContent = readFileSync14(themeConfigPath, "utf-8");
+    globalsContent = readFileSync15(globalsPath, "utf-8");
+    themeConfigContent = readFileSync15(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -3649,7 +3790,7 @@ function themeRegisterCommand(file, cwd, options) {
     return;
   }
   const cssExists = existsSync11(cssFilePath);
-  const cssChanged = !cssExists || readFileSync14(cssFilePath, "utf-8") !== css;
+  const cssChanged = !cssExists || readFileSync15(cssFilePath, "utf-8") !== css;
   const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged, error: configError } = insertThemeConfig(
     themeConfigContent,
@@ -3733,7 +3874,7 @@ function themeRegisterCommand(file, cwd, options) {
 }
 
 // src/commands/theme-unregister.ts
-import { readFileSync as readFileSync15, writeFileSync as writeFileSync8, existsSync as existsSync12, unlinkSync } from "fs";
+import { readFileSync as readFileSync16, writeFileSync as writeFileSync8, existsSync as existsSync12, unlinkSync } from "fs";
 import { join as join14 } from "path";
 function removeGlobalsImport(content, slug2) {
   const importLine = `@import './${slug2}-theme.css';`;
@@ -3783,8 +3924,8 @@ function themeUnregisterCommand(slug2, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync15(globalsPath, "utf-8");
-    themeConfigContent = readFileSync15(themeConfigPath, "utf-8");
+    globalsContent = readFileSync16(globalsPath, "utf-8");
+    themeConfigContent = readFileSync16(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -3836,7 +3977,7 @@ function themeUnregisterCommand(slug2, cwd, options) {
 
 // src/commands/theme-sync.ts
 import {
-  readFileSync as readFileSync16,
+  readFileSync as readFileSync17,
   writeFileSync as writeFileSync9,
   mkdirSync as mkdirSync5,
   existsSync as existsSync13,
@@ -3844,9 +3985,9 @@ import {
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-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 { join as join15, basename as basename3, resolve as resolve12, sep, relative as relative2 } from "path";
+import { parse as parseYaml3 } from "yaml";
+import { generateThemeData as generateThemeData5, validateFontCoverage, formatFontCoverageError } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
 var PRIVATE_THEMES_REPO_URL = "git@github.com:low-orbit-studio/visor-themes-private.git";
 var PRIVATE_THEMES_ENV_VAR = "VISOR_THEMES_PRIVATE_PATH";
@@ -3884,7 +4025,7 @@ function resolveCustomSources(repoRoot, mainRepoRoot, warn) {
   };
   const envPath = process.env[PRIVATE_THEMES_ENV_VAR];
   if (envPath && envPath.trim() !== "") {
-    const resolved = resolve11(envPath);
+    const resolved = resolve12(envPath);
     if (!existsSync13(resolved)) {
       throw new Error(
         `${PRIVATE_THEMES_ENV_VAR} is set to "${envPath}" but the path does not exist. Expected a directory containing {slug}/theme.visor.yaml entries.`
@@ -4008,17 +4149,17 @@ function enforceWorkspaceGuard(cwd) {
   ].join("\n");
 }
 function extractGroup(yamlContent) {
-  const parsed = parseYaml2(yamlContent);
+  const parsed = parseYaml3(yamlContent);
   if (typeof parsed?.group === "string") return parsed.group;
   return void 0;
 }
 function extractLabel(yamlContent) {
-  const parsed = parseYaml2(yamlContent);
+  const parsed = parseYaml3(yamlContent);
   if (typeof parsed?.label === "string") return parsed.label;
   return void 0;
 }
 function extractDefaultMode(yamlContent) {
-  const parsed = parseYaml2(yamlContent);
+  const parsed = parseYaml3(yamlContent);
   const v = parsed?.["default-mode"];
   if (v === "dark" || v === "light") return v;
   return void 0;
@@ -4251,14 +4392,14 @@ function themeSyncCommand(cwd, options) {
   const processFile = (filePath, isCustom, slugOverride) => {
     let yamlContent;
     try {
-      yamlContent = readFileSync16(filePath, "utf-8");
+      yamlContent = readFileSync17(filePath, "utf-8");
     } catch {
       failures.push({ filePath, error: `Could not read: ${filePath}` });
       return;
     }
     let data;
     try {
-      data = generateThemeData4(yamlContent);
+      data = generateThemeData5(yamlContent);
     } catch (err) {
       failures.push({
         filePath,
@@ -4301,8 +4442,8 @@ function themeSyncCommand(cwd, options) {
   let globalsContent;
   let themeConfigContent;
   try {
-    globalsContent = readFileSync16(globalsPath, "utf-8");
-    themeConfigContent = readFileSync16(themeConfigPath, "utf-8");
+    globalsContent = readFileSync17(globalsPath, "utf-8");
+    themeConfigContent = readFileSync17(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -4436,7 +4577,7 @@ function themeSyncCommand(cwd, options) {
 
 // src/commands/theme-batch-apply-flutter.ts
 import {
-  readFileSync as readFileSync17,
+  readFileSync as readFileSync18,
   writeFileSync as writeFileSync10,
   mkdirSync as mkdirSync6,
   existsSync as existsSync14,
@@ -4444,7 +4585,7 @@ import {
   rmSync
 } from "fs";
 import { join as join16, basename as basename4, dirname as dirname7 } from "path";
-import { generateThemeData as generateThemeData5 } from "@loworbitstudio/visor-theme-engine";
+import { generateThemeData as generateThemeData6 } from "@loworbitstudio/visor-theme-engine";
 import { flutterAdapter as flutterAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 function scanThemeDir2(dir) {
   if (!existsSync14(dir)) return [];
@@ -4604,14 +4745,14 @@ function themeBatchApplyFlutterCommand(cwd, options) {
   for (const filePath of allFiles) {
     let yamlContent;
     try {
-      yamlContent = readFileSync17(filePath, "utf-8");
+      yamlContent = readFileSync18(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       continue;
     }
     let data;
     try {
-      data = generateThemeData5(yamlContent);
+      data = generateThemeData6(yamlContent);
     } catch (err) {
       errors.push(
         `Failed to parse ${basename4(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
@@ -4727,8 +4868,8 @@ function themeBatchApplyFlutterCommand(cwd, options) {
 }
 
 // src/commands/fonts-add.ts
-import { existsSync as existsSync15, statSync as statSync7, readdirSync as readdirSync8, readFileSync as readFileSync18 } from "fs";
-import { resolve as resolve12, basename as basename5, extname as extname4 } from "path";
+import { existsSync as existsSync15, statSync as statSync7, readdirSync as readdirSync8, readFileSync as readFileSync19 } from "fs";
+import { resolve as resolve13, basename as basename5, extname as extname4 } from "path";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 function deriveFamilySlug(filename) {
   const name = basename5(filename, extname4(filename));
@@ -4772,7 +4913,7 @@ function deriveFamilySlug(filename) {
   return parts.join("-").toLowerCase();
 }
 function collectWoff2Files(inputPath) {
-  const resolved = resolve12(inputPath);
+  const resolved = resolve13(inputPath);
   if (!existsSync15(resolved)) {
     throw new Error(`Path not found: ${resolved}`);
   }
@@ -4786,7 +4927,7 @@ function collectWoff2Files(inputPath) {
     return [resolved];
   }
   if (stat.isDirectory()) {
-    const files = readdirSync8(resolved).filter((f) => extname4(f).toLowerCase() === ".woff2").map((f) => resolve12(resolved, f));
+    const files = readdirSync8(resolved).filter((f) => extname4(f).toLowerCase() === ".woff2").map((f) => resolve13(resolved, f));
     if (files.length === 0) {
       throw new Error(
         `No .woff2 files found in directory: ${resolved}`
@@ -4801,7 +4942,7 @@ function collectWoff2Files(inputPath) {
   throw new Error(`Path is neither a file nor a directory: ${resolved}`);
 }
 function getNonWoff2Fonts(inputPath) {
-  const resolved = resolve12(inputPath);
+  const resolved = resolve13(inputPath);
   if (!existsSync15(resolved) || !statSync7(resolved).isDirectory()) {
     return [];
   }
@@ -4839,7 +4980,7 @@ function createR2Client(config) {
   });
 }
 async function uploadFile(client, bucket, key, filePath) {
-  const body = readFileSync18(filePath);
+  const body = readFileSync19(filePath);
   await client.send(
     new PutObjectCommand({
       Bucket: bucket,
@@ -4855,7 +4996,7 @@ async function fontsAddCommand(inputPath, options) {
     const r2Config = getR2Config();
     const files = collectWoff2Files(inputPath);
     const familySlug = options.family ?? deriveFamilySlug(basename5(files[0]));
-    const resolved = resolve12(inputPath);
+    const resolved = resolve13(inputPath);
     const nonWoff2 = statSync7(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
     if (!json) {
       logger.heading("Visor Font Upload");
@@ -5143,7 +5284,7 @@ function findCssFiles(dir, maxDepth = 3) {
 }
 
 // src/utils/patterns.ts
-import { existsSync as existsSync17, readdirSync as readdirSync10, readFileSync as readFileSync20 } from "fs";
+import { existsSync as existsSync17, readdirSync as readdirSync10, readFileSync as readFileSync21 } from "fs";
 import { join as join18 } from "path";
 import { parse as parseYAML } from "yaml";
 function loadPatternsFromYaml(repoRoot) {
@@ -5153,7 +5294,7 @@ function loadPatternsFromYaml(repoRoot) {
     (f) => f.endsWith(".visor-pattern.yaml")
   );
   return files.map((file) => {
-    const content = readFileSync20(join18(patternsDir, file), "utf-8");
+    const content = readFileSync21(join18(patternsDir, file), "utf-8");
     return parseYAML(content);
   }).filter(Boolean);
 }
@@ -5542,9 +5683,9 @@ 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 relative4 } from "path";
-import { parse as parseYaml3 } from "yaml";
+import { readFileSync as readFileSync22, writeFileSync as writeFileSync11, readdirSync as readdirSync11, statSync as statSync8, existsSync as existsSync18 } from "fs";
+import { resolve as resolve14, join as join19, relative as relative4 } from "path";
+import { parse as parseYaml4 } from "yaml";
 import pc4 from "picocolors";
 var V7_ENTR_SUBSTITUTION_MAP = {
   "--panel": "--surface-card",
@@ -5573,8 +5714,8 @@ function readMapFromThemeFile(themeId, cwd) {
   for (const candidate of candidates) {
     if (existsSync18(candidate)) {
       try {
-        const raw = readFileSync21(candidate, "utf-8");
-        const parsed = parseYaml3(raw);
+        const raw = readFileSync22(candidate, "utf-8");
+        const parsed = parseYaml4(raw);
         if (parsed?.migrate?.["token-substitution"]) {
           return parsed.migrate["token-substitution"];
         }
@@ -5657,7 +5798,7 @@ function runSubstitutionPass(targetPath, map, themeId) {
   const fileResults = [];
   let totalSubstitutions = 0;
   for (const file of files) {
-    const content = readFileSync21(file, "utf-8");
+    const content = readFileSync22(file, "utf-8");
     const { newContent, substitutions } = applySubstitutionsToContent(content, map);
     if (substitutions.length > 0) {
       fileResults.push({ file, substitutions, originalContent: content, newContent });
@@ -5691,7 +5832,7 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
     process.exit(1);
     return;
   }
-  const targetPath = resolve13(cwd, targetArg ?? ".");
+  const targetPath = resolve14(cwd, targetArg ?? ".");
   try {
     statSync8(targetPath);
   } catch {
@@ -5780,16 +5921,16 @@ function migrateTokenSubstitutionCommand(targetArg, cwd, options) {
 }
 
 // src/commands/sandbox/init.ts
-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 { existsSync as existsSync21, mkdirSync as mkdirSync9, readFileSync as readFileSync25, rmSync as rmSync2 } from "fs";
+import { isAbsolute as isAbsolute2, join as join22, resolve as resolve16, 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";
+import { readFileSync as readFileSync23, existsSync as existsSync19 } from "fs";
+import { dirname as dirname8, resolve as resolve15, isAbsolute } from "path";
 function parseHandoff(handoffPath) {
-  const text = readFileSync22(handoffPath, "utf-8");
+  const text = readFileSync23(handoffPath, "utf-8");
   const lines2 = text.split("\n");
   const warnings = [];
   const pattern2 = extractPatternSlug(lines2, warnings);
@@ -5828,7 +5969,7 @@ function extractRecipePath(text, handoffPath, warnings) {
   }
   const href = m[2].trim();
   if (isAbsolute(href)) return href;
-  return resolve14(dirname8(handoffPath), href);
+  return resolve15(dirname8(handoffPath), href);
 }
 var STATUS_PATTERNS = [
   { re: /NEW\s+gap/i, status: "gap-new" },
@@ -5875,7 +6016,7 @@ function extractPrimitives(text, warnings) {
   return primitives;
 }
 function extractRecipeArtifacts(recipePath, warnings) {
-  const text = readFileSync22(recipePath, "utf-8");
+  const text = readFileSync23(recipePath, "utf-8");
   const screens = extractScreens(text);
   const mockShapes = extractMockFields(text, warnings);
   return { screens, mockShapes };
@@ -6527,7 +6668,7 @@ 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 { mkdirSync as mkdirSync8, readdirSync as readdirSync13, readFileSync as readFileSync24, statSync as statSync9, writeFileSync as writeFileSync13 } from "fs";
 import { join as join21 } from "path";
 
 // src/commands/sandbox/strip-chrome.ts
@@ -6777,11 +6918,11 @@ function copyTreeRelative(srcDir, destDir, relDir = "", stripChromeSelectors = [
       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 html = readFileSync24(srcPath, "utf-8");
         const stripped = stripDocumentaryChrome(html, stripChromeSelectors);
         writeFileSync13(destPath, stripped);
       } else {
-        writeFileSync13(destPath, readFileSync23(srcPath));
+        writeFileSync13(destPath, readFileSync24(srcPath));
       }
       out.push(join21("public", "prototype", relDir, name).replace(/\\/g, "/"));
     }
@@ -6835,7 +6976,7 @@ 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);
+  const handoffPath = isAbsolute2(options.handoff) ? options.handoff : resolve16(cwd, options.handoff);
   if (!existsSync21(handoffPath)) {
     throw new Error(`Handoff manifest not found: ${handoffPath}`);
   }
@@ -6858,7 +6999,7 @@ async function runInit(name, cwd, options) {
   const port = await findOpenPort();
   let prototypeImport;
   if (options.fromHtmlPrototype) {
-    const prototypeDir = isAbsolute2(options.fromHtmlPrototype) ? options.fromHtmlPrototype : resolve15(cwd, options.fromHtmlPrototype);
+    const prototypeDir = isAbsolute2(options.fromHtmlPrototype) ? options.fromHtmlPrototype : resolve16(cwd, options.fromHtmlPrototype);
     if (!existsSync21(prototypeDir)) {
       throw new Error(`HTML prototype directory not found: ${prototypeDir}`);
     }
@@ -6918,9 +7059,9 @@ async function runInit(name, cwd, options) {
 function applyThemeIfPossible(sandboxDir, manifest, theme2, cwd, json, themeFile) {
   const candidates = [];
   if (themeFile) {
-    candidates.push(isAbsolute2(themeFile) ? themeFile : resolve15(cwd, themeFile));
+    candidates.push(isAbsolute2(themeFile) ? themeFile : resolve16(cwd, themeFile));
   }
-  candidates.push(isAbsolute2(theme2) ? theme2 : resolve15(cwd, theme2));
+  candidates.push(isAbsolute2(theme2) ? theme2 : resolve16(cwd, theme2));
   const privateRoot = process.env.VISOR_THEMES_PRIVATE_PATH;
   if (privateRoot && privateRoot.length > 0) {
     candidates.push(join22(privateRoot, "themes", theme2, "theme.visor.yaml"));
@@ -7004,7 +7145,7 @@ function readCliVersion() {
       const segments = new Array(i).fill("..");
       const candidate = join22(here, ...segments, "package.json");
       try {
-        const pkg2 = JSON.parse(readFileSync24(candidate, "utf-8"));
+        const pkg2 = JSON.parse(readFileSync25(candidate, "utf-8"));
         if (pkg2.name === "@loworbitstudio/visor" && pkg2.version) return pkg2.version;
       } catch {
       }
@@ -7015,7 +7156,7 @@ function readCliVersion() {
 }
 
 // src/commands/sandbox/dev.ts
-import { existsSync as existsSync22, readFileSync as readFileSync25 } from "fs";
+import { existsSync as existsSync22, readFileSync as readFileSync26 } from "fs";
 import { join as join23 } from "path";
 import * as childProcess3 from "child_process";
 function sandboxDevCommand(cwd, options) {
@@ -7031,7 +7172,7 @@ function sandboxDevCommand(cwd, options) {
   }
   let config;
   try {
-    config = JSON.parse(readFileSync25(configPath, "utf-8"));
+    config = JSON.parse(readFileSync26(configPath, "utf-8"));
   } catch (err) {
     fail(json, `Invalid sandbox.json at ${configPath}: ${err.message}`);
     return;
@@ -7091,7 +7232,7 @@ import {
   copyFileSync as copyFileSync2,
   existsSync as existsSync23,
   mkdirSync as mkdirSync10,
-  readFileSync as readFileSync26,
+  readFileSync as readFileSync27,
   readdirSync as readdirSync14,
   rmSync as rmSync3,
   writeFileSync as writeFileSync14
@@ -7116,7 +7257,7 @@ function sandboxApproveCommand(cwd, options) {
   runCapture(sandboxDir, configPath, options.name, json);
 }
 function runCapture(sandboxDir, configPath, sandboxName, json) {
-  const config = JSON.parse(readFileSync26(configPath, "utf-8"));
+  const config = JSON.parse(readFileSync27(configPath, "utf-8"));
   const captureScriptPath = join24(sandboxDir, "playwright.capture.mjs");
   writeFileSync14(captureScriptPath, captureScriptTemplate(), "utf-8");
   ensurePlaywrightInstalled(sandboxDir, json);
@@ -7254,7 +7395,7 @@ function fail2(json, message) {
 // src/index.ts
 var __dirname2 = dirname10(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync27(join25(__dirname2, "..", "package.json"), "utf-8")
+  readFileSync28(join25(__dirname2, "..", "package.json"), "utf-8")
 );
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version(pkg.version);

package/dist/registry.json

@@ -2687,7 +2687,7 @@
         {
           "path": "components/ui/page-header/page-header.tsx",
           "type": "registry:ui",
-          "content": "import * as React from \"react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\nimport { cn } from \"../../../lib/utils\"\nimport styles from \"./page-header.module.css\"\n\nconst pageHeaderVariants = cva(styles.base, {\n  variants: {\n    size: {\n      sm: styles.sizeSm,\n      md: styles.sizeMd,\n      lg: styles.sizeLg,\n    },\n  },\n  defaultVariants: {\n    size: \"md\",\n  },\n})\n\ntype PageHeaderElement = \"header\" | \"section\" | \"div\"\ntype TitleElement = \"h1\" | \"h2\" | \"h3\"\n\n/** Token preset values for the `titleSize` prop. */\nconst TITLE_SIZE_TOKENS = [\"default\", \"marquee\"] as const\ntype TitleSizeToken = (typeof TITLE_SIZE_TOKENS)[number]\n\n/** Token preset values for the `titleFamily` prop. */\nconst TITLE_FAMILY_TOKENS = [\"heading\", \"display\"] as const\ntype TitleFamilyToken = (typeof TITLE_FAMILY_TOKENS)[number]\n\nfunction isTitleSizeToken(value: string): value is TitleSizeToken {\n  return (TITLE_SIZE_TOKENS as readonly string[]).includes(value)\n}\n\nfunction isTitleFamilyToken(value: string): value is TitleFamilyToken {\n  return (TITLE_FAMILY_TOKENS as readonly string[]).includes(value)\n}\n\nexport interface PageHeaderProps\n  extends Omit<React.HTMLAttributes<HTMLElement>, \"title\">,\n    VariantProps<typeof pageHeaderVariants> {\n  /** Optional small uppercase label rendered above the title. */\n  eyebrow?: React.ReactNode\n  /** Page heading content. Rendered in the element given by `titleAs`. */\n  title: React.ReactNode\n  /** Optional supporting copy rendered below the title. */\n  description?: React.ReactNode\n  /** Optional ReactNode rendered above the title row (typically a Breadcrumb). */\n  breadcrumb?: React.ReactNode\n  /**\n   * Optional media/identity node rendered to the LEFT of the title block inside\n   * the title row (typically an Avatar or identity plate). When present the row\n   * forms an identity lockup and the slot top-aligns against the title/description\n   * stack (VI-539). Omitting it leaves the row exactly as the default\n   * text|actions layout, so existing call sites render unchanged.\n   */\n  leading?: React.ReactNode\n  /** Optional ReactNode rendered on the right side of the title row. */\n  actions?: React.ReactNode\n  /** Root element tag. Defaults to `header`. */\n  as?: PageHeaderElement\n  /** Heading level for the title. Defaults to `h1`. */\n  titleAs?: TitleElement\n  /**\n   * Title font-size override. Token presets (`\"default\" | \"marquee\"`) map to\n   * `data-title-size` attributes; any other string is forwarded as a raw CSS\n   * length on the `--page-header-title-size` custom property.\n   */\n  titleSize?: \"default\" | \"marquee\" | (string & {})\n  /**\n   * Title font-family override. Token presets (`\"heading\" | \"display\"`) map\n   * to `data-title-family` attributes; any other string is forwarded as a\n   * raw CSS family on the `--page-header-title-family` custom property.\n   */\n  titleFamily?: \"heading\" | \"display\" | (string & {})\n  /**\n   * Title line-height override. Forwarded as a raw CSS `line-height` value\n   * on the `--page-header-title-leading` custom property (a unitless number\n   * like `1.05` or any CSS length). When omitted, the title falls back to its\n   * default line-height (tight for the standard title, `1` for the marquee\n   * scale), so existing call sites render unchanged.\n   */\n  titleLeading?: string | number\n}\n\nconst PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(\n  (\n    {\n      className,\n      size,\n      eyebrow,\n      title,\n      description,\n      breadcrumb,\n      leading,\n      actions,\n      as = \"header\",\n      titleAs = \"h1\",\n      titleSize,\n      titleFamily,\n      titleLeading,\n      ...props\n    },\n    ref\n  ) => {\n    const Root = as as React.ElementType\n    const Title = titleAs as React.ElementType\n\n    const titleSizeToken =\n      typeof titleSize === \"string\" && isTitleSizeToken(titleSize)\n        ? titleSize\n        : undefined\n    const titleFamilyToken =\n      typeof titleFamily === \"string\" && isTitleFamilyToken(titleFamily)\n        ? titleFamily\n        : undefined\n\n    const rawTitleSize =\n      typeof titleSize === \"string\" && !titleSizeToken ? titleSize : undefined\n    const rawTitleFamily =\n      typeof titleFamily === \"string\" && !titleFamilyToken\n        ? titleFamily\n        : undefined\n\n    const hasTitleLeading = titleLeading !== undefined && titleLeading !== null\n\n    const titleStyle: React.CSSProperties | undefined =\n      rawTitleSize || rawTitleFamily || hasTitleLeading\n        ? {\n            ...(rawTitleSize\n              ? ({\n                  \"--page-header-title-size\": rawTitleSize,\n                } as React.CSSProperties)\n              : null),\n            ...(rawTitleFamily\n              ? ({\n                  \"--page-header-title-family\": rawTitleFamily,\n                } as React.CSSProperties)\n              : null),\n            ...(hasTitleLeading\n              ? ({\n                  \"--page-header-title-leading\": String(titleLeading),\n                } as React.CSSProperties)\n              : null),\n          }\n        : undefined\n\n    // When a raw string is supplied, switch the title into the \"marquee\" /\n    // \"display\" rules that consume the custom property so the override\n    // actually takes effect. Token values map directly to data-attributes.\n    const resolvedTitleSizeAttr =\n      titleSizeToken ?? (rawTitleSize ? \"marquee\" : undefined)\n    const resolvedTitleFamilyAttr =\n      titleFamilyToken ?? (rawTitleFamily ? \"display\" : undefined)\n\n    return (\n      <Root\n        ref={ref}\n        data-slot=\"page-header\"\n        className={cn(pageHeaderVariants({ size }), className)}\n        {...props}\n      >\n        {breadcrumb ? (\n          <div data-slot=\"page-header-breadcrumb\" className={styles.breadcrumb}>\n            {breadcrumb}\n          </div>\n        ) : null}\n        <div\n          data-slot=\"page-header-row\"\n          data-has-leading={leading ? \"\" : undefined}\n          className={styles.row}\n        >\n          {leading ? (\n            <div data-slot=\"page-header-leading\" className={styles.leading}>\n              {leading}\n            </div>\n          ) : null}\n          <div data-slot=\"page-header-text\" className={styles.text}>\n            {eyebrow ? (\n              <div data-slot=\"page-header-eyebrow\" className={styles.eyebrow}>\n                {eyebrow}\n              </div>\n            ) : null}\n            <Title\n              data-slot=\"page-header-title\"\n              data-title-size={resolvedTitleSizeAttr}\n              data-title-family={resolvedTitleFamilyAttr}\n              className={styles.title}\n              style={titleStyle}\n            >\n              {title}\n            </Title>\n            {description ? (\n              <p\n                data-slot=\"page-header-description\"\n                className={styles.description}\n              >\n                {description}\n              </p>\n            ) : null}\n          </div>\n          {actions ? (\n            <div data-slot=\"page-header-actions\" className={styles.actions}>\n              {actions}\n            </div>\n          ) : null}\n        </div>\n      </Root>\n    )\n  }\n)\nPageHeader.displayName = \"PageHeader\"\n\nexport { PageHeader, pageHeaderVariants }\n"
+          "content": "import * as React from \"react\"\nimport { cva, type VariantProps } from \"class-variance-authority\"\nimport { cn } from \"../../../lib/utils\"\nimport styles from \"./page-header.module.css\"\n\nconst pageHeaderVariants = cva(styles.base, {\n  variants: {\n    size: {\n      sm: styles.sizeSm,\n      md: styles.sizeMd,\n      lg: styles.sizeLg,\n    },\n  },\n  defaultVariants: {\n    size: \"md\",\n  },\n})\n\ntype PageHeaderElement = \"header\" | \"section\" | \"div\"\ntype TitleElement = \"h1\" | \"h2\" | \"h3\"\n\n/** Token preset values for the `titleSize` prop. */\nconst TITLE_SIZE_TOKENS = [\"default\", \"marquee\"] as const\ntype TitleSizeToken = (typeof TITLE_SIZE_TOKENS)[number]\n\n/** Token preset values for the `titleFamily` prop. */\nconst TITLE_FAMILY_TOKENS = [\"heading\", \"display\"] as const\ntype TitleFamilyToken = (typeof TITLE_FAMILY_TOKENS)[number]\n\nfunction isTitleSizeToken(value: string): value is TitleSizeToken {\n  return (TITLE_SIZE_TOKENS as readonly string[]).includes(value)\n}\n\nfunction isTitleFamilyToken(value: string): value is TitleFamilyToken {\n  return (TITLE_FAMILY_TOKENS as readonly string[]).includes(value)\n}\n\nexport interface PageHeaderProps\n  extends Omit<React.HTMLAttributes<HTMLElement>, \"title\">,\n    VariantProps<typeof pageHeaderVariants> {\n  /** Optional small uppercase label rendered above the title. */\n  eyebrow?: React.ReactNode\n  /** Page heading content. Rendered in the element given by `titleAs`. */\n  title: React.ReactNode\n  /** Optional supporting copy rendered below the title. */\n  description?: React.ReactNode\n  /** Optional ReactNode rendered above the title row (typically a Breadcrumb). */\n  breadcrumb?: React.ReactNode\n  /**\n   * Optional media/identity node rendered to the LEFT of the title block inside\n   * the title row (typically an Avatar or identity plate). When present the row\n   * forms an identity lockup and the slot vertically centers against the\n   * title/description stack (the VI-539 top-align was superseded by the VI-545\n   * admin-editorial reconcile). Omitting it leaves the row exactly as the default\n   * text|actions layout, so existing call sites render unchanged.\n   */\n  leading?: React.ReactNode\n  /** Optional ReactNode rendered on the right side of the title row. */\n  actions?: React.ReactNode\n  /** Root element tag. Defaults to `header`. */\n  as?: PageHeaderElement\n  /** Heading level for the title. Defaults to `h1`. */\n  titleAs?: TitleElement\n  /**\n   * Title font-size override. Token presets (`\"default\" | \"marquee\"`) map to\n   * `data-title-size` attributes; any other string is forwarded as a raw CSS\n   * length on the `--page-header-title-size` custom property.\n   */\n  titleSize?: \"default\" | \"marquee\" | (string & {})\n  /**\n   * Title font-family override. Token presets (`\"heading\" | \"display\"`) map\n   * to `data-title-family` attributes; any other string is forwarded as a\n   * raw CSS family on the `--page-header-title-family` custom property.\n   */\n  titleFamily?: \"heading\" | \"display\" | (string & {})\n  /**\n   * Title line-height override. Forwarded as a raw CSS `line-height` value\n   * on the `--page-header-title-leading` custom property (a unitless number\n   * like `1.05` or any CSS length). When omitted, the title falls back to its\n   * default line-height (tight for the standard title, `1` for the marquee\n   * scale), so existing call sites render unchanged.\n   */\n  titleLeading?: string | number\n}\n\nconst PageHeader = React.forwardRef<HTMLElement, PageHeaderProps>(\n  (\n    {\n      className,\n      size,\n      eyebrow,\n      title,\n      description,\n      breadcrumb,\n      leading,\n      actions,\n      as = \"header\",\n      titleAs = \"h1\",\n      titleSize,\n      titleFamily,\n      titleLeading,\n      ...props\n    },\n    ref\n  ) => {\n    const Root = as as React.ElementType\n    const Title = titleAs as React.ElementType\n\n    const titleSizeToken =\n      typeof titleSize === \"string\" && isTitleSizeToken(titleSize)\n        ? titleSize\n        : undefined\n    const titleFamilyToken =\n      typeof titleFamily === \"string\" && isTitleFamilyToken(titleFamily)\n        ? titleFamily\n        : undefined\n\n    const rawTitleSize =\n      typeof titleSize === \"string\" && !titleSizeToken ? titleSize : undefined\n    const rawTitleFamily =\n      typeof titleFamily === \"string\" && !titleFamilyToken\n        ? titleFamily\n        : undefined\n\n    const hasTitleLeading = titleLeading !== undefined && titleLeading !== null\n\n    const titleStyle: React.CSSProperties | undefined =\n      rawTitleSize || rawTitleFamily || hasTitleLeading\n        ? {\n            ...(rawTitleSize\n              ? ({\n                  \"--page-header-title-size\": rawTitleSize,\n                } as React.CSSProperties)\n              : null),\n            ...(rawTitleFamily\n              ? ({\n                  \"--page-header-title-family\": rawTitleFamily,\n                } as React.CSSProperties)\n              : null),\n            ...(hasTitleLeading\n              ? ({\n                  \"--page-header-title-leading\": String(titleLeading),\n                } as React.CSSProperties)\n              : null),\n          }\n        : undefined\n\n    // When a raw string is supplied, switch the title into the \"marquee\" /\n    // \"display\" rules that consume the custom property so the override\n    // actually takes effect. Token values map directly to data-attributes.\n    const resolvedTitleSizeAttr =\n      titleSizeToken ?? (rawTitleSize ? \"marquee\" : undefined)\n    const resolvedTitleFamilyAttr =\n      titleFamilyToken ?? (rawTitleFamily ? \"display\" : undefined)\n\n    return (\n      <Root\n        ref={ref}\n        data-slot=\"page-header\"\n        className={cn(pageHeaderVariants({ size }), className)}\n        {...props}\n      >\n        {breadcrumb ? (\n          <div data-slot=\"page-header-breadcrumb\" className={styles.breadcrumb}>\n            {breadcrumb}\n          </div>\n        ) : null}\n        <div\n          data-slot=\"page-header-row\"\n          data-has-leading={leading ? \"\" : undefined}\n          className={styles.row}\n        >\n          {leading ? (\n            <div data-slot=\"page-header-leading\" className={styles.leading}>\n              {leading}\n            </div>\n          ) : null}\n          <div data-slot=\"page-header-text\" className={styles.text}>\n            {eyebrow ? (\n              <div data-slot=\"page-header-eyebrow\" className={styles.eyebrow}>\n                {eyebrow}\n              </div>\n            ) : null}\n            <Title\n              data-slot=\"page-header-title\"\n              data-title-size={resolvedTitleSizeAttr}\n              data-title-family={resolvedTitleFamilyAttr}\n              className={styles.title}\n              style={titleStyle}\n            >\n              {title}\n            </Title>\n            {description ? (\n              <p\n                data-slot=\"page-header-description\"\n                className={styles.description}\n              >\n                {description}\n              </p>\n            ) : null}\n          </div>\n          {actions ? (\n            <div data-slot=\"page-header-actions\" className={styles.actions}>\n              {actions}\n            </div>\n          ) : null}\n        </div>\n      </Root>\n    )\n  }\n)\nPageHeader.displayName = \"PageHeader\"\n\nexport { PageHeader, pageHeaderVariants }\n"
         },
         {
           "path": "components/ui/page-header/page-header.module.css",
@@ -4831,7 +4831,7 @@
         {
           "path": "components/visual/hero-glow/hero-glow.module.css",
           "type": "registry:ui",
-          "content": "/* HeroGlow: breathing radial glow band for hero media\n *\n * Port of bl-hero-glow (blacklight-website globals-css, BL-326).\n *\n * Color contract:\n *   Color is driven exclusively by --glow-color, which the consumer sets\n *   inline or resets every rAF frame (ex. keyed to the active artist color).\n *   No hex values are baked in. Fallback is transparent so nothing renders\n *   when the var is unset — intentional: callers must supply a color.\n *\n * Layout:\n *   position: absolute with negative inset so the glow bleeds outside the\n *   parent's box. The parent must be position: relative. pointer-events: none\n *   ensures the glow never captures clicks.\n *\n * Animation:\n *   @keyframes hero-glow-breathe: opacity 0.75 ↔ 1, scale 1 ↔ 1.03, 7s cycle.\n *   prefers-reduced-motion: animation is disabled — glow appears at rest state.\n */\n\n/* ── Keyframe ────────────────────────────────────────────────────────────── */\n\n@keyframes hero-glow-breathe {\n  0%,\n  100% {\n    opacity: 0.75;\n    transform: scale(1);\n  }\n  50% {\n    opacity: 1;\n    transform: scale(1.03);\n  }\n}\n\n/* ── Root ────────────────────────────────────────────────────────────────── */\n\n.root {\n  position: absolute;\n  inset: -6% -8% -10%;\n  pointer-events: none;\n  background: radial-gradient(\n    70% 60% at 50% 55%,\n    color-mix(in srgb, var(--glow-color, transparent) 16%, transparent),\n    transparent 72%\n  );\n  animation: hero-glow-breathe 7s ease-in-out infinite;\n}\n\n/* ── Reduced motion ─────────────────────────────────────────────────────── */\n\n@media (prefers-reduced-motion: reduce) {\n  .root {\n    animation: none;\n    opacity: 0.75;\n    transform: scale(1);\n  }\n}\n"
+          "content": "/* HeroGlow: breathing radial glow band for hero media\n *\n * Port of bl-hero-glow (blacklight-website globals-css, BL-326).\n *\n * Color contract:\n *   Color is driven exclusively by --glow-color, which the consumer sets\n *   inline or resets every rAF frame (ex. keyed to the active artist color).\n *   No hex values are baked in. Fallback is transparent so nothing renders\n *   when the var is unset — intentional: callers must supply a color.\n *\n * Layout:\n *   position: absolute with negative inset so the glow bleeds outside the\n *   parent's box. The parent must be position: relative. pointer-events: none\n *   ensures the glow never captures clicks.\n *\n * Animation:\n *   @keyframes hero-glow-breathe: opacity 0.75 ↔ 1, scale 1 ↔ 1.03, 7s cycle.\n *   prefers-reduced-motion: animation is disabled — glow rests at full opacity (1),\n *   faithful to the bl-hero-glow origin (not the keyframe's 0.75 rest value).\n */\n\n/* ── Keyframe ────────────────────────────────────────────────────────────── */\n\n@keyframes hero-glow-breathe {\n  0%,\n  100% {\n    opacity: 0.75;\n    transform: scale(1);\n  }\n  50% {\n    opacity: 1;\n    transform: scale(1.03);\n  }\n}\n\n/* ── Root ────────────────────────────────────────────────────────────────── */\n\n.root {\n  position: absolute;\n  inset: -6% -8% -10%;\n  pointer-events: none;\n  background: radial-gradient(\n    70% 60% at 50% 55%,\n    color-mix(in srgb, var(--glow-color, transparent) 16%, transparent),\n    transparent 72%\n  );\n  animation: hero-glow-breathe 7s ease-in-out infinite;\n}\n\n/* ── Reduced motion ─────────────────────────────────────────────────────── */\n\n@media (prefers-reduced-motion: reduce) {\n  .root {\n    animation: none;\n    /* Rest at full opacity, faithful to the bl-hero-glow origin (BL-326);\n       do not re-normalize to the keyframe's 0.75 rest value (VI-581). */\n    opacity: 1;\n    transform: scale(1);\n  }\n}\n"
         }
       ]
     },

package/dist/visor-manifest.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-06-25T19:22:02.080Z",
+  "generated_at": "2026-07-02T17:50:48.085Z",
   "components": {
     "accessibility-specimen": {
       "category": "specimen",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loworbitstudio/visor",
-  "version": "1.13.0",
+  "version": "1.14.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.17.0",
+    "@loworbitstudio/visor-theme-engine": "^0.17.1",
     "commander": "^13.1.0",
     "diff": "^8.0.4",
     "picocolors": "^1.1.1",