@loworbitstudio/visor 1.16.1 → 1.18.0

package/dist/CHANGELOG.json

@@ -1,6 +1,6 @@
 {
   "version": "0.4.0",
-  "generated_at": "2026-07-07T17:14:24.752Z",
+  "generated_at": "2026-07-09T19:24:03.748Z",
   "components": {
     "accessibility-specimen": {
       "changeType": "current",
@@ -224,6 +224,18 @@
       "breakingChange": false,
       "migrationNote": null
     },
+    "doc-frame": {
+      "changeType": "current",
+      "files": [],
+      "breakingChange": false,
+      "migrationNote": null
+    },
+    "doc-nav": {
+      "changeType": "current",
+      "files": [],
+      "breakingChange": false,
+      "migrationNote": null
+    },
     "dropdown-menu": {
       "changeType": "current",
       "files": [],

package/dist/index.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import { readFileSync as readFileSync32 } from "fs";
-import { dirname as dirname12, join as join32 } from "path";
+import { readFileSync as readFileSync33 } from "fs";
+import { dirname as dirname13, join as join33 } from "path";
 import { fileURLToPath as fileURLToPath4 } from "url";
 import { Command as Command2 } from "commander";
 
@@ -35,7 +35,7 @@ function loadManifest() {
 function findItem(registry, name) {
   return registry.items.find((item) => item.name === name);
 }
-function resolveTransitiveDeps(registry, names, onWarning) {
+function resolveTransitiveDeps(registry, names, onWarning, includeSuggested = false) {
   const resolved = /* @__PURE__ */ new Map();
   const queue = names.map((n) => ({
     name: n,
@@ -49,10 +49,11 @@ function resolveTransitiveDeps(registry, names, onWarning) {
       throw new Error(`Registry item "${name}" not found.`);
     }
     resolved.set(name, item);
-    if (item.registryDependencies) {
+    const walkDeps = includeSuggested ? [...item.registryDependencies ?? [], ...item.suggestedDependencies ?? []] : item.registryDependencies;
+    if (walkDeps) {
       const childAncestors = new Set(ancestors);
       childAncestors.add(name);
-      for (const dep of item.registryDependencies) {
+      for (const dep of walkDeps) {
         if (childAncestors.has(dep)) {
           onWarning?.(`Circular registry dependency: ${name} \u2192 ${dep}`);
         } else if (!resolved.has(dep)) {
@@ -63,6 +64,17 @@ function resolveTransitiveDeps(registry, names, onWarning) {
   }
   return Array.from(resolved.values());
 }
+function collectSuggestedDeps(registry, rootNames, resolvedNames) {
+  const suggested = /* @__PURE__ */ new Set();
+  for (const name of rootNames) {
+    const item = findItem(registry, name);
+    if (!item?.suggestedDependencies) continue;
+    for (const dep of item.suggestedDependencies) {
+      if (!resolvedNames.has(dep)) suggested.add(dep);
+    }
+  }
+  return Array.from(suggested).sort();
+}
 function collectDependencies(items) {
   const deps = /* @__PURE__ */ new Set();
   const devDeps = /* @__PURE__ */ new Set();
@@ -2169,6 +2181,7 @@ function runFlutterPubGet(cwd, bin) {
 function addCommand(components, cwd, options = {}) {
   const json = options.json ?? false;
   const dryRun = options.dryRun ?? false;
+  const withSuggested = options.withSuggested ?? false;
   const target = options.target ?? "react";
   const prefix = dryRun ? "[dry-run] " : "";
   let autoInitialized = false;
@@ -2318,9 +2331,14 @@ function addCommand(components, cwd, options = {}) {
   const circularWarnings = [];
   let items;
   try {
-    items = resolveTransitiveDeps(targetRegistry, canonicalNames, (msg) => {
-      circularWarnings.push(msg);
-    });
+    items = resolveTransitiveDeps(
+      targetRegistry,
+      canonicalNames,
+      (msg) => {
+        circularWarnings.push(msg);
+      },
+      withSuggested
+    );
   } catch (error) {
     if (json) {
       const message = error instanceof Error ? error.message : String(error);
@@ -2334,6 +2352,8 @@ function addCommand(components, cwd, options = {}) {
       logger.warn(warning);
     }
   }
+  const resolvedNames = new Set(items.map((i) => i.name));
+  const suggestedAvailable = withSuggested ? [] : collectSuggestedDeps(targetRegistry, canonicalNames, resolvedNames);
   if (!json) {
     logger.info(
       `Resolving ${itemNames.length} item(s) \u2192 ${items.length} total (with dependencies)`
@@ -2501,6 +2521,7 @@ function addCommand(components, cwd, options = {}) {
           autoInitialized,
           requested: itemNames,
           resolved: items.map((i) => i.name),
+          ...suggestedAvailable.length > 0 ? { suggested: suggestedAvailable } : {},
           files: { written: writtenFiles, skipped: skippedFiles },
           dependencies: { installed: installedDeps, failed: failedDeps },
           warnings
@@ -2511,6 +2532,17 @@ function addCommand(components, cwd, options = {}) {
     );
     process.exit(failedDeps.length > 0 ? 1 : 0);
   }
+  if (suggestedAvailable.length > 0) {
+    logger.blank();
+    logger.info(
+      `Suggested slot-fill components (not installed): ${suggestedAvailable.join(", ")}`
+    );
+    logger.info(
+      `  These fill the block's slots but aren't required to render it. Add with:`
+    );
+    logger.info(`  npx visor add ${canonicalNames.join(" ")} --block --with-suggested`);
+    logger.info(`  or: npx visor add ${suggestedAvailable.join(" ")}`);
+  }
   if (failedDeps.length > 0) {
     process.exit(1);
   }
@@ -8140,10 +8172,394 @@ function spawnCommand(cwd, options) {
   }
 }
 
+// src/commands/render.ts
+import { existsSync as existsSync30, mkdirSync as mkdirSync14, readFileSync as readFileSync32 } from "fs";
+import { dirname as dirname12, isAbsolute as isAbsolute6, resolve as resolve20 } from "path";
+var FIXTURES = {
+  "stat-card": {
+    default: {
+      export: "StatCard",
+      props: `{
+        label: "Total Revenue",
+        value: "$48,120",
+        delta: { value: "+12.4%", direction: "up", label: "vs last month" },
+        footer: "Updated moments ago",
+      }`
+    }
+  },
+  "doc-nav": {
+    default: {
+      export: "DocNav",
+      interactiveTarget: '[data-slot="doc-nav-group-trigger"]',
+      props: `{
+        currentPath: "/docs/getting-started",
+        docs: [
+          { order: 0, label: "Overview", href: "/docs/overview" },
+          { order: 1, label: "Getting Started", href: "/docs/getting-started" },
+          { order: 2, label: "Installation", href: "/docs/installation" },
+          { order: 1, label: "Dashboard", href: "/docs/veronica/dashboard", scope: ["Veronica"], group: "Veronica" },
+          { order: 2, label: "Settings", href: "/docs/veronica/settings", scope: ["Veronica"], group: "Veronica" },
+          { order: 1, label: "Overview", href: "/docs/solespark/overview", scope: ["SoleSpark"], group: "SoleSpark" },
+          { order: 10, label: "Changelog", href: "/docs/changelog" },
+        ],
+      }`
+    }
+  },
+  button: {
+    default: {
+      export: "Button",
+      interactiveTarget: "button",
+      props: `{ children: "Get started" }`
+    }
+  },
+  badge: {
+    default: {
+      export: "Badge",
+      props: `{ children: "New" }`
+    }
+  }
+};
+var VALID_MODES = /* @__PURE__ */ new Set(["light", "dark"]);
+var VALID_STATES = /* @__PURE__ */ new Set(["default", "hover", "focus", "active"]);
+function missingDepsError(missing) {
+  const installArgs = missing.join(" ");
+  const needsBrowsers = missing.includes("playwright");
+  return {
+    code: "OPTIONAL_DEP_MISSING",
+    message: `\`visor render\` needs ${missing.join(" and ")}, which ${missing.length > 1 ? "are" : "is"} not installed.`,
+    hint: `Install with: npm install -D ${installArgs}${needsBrowsers ? " && npx playwright install chromium" : ""}`
+  };
+}
+function pascalCase(kebab) {
+  return kebab.split(/[-_]/).filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+function firstExisting(candidates) {
+  for (const c of candidates) {
+    if (existsSync30(c)) return c;
+  }
+  return null;
+}
+function resolveComponentFile(cwd, name) {
+  return firstExisting([
+    resolve20(cwd, "components", "ui", name, `${name}.tsx`),
+    resolve20(cwd, "components", "devtools", name, `${name}.tsx`),
+    resolve20(cwd, "components", "ui", name, "index.tsx")
+  ]);
+}
+function resolveThemeCssFile(cwd, slug2) {
+  return firstExisting([
+    resolve20(cwd, "packages", "docs", "app", `${slug2}-theme.css`),
+    resolve20(cwd, "app", `${slug2}-theme.css`),
+    resolve20(cwd, `${slug2}-theme.css`)
+  ]);
+}
+function resolveTokensCssFile(cwd) {
+  return firstExisting([
+    resolve20(cwd, "packages", "tokens", "dist", "tokens.css"),
+    resolve20(cwd, "node_modules", "@loworbitstudio", "visor-core", "dist", "tokens.css")
+  ]);
+}
+async function loadOptional(moduleName) {
+  try {
+    return await import(moduleName);
+  } catch {
+    return null;
+  }
+}
+var ANIMATION_DISABLE_CSS = "*, *::before, *::after { animation-duration: 0s !important; animation-delay: 0s !important; transition-duration: 0s !important; transition-delay: 0s !important; caret-color: transparent !important; }";
+async function settle(page, fontsTimeout = 5e3) {
+  await page.waitForLoadState("networkidle").catch(() => {
+  });
+  await page.addStyleTag({ content: ANIMATION_DISABLE_CSS });
+  await page.evaluate(
+    `new Promise(function (r) {  var t = setTimeout(r, ${fontsTimeout});  if (document.fonts && document.fonts.ready) { document.fonts.ready.then(function () { clearTimeout(t); r(); }); }  else { clearTimeout(t); r(); }})`
+  );
+}
+function buildHtml(opts) {
+  const htmlClass = opts.mode === "dark" ? "dark" : "";
+  return `<!doctype html>
+<html lang="en" class="${htmlClass}" style="color-scheme: ${opts.mode}">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<style data-visor="tokens">
+${opts.tokensCss}
+</style>
+<style data-visor="theme">
+${opts.themeCss}
+</style>
+<style data-visor="component">
+${opts.componentCss}
+</style>
+<style data-visor="harness">
+html, body { margin: 0; padding: 0; }
+#theme-scope {
+  box-sizing: border-box;
+  min-height: 100vh;
+  padding: 48px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--surface-page, #ffffff);
+  color: var(--text-primary, #111827);
+  font-family: var(--font-sans, system-ui, -apple-system, sans-serif);
+}
+#root { width: 100%; max-width: 420px; }
+</style>
+</head>
+<body>
+<div id="theme-scope" class="${opts.themeClass}">
+<div id="root"></div>
+</div>
+<script>
+${opts.bundleJs}
+</script>
+</body>
+</html>`;
+}
+function buildEntrySource(componentFile, fixture, exportName) {
+  return `import * as React from "react";
+import { createRoot } from "react-dom/client";
+import * as __mod from ${JSON.stringify(componentFile)};
+
+function __resolveComponent(mod, preferred) {
+  if (preferred && mod[preferred]) return mod[preferred];
+  if (mod.default) return mod.default;
+  var isComp = function (v) {
+    return typeof v === "function" || (v && typeof v === "object" && "$$typeof" in v);
+  };
+  for (var k in mod) { if (isComp(mod[k])) return mod[k]; }
+  throw new Error("visor render: no React component export found");
+}
+
+var __Component = __resolveComponent(__mod, ${JSON.stringify(exportName)});
+var __props = ${fixture.props};
+createRoot(document.getElementById("root")).render(
+  React.createElement(__Component, __props)
+);`;
+}
+async function renderCommand(component, cwd, options) {
+  const json = options.json ?? false;
+  const mode = (options.mode ?? "light").toLowerCase();
+  const state = (options.state ?? "default").toLowerCase();
+  const fail3 = (code, message, extra) => {
+    if (json) {
+      console.log(JSON.stringify({ success: false, error: { code, message }, ...extra }, null, 2));
+    } else {
+      logger.error(message);
+      if (extra?.hint) logger.item(String(extra.hint));
+    }
+    process.exit(1);
+  };
+  if (!VALID_MODES.has(mode)) {
+    fail3("BAD_MODE", `Invalid --mode "${mode}". Use "light" or "dark".`);
+  }
+  if (!VALID_STATES.has(state)) {
+    fail3("BAD_STATE", `Invalid --state "${state}". Use one of: ${[...VALID_STATES].join(", ")}.`);
+  }
+  const componentFile = resolveComponentFile(cwd, component);
+  if (!componentFile) {
+    fail3(
+      "COMPONENT_NOT_FOUND",
+      `Component "${component}" not found under components/ui/. Expected components/ui/${component}/${component}.tsx.`
+    );
+  }
+  const themeCssFile = resolveThemeCssFile(cwd, options.theme);
+  if (!themeCssFile) {
+    fail3(
+      "THEME_NOT_FOUND",
+      `Theme "${options.theme}" not found. Expected packages/docs/app/${options.theme}-theme.css.`,
+      { hint: "Run `visor theme sync` to (re)generate theme CSS, or check the slug." }
+    );
+  }
+  const tokensCssFile = resolveTokensCssFile(cwd);
+  if (!tokensCssFile) {
+    fail3(
+      "TOKENS_NOT_FOUND",
+      "Emitted tokens.css not found. Expected packages/tokens/dist/tokens.css.",
+      { hint: "Run `npm run build -w packages/tokens` first." }
+    );
+  }
+  const fixtureName = options.fixture ?? "default";
+  const componentFixtures = FIXTURES[component];
+  const fixture = componentFixtures?.[fixtureName] ?? { props: "{}" };
+  if (options.fixture && !componentFixtures?.[fixtureName]) {
+    fail3(
+      "FIXTURE_NOT_FOUND",
+      `Fixture "${fixtureName}" not registered for "${component}". Available: ${componentFixtures ? Object.keys(componentFixtures).join(", ") : "(none)"}.`
+    );
+  }
+  if (!componentFixtures && !json) {
+    logger.warn(
+      `No fixture registered for "${component}" \u2014 rendering with empty props. Add one to FIXTURES in render.ts for representative content.`
+    );
+  }
+  const exportName = fixture.export ?? pascalCase(component);
+  const esbuild = await loadOptional("esbuild");
+  const playwright = await loadOptional("playwright");
+  const missing = [];
+  if (!esbuild) missing.push("esbuild");
+  if (!playwright) missing.push("playwright");
+  if (missing.length > 0) {
+    const dep = missingDepsError(missing);
+    fail3(dep.code, dep.message, { missing, hint: dep.hint });
+  }
+  let componentCss = "";
+  let bundleJs = "";
+  try {
+    const entrySource = buildEntrySource(componentFile, fixture, exportName);
+    const result = await esbuild.build({
+      stdin: {
+        contents: entrySource,
+        resolveDir: cwd,
+        loader: "tsx",
+        sourcefile: "visor-render-entry.tsx"
+      },
+      bundle: true,
+      format: "iife",
+      platform: "browser",
+      jsx: "automatic",
+      write: false,
+      outdir: "visor-render-out",
+      define: { "process.env.NODE_ENV": '"production"' },
+      banner: { js: "globalThis.process = globalThis.process || { env: {} };" },
+      logLevel: "silent"
+    });
+    for (const file of result.outputFiles ?? []) {
+      if (file.path.endsWith(".css")) componentCss += file.text;
+      else if (file.path.endsWith(".js")) bundleJs += file.text;
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    fail3("BUNDLE_FAILED", `Failed to bundle ${component}: ${message}`);
+  }
+  const themeClass = `${options.theme}-theme`;
+  const html = buildHtml({
+    tokensCss: readFileSync32(tokensCssFile, "utf-8"),
+    themeCss: readFileSync32(themeCssFile, "utf-8"),
+    componentCss,
+    bundleJs,
+    themeClass,
+    mode
+  });
+  const width = Number(options.width ?? 720);
+  const height = Number(options.height ?? 640);
+  const outPath = resolveOutPath(cwd, options.out, component, options.theme, mode, state);
+  mkdirSync14(dirname12(outPath), { recursive: true });
+  const browser = await playwright.chromium.launch();
+  let probe;
+  try {
+    const context = await browser.newContext({
+      viewport: { width, height },
+      colorScheme: mode,
+      deviceScaleFactor: 2
+    });
+    const page = await context.newPage();
+    await page.setContent(html, { waitUntil: "load" });
+    await page.waitForFunction(
+      "document.getElementById('root') && document.getElementById('root').childElementCount > 0",
+      void 0,
+      { timeout: 1e4 }
+    ).catch(() => {
+    });
+    await settle(page);
+    probe = await page.evaluate(
+      `(function () {
+        var scope = document.getElementById("theme-scope");
+        var html = document.documentElement;
+        var read = function (el, prop) {
+          return getComputedStyle(el).getPropertyValue(prop).trim();
+        };
+        var themed = read(scope, "--surface-card");
+        var base = read(html, "--surface-card");
+        return {
+          themedSurfaceCard: themed,
+          baseSurfaceCard: base,
+          themedBg: getComputedStyle(scope).backgroundColor,
+          mapped: themed !== "" && themed !== base,
+        };
+      })()`
+    );
+    if (state !== "default") {
+      const target = fixture.interactiveTarget ?? "#root button, #root a, #root input, #root [tabindex]";
+      const el = await page.$(target);
+      if (el) {
+        if (state === "hover") await el.hover();
+        else if (state === "focus") await el.focus();
+        else if (state === "active") {
+          await el.hover();
+          await page.mouse.down();
+        }
+        await page.waitForTimeout(80);
+      } else if (!json) {
+        logger.warn(`No interactive target ("${target}") found for state "${state}".`);
+      }
+    }
+    await page.screenshot({ path: outPath, fullPage: true });
+    if (state === "active") await page.mouse.up().catch(() => {
+    });
+  } finally {
+    await browser.close();
+  }
+  const fileSize = existsSync30(outPath) ? statBytes(outPath) : 0;
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          component,
+          theme: options.theme,
+          mode,
+          state,
+          fixture: fixtureName,
+          out: outPath,
+          bytes: fileSize,
+          probe
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  logger.success(`Rendered ${component} \xB7 ${options.theme} \xB7 ${mode}${state !== "default" ? ` \xB7 ${state}` : ""}`);
+  logger.item(`\u2192 ${outPath} (${formatBytes2(fileSize)})`);
+  logger.blank();
+  if (probe.mapped) {
+    logger.success(
+      `Themed --surface-card resolved to ${probe.themedSurfaceCard} (base primitive: ${probe.baseSurfaceCard}) \u2014 theme mapping applied.`
+    );
+  } else {
+    logger.warn(
+      `Themed --surface-card (${probe.themedSurfaceCard}) equals the base primitive (${probe.baseSurfaceCard}). The theme override did not apply \u2014 check @layer/mode scoping (VI-511).`
+    );
+  }
+}
+function resolveOutPath(cwd, out, component, theme2, mode, state) {
+  if (out) {
+    return isAbsolute6(out) ? out : resolve20(cwd, out);
+  }
+  const suffix = state === "default" ? "" : `__${state}`;
+  return resolve20(cwd, ".visor", "renders", `${component}__${theme2}__${mode}${suffix}.png`);
+}
+function statBytes(path2) {
+  try {
+    return readFileSync32(path2).length;
+  } catch {
+    return 0;
+  }
+}
+function formatBytes2(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb.toFixed(1)} KB`;
+  return `${(kb / 1024).toFixed(1)} MB`;
+}
+
 // src/index.ts
-var __dirname2 = dirname12(fileURLToPath4(import.meta.url));
+var __dirname2 = dirname13(fileURLToPath4(import.meta.url));
 var pkg = JSON.parse(
-  readFileSync32(join32(__dirname2, "..", "package.json"), "utf-8")
+  readFileSync33(join33(__dirname2, "..", "package.json"), "utf-8")
 );
 var program = new Command2();
 program.name("visor").description("CLI for the Visor design system").version(pkg.version);
@@ -8154,9 +8570,9 @@ program.command("init").description("Initialize Visor \u2014 with --template nex
 program.command("list").description("List all available registry items").option("--json", "output structured JSON (for AI agents)").option("--category <name>", "filter items by category").action((options) => {
   listCommand(process.cwd(), options);
 });
-program.command("add").description("Add components, hooks, blocks, or utilities to your project").argument("[items...]", "names of registry items to add").option("--overwrite", "overwrite existing files", false).option("--category <name>", "install all items from a category").option("--block", "install blocks instead of components").option("--target <platform>", "target platform: react (default) or flutter", "react").option("--dry-run", "preview what would be added without writing files").option("--json", "output structured JSON (for AI agents)").action((items, options) => {
+program.command("add").description("Add components, hooks, blocks, or utilities to your project").argument("[items...]", "names of registry items to add").option("--overwrite", "overwrite existing files", false).option("--category <name>", "install all items from a category").option("--block", "install blocks instead of components").option("--with-suggested", "also install a block's suggested slot-fill components (e.g. breadcrumb, dropdown-menu, sidebar for admin-shell)").option("--target <platform>", "target platform: react (default) or flutter", "react").option("--dry-run", "preview what would be added without writing files").option("--json", "output structured JSON (for AI agents)").action((items, options) => {
   const target = options.target === "flutter" ? "flutter" : "react";
-  addCommand(items, process.cwd(), { overwrite: options.overwrite, category: options.category, block: options.block, target, dryRun: options.dryRun, json: options.json });
+  addCommand(items, process.cwd(), { overwrite: options.overwrite, category: options.category, block: options.block, withSuggested: options.withSuggested, target, dryRun: options.dryRun, json: options.json });
 });
 program.command("diff").description(
   "Show differences between local files and the registry"
@@ -8341,4 +8757,9 @@ program.command("spawn").description(
 ).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) => {
   spawnCommand(process.cwd(), options);
 });
+program.command("render").description(
+  "Render a single component to a PNG using the real emitted tokens + real theme CSS + the real component (serverless, no next dev). A per-component render-fidelity harness."
+).argument("<component>", "component name under components/ui/ (e.g. doc-nav, stat-card)").requiredOption("--theme <slug>", "theme slug (e.g. space, neutral) \u2014 resolves packages/docs/app/<slug>-theme.css").option("--mode <mode>", "color mode: light or dark", "light").option("--state <state>", "interactive state to capture: default, hover, focus, active", "default").option("--fixture <name>", "named fixture for the component (default: 'default')").option("-o, --out <path>", "output PNG path (default: .visor/renders/<component>__<theme>__<mode>.png)").option("--width <px>", "viewport width in px", "720").option("--height <px>", "viewport height in px", "640").option("--json", "output structured JSON (for AI agents)").action(async (component, options) => {
+  await renderCommand(component, process.cwd(), options);
+});
 program.parse();