@loworbitstudio/visor 1.21.0 → 1.22.0

package/dist/CHANGELOG.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-07-21T20:04:25.720Z",
+  "generated_at": "2026-09-05T02:55:23.179Z",
   "components": {
     "accessibility-specimen": {
       "changeType": "current",

package/dist/index.js

@@ -2,7 +2,7 @@
 
 // src/index.ts
 import { readFileSync as readFileSync33 } from "fs";
-import { dirname as dirname14, join as join33 } from "path";
+import { dirname as dirname15, join as join33 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
 
@@ -1693,27 +1693,10 @@ function initCommand(cwd, options) {
     );
     process.exit(1);
   }
-  if (configExists(cwd)) {
-    filesSkipped.push("visor.json");
-    if (!json) {
-      logger.warn("visor.json already exists. Skipping config creation.");
-    }
-  } else {
-    writeConfig(cwd, DEFAULT_CONFIG);
-    filesCreated.push("visor.json");
-    if (!json) {
-      logger.success("Created visor.json");
-      logger.blank();
-      logger.info("Default paths:");
-      logger.item(`components      \u2192 ${DEFAULT_CONFIG.paths.components}`);
-      logger.item(`deck components \u2192 ${DEFAULT_CONFIG.paths.deckComponents}`);
-      logger.item(`blocks          \u2192 ${DEFAULT_CONFIG.paths.blocks}`);
-      logger.item(`hooks           \u2192 ${DEFAULT_CONFIG.paths.hooks}`);
-      logger.item(`lib             \u2192 ${DEFAULT_CONFIG.paths.lib}`);
-    }
-  }
   if (options?.template === "nextjs") {
     scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings);
+  } else {
+    writeVisorConfig(cwd, json, filesCreated, filesSkipped);
   }
   if (options?.template !== "nextjs") {
     const missingTokens = !hasVisorTokens(cwd);
@@ -1845,12 +1828,34 @@ function emitError(json, message) {
     logger.error(message);
   }
 }
+function writeVisorConfig(cwd, json, filesCreated, filesSkipped) {
+  if (configExists(cwd)) {
+    filesSkipped.push("visor.json");
+    if (!json) {
+      logger.warn("visor.json already exists. Skipping config creation.");
+    }
+    return;
+  }
+  writeConfig(cwd, DEFAULT_CONFIG);
+  filesCreated.push("visor.json");
+  if (!json) {
+    logger.success("Created visor.json");
+    logger.blank();
+    logger.info("Default paths:");
+    logger.item(`components      \u2192 ${DEFAULT_CONFIG.paths.components}`);
+    logger.item(`deck components \u2192 ${DEFAULT_CONFIG.paths.deckComponents}`);
+    logger.item(`blocks          \u2192 ${DEFAULT_CONFIG.paths.blocks}`);
+    logger.item(`hooks           \u2192 ${DEFAULT_CONFIG.paths.hooks}`);
+    logger.item(`lib             \u2192 ${DEFAULT_CONFIG.paths.lib}`);
+  }
+}
 function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   if (!json) {
     logger.blank();
     logger.info("Scaffolding a Borealis-native Next.js app...");
   }
   runCreateNextApp(cwd, json);
+  writeVisorConfig(cwd, json, filesCreated, filesSkipped);
   runInstallVisorDeps(cwd, json);
   const yamlPath = join8(cwd, ".visor.yaml");
   if (existsSync6(yamlPath)) {
@@ -7992,10 +7997,10 @@ import {
   existsSync as existsSync29,
   readFileSync as readFileSync31,
   readdirSync as readdirSync16,
-  rmSync as rmSync4
+  rmSync as rmSync4,
+  statSync as statSync11
 } from "fs";
-import { basename as basename8, isAbsolute as isAbsolute5, join as join31, resolve as resolve19 } from "path";
-import { homedir as homedir3 } from "os";
+import { basename as basename8, dirname as dirname13, isAbsolute as isAbsolute5, join as join31, resolve as resolve19 } from "path";
 import * as childProcess6 from "child_process";
 import { parse as parseYaml5 } from "yaml";
 import { generateThemeData as generateThemeData7 } from "@loworbitstudio/visor-theme-engine";
@@ -8003,7 +8008,7 @@ import { nextjsAdapter as nextjsAdapter3 } from "@loworbitstudio/visor-theme-eng
 import { validate as validate3 } from "@loworbitstudio/visor-theme-engine";
 
 // src/lib/blessed-discovery.ts
-import { existsSync as existsSync28, readdirSync as readdirSync15 } from "fs";
+import { existsSync as existsSync28, readdirSync as readdirSync15, statSync as statSync10 } from "fs";
 import { join as join30 } from "path";
 var WALK_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -8014,11 +8019,15 @@ var WALK_EXCLUDE_DIRS = /* @__PURE__ */ new Set([
   "coverage",
   ".cache"
 ]);
+var REFERENCE_BUILD_DIRNAME = "reference-build";
+var APPROVED_CAPTURES_SUBPATH = join30("captures", "approved");
+var MISSING_MANIFEST_REASON = `missing ${BLESSED_MANIFEST_FILENAME}`;
 function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
   const builds = [];
+  const incomplete = [];
   const errors = [];
   if (!existsSync28(blessedDir)) {
-    return { builds, errors };
+    return { builds, incomplete, errors };
   }
   walk2(blessedDir, 0);
   builds.sort((a, b) => {
@@ -8027,7 +8036,8 @@ function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
     }
     return a.manifest.pattern.localeCompare(b.manifest.pattern);
   });
-  return { builds, errors };
+  incomplete.sort((a, b) => a.dir.localeCompare(b.dir));
+  return { builds, incomplete, errors };
   function walk2(dir, depth) {
     if (depth > maxDepth) return;
     let entries;
@@ -8048,6 +8058,10 @@ function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
       }
       return;
     }
+    if (isNearMissRoot(dir, entries)) {
+      incomplete.push({ dir, reason: MISSING_MANIFEST_REASON });
+      return;
+    }
     for (const entry of entries) {
       if (!entry.isDirectory()) continue;
       if (WALK_EXCLUDE_DIRS.has(entry.name)) continue;
@@ -8055,6 +8069,19 @@ function discoverBlessedBuilds(blessedDir, maxDepth = 8) {
     }
   }
 }
+function isNearMissRoot(dir, entries) {
+  const hasReferenceBuild = entries.some(
+    (entry) => entry.isDirectory() && entry.name === REFERENCE_BUILD_DIRNAME
+  );
+  if (!hasReferenceBuild) return false;
+  const approved = join30(dir, APPROVED_CAPTURES_SUBPATH);
+  try {
+    if (!statSync10(approved).isDirectory()) return false;
+  } catch {
+    return false;
+  }
+  return !existsSync28(join30(dir, REFERENCE_BUILD_DIRNAME, BLESSED_MANIFEST_FILENAME));
+}
 function resolveBlessedBuild(blessedDir, shape, pattern2) {
   const { builds } = discoverBlessedBuilds(blessedDir);
   const build = builds.find(
@@ -8064,13 +8091,18 @@ function resolveBlessedBuild(blessedDir, shape, pattern2) {
 }
 
 // src/commands/spawn.ts
-var DEFAULT_BLESSED_DIR = join31(
-  homedir3(),
-  "Code",
-  "low-orbit",
-  "low-orbit-playbook",
-  "design-prototypes"
-);
+var BLESSED_ROOT_DIRNAME = "design-prototypes";
+var NO_BLESSED_ROOT_ERROR = `No blessed-build root configured. Pass --blessed-dir <path>, set VISOR_BLESSED_DIR, or run from a checkout that contains a '${BLESSED_ROOT_DIRNAME}/' directory. See docs/blessed-builds.md.`;
+function discoverBlessedRoot(cwd) {
+  let dir = resolve19(cwd);
+  for (; ; ) {
+    const candidate = join31(dir, BLESSED_ROOT_DIRNAME);
+    if (existsSync29(candidate) && statSync11(candidate).isDirectory()) return candidate;
+    const parent = dirname13(dir);
+    if (parent === dir) return void 0;
+    dir = parent;
+  }
+}
 var FORK_EXCLUDE = /* @__PURE__ */ new Set([
   "node_modules",
   ".next",
@@ -8099,8 +8131,11 @@ function parseBlessedIdentifier(from) {
   return { shape: parts[0], pattern: parts[1] };
 }
 function resolveBlessedDir(cwd, options) {
-  const raw = options.blessedDir ?? (process.env.VISOR_BLESSED_DIR && process.env.VISOR_BLESSED_DIR.length > 0 ? process.env.VISOR_BLESSED_DIR : void 0) ?? DEFAULT_BLESSED_DIR;
-  return isAbsolute5(raw) ? raw : resolve19(cwd, raw);
+  const explicit = options.blessedDir ?? (process.env.VISOR_BLESSED_DIR && process.env.VISOR_BLESSED_DIR.length > 0 ? process.env.VISOR_BLESSED_DIR : void 0);
+  if (explicit !== void 0) {
+    return isAbsolute5(explicit) ? explicit : resolve19(cwd, explicit);
+  }
+  return discoverBlessedRoot(cwd);
 }
 function resolveThemeFile(theme2, cwd, themeFile) {
   const candidates = [];
@@ -8162,6 +8197,7 @@ function runSpawn(cwd, options) {
   if (!options.output) throw new Error("Missing required --output <path>.");
   const { shape, pattern: pattern2 } = parseBlessedIdentifier(options.from);
   const blessedDir = resolveBlessedDir(cwd, options);
+  if (blessedDir === void 0) throw new Error(NO_BLESSED_ROOT_ERROR);
   const { build, available } = resolveBlessedBuild(blessedDir, shape, pattern2);
   if (!build) {
     const list = available.length > 0 ? available.map((b) => `  - blessed:${b.manifest.shape}:${b.manifest.pattern}`).join("\n") : "  (none found)";
@@ -8218,7 +8254,8 @@ ${list}`
 }
 function listBlessed(cwd, options) {
   const blessedDir = resolveBlessedDir(cwd, options);
-  const { builds, errors } = discoverBlessedBuilds(blessedDir);
+  if (blessedDir === void 0) throw new Error(NO_BLESSED_ROOT_ERROR);
+  const { builds, incomplete, errors } = discoverBlessedBuilds(blessedDir);
   if (options.json) {
     console.log(
       JSON.stringify({
@@ -8233,6 +8270,7 @@ function listBlessed(cwd, options) {
           three_gates_status: b.manifest.three_gates_status,
           dir: b.dir
         })),
+        incomplete,
         errors
       })
     );
@@ -8246,6 +8284,14 @@ function listBlessed(cwd, options) {
     logger.success(`blessed:${b.manifest.shape}:${b.manifest.pattern}`);
     logger.item(`base theme: ${b.manifest.base_theme}  \xB7  requires visor ${b.manifest.requires_visor}  \xB7  gates: ${b.manifest.three_gates_status}`);
   }
+  if (incomplete.length > 0) {
+    logger.blank();
+    logger.heading(`Near-miss builds (not spawnable) \u2014 ${incomplete.length}`);
+    for (const i of incomplete) {
+      logger.warn(i.dir);
+      logger.item(i.reason);
+    }
+  }
   for (const e of errors) {
     logger.warn(`Skipped ${e.dir}: ${e.error}`);
   }
@@ -8288,7 +8334,7 @@ function spawnCommand(cwd, options) {
 
 // src/commands/render.ts
 import { existsSync as existsSync30, mkdirSync as mkdirSync14, readFileSync as readFileSync32 } from "fs";
-import { dirname as dirname13, isAbsolute as isAbsolute6, resolve as resolve20 } from "path";
+import { dirname as dirname14, isAbsolute as isAbsolute6, resolve as resolve20 } from "path";
 var FIXTURES = {
   "stat-card": {
     default: {
@@ -8650,7 +8696,7 @@ async function renderCommand(component, cwd, options) {
   const width = Number(options.width ?? 720);
   const height = Number(options.height ?? 640);
   const outPath = resolveOutPath(cwd, options.out, component, options.theme, mode, state);
-  mkdirSync14(dirname13(outPath), { recursive: true });
+  mkdirSync14(dirname14(outPath), { recursive: true });
   const browser = await playwright.chromium.launch();
   let probe;
   try {
@@ -8762,7 +8808,7 @@ function formatBytes2(bytes) {
 }
 
 // src/index.ts
-var __dirname2 = dirname14(fileURLToPath4(import.meta.url));
+var __dirname2 = dirname15(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
   readFileSync33(join33(__dirname2, "..", "package.json"), "utf-8")
 );
@@ -8959,7 +9005,7 @@ sandbox.command("approve").description(
 );
 program.command("spawn").description(
   "Fork a Playbook blessed reference build with atomic theme re-skinning \u2014 one command replaces cp -R + npm install + theme apply"
-).option("--from <identifier>", "blessed build to spawn: blessed:{shape}:{pattern}").option("--theme <id>", "theme id (or path to a .visor.yaml) to re-skin the fork with").option("--theme-file <path>", "explicit path to a theme.visor.yaml \u2014 bypasses --theme name resolution").option("--output <path>", "destination directory for the forked project").option("--blessed-dir <path>", "override the blessed-build root (default: VISOR_BLESSED_DIR or ~/Code/low-orbit/low-orbit-playbook/design-prototypes)").option("--install", "run npm install in the forked project (default: skip)").option("--validate", "validate the applied theme after forking (default: skip)").option("--list-blessed", "list all discoverable blessed builds and exit").option("--json", "output structured JSON (for AI agents)").action((options) => {
+).option("--from <identifier>", "blessed build to spawn: blessed:{shape}:{pattern}").option("--theme <id>", "theme id (or path to a .visor.yaml) to re-skin the fork with").option("--theme-file <path>", "explicit path to a theme.visor.yaml \u2014 bypasses --theme name resolution").option("--output <path>", "destination directory for the forked project").option("--blessed-dir <path>", "override the blessed-build root (default: VISOR_BLESSED_DIR, else the nearest design-prototypes/ directory found by walking up from the cwd)").option("--install", "run npm install in the forked project (default: skip)").option("--validate", "validate the applied theme after forking (default: skip)").option("--list-blessed", "list all discoverable blessed builds and exit").option("--json", "output structured JSON (for AI agents)").action((options) => {
   spawnCommand(process.cwd(), options);
 });
 program.command("render").description(