@loworbitstudio/visor 0.1.0 → 0.5.0

package/dist/index.js

@@ -1,21 +1,569 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { Command as Command2 } from "commander";
+
+// src/commands/check.ts
 import { Command } from "commander";
 
+// src/registry/resolve.ts
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __dirname = dirname(fileURLToPath(import.meta.url));
+var cachedRegistry = null;
+var cachedManifest = null;
+function loadRegistry() {
+  if (cachedRegistry) return cachedRegistry;
+  const registryPath = join(__dirname, "registry.json");
+  const raw = readFileSync(registryPath, "utf-8");
+  cachedRegistry = JSON.parse(raw);
+  return cachedRegistry;
+}
+function loadManifest() {
+  if (cachedManifest) return cachedManifest;
+  const manifestPath = join(__dirname, "visor-manifest.json");
+  const raw = readFileSync(manifestPath, "utf-8");
+  cachedManifest = JSON.parse(raw);
+  return cachedManifest;
+}
+function findItem(registry, name) {
+  return registry.items.find((item) => item.name === name);
+}
+function resolveTransitiveDeps(registry, names, onWarning) {
+  const resolved = /* @__PURE__ */ new Map();
+  const queue = names.map((n) => ({
+    name: n,
+    ancestors: /* @__PURE__ */ new Set()
+  }));
+  while (queue.length > 0) {
+    const { name, ancestors } = queue.shift();
+    if (resolved.has(name)) continue;
+    const item = findItem(registry, name);
+    if (!item) {
+      throw new Error(`Registry item "${name}" not found.`);
+    }
+    resolved.set(name, item);
+    if (item.registryDependencies) {
+      const childAncestors = new Set(ancestors);
+      childAncestors.add(name);
+      for (const dep of item.registryDependencies) {
+        if (childAncestors.has(dep)) {
+          onWarning?.(`Circular registry dependency: ${name} \u2192 ${dep}`);
+        } else if (!resolved.has(dep)) {
+          queue.push({ name: dep, ancestors: childAncestors });
+        }
+      }
+    }
+  }
+  return Array.from(resolved.values());
+}
+function collectDependencies(items) {
+  const deps = /* @__PURE__ */ new Set();
+  const devDeps = /* @__PURE__ */ new Set();
+  const pubDeps = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    if (item.dependencies) {
+      for (const dep of item.dependencies) {
+        deps.add(dep);
+      }
+    }
+    if (item.devDependencies) {
+      for (const dep of item.devDependencies) {
+        devDeps.add(dep);
+      }
+    }
+    if (item.pubDependencies) {
+      for (const dep of item.pubDependencies) {
+        pubDeps.set(dep.pub, dep);
+      }
+    }
+  }
+  return {
+    dependencies: Array.from(deps).sort(),
+    devDependencies: Array.from(devDeps).sort(),
+    pubDependencies: Array.from(pubDeps.values()).sort(
+      (a, b) => a.pub.localeCompare(b.pub)
+    )
+  };
+}
+function filterItemsByTarget(items, target) {
+  return items.filter(
+    (item) => item.target === target || item.target === void 0
+  );
+}
+function slug(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function findItemForTarget(registry, name, target) {
+  const needle = slug(name);
+  return registry.items.find(
+    (item) => slug(item.name) === needle && item.target === target
+  ) ?? registry.items.find(
+    (item) => slug(item.name) === needle && item.target === void 0
+  );
+}
+
+// src/check/catalog.ts
+var STOP_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "with",
+  "for",
+  "and",
+  "or",
+  "to",
+  "in",
+  "of",
+  "is",
+  "that",
+  "this",
+  "it",
+  "as",
+  "at",
+  "by",
+  "on",
+  "be",
+  "are",
+  "was",
+  "were"
+]);
+function toKebab(s) {
+  return s.replace(/([A-Z])/g, (m) => `-${m.toLowerCase()}`).replace(/^-/, "").toLowerCase();
+}
+function tokenize(text) {
+  return text.toLowerCase().split(/[\s\-_,]+/).filter((t) => t.length > 1 && !STOP_WORDS.has(t));
+}
+function installCmd(name, type) {
+  if (type === "block") return `npx visor add ${name} --block`;
+  if (type === "pattern") return null;
+  return `npx visor add ${name}`;
+}
+function getAllCatalogItems(manifest) {
+  const items = [];
+  for (const [name, c] of Object.entries(manifest.components)) {
+    items.push({ type: "component", name, category: c.category, description: c.description });
+    for (const sub of c.sub_components ?? []) {
+      items.push({ type: "component", name: toKebab(sub.name), category: c.category, description: sub.description });
+    }
+  }
+  for (const [name, b] of Object.entries(manifest.blocks)) {
+    items.push({ type: "block", name, category: b.category, description: b.description });
+  }
+  for (const [name, h] of Object.entries(manifest.hooks)) {
+    items.push({ type: "hook", name, description: h.description });
+  }
+  for (const [name, p] of Object.entries(manifest.patterns)) {
+    items.push({ type: "pattern", name, description: p.description });
+  }
+  return items;
+}
+function findByName(manifest, pattern2) {
+  const normalized = toKebab(pattern2);
+  if (normalized in manifest.components) {
+    const c = manifest.components[normalized];
+    return { found: true, name: normalized, type: "component", category: c.category, description: c.description, installCmd: `npx visor add ${normalized}` };
+  }
+  if (normalized in manifest.blocks) {
+    const b = manifest.blocks[normalized];
+    return { found: true, name: normalized, type: "block", category: b.category, description: b.description, installCmd: `npx visor add ${normalized} --block` };
+  }
+  if (normalized in manifest.hooks) {
+    const h = manifest.hooks[normalized];
+    return { found: true, name: normalized, type: "hook", description: h.description, installCmd: `npx visor add ${normalized}` };
+  }
+  if (normalized in manifest.patterns) {
+    const p = manifest.patterns[normalized];
+    return { found: true, name: normalized, type: "pattern", description: p.description, installCmd: null };
+  }
+  for (const [parentName, c] of Object.entries(manifest.components)) {
+    for (const sub of c.sub_components ?? []) {
+      if (toKebab(sub.name) === normalized) {
+        return { found: true, name: toKebab(sub.name), type: "component", category: c.category, description: sub.description, installCmd: `npx visor add ${parentName}` };
+      }
+    }
+  }
+  return { found: false };
+}
+function fuzzyFind(manifest, query, limit = 5) {
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+  const results = [];
+  for (const item of getAllCatalogItems(manifest)) {
+    const searchText = [item.name, item.description].join(" ").toLowerCase();
+    const matched = queryTokens.filter((t) => searchText.includes(t));
+    if (matched.length > 0) {
+      results.push({
+        name: item.name,
+        type: item.type,
+        category: item.category,
+        description: item.description,
+        score: matched.length,
+        matchReason: `Matched: ${matched.join(", ")}`,
+        installCmd: installCmd(item.name, item.type)
+      });
+    }
+  }
+  return results.sort((a, b) => b.score - a.score).slice(0, limit);
+}
+
+// src/check/jsx-scan.ts
+import { readFileSync as readFileSync2, readdirSync, statSync } from "fs";
+import { resolve, extname, join as join2 } from "path";
+
+// src/check/native-map.ts
+var NATIVE_TO_VISOR = {
+  button: { visorName: "button", displayName: "Button" },
+  textarea: { visorName: "textarea", displayName: "Textarea" },
+  form: { visorName: "form", displayName: "Form" },
+  label: { visorName: "label", displayName: "Label" },
+  fieldset: { visorName: "fieldset", displayName: "Fieldset" },
+  select: { visorName: "select", displayName: "Select" },
+  table: { visorName: "table", displayName: "Table", notes: "use DataTable for full interactive features" },
+  img: { visorName: "image", displayName: "Image" },
+  dialog: { visorName: "dialog", displayName: "Dialog" },
+  details: { visorName: "accordion", displayName: "Accordion", notes: "or Collapsible for a single section" },
+  summary: { visorName: "accordion", displayName: "Accordion", notes: "wrap as Accordion trigger" }
+};
+var INPUT_TYPE_MAP = {
+  number: { visorName: "number-input", displayName: "NumberInput" },
+  password: { visorName: "password-input", displayName: "PasswordInput" },
+  search: { visorName: "search-input", displayName: "SearchInput" },
+  tel: { visorName: "phone-input", displayName: "PhoneInput" },
+  phone: { visorName: "phone-input", displayName: "PhoneInput" },
+  // All other input types (text, email, url, date, etc.) map to the base Input.
+  _default: { visorName: "input", displayName: "Input" }
+};
+
+// src/check/jsx-scan.ts
+async function getBabelParser() {
+  const { parse } = await import("@babel/parser");
+  return parse;
+}
+function walk(node, visit) {
+  if (!node || typeof node !== "object") return;
+  const obj = node;
+  visit(obj);
+  for (const key of Object.keys(obj)) {
+    if (key === "parent" || key === "tokens" || key === "errors") continue;
+    const val = obj[key];
+    if (Array.isArray(val)) {
+      for (const child of val) walk(child, visit);
+    } else if (val && typeof val === "object" && "type" in val) {
+      walk(val, visit);
+    }
+  }
+}
+function getInputType(attribs) {
+  for (const attr of attribs) {
+    const a = attr;
+    if (a.type !== "JSXAttribute") continue;
+    const nameNode = a.name;
+    if (nameNode?.name !== "type") continue;
+    const valueNode = a.value;
+    if (!valueNode) continue;
+    if (valueNode.type === "StringLiteral") {
+      return String(valueNode.value ?? "text");
+    }
+    if (valueNode.type === "JSXExpressionContainer") {
+      const expr = valueNode.expression;
+      if (expr?.type === "StringLiteral") return String(expr.value ?? "text");
+    }
+  }
+  return "_default";
+}
+function collectJsxFindings(source, filePath, parse) {
+  let ast;
+  try {
+    ast = parse(source, {
+      sourceType: "module",
+      plugins: ["jsx", "typescript"],
+      errorRecovery: true
+    });
+  } catch {
+    return [];
+  }
+  const findings = [];
+  walk(ast, (node) => {
+    if (node.type !== "JSXOpeningElement") return;
+    const nameNode = node.name;
+    if (!nameNode) return;
+    const tagName = nameNode.type === "JSXIdentifier" ? String(nameNode.name ?? "") : "";
+    if (!tagName || tagName[0] !== tagName[0].toLowerCase()) return;
+    const loc = node.loc;
+    const line = loc?.start?.line ?? 0;
+    const column = loc?.start?.column ?? 0;
+    if (tagName === "input") {
+      const attribs = node.attributes ?? [];
+      const typeVal = getInputType(attribs);
+      const mapping2 = INPUT_TYPE_MAP[typeVal] ?? INPUT_TYPE_MAP["_default"];
+      findings.push({
+        file: filePath,
+        line,
+        column,
+        nativeTag: typeVal !== "_default" ? `input[type=${typeVal}]` : "input",
+        suggestedPrimitive: mapping2.displayName,
+        installCmd: `npx visor add ${mapping2.visorName}`
+      });
+      return;
+    }
+    const mapping = NATIVE_TO_VISOR[tagName];
+    if (!mapping) return;
+    const finding = {
+      file: filePath,
+      line,
+      column,
+      nativeTag: tagName,
+      suggestedPrimitive: mapping.displayName,
+      installCmd: `npx visor add ${mapping.visorName}`
+    };
+    if (mapping.notes) finding.rationale = mapping.notes;
+    findings.push(finding);
+  });
+  return findings;
+}
+function collectFiles(pathArg) {
+  const JSX_EXTS = /* @__PURE__ */ new Set([".jsx", ".tsx", ".js", ".ts"]);
+  try {
+    const s = statSync(pathArg);
+    if (s.isDirectory()) {
+      let recurse2 = function(dir) {
+        for (const entry of readdirSync(dir)) {
+          if (entry.startsWith(".") || entry === "node_modules") continue;
+          const full = join2(dir, entry);
+          const es = statSync(full);
+          if (es.isDirectory()) recurse2(full);
+          else if (JSX_EXTS.has(extname(full))) files.push(full);
+        }
+      };
+      var recurse = recurse2;
+      const files = [];
+      recurse2(pathArg);
+      return files;
+    }
+    if (JSX_EXTS.has(extname(pathArg))) return [pathArg];
+  } catch {
+  }
+  return [];
+}
+async function scanJsx(pathArg) {
+  const parse = await getBabelParser();
+  let files;
+  let stdinMode = false;
+  if (pathArg === "-") {
+    stdinMode = true;
+    files = ["<stdin>"];
+  } else {
+    files = collectFiles(resolve(pathArg));
+  }
+  const allFindings = [];
+  for (const file of files) {
+    let source;
+    if (stdinMode) {
+      source = readFileSync2(0, "utf-8");
+    } else {
+      try {
+        source = readFileSync2(file, "utf-8");
+      } catch {
+        continue;
+      }
+    }
+    allFindings.push(...collectJsxFindings(source, stdinMode ? "<stdin>" : file, parse));
+  }
+  return {
+    findings: allFindings,
+    summary: { scanned: files.length, hits: allFindings.length }
+  };
+}
+
+// src/utils/logger.ts
+import pc from "picocolors";
+var logger = {
+  info(message) {
+    console.log(message);
+  },
+  success(message) {
+    console.log(pc.green(`\u2713 ${message}`));
+  },
+  warn(message) {
+    console.log(pc.yellow(`\u26A0 ${message}`));
+  },
+  error(message) {
+    console.error(pc.red(`\u2717 ${message}`));
+  },
+  item(message) {
+    console.log(pc.dim(`  ${message}`));
+  },
+  heading(message) {
+    console.log(pc.bold(message));
+  },
+  blank() {
+    console.log();
+  }
+};
+
+// src/commands/check.ts
+var TYPE_FILTER = {
+  ui: "component",
+  blocks: "block",
+  hooks: "hook",
+  patterns: "pattern"
+};
+function checkListCommand(options) {
+  const manifest = loadManifest();
+  let items = getAllCatalogItems(manifest);
+  if (options.type && options.type !== "all") {
+    const filterType = TYPE_FILTER[options.type];
+    items = items.filter((i) => i.type === filterType);
+  }
+  const byType = {};
+  for (const item of items) {
+    byType[item.type] = (byType[item.type] ?? 0) + 1;
+  }
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          items: items.map((i) => ({ type: i.type, name: i.name, category: i.category ?? null, description: i.description })),
+          summary: { total: items.length, byType }
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const key = item.type;
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(item);
+  }
+  for (const [type, group] of groups) {
+    logger.heading(`${type}s (${group.length})`);
+    logger.blank();
+    for (const item of group) {
+      logger.info(`  ${item.name.padEnd(28)} ${item.description}`);
+    }
+    logger.blank();
+  }
+}
+function checkHasCommand(pattern2, options) {
+  const manifest = loadManifest();
+  if (options.fuzzy) {
+    const results = fuzzyFind(manifest, pattern2, 5);
+    if (results.length === 0) {
+      if (options.json) {
+        console.log(JSON.stringify({ success: false, found: false, query: pattern2, results: [] }, null, 2));
+      } else {
+        logger.warn(`No fuzzy matches for "${pattern2}"`);
+      }
+      process.exit(1);
+      return;
+    }
+    if (options.json) {
+      console.log(JSON.stringify({ success: true, found: true, query: pattern2, results }, null, 2));
+      process.exit(0);
+      return;
+    }
+    logger.heading(`Fuzzy matches for "${pattern2}":`);
+    logger.blank();
+    for (const r of results) {
+      const cmd2 = r.installCmd ? ` \u2014 ${r.installCmd}` : "";
+      logger.info(`  ${r.name} [${r.type}]${cmd2}`);
+      logger.info(`    ${r.description.slice(0, 80)}`);
+    }
+    return;
+  }
+  const result = findByName(manifest, pattern2);
+  if (!result.found) {
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, found: false, query: pattern2 }, null, 2));
+    } else {
+      logger.warn(`"${pattern2}" not found in Visor catalog. Try --fuzzy for partial matches.`);
+    }
+    process.exit(1);
+    return;
+  }
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          found: true,
+          name: result.name,
+          type: result.type,
+          category: result.category ?? null,
+          description: result.description,
+          installCmd: result.installCmd
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  const cmd = result.installCmd ? ` \u2014 ${result.installCmd}` : "";
+  logger.success(`${result.name} [${result.type}]${cmd}`);
+  logger.info(`  ${result.description}`);
+}
+async function checkDiffCommand(pathArg, options) {
+  const result = await scanJsx(pathArg);
+  if (options.json) {
+    console.log(JSON.stringify({ success: true, ...result }, null, 2));
+    if (options.failOnHits && result.summary.hits > 0) process.exit(1);
+    process.exit(0);
+    return;
+  }
+  if (result.summary.hits === 0) {
+    logger.success(`No native HTML primitives found \u2014 ${result.summary.scanned} file(s) scanned.`);
+    return;
+  }
+  logger.heading(`Found ${result.summary.hits} native HTML usage(s) in ${result.summary.scanned} file(s):
+`);
+  for (const f of result.findings) {
+    const loc = `${f.file}:${f.line}:${f.column}`;
+    const note = f.rationale ? ` (${f.rationale})` : "";
+    logger.warn(`  <${f.nativeTag}> \u2192 use <${f.suggestedPrimitive}>${note}`);
+    logger.item(`  ${loc}  ${f.installCmd}`);
+  }
+  logger.blank();
+  if (options.failOnHits) 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) => {
+    checkListCommand(options);
+  });
+  check.command("has").description("Check whether a component, block, hook, or pattern exists in the Visor catalog").argument("<pattern>", "component name (kebab-case or PascalCase)").option("--fuzzy", "run fuzzy match and return top 5 results").option("--json", "output structured JSON (for AI agents)").action((pattern2, options) => {
+    checkHasCommand(pattern2, options);
+  });
+  check.command("diff").description("Scan JSX/TSX for native HTML elements that have Visor equivalents").argument("<path>", "file path, directory, or - for stdin").option("--fail-on-hits", "exit 1 if any native HTML usages are found (for CI use)").option("--json", "output structured JSON (for AI agents)").action(async (pathArg, options) => {
+    await checkDiffCommand(pathArg, options);
+  });
+  return check;
+}
+
 // src/commands/init.ts
-import { existsSync as existsSync3, writeFileSync as writeFileSync2, mkdirSync } from "fs";
-import { join as join3, dirname } from "path";
+import { existsSync as existsSync3, writeFileSync as writeFileSync2, mkdirSync, readFileSync as readFileSync5 } from "fs";
+import { join as join5, dirname as dirname2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import * as childProcess from "child_process";
 
 // src/config/config.ts
-import { readFileSync, writeFileSync, existsSync } from "fs";
-import { join } from "path";
+import { readFileSync as readFileSync3, writeFileSync, existsSync } from "fs";
+import { join as join3 } from "path";
 
 // src/config/defaults.ts
 var DEFAULT_CONFIG = {
   paths: {
     components: "components/ui",
     deckComponents: "components/deck",
+    flutterComponents: "lib/visor/components",
     blocks: "blocks",
     hooks: "hooks",
     lib: "lib"
@@ -25,7 +573,7 @@ var CONFIG_FILE = "visor.json";
 
 // src/config/config.ts
 function getConfigPath(cwd) {
-  return join(cwd, CONFIG_FILE);
+  return join3(cwd, CONFIG_FILE);
 }
 function configExists(cwd) {
   return existsSync(getConfigPath(cwd));
@@ -37,8 +585,29 @@ function loadConfig(cwd) {
       `No ${CONFIG_FILE} found. Run "visor init" first.`
     );
   }
-  const raw = readFileSync(configPath, "utf-8");
+  const raw = readFileSync3(configPath, "utf-8");
   const parsed = JSON.parse(raw);
+  const knownKeys = /* @__PURE__ */ new Set(["paths"]);
+  for (const key of Object.keys(parsed)) {
+    if (!knownKeys.has(key)) {
+      console.warn(`Warning: unknown key "${key}" in visor.json`);
+    }
+  }
+  if (parsed.paths !== void 0) {
+    if (typeof parsed.paths !== "object" || parsed.paths === null || Array.isArray(parsed.paths)) {
+      throw new Error(
+        `Invalid visor.json: paths must be an object, got ${Array.isArray(parsed.paths) ? "array" : typeof parsed.paths}`
+      );
+    }
+    const paths = parsed.paths;
+    for (const [key, value] of Object.entries(paths)) {
+      if (typeof value !== "string") {
+        throw new Error(
+          `Invalid visor.json: paths.${key} must be a string, got ${typeof value}`
+        );
+      }
+    }
+  }
   return {
     paths: {
       ...DEFAULT_CONFIG.paths,
@@ -53,12 +622,12 @@ function writeConfig(cwd, config) {
 
 // src/utils/packages.ts
 import { execFileSync } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { join as join2 } from "path";
+import { existsSync as existsSync2, readFileSync as readFileSync4 } from "fs";
+import { join as join4 } from "path";
 function readPackageJson(cwd) {
-  const pkgPath = join2(cwd, "package.json");
+  const pkgPath = join4(cwd, "package.json");
   if (!existsSync2(pkgPath)) return null;
-  return JSON.parse(readFileSync2(pkgPath, "utf-8"));
+  return JSON.parse(readFileSync4(pkgPath, "utf-8"));
 }
 function isPackageInstalled(packageName, cwd) {
   const pkg = readPackageJson(cwd);
@@ -82,38 +651,46 @@ function installPackages(packages, cwd, dev = false) {
   }
 }
 
-// src/utils/logger.ts
-import pc from "picocolors";
-var logger = {
-  info(message) {
-    console.log(message);
-  },
-  success(message) {
-    console.log(pc.green(`\u2713 ${message}`));
-  },
-  warn(message) {
-    console.log(pc.yellow(`\u26A0 ${message}`));
-  },
-  error(message) {
-    console.error(pc.red(`\u2717 ${message}`));
-  },
-  item(message) {
-    console.log(pc.dim(`  ${message}`));
-  },
-  heading(message) {
-    console.log(pc.bold(message));
-  },
-  blank() {
-    console.log();
-  }
-};
-
 // src/commands/templates/nextjs.ts
+var NEXTJS_PINNED_VERSION = "15.1.6";
+var CREATE_NEXT_APP_FLAGS = [
+  "--ts",
+  "--app",
+  "--no-tailwind",
+  "--no-eslint",
+  "--no-src-dir",
+  "--import-alias",
+  "@/*",
+  "--use-npm"
+];
 var NEXTJS_STARTER_YAML = `name: my-app
 version: 1
 colors:
   primary: "#2563EB"
 `;
+function generateNextjsLayout() {
+  return `import "./globals.css";
+import { FOWT_SCRIPT } from "@loworbitstudio/visor-theme-engine/fowt";
+import type { Metadata } from "next";
+import type { ReactNode } from "react";
+
+export const metadata: Metadata = {
+  title: "My Visor App",
+  description: "Built with Visor \u2014 Low Orbit Studio's design system.",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <script>{FOWT_SCRIPT}</script>
+      </head>
+      <body>{children}</body>
+    </html>
+  );
+}
+`;
+}
 
 // src/commands/init.ts
 import { generateThemeData } from "@loworbitstudio/visor-theme-engine";
@@ -124,18 +701,14 @@ function initCommand(cwd, options) {
   const filesSkipped = [];
   const warnings = [];
   if (options?.template && options.template !== "nextjs") {
-    if (json) {
-      console.log(
-        JSON.stringify(
-          { success: false, error: `Unknown template: ${options.template}. Available templates: nextjs` },
-          null,
-          2
-        )
-      );
-    } else {
-      logger.error(`Unknown template: ${options.template}`);
-      logger.info("Available templates: nextjs");
-    }
+    emitError(json, `Unknown template: ${options.template}. Available templates: nextjs`);
+    process.exit(1);
+  }
+  if (options?.template === "nextjs" && existsSync3(join5(cwd, "package.json"))) {
+    emitError(
+      json,
+      "package.json already exists in this directory. visor init --template nextjs only scaffolds into empty directories. For an existing app, see the retrofit flow: https://visor.loworbit.studio/docs/guides/migration"
+    );
     process.exit(1);
   }
   if (configExists(cwd)) {
@@ -158,52 +731,63 @@ function initCommand(cwd, options) {
     }
   }
   if (options?.template === "nextjs") {
-    scaffoldNextjs(cwd, json, filesCreated, filesSkipped);
+    scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings);
   }
-  const missingTokens = !hasVisorTokens(cwd);
-  if (missingTokens) {
-    const warning = "@loworbitstudio/visor-core is not installed. Components require it for styling.";
-    warnings.push(warning);
-    if (!json) {
-      logger.blank();
-      logger.warn(warning);
-      logger.info("  For Next.js: re-run with --template nextjs to generate tokens inline.");
+  if (options?.template !== "nextjs") {
+    const missingTokens = !hasVisorTokens(cwd);
+    if (missingTokens) {
+      const warning = "@loworbitstudio/visor-core is not installed. Components require it for styling.";
+      warnings.push(warning);
+      if (!json) {
+        logger.blank();
+        logger.warn(warning);
+        logger.info("  For a complete one-command setup: run `npx @loworbitstudio/visor init --template nextjs` in an empty directory.");
+      }
     }
   }
   if (json) {
-    const nextSteps = [];
-    if (options?.template === "nextjs") {
-      nextSteps.push("Customize colors in .visor.yaml");
-      nextSteps.push("Add FOWT prevention script to your layout.tsx <head>");
-      nextSteps.push("Run: npx visor add button \u2014 to add your first component");
-    } else {
-      nextSteps.push("Run: npx visor add button \u2014 to add your first component");
-    }
-    if (missingTokens) {
-      nextSteps.push("Re-run with --template nextjs to generate tokens inline (no npm package needed)");
-    }
-    console.log(
-      JSON.stringify(
-        {
-          success: true,
-          config: DEFAULT_CONFIG,
-          files: { created: filesCreated, skipped: filesSkipped },
-          warnings,
-          nextSteps
-        },
-        null,
-        2
-      )
-    );
+    const nextSteps = buildNextSteps(options, warnings);
+    const result = {
+      success: true,
+      config: DEFAULT_CONFIG,
+      files: { created: filesCreated, skipped: filesSkipped },
+      warnings,
+      nextSteps
+    };
+    console.log(JSON.stringify(result, null, 2));
     process.exit(0);
   }
 }
-function scaffoldNextjs(cwd, json, filesCreated, filesSkipped) {
+function buildNextSteps(options, warnings) {
+  const steps = [];
+  if (options?.template === "nextjs") {
+    steps.push("Run: npm run dev \u2014 start the development server");
+    steps.push("Customize colors in .visor.yaml, then re-run `npx visor theme apply .visor.yaml --adapter nextjs`");
+    steps.push("Run: npx visor add button \u2014 add your first component");
+  } else {
+    steps.push("Run: npx visor add button \u2014 add your first component");
+  }
+  if (warnings.some((w) => w.includes("visor-core"))) {
+    steps.push("For a complete one-command setup: re-run with --template nextjs in an empty directory");
+  }
+  return steps;
+}
+function emitError(json, message) {
+  if (json) {
+    const result = { success: false, error: message };
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    logger.error(message);
+  }
+}
+function scaffoldNextjs(cwd, json, filesCreated, filesSkipped, warnings) {
   if (!json) {
     logger.blank();
-    logger.info("Scaffolding NextJS theme...");
+    logger.info("Scaffolding a Borealis-native Next.js app...");
   }
-  const yamlPath = join3(cwd, ".visor.yaml");
+  runCreateNextApp(cwd, json);
+  runInstallVisorDeps(cwd, json);
+  const yamlPath = join5(cwd, ".visor.yaml");
   if (existsSync3(yamlPath)) {
     filesSkipped.push(".visor.yaml");
     if (!json) {
@@ -222,119 +806,143 @@ function scaffoldNextjs(cwd, json, filesCreated, filesSkipped) {
     tokens: data.tokens,
     config: data.config
   });
-  const globalsPath = join3(cwd, "app", "globals.css");
-  const globalsDir = dirname(globalsPath);
+  const globalsPath = join5(cwd, "app", "globals.css");
+  const globalsDir = dirname2(globalsPath);
+  mkdirSync(globalsDir, { recursive: true });
   if (existsSync3(globalsPath)) {
-    filesSkipped.push("app/globals.css");
-    if (!json) {
-      logger.warn("app/globals.css already exists. Skipping.");
-    }
+    writeFileSync2(globalsPath, css, "utf-8");
+    filesCreated.push("app/globals.css");
   } else {
-    mkdirSync(globalsDir, { recursive: true });
     writeFileSync2(globalsPath, css, "utf-8");
     filesCreated.push("app/globals.css");
+  }
+  if (!json) {
+    logger.success("Created app/globals.css with theme tokens");
+  }
+  const layoutPath = join5(cwd, "app", "layout.tsx");
+  writeFileSync2(layoutPath, generateNextjsLayout(), "utf-8");
+  filesCreated.push("app/layout.tsx");
+  if (!json) {
+    logger.success("Wired app/layout.tsx with FOWT prevention and theme tokens");
+  }
+  const stampDir = join5(cwd, ".lo");
+  const stampPath = join5(stampDir, "borealis.json");
+  if (existsSync3(stampPath)) {
+    filesSkipped.push(".lo/borealis.json");
+    if (!json) {
+      logger.warn(".lo/borealis.json already exists. Skipping.");
+    }
+  } else {
+    mkdirSync(stampDir, { recursive: true });
+    const stamp = {
+      visorVersion: readVisorCliVersion(),
+      initializedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    writeFileSync2(stampPath, JSON.stringify(stamp, null, 2) + "\n", "utf-8");
+    filesCreated.push(".lo/borealis.json");
     if (!json) {
-      logger.success("Created app/globals.css with theme tokens");
+      logger.success("Stamped .lo/borealis.json");
     }
   }
   if (!json) {
+    logger.blank();
+    logger.success("Your Borealis-native Next.js app is ready.");
     logger.blank();
     logger.info("Next steps:");
-    logger.item("Customize colors in .visor.yaml");
-    logger.item("Add FOWT prevention script to your layout.tsx <head>");
-    logger.item("Run: npx visor add button \u2014 to add your first component");
+    logger.item("npm run dev                           # start the dev server");
+    logger.item("Edit .visor.yaml to customize tokens, then re-run theme apply");
+    logger.item("npx visor add button                  # add your first component");
   }
+  void warnings;
 }
-
-// src/registry/resolve.ts
-import { readFileSync as readFileSync3 } from "fs";
-import { join as join4, dirname as dirname2 } from "path";
-import { fileURLToPath } from "url";
-var __dirname = dirname2(fileURLToPath(import.meta.url));
-var cachedRegistry = null;
-function loadRegistry() {
-  if (cachedRegistry) return cachedRegistry;
-  const registryPath = join4(__dirname, "registry.json");
-  const raw = readFileSync3(registryPath, "utf-8");
-  cachedRegistry = JSON.parse(raw);
-  return cachedRegistry;
+function runCreateNextApp(cwd, json) {
+  if (!json) {
+    logger.info(`Running create-next-app@${NEXTJS_PINNED_VERSION}...`);
+  }
+  const result = childProcess.spawnSync(
+    "npx",
+    [`create-next-app@${NEXTJS_PINNED_VERSION}`, ".", ...CREATE_NEXT_APP_FLAGS],
+    { cwd, stdio: json ? "ignore" : "inherit" }
+  );
+  assertSpawnSuccess(result, "create-next-app");
 }
-function findItem(registry, name) {
-  return registry.items.find((item) => item.name === name);
+function runInstallVisorDeps(cwd, json) {
+  if (!json) {
+    logger.info("Installing @loworbitstudio/visor-core and visor-theme-engine...");
+  }
+  const result = childProcess.spawnSync(
+    "npm",
+    [
+      "install",
+      "@loworbitstudio/visor-core",
+      "@loworbitstudio/visor-theme-engine"
+    ],
+    { cwd, stdio: json ? "ignore" : "inherit" }
+  );
+  assertSpawnSuccess(result, "npm install");
 }
-function resolveTransitiveDeps(registry, names) {
-  const resolved = /* @__PURE__ */ new Map();
-  const queue = [...names];
-  while (queue.length > 0) {
-    const name = queue.shift();
-    if (resolved.has(name)) continue;
-    const item = findItem(registry, name);
-    if (!item) {
-      throw new Error(`Registry item "${name}" not found.`);
-    }
-    resolved.set(name, item);
-    if (item.registryDependencies) {
-      for (const dep of item.registryDependencies) {
-        if (!resolved.has(dep)) {
-          queue.push(dep);
-        }
-      }
-    }
+function assertSpawnSuccess(result, label) {
+  if (result.error) {
+    throw new Error(`${label} failed to start: ${result.error.message}`);
+  }
+  if (typeof result.status === "number" && result.status !== 0) {
+    throw new Error(`${label} exited with code ${result.status}`);
   }
-  return Array.from(resolved.values());
 }
-function collectDependencies(items) {
-  const deps = /* @__PURE__ */ new Set();
-  const devDeps = /* @__PURE__ */ new Set();
-  for (const item of items) {
-    if (item.dependencies) {
-      for (const dep of item.dependencies) {
-        deps.add(dep);
-      }
-    }
-    if (item.devDependencies) {
-      for (const dep of item.devDependencies) {
-        devDeps.add(dep);
+function readVisorCliVersion() {
+  try {
+    const here = dirname2(fileURLToPath2(import.meta.url));
+    for (let i = 0; i < 5; i++) {
+      const segments = new Array(i).fill("..");
+      const candidate = join5(here, ...segments, "package.json");
+      try {
+        const pkg = JSON.parse(readFileSync5(candidate, "utf-8"));
+        if (pkg.name === "@loworbitstudio/visor" && pkg.version) {
+          return pkg.version;
+        }
+      } catch {
       }
     }
+  } catch {
   }
-  return {
-    dependencies: Array.from(deps).sort(),
-    devDependencies: Array.from(devDeps).sort()
-  };
+  return "0.0.0-dev";
 }
 
 // src/utils/fs.ts
 import {
   writeFileSync as writeFileSync3,
-  readFileSync as readFileSync4,
+  readFileSync as readFileSync6,
   existsSync as existsSync4,
   mkdirSync as mkdirSync2
 } from "fs";
-import { dirname as dirname3, join as join5 } from "path";
+import { dirname as dirname3, join as join6 } from "path";
 function resolveOutputPath(registryPath, type, config, cwd) {
   let relativePath;
   if (type === "registry:block") {
     relativePath = registryPath.replace(/^blocks\//, "");
-    return join5(cwd, config.paths.blocks, relativePath);
+    return join6(cwd, config.paths.blocks, relativePath);
   }
   if (type === "registry:ui") {
     if (registryPath.startsWith("components/deck/")) {
       relativePath = registryPath.replace(/^components\/deck\//, "");
-      return join5(cwd, config.paths.deckComponents, relativePath);
+      return join6(cwd, config.paths.deckComponents, relativePath);
+    }
+    if (registryPath.startsWith("components/flutter/")) {
+      relativePath = registryPath.replace(/^components\/flutter\//, "");
+      return join6(cwd, config.paths.flutterComponents, relativePath);
     }
     relativePath = registryPath.replace(/^components\/ui\//, "");
-    return join5(cwd, config.paths.components, relativePath);
+    return join6(cwd, config.paths.components, relativePath);
   }
   if (type === "registry:hook") {
     relativePath = registryPath.replace(/^hooks\//, "");
-    return join5(cwd, config.paths.hooks, relativePath);
+    return join6(cwd, config.paths.hooks, relativePath);
   }
   if (type === "registry:lib") {
     relativePath = registryPath.replace(/^lib\//, "");
-    return join5(cwd, config.paths.lib, relativePath);
+    return join6(cwd, config.paths.lib, relativePath);
   }
-  return join5(cwd, registryPath);
+  return join6(cwd, registryPath);
 }
 function writeFile(filePath, content) {
   const dir = dirname3(filePath);
@@ -345,7 +953,7 @@ function writeFile(filePath, content) {
 }
 function readFile(filePath) {
   if (!existsSync4(filePath)) return null;
-  return readFileSync4(filePath, "utf-8");
+  return readFileSync6(filePath, "utf-8");
 }
 function fileExists(filePath) {
   return existsSync4(filePath);
@@ -488,9 +1096,141 @@ function listCommand(cwd, options = {}) {
   }
 }
 
+// src/utils/pubspec.ts
+import { existsSync as existsSync5, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "fs";
+import { join as join7 } from "path";
+import { parseDocument, YAMLMap } from "yaml";
+function mergePubspec(pubspecText, deps) {
+  const doc = parseDocument(pubspecText);
+  const added = [];
+  const skipped = [];
+  let depsNode = doc.get("dependencies");
+  if (depsNode == null || !(depsNode instanceof YAMLMap)) {
+    depsNode = new YAMLMap();
+    doc.set("dependencies", depsNode);
+  }
+  for (const dep of deps) {
+    if (depsNode.has(dep.pub)) {
+      skipped.push(dep.pub);
+      continue;
+    }
+    depsNode.set(dep.pub, dep.version);
+    added.push(dep.pub);
+  }
+  return { text: doc.toString(), added, skipped };
+}
+function pubspecPath(cwd) {
+  return join7(cwd, "pubspec.yaml");
+}
+function pubspecExists(cwd) {
+  return existsSync5(pubspecPath(cwd));
+}
+function isPubPackageInstalled(packageName, cwd) {
+  if (!pubspecExists(cwd)) return false;
+  const text = readFileSync7(pubspecPath(cwd), "utf-8");
+  const doc = parseDocument(text);
+  const depsNode = doc.get("dependencies");
+  if (!(depsNode instanceof YAMLMap)) return false;
+  return depsNode.has(packageName);
+}
+function getUninstalledPubDeps(deps, cwd) {
+  return deps.filter((d) => !isPubPackageInstalled(d.pub, cwd));
+}
+function addPubDependencies(deps, cwd) {
+  const path2 = pubspecPath(cwd);
+  if (!existsSync5(path2)) {
+    throw new Error(
+      `No pubspec.yaml found at ${path2}. Run this command from a Flutter project root.`
+    );
+  }
+  const text = readFileSync7(path2, "utf-8");
+  const result = mergePubspec(text, deps);
+  if (result.added.length > 0) {
+    writeFileSync4(path2, result.text, "utf-8");
+  }
+  return result;
+}
+
+// src/utils/flutter.ts
+import { execFileSync as execFileSync2 } from "child_process";
+import { existsSync as existsSync6, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { homedir } from "os";
+import { join as join8 } from "path";
+function isExecutable(path2) {
+  try {
+    const s = statSync2(path2);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+function fromPath(env) {
+  const pathVar = env.PATH ?? "";
+  const sep = process.platform === "win32" ? ";" : ":";
+  const bin = process.platform === "win32" ? "flutter.bat" : "flutter";
+  for (const dir of pathVar.split(sep)) {
+    if (!dir) continue;
+    const candidate = join8(dir, bin);
+    if (isExecutable(candidate)) return candidate;
+  }
+  return null;
+}
+function fromFvm(home) {
+  const fvmDefault = join8(home, "fvm", "default", "bin", "flutter");
+  if (isExecutable(fvmDefault)) return fvmDefault;
+  const versionsDir = join8(home, "fvm", "versions");
+  if (!existsSync6(versionsDir)) return null;
+  let best = null;
+  try {
+    for (const name of readdirSync2(versionsDir)) {
+      const candidate = join8(versionsDir, name, "bin", "flutter");
+      if (!isExecutable(candidate)) continue;
+      if (!best || compareSemver(name, best.version) > 0) {
+        best = { version: name, path: candidate };
+      }
+    }
+  } catch {
+    return null;
+  }
+  return best?.path ?? null;
+}
+function compareSemver(a, b) {
+  const pa = a.split(".").map((x) => parseInt(x, 10) || 0);
+  const pb = b.split(".").map((x) => parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const av = pa[i] ?? 0;
+    const bv = pb[i] ?? 0;
+    if (av !== bv) return av - bv;
+  }
+  return 0;
+}
+function findFlutterBin(options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? homedir();
+  const envRoot = env.FLUTTER_ROOT;
+  if (envRoot) {
+    const bin = join8(envRoot, "bin", "flutter");
+    if (isExecutable(bin)) return bin;
+  }
+  const fromPathBin = fromPath(env);
+  if (fromPathBin) return fromPathBin;
+  return fromFvm(home);
+}
+function runFlutterPubGet(cwd, bin) {
+  try {
+    execFileSync2(bin, ["pub", "get"], { cwd, stdio: "inherit" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 // src/commands/add.ts
 function addCommand(components, cwd, options = {}) {
   const json = options.json ?? false;
+  const dryRun = options.dryRun ?? false;
+  const target = options.target ?? "react";
+  const prefix = dryRun ? "[dry-run] " : "";
   let autoInitialized = false;
   if (!configExists(cwd)) {
     writeConfig(cwd, DEFAULT_CONFIG);
@@ -514,9 +1254,12 @@ function addCommand(components, cwd, options = {}) {
     }
     process.exit(1);
   }
+  const targetRegistry = {
+    items: filterItemsByTarget(registry.items, target)
+  };
   if (options.block && components.length > 0) {
     for (const name of components) {
-      const item = registry.items.find((i) => i.name === name);
+      const item = targetRegistry.items.find((i) => i.name === name);
       if (item && item.type !== "registry:block") {
         if (json) {
           console.log(
@@ -553,7 +1296,7 @@ function addCommand(components, cwd, options = {}) {
       }
       process.exit(1);
     }
-    const categoryItems = registry.items.filter(
+    const categoryItems = targetRegistry.items.filter(
       (item) => item.category === options.category
     );
     if (categoryItems.length === 0) {
@@ -579,7 +1322,7 @@ function addCommand(components, cwd, options = {}) {
   }
   if (itemNames.length === 0) {
     if (options.block) {
-      const blockItems = registry.items.filter(
+      const blockItems = targetRegistry.items.filter(
         (item) => item.type === "registry:block"
       );
       if (json) {
@@ -618,9 +1361,26 @@ function addCommand(components, cwd, options = {}) {
     }
     process.exit(1);
   }
+  const canonicalNames = [];
+  for (const name of itemNames) {
+    const resolved = findItemForTarget(targetRegistry, name, target);
+    if (!resolved) {
+      const message = `Registry item "${name}" not found for target "${target}".`;
+      if (json) {
+        console.log(JSON.stringify({ success: false, error: message }, null, 2));
+      } else {
+        logger.error(message);
+      }
+      process.exit(1);
+    }
+    canonicalNames.push(resolved.name);
+  }
+  const circularWarnings = [];
   let items;
   try {
-    items = resolveTransitiveDeps(registry, itemNames);
+    items = resolveTransitiveDeps(targetRegistry, canonicalNames, (msg) => {
+      circularWarnings.push(msg);
+    });
   } catch (error) {
     if (json) {
       const message = error instanceof Error ? error.message : String(error);
@@ -629,6 +1389,11 @@ function addCommand(components, cwd, options = {}) {
     }
     throw error;
   }
+  if (circularWarnings.length > 0 && !json) {
+    for (const warning of circularWarnings) {
+      logger.warn(warning);
+    }
+  }
   if (!json) {
     logger.info(
       `Resolving ${itemNames.length} item(s) \u2192 ${items.length} total (with dependencies)`
@@ -645,16 +1410,18 @@ function addCommand(components, cwd, options = {}) {
         config,
         cwd
       );
-      if (fileExists(outputPath) && !options.overwrite) {
+      if (!dryRun && fileExists(outputPath) && !options.overwrite) {
         if (!json) {
-          logger.item(`skip ${file.path} (already exists)`);
+          logger.item(`${prefix}skip ${file.path} (already exists)`);
         }
         skippedFiles.push(file.path);
         continue;
       }
-      writeFile(outputPath, file.content);
+      if (!dryRun) {
+        writeFile(outputPath, file.content);
+      }
       if (!json) {
-        logger.success(file.path);
+        logger.success(`${prefix}${file.path}`);
       }
       writtenFiles.push(file.path);
     }
@@ -662,60 +1429,135 @@ function addCommand(components, cwd, options = {}) {
   if (!json) {
     logger.blank();
     logger.info(
-      `Files: ${writtenFiles.length} written, ${skippedFiles.length} skipped`
+      `${prefix}Files: ${writtenFiles.length} written, ${skippedFiles.length} skipped`
     );
   }
-  const { dependencies, devDependencies } = collectDependencies(items);
-  const uninstalledDeps = getUninstalledDeps(dependencies, cwd);
-  const uninstalledDevDeps = getUninstalledDeps(devDependencies, cwd);
+  const { dependencies, devDependencies, pubDependencies } = collectDependencies(items);
   const installedDeps = [];
   const failedDeps = [];
-  if (uninstalledDeps.length > 0) {
-    if (!json) {
-      logger.blank();
-      logger.info("Installing dependencies...");
-    }
-    if (installPackages(uninstalledDeps, cwd)) {
-      installedDeps.push(...uninstalledDeps);
-    } else {
-      failedDeps.push(...uninstalledDeps);
-      if (!json) {
-        logger.warn("Some dependencies failed to install. Install them manually:");
-        logger.info(`  npm install ${uninstalledDeps.join(" ")}`);
+  const warnings = [];
+  if (target === "flutter") {
+    const uninstalledPubDeps = dryRun ? pubDependencies : pubspecExists(cwd) ? getUninstalledPubDeps(pubDependencies, cwd) : pubDependencies;
+    if (uninstalledPubDeps.length > 0) {
+      if (dryRun) {
+        if (!json) {
+          logger.blank();
+          logger.info(
+            `${prefix}Would add pub dependencies: ${uninstalledPubDeps.map((d) => `${d.pub}@${d.version}`).join(", ")}`
+          );
+        }
+        installedDeps.push(...uninstalledPubDeps.map((d) => d.pub));
+      } else if (!pubspecExists(cwd)) {
+        const message = "No pubspec.yaml found. Run this from a Flutter project root, or add " + uninstalledPubDeps.map((d) => `${d.pub}: ${d.version}`).join(", ") + " to pubspec.yaml manually.";
+        warnings.push(message);
+        if (!json) {
+          logger.blank();
+          logger.warn(message);
+        }
+      } else {
+        if (!json) {
+          logger.blank();
+          logger.info("Updating pubspec.yaml...");
+        }
+        const result = addPubDependencies(uninstalledPubDeps, cwd);
+        installedDeps.push(...result.added);
+        const flutterBin = findFlutterBin();
+        if (flutterBin) {
+          if (!json) {
+            logger.info("Running flutter pub get...");
+          }
+          if (!runFlutterPubGet(cwd, flutterBin)) {
+            const warning = "flutter pub get failed. Run it manually to refresh dependencies.";
+            warnings.push(warning);
+            if (!json) logger.warn(warning);
+          }
+        } else {
+          const warning = "flutter CLI not found. Run `flutter pub get` manually after setting up Flutter (or FVM).";
+          warnings.push(warning);
+          if (!json) logger.warn(warning);
+        }
       }
     }
-  }
-  if (uninstalledDevDeps.length > 0) {
-    if (!json) {
-      logger.blank();
-      logger.info("Installing dev dependencies...");
+  } else {
+    const uninstalledDeps = dryRun ? dependencies : getUninstalledDeps(dependencies, cwd);
+    const uninstalledDevDeps = dryRun ? devDependencies : getUninstalledDeps(devDependencies, cwd);
+    if (uninstalledDeps.length > 0) {
+      if (dryRun) {
+        if (!json) {
+          logger.blank();
+          logger.info(
+            `${prefix}Would install dependencies: ${uninstalledDeps.join(", ")}`
+          );
+        }
+        installedDeps.push(...uninstalledDeps);
+      } else {
+        if (!json) {
+          logger.blank();
+          logger.info("Installing dependencies...");
+        }
+        if (installPackages(uninstalledDeps, cwd)) {
+          installedDeps.push(...uninstalledDeps);
+        } else {
+          failedDeps.push(...uninstalledDeps);
+          if (!json) {
+            logger.warn(
+              "Some dependencies failed to install. Install them manually:"
+            );
+            logger.info(`  npm install ${uninstalledDeps.join(" ")}`);
+          }
+        }
+      }
     }
-    if (installPackages(uninstalledDevDeps, cwd, true)) {
-      installedDeps.push(...uninstalledDevDeps);
-    } else {
-      failedDeps.push(...uninstalledDevDeps);
-      if (!json) {
-        logger.warn("Some dev dependencies failed to install. Install them manually:");
-        logger.info(`  npm install --save-dev ${uninstalledDevDeps.join(" ")}`);
+    if (uninstalledDevDeps.length > 0) {
+      if (dryRun) {
+        if (!json) {
+          logger.blank();
+          logger.info(
+            `${prefix}Would install dev dependencies: ${uninstalledDevDeps.join(", ")}`
+          );
+        }
+        installedDeps.push(...uninstalledDevDeps);
+      } else {
+        if (!json) {
+          logger.blank();
+          logger.info("Installing dev dependencies...");
+        }
+        if (installPackages(uninstalledDevDeps, cwd, true)) {
+          installedDeps.push(...uninstalledDevDeps);
+        } else {
+          failedDeps.push(...uninstalledDevDeps);
+          if (!json) {
+            logger.warn(
+              "Some dev dependencies failed to install. Install them manually:"
+            );
+            logger.info(
+              `  npm install --save-dev ${uninstalledDevDeps.join(" ")}`
+            );
+          }
+        }
       }
     }
-  }
-  const warnings = [];
-  if (!hasVisorTokens(cwd)) {
-    const warning = "@loworbitstudio/visor-core is not installed. Components require it for styling.";
-    warnings.push(warning);
-    if (!json) {
-      logger.blank();
-      logger.warn(warning);
-      logger.info("  For Next.js: npx @loworbitstudio/visor init --template nextjs");
-      logger.info("  This generates all tokens inline \u2014 no npm package needed.");
+    if (!hasVisorTokens(cwd)) {
+      const warning = "@loworbitstudio/visor-core is not installed. Components require it for styling.";
+      warnings.push(warning);
+      if (!json) {
+        logger.blank();
+        logger.warn(warning);
+        logger.info(
+          "  For Next.js: npx @loworbitstudio/visor init --template nextjs"
+        );
+        logger.info(
+          "  This generates all tokens inline \u2014 no npm package needed."
+        );
+      }
     }
   }
   if (json) {
     console.log(
       JSON.stringify(
         {
-          success: true,
+          success: failedDeps.length === 0,
+          ...dryRun ? { dryRun: true } : {},
           autoInitialized,
           requested: itemNames,
           resolved: items.map((i) => i.name),
@@ -727,7 +1569,10 @@ function addCommand(components, cwd, options = {}) {
         2
       )
     );
-    process.exit(0);
+    process.exit(failedDeps.length > 0 ? 1 : 0);
+  }
+  if (failedDeps.length > 0) {
+    process.exit(1);
   }
 }
 
@@ -750,10 +1595,15 @@ function hasDifferences(localContent, registryContent) {
 // src/commands/diff.ts
 function diffCommand(componentName, cwd, options = {}) {
   const json = options.json ?? false;
+  const all = options.all ?? false;
   let config;
   let registry;
   try {
-    config = loadConfig(cwd);
+    if (all && !configExists(cwd)) {
+      config = DEFAULT_CONFIG;
+    } else {
+      config = loadConfig(cwd);
+    }
     registry = loadRegistry();
   } catch (error) {
     if (json) {
@@ -763,6 +1613,79 @@ function diffCommand(componentName, cwd, options = {}) {
     }
     throw error;
   }
+  if (all) {
+    const results = [];
+    for (const item of registry.items) {
+      const changedFiles = [];
+      let hasModified = false;
+      let hasAdded = false;
+      for (const file of item.files) {
+        const outputPath = resolveOutputPath(
+          file.path,
+          file.type,
+          config,
+          cwd
+        );
+        const localContent = readFile(outputPath);
+        if (localContent === null) {
+          hasAdded = true;
+          changedFiles.push(file.path);
+          continue;
+        }
+        if (hasDifferences(localContent, file.content)) {
+          hasModified = true;
+          changedFiles.push(file.path);
+        }
+      }
+      let changeType;
+      if (hasModified) {
+        changeType = "modified";
+      } else if (hasAdded && changedFiles.length === item.files.length) {
+        changeType = "added";
+      } else if (hasAdded) {
+        changeType = "modified";
+      } else {
+        changeType = "unchanged";
+      }
+      results.push({
+        component: item.name,
+        changeType,
+        files: changedFiles,
+        breakingChange: false,
+        migrationNote: null
+      });
+    }
+    const total = results.length;
+    const changed = results.filter((r) => r.changeType !== "unchanged").length;
+    const unchanged = total - changed;
+    if (json) {
+      console.log(
+        JSON.stringify(
+          {
+            success: true,
+            results,
+            summary: { total, changed, unchanged }
+          },
+          null,
+          2
+        )
+      );
+      process.exit(0);
+      return;
+    }
+    const changedItems = results.filter((r) => r.changeType !== "unchanged");
+    if (changedItems.length === 0) {
+      logger.success(`All ${total} components match the registry.`);
+    } else {
+      logger.heading(`${changed} component(s) with upstream changes`);
+      for (const r of changedItems) {
+        logger.info(`  ${r.component} [${r.changeType}]: ${r.files.join(", ")}`);
+      }
+      logger.blank();
+      logger.info(`Total: ${total} | Changed: ${changed} | Unchanged: ${unchanged}`);
+    }
+    return;
+  }
   const itemsToDiff = componentName ? (() => {
     const item = findItem(registry, componentName);
     if (!item) {
@@ -850,15 +1773,94 @@ function diffCommand(componentName, cwd, options = {}) {
   }
 }
 
+// src/commands/info.ts
+function infoCommand(name, cwd, options = {}) {
+  const json = options.json ?? false;
+  let manifest;
+  try {
+    manifest = loadManifest();
+  } catch (error) {
+    if (json) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.error(JSON.stringify({ success: false, error: message }, null, 2));
+      process.exit(1);
+    }
+    throw error;
+  }
+  let kind = null;
+  let data = null;
+  if (name in manifest.components) {
+    kind = "component";
+    data = manifest.components[name];
+  } else if (name in manifest.hooks) {
+    kind = "hook";
+    data = manifest.hooks[name];
+  } else if (name in manifest.blocks) {
+    kind = "block";
+    data = manifest.blocks[name];
+  } else if (name in manifest.patterns) {
+    kind = "pattern";
+    data = manifest.patterns[name];
+  }
+  if (kind === null || data === null) {
+    const errorPayload = {
+      success: false,
+      error: `Component ${name} not found. Run visor list --json to see available names.`
+    };
+    if (json) {
+      console.error(JSON.stringify(errorPayload, null, 2));
+    } else {
+      logger.error(errorPayload.error);
+    }
+    process.exit(1);
+    return;
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          name,
+          kind,
+          data
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  const entry = data;
+  logger.heading(`${name} (${kind})`);
+  logger.blank();
+  if (entry.description) {
+    logger.info(String(entry.description));
+    logger.blank();
+  }
+  if (Array.isArray(entry.when_to_use) && entry.when_to_use.length > 0) {
+    logger.info("When to use:");
+    for (const item of entry.when_to_use) {
+      logger.info(`  \u2022 ${item}`);
+    }
+    logger.blank();
+  }
+  if (entry.example) {
+    logger.info("Example:");
+    logger.info(String(entry.example));
+  }
+}
+
 // src/commands/theme-apply.ts
-import { readFileSync as readFileSync5, writeFileSync as writeFileSync4, mkdirSync as mkdirSync3 } from "fs";
-import { resolve, dirname as dirname4 } from "path";
+import { readFileSync as readFileSync8, writeFileSync as writeFileSync5, mkdirSync as mkdirSync3 } from "fs";
+import { resolve as resolve2, dirname as dirname4, join as join9 } from "path";
 import { generateTheme, generateThemeData as generateThemeData2 } from "@loworbitstudio/visor-theme-engine";
 import {
   nextjsAdapter as nextjsAdapter2,
   fumadocsAdapter,
   deckAdapter,
-  docsAdapter
+  docsAdapter,
+  flutterAdapter
 } from "@loworbitstudio/visor-theme-engine/adapters";
 function defaultOutputPath(adapter, themeName) {
   switch (adapter) {
@@ -867,22 +1869,24 @@ function defaultOutputPath(adapter, themeName) {
     case "fumadocs":
       return "visor-fumadocs-bridge.css";
     case "deck": {
-      const slug = (themeName ?? "theme").toLowerCase().replace(/\s+/g, "-");
-      return `visor-deck-${slug}.css`;
+      const slug2 = (themeName ?? "theme").toLowerCase().replace(/\s+/g, "-");
+      return `visor-deck-${slug2}.css`;
     }
     case "docs": {
-      const slug = (themeName ?? "theme").toLowerCase().replace(/\s+/g, "-");
-      return `${slug}-theme.css`;
+      const slug2 = (themeName ?? "theme").toLowerCase().replace(/\s+/g, "-");
+      return `${slug2}-theme.css`;
     }
+    case "flutter":
+      return "packages/ui";
     default:
       return "visor-theme.css";
   }
 }
 function themeApplyCommand(file, cwd, options) {
-  const filePath = resolve(cwd, file);
+  const filePath = resolve2(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync5(filePath, "utf-8");
+    yamlContent = readFileSync8(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -897,7 +1901,8 @@ function themeApplyCommand(file, cwd, options) {
     }
     process.exit(2);
   }
-  let css;
+  let css = null;
+  let fileMap = null;
   let themeName;
   let sections;
   try {
@@ -922,6 +1927,17 @@ function themeApplyCommand(file, cwd, options) {
         case "docs":
           css = docsAdapter(adapterInput);
           break;
+        case "flutter": {
+          const flutterOptions = {
+            packageName: options.packageName,
+            tokensOnly: options.tokensOnly,
+            lightOnly: options.lightOnly,
+            darkOnly: options.darkOnly,
+            themeClassName: options.themeClassName
+          };
+          fileMap = flutterAdapter(adapterInput, flutterOptions);
+          break;
+        }
         default:
           throw new Error(`Unknown adapter: ${options.adapter}`);
       }
@@ -946,12 +1962,56 @@ function themeApplyCommand(file, cwd, options) {
     }
     process.exit(1);
   }
-  const outputFile = options.output ?? defaultOutputPath(options.adapter, themeName);
-  const outputPath = resolve(cwd, outputFile);
+  const outputTarget = options.output ?? defaultOutputPath(options.adapter, themeName);
+  const outputPath = resolve2(cwd, outputTarget);
+  if (fileMap) {
+    try {
+      mkdirSync3(outputPath, { recursive: true });
+      let totalBytes = 0;
+      for (const [relPath, content] of Object.entries(fileMap.files)) {
+        const filePath2 = join9(outputPath, relPath);
+        mkdirSync3(dirname4(filePath2), { recursive: true });
+        writeFileSync5(filePath2, content, "utf-8");
+        totalBytes += content.length;
+      }
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            success: true,
+            directory: outputPath,
+            adapter: options.adapter,
+            files: Object.keys(fileMap.files),
+            size: totalBytes
+          })
+        );
+      } else {
+        logger.success(`Flutter theme package generated: ${outputPath}`);
+        logger.info(`Adapter: ${options.adapter}`);
+        logger.item(`Files: ${Object.keys(fileMap.files).length}`);
+        logger.item(`Size: ${formatSize(totalBytes)}`);
+      }
+    } catch {
+      if (options.json) {
+        console.log(
+          JSON.stringify({
+            success: false,
+            error: `Could not write package to: ${outputPath}`
+          })
+        );
+      } else {
+        logger.error(`Could not write package to: ${outputPath}`);
+      }
+      process.exit(2);
+    }
+    return;
+  }
+  if (css === null) {
+    process.exit(1);
+  }
   const outputDir = dirname4(outputPath);
   try {
     mkdirSync3(outputDir, { recursive: true });
-    writeFileSync4(outputPath, css, "utf-8");
+    writeFileSync5(outputPath, css, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -992,8 +2052,8 @@ function formatSize(bytes) {
 }
 
 // src/commands/theme-export.ts
-import { readFileSync as readFileSync6 } from "fs";
-import { resolve as resolve2 } from "path";
+import { readFileSync as readFileSync9 } from "fs";
+import { resolve as resolve3 } from "path";
 import {
   parseConfig,
   resolveConfig,
@@ -1001,10 +2061,10 @@ import {
   exportTheme
 } from "@loworbitstudio/visor-theme-engine";
 function themeExportCommand(file, cwd, options) {
-  const filePath = resolve2(cwd, file ?? ".visor.yaml");
+  const filePath = resolve3(cwd, file ?? ".visor.yaml");
   let yamlContent;
   try {
-    yamlContent = readFileSync6(filePath, "utf-8");
+    yamlContent = readFileSync9(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -1056,16 +2116,16 @@ function themeExportCommand(file, cwd, options) {
 }
 
 // src/commands/theme-validate.ts
-import { readFileSync as readFileSync7 } from "fs";
-import { resolve as resolve3 } from "path";
+import { readFileSync as readFileSync10 } from "fs";
+import { resolve as resolve4 } from "path";
 import { parse as parseYaml } from "yaml";
 import { validate } from "@loworbitstudio/visor-theme-engine";
 import pc2 from "picocolors";
 function themeValidateCommand(file, cwd, options) {
-  const filePath = resolve3(cwd, file);
+  const filePath = resolve4(cwd, file);
   let fileContent;
   try {
-    fileContent = readFileSync7(filePath, "utf-8");
+    fileContent = readFileSync10(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(
@@ -1147,13 +2207,13 @@ function themeValidateCommand(file, cwd, options) {
 function printIssue(issue) {
   const prefix = issue.severity === "error" ? pc2.red("  ERROR") : pc2.yellow("  WARN ");
   const code = pc2.dim(`[${issue.code}]`);
-  const path = issue.path ? pc2.dim(` (${issue.path})`) : "";
-  console.log(`${prefix} ${code} ${issue.message}${path}`);
+  const path2 = issue.path ? pc2.dim(` (${issue.path})`) : "";
+  console.log(`${prefix} ${code} ${issue.message}${path2}`);
 }
 
 // src/commands/theme-extract.ts
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync5, existsSync as existsSync5, readdirSync, statSync } from "fs";
-import { resolve as resolve4, join as join6, basename, extname, relative } from "path";
+import { readFileSync as readFileSync11, writeFileSync as writeFileSync6, existsSync as existsSync7, readdirSync as readdirSync3, statSync as statSync3 } from "fs";
+import { resolve as resolve5, join as join10, basename, extname as extname2, relative } from "path";
 import { stringify as stringifyYaml } from "yaml";
 import {
   extractFromCSS,
@@ -1182,8 +2242,8 @@ var CSS_DIRS = [
   "packages/design-tokens"
 ];
 function themeExtractCommand(cwd, options) {
-  const targetDir = resolve4(cwd, options.from ?? ".");
-  if (!existsSync5(targetDir)) {
+  const targetDir = resolve5(cwd, options.from ?? ".");
+  if (!existsSync7(targetDir)) {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Directory not found: ${targetDir}` }));
     } else {
@@ -1236,17 +2296,17 @@ function themeExtractCommand(cwd, options) {
 function collectCSSFiles(targetDir) {
   const files = [];
   const seen = /* @__PURE__ */ new Set();
-  for (const pattern of CSS_FILE_PATTERNS) {
-    const rootPath = join6(targetDir, pattern);
+  for (const pattern2 of CSS_FILE_PATTERNS) {
+    const rootPath = join10(targetDir, pattern2);
     addFileIfExists(rootPath, files, seen);
     for (const dir of CSS_DIRS) {
-      const dirPath = join6(targetDir, dir, pattern);
+      const dirPath = join10(targetDir, dir, pattern2);
       addFileIfExists(dirPath, files, seen);
     }
   }
   for (const dir of CSS_DIRS) {
-    const dirPath = join6(targetDir, dir);
-    if (existsSync5(dirPath) && statSync(dirPath).isDirectory()) {
+    const dirPath = join10(targetDir, dir);
+    if (existsSync7(dirPath) && statSync3(dirPath).isDirectory()) {
       scanDirForCSS(dirPath, files, seen, 2);
     }
   }
@@ -1254,11 +2314,11 @@ function collectCSSFiles(targetDir) {
   return files;
 }
 function addFileIfExists(filePath, files, seen) {
-  const resolved = resolve4(filePath);
+  const resolved = resolve5(filePath);
   if (seen.has(resolved)) return;
-  if (!existsSync5(resolved)) return;
+  if (!existsSync7(resolved)) return;
   try {
-    const content = readFileSync8(resolved, "utf-8");
+    const content = readFileSync11(resolved, "utf-8");
     if (content.includes("--")) {
       files.push({ path: resolved, content });
       seen.add(resolved);
@@ -1267,7 +2327,7 @@ function addFileIfExists(filePath, files, seen) {
   }
 }
 function scanDirForCSS(dir, files, seen, maxDepth) {
-  if (!existsSync5(dir)) return;
+  if (!existsSync7(dir)) return;
   const SKIP_DIRS = /* @__PURE__ */ new Set([
     "node_modules",
     ".next",
@@ -1281,15 +2341,15 @@ function scanDirForCSS(dir, files, seen, maxDepth) {
     ".vercel"
   ]);
   try {
-    const entries = readdirSync(dir, { withFileTypes: true });
+    const entries = readdirSync3(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) {
         if (SKIP_DIRS.has(entry.name)) continue;
         if (maxDepth > 0) {
-          scanDirForCSS(join6(dir, entry.name), files, seen, maxDepth - 1);
+          scanDirForCSS(join10(dir, entry.name), files, seen, maxDepth - 1);
         }
-      } else if (entry.isFile() && extname(entry.name) === ".css") {
-        addFileIfExists(join6(dir, entry.name), files, seen);
+      } else if (entry.isFile() && extname2(entry.name) === ".css") {
+        addFileIfExists(join10(dir, entry.name), files, seen);
       }
     }
   } catch {
@@ -1371,10 +2431,10 @@ function extractVarName(varExpr) {
 function parseNextFontFromLayouts(targetDir) {
   const fontMap = /* @__PURE__ */ new Map();
   for (const relPath of LAYOUT_FILE_PATHS) {
-    const fullPath = join6(targetDir, relPath);
-    if (!existsSync5(fullPath)) continue;
+    const fullPath = join10(targetDir, relPath);
+    if (!existsSync7(fullPath)) continue;
     try {
-      const content = readFileSync8(fullPath, "utf-8");
+      const content = readFileSync11(fullPath, "utf-8");
       parseNextFontDeclarations(content, fontMap);
     } catch {
     }
@@ -1421,7 +2481,7 @@ function parseNextFontDeclarations(content, fontMap) {
       const srcMatch = block.match(/src\s*:\s*["']([^"']+)["']/);
       if (srcMatch) {
         const srcPath = srcMatch[1];
-        const fileName = basename(srcPath, extname(srcPath));
+        const fileName = basename(srcPath, extname2(srcPath));
         const fontBaseName = fileName.replace(/[-_](Variable|Regular|Bold|Light|Medium|SemiBold|ExtraBold|Thin|Black|Italic).*$/i, "").replace(/[-_]/g, " ").trim();
         if (fontBaseName) {
           fontMap.set(varName, fontBaseName);
@@ -1459,10 +2519,10 @@ var MONO_FONT_NAMES = /* @__PURE__ */ new Set([
   "IBM Plex Mono"
 ]);
 function extractFontHints(targetDir) {
-  const pkgPath = join6(targetDir, "package.json");
-  if (!existsSync5(pkgPath)) return void 0;
+  const pkgPath = join10(targetDir, "package.json");
+  if (!existsSync7(pkgPath)) return void 0;
   try {
-    const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+    const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
     const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
     const fonts2 = [];
     for (const [dep, _] of Object.entries(allDeps)) {
@@ -1498,10 +2558,10 @@ function extractFontHints(targetDir) {
   }
 }
 function inferThemeName(targetDir) {
-  const pkgPath = join6(targetDir, "package.json");
-  if (existsSync5(pkgPath)) {
+  const pkgPath = join10(targetDir, "package.json");
+  if (existsSync7(pkgPath)) {
     try {
-      const pkg = JSON.parse(readFileSync8(pkgPath, "utf-8"));
+      const pkg = JSON.parse(readFileSync11(pkgPath, "utf-8"));
       if (pkg.name) {
         const name = pkg.name.replace(/^@[\w-]+\//, "");
         return `${name}-theme`;
@@ -1538,7 +2598,7 @@ function outputJSON(result, validationResult) {
 }
 function outputYAML(result, outputPath, cwd, validationResult) {
   const yamlStr = buildAnnotatedYAML(result);
-  const outFile = resolve4(cwd, outputPath ?? ".visor.yaml");
+  const outFile = resolve5(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;
@@ -1566,7 +2626,7 @@ function outputYAML(result, outputPath, cwd, validationResult) {
     }
     logger.blank();
   }
-  writeFileSync5(outFile, yamlStr, "utf-8");
+  writeFileSync6(outFile, yamlStr, "utf-8");
   logger.success(`Theme written to ${relative(cwd, outFile)}`);
   if (validationResult) {
     logger.blank();
@@ -1624,14 +2684,14 @@ function buildAnnotatedYAML(result) {
 }
 
 // src/commands/theme-register.ts
-import { readFileSync as readFileSync9, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4, existsSync as existsSync7 } from "fs";
-import { resolve as resolve6, join as join8 } from "path";
+import { readFileSync as readFileSync12, writeFileSync as writeFileSync7, mkdirSync as mkdirSync4, existsSync as existsSync9 } from "fs";
+import { resolve as resolve7, join as join12 } from "path";
 import { generateThemeData as generateThemeData3 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
 
 // src/utils/theme-helpers.ts
-import { existsSync as existsSync6 } from "fs";
-import { resolve as resolve5, dirname as dirname5, join as join7 } from "path";
+import { existsSync as existsSync8 } from "fs";
+import { resolve as resolve6, dirname as dirname5, join as join11 } from "path";
 function toSlug(name) {
   return name.toLowerCase().replace(/\s+/g, "-");
 }
@@ -1639,9 +2699,9 @@ function toLabel(name) {
   return name.split(/[\s-]+/).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
 function findRepoRoot(startDir) {
-  let current = resolve5(startDir);
+  let current = resolve6(startDir);
   while (true) {
-    if (existsSync6(join7(current, "packages", "docs"))) {
+    if (existsSync8(join11(current, "packages", "docs"))) {
       return current;
     }
     const parent = dirname5(current);
@@ -1652,8 +2712,8 @@ function findRepoRoot(startDir) {
 }
 
 // src/commands/theme-register.ts
-function insertGlobalsImport(content, slug) {
-  const importLine = `@import './${slug}-theme.css';`;
+function insertGlobalsImport(content, slug2) {
+  const importLine = `@import './${slug2}-theme.css';`;
   if (content.includes(importLine)) {
     return { updated: content, changed: false };
   }
@@ -1684,8 +2744,8 @@ function insertGlobalsImport(content, slug) {
   lines.splice(insertAt, 0, importLine);
   return { updated: lines.join("\n"), changed: true };
 }
-function insertThemeConfig(content, slug, label, group) {
-  if (content.includes(`value: "${slug}"`)) {
+function insertThemeConfig(content, slug2, label, group) {
+  if (content.includes(`value: "${slug2}"`)) {
     return { updated: content, changed: false };
   }
   const escapedGroup = group.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1718,7 +2778,7 @@ function insertThemeConfig(content, slug, label, group) {
   }
   let insertPos = closingBracket;
   for (const e of entries) {
-    if (slug < e.value) {
+    if (slug2 < e.value) {
       insertPos = e.start;
       break;
     }
@@ -1727,7 +2787,7 @@ function insertThemeConfig(content, slug, label, group) {
   const lineContent = content.slice(prevNewline + 1, insertPos);
   const indentMatch = /^(\s*)/.exec(lineContent);
   const indent = indentMatch ? indentMatch[1] : "      ";
-  const newEntry = `{ value: "${slug}", label: "${label}" }`;
+  const newEntry = `{ value: "${slug2}", label: "${label}" }`;
   const insertion = entries.length === 0 ? `
 ${indent}${newEntry},
     ` : `${indent}${newEntry},
@@ -1736,10 +2796,10 @@ ${indent}${newEntry},
   return { updated, changed: true };
 }
 function themeRegisterCommand(file, cwd, options) {
-  const filePath = resolve6(cwd, file);
+  const filePath = resolve7(cwd, file);
   let yamlContent;
   try {
-    yamlContent = readFileSync9(filePath, "utf-8");
+    yamlContent = readFileSync12(filePath, "utf-8");
   } catch {
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: `Could not read file: ${filePath}` }));
@@ -1763,7 +2823,7 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const slug = toSlug(data.config.name);
+  const slug2 = toSlug(data.config.name);
   const label = toLabel(data.config.name);
   const adapterInput = {
     primitives: data.primitives,
@@ -1782,11 +2842,11 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join8(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join8(docsAppDir, `${slug}-theme.css`);
-  const globalsPath = join8(docsAppDir, "globals.css");
-  const themeConfigPath = join8(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  if (!existsSync7(docsAppDir)) {
+  const docsAppDir = join12(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join12(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join12(docsAppDir, "globals.css");
+  const themeConfigPath = join12(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync9(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -1799,8 +2859,8 @@ function themeRegisterCommand(file, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync9(globalsPath, "utf-8");
-    themeConfigContent = readFileSync9(themeConfigPath, "utf-8");
+    globalsContent = readFileSync12(globalsPath, "utf-8");
+    themeConfigContent = readFileSync12(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -1811,12 +2871,12 @@ function themeRegisterCommand(file, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync7(cssFilePath);
-  const cssChanged = !cssExists || readFileSync9(cssFilePath, "utf-8") !== css;
-  const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug);
+  const cssExists = existsSync9(cssFilePath);
+  const cssChanged = !cssExists || readFileSync12(cssFilePath, "utf-8") !== css;
+  const { updated: newGlobals, changed: globalsChanged } = insertGlobalsImport(globalsContent, slug2);
   const { updated: newThemeConfig, changed: themeConfigChanged, error: configError } = insertThemeConfig(
     themeConfigContent,
-    slug,
+    slug2,
     label,
     options.group
   );
@@ -1834,7 +2894,7 @@ function themeRegisterCommand(file, cwd, options) {
       console.log(JSON.stringify({
         success: true,
         dryRun: true,
-        slug,
+        slug: slug2,
         label,
         group: options.group,
         changes: {
@@ -1845,7 +2905,7 @@ function themeRegisterCommand(file, cwd, options) {
       }));
     } else {
       logger.info("Dry run \u2014 no files written");
-      logger.item(`Theme: ${label} (${slug})`);
+      logger.item(`Theme: ${label} (${slug2})`);
       logger.item(`Group: ${options.group}`);
       logger.item(`CSS file: ${cssFilePath} \u2014 ${cssChanged ? cssExists ? "update" : "create" : "no change"}`);
       logger.item(`globals.css: ${globalsChanged ? "add import" : "already registered"}`);
@@ -1856,13 +2916,13 @@ function themeRegisterCommand(file, cwd, options) {
   try {
     if (cssChanged) {
       mkdirSync4(docsAppDir, { recursive: true });
-      writeFileSync6(cssFilePath, css, "utf-8");
+      writeFileSync7(cssFilePath, css, "utf-8");
     }
     if (globalsChanged) {
-      writeFileSync6(globalsPath, newGlobals, "utf-8");
+      writeFileSync7(globalsPath, newGlobals, "utf-8");
     }
     if (themeConfigChanged) {
-      writeFileSync6(themeConfigPath, newThemeConfig, "utf-8");
+      writeFileSync7(themeConfigPath, newThemeConfig, "utf-8");
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -1877,14 +2937,14 @@ function themeRegisterCommand(file, cwd, options) {
   if (options.json) {
     console.log(JSON.stringify({
       success: true,
-      slug,
+      slug: slug2,
       label,
       group: options.group,
       files: { css: cssFilePath, globals: globalsPath, themeConfig: themeConfigPath },
       changes: { cssFile: cssChanged, globalsCSS: globalsChanged, themeConfig: themeConfigChanged }
     }));
   } else {
-    logger.success(`Theme registered: ${label} (${slug})`);
+    logger.success(`Theme registered: ${label} (${slug2})`);
     logger.item(`Group: ${options.group}`);
     if (cssChanged) logger.item(`CSS: ${cssFilePath}`);
     if (globalsChanged) logger.item(`globals.css updated`);
@@ -1896,28 +2956,28 @@ function themeRegisterCommand(file, cwd, options) {
 }
 
 // src/commands/theme-unregister.ts
-import { readFileSync as readFileSync10, writeFileSync as writeFileSync7, existsSync as existsSync8, unlinkSync } from "fs";
-import { join as join9 } from "path";
-function removeGlobalsImport(content, slug) {
-  const importLine = `@import './${slug}-theme.css';`;
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync8, existsSync as existsSync10, unlinkSync } from "fs";
+import { join as join13 } from "path";
+function removeGlobalsImport(content, slug2) {
+  const importLine = `@import './${slug2}-theme.css';`;
   if (!content.includes(importLine)) {
     return { updated: content, changed: false };
   }
   const updated = content.split("\n").filter((line) => line !== importLine).join("\n");
   return { updated, changed: true };
 }
-function removeThemeConfigEntry(content, slug) {
-  if (!content.includes(`value: "${slug}"`)) {
+function removeThemeConfigEntry(content, slug2) {
+  if (!content.includes(`value: "${slug2}"`)) {
     return { updated: content, changed: false };
   }
   const entryPattern = new RegExp(
-    `\\s*\\{\\s*value:\\s*"${slug.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^}]*\\},?`,
+    `\\s*\\{\\s*value:\\s*"${slug2.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"[^}]*\\},?`,
     "g"
   );
   const updated = content.replace(entryPattern, "");
   return { updated, changed: true };
 }
-function themeUnregisterCommand(slug, cwd, options) {
+function themeUnregisterCommand(slug2, cwd, options) {
   const repoRoot = findRepoRoot(cwd);
   if (!repoRoot) {
     const msg = "Could not locate repo root (packages/docs/ not found). Run from within the visor repo.";
@@ -1929,11 +2989,11 @@ function themeUnregisterCommand(slug, cwd, options) {
     process.exit(1);
     return;
   }
-  const docsAppDir = join9(repoRoot, "packages", "docs", "app");
-  const cssFilePath = join9(docsAppDir, `${slug}-theme.css`);
-  const globalsPath = join9(docsAppDir, "globals.css");
-  const themeConfigPath = join9(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  if (!existsSync8(docsAppDir)) {
+  const docsAppDir = join13(repoRoot, "packages", "docs", "app");
+  const cssFilePath = join13(docsAppDir, `${slug2}-theme.css`);
+  const globalsPath = join13(docsAppDir, "globals.css");
+  const themeConfigPath = join13(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  if (!existsSync10(docsAppDir)) {
     const msg = `Docs app directory not found: ${docsAppDir}`;
     if (options.json) {
       console.log(JSON.stringify({ success: false, error: msg }));
@@ -1946,8 +3006,8 @@ function themeUnregisterCommand(slug, cwd, options) {
   let globalsContent = "";
   let themeConfigContent = "";
   try {
-    globalsContent = readFileSync10(globalsPath, "utf-8");
-    themeConfigContent = readFileSync10(themeConfigPath, "utf-8");
+    globalsContent = readFileSync13(globalsPath, "utf-8");
+    themeConfigContent = readFileSync13(themeConfigPath, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -1958,21 +3018,21 @@ function themeUnregisterCommand(slug, cwd, options) {
     process.exit(1);
     return;
   }
-  const cssExists = existsSync8(cssFilePath);
-  const { updated: newGlobals, changed: globalsChanged } = removeGlobalsImport(globalsContent, slug);
-  const { updated: newThemeConfig, changed: themeConfigChanged } = removeThemeConfigEntry(themeConfigContent, slug);
+  const cssExists = existsSync10(cssFilePath);
+  const { updated: newGlobals, changed: globalsChanged } = removeGlobalsImport(globalsContent, slug2);
+  const { updated: newThemeConfig, changed: themeConfigChanged } = removeThemeConfigEntry(themeConfigContent, slug2);
   if (!cssExists && !globalsChanged && !themeConfigChanged) {
     if (options.json) {
-      console.log(JSON.stringify({ success: true, slug, changes: { cssFile: false, globalsCSS: false, themeConfig: false } }));
+      console.log(JSON.stringify({ success: true, slug: slug2, changes: { cssFile: false, globalsCSS: false, themeConfig: false } }));
     } else {
-      logger.info(`Theme "${slug}" is not registered \u2014 nothing to remove.`);
+      logger.info(`Theme "${slug2}" is not registered \u2014 nothing to remove.`);
     }
     return;
   }
   try {
     if (cssExists) unlinkSync(cssFilePath);
-    if (globalsChanged) writeFileSync7(globalsPath, newGlobals, "utf-8");
-    if (themeConfigChanged) writeFileSync7(themeConfigPath, newThemeConfig, "utf-8");
+    if (globalsChanged) writeFileSync8(globalsPath, newGlobals, "utf-8");
+    if (themeConfigChanged) writeFileSync8(themeConfigPath, newThemeConfig, "utf-8");
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
     if (options.json) {
@@ -1986,11 +3046,11 @@ function themeUnregisterCommand(slug, cwd, options) {
   if (options.json) {
     console.log(JSON.stringify({
       success: true,
-      slug,
+      slug: slug2,
       changes: { cssFile: cssExists, globalsCSS: globalsChanged, themeConfig: themeConfigChanged }
     }));
   } else {
-    logger.success(`Theme unregistered: ${slug}`);
+    logger.success(`Theme unregistered: ${slug2}`);
     if (cssExists) logger.item(`CSS file removed: ${cssFilePath}`);
     if (globalsChanged) logger.item(`globals.css updated`);
     if (themeConfigChanged) logger.item(`theme-config.ts updated`);
@@ -1999,32 +3059,47 @@ function themeUnregisterCommand(slug, cwd, options) {
 
 // src/commands/theme-sync.ts
 import {
-  readFileSync as readFileSync11,
-  writeFileSync as writeFileSync8,
+  readFileSync as readFileSync14,
+  writeFileSync as writeFileSync9,
   mkdirSync as mkdirSync5,
-  existsSync as existsSync9,
-  readdirSync as readdirSync2,
+  existsSync as existsSync11,
+  readdirSync as readdirSync4,
   unlinkSync as unlinkSync2,
   copyFileSync
 } from "fs";
-import { join as join10, basename as basename2 } from "path";
+import { join as join14, basename as basename2 } from "path";
 import { parse as parseYaml2 } from "yaml";
 import { generateThemeData as generateThemeData4 } from "@loworbitstudio/visor-theme-engine";
 import { docsAdapter as docsAdapter3 } from "@loworbitstudio/visor-theme-engine/adapters";
-var GLOBALS_BEGIN_MARKER = "/* BEGIN visor-theme-imports \u2014 generated by `visor theme sync` */";
+var GLOBALS_BEGIN_MARKER = "/* BEGIN visor-theme-imports \u2014 managed by `visor theme sync` */";
 var GLOBALS_END_MARKER = "/* END visor-theme-imports */";
+var STOCK_GROUPS_BEGIN_MARKER = "/* BEGIN visor-stock-themes \u2014 managed by `visor theme sync` */";
+var STOCK_GROUPS_END_MARKER = "/* END visor-stock-themes */";
 var GITIGNORE_BEGIN_MARKER = "# BEGIN visor-custom-theme-css (managed by `visor theme sync` \u2014 do not edit manually)";
 var GITIGNORE_END_MARKER = "# END visor-custom-theme-css";
-var THEME_CONFIG_HEADER = "// This file is auto-generated by `visor theme sync`. Do not edit manually.\n";
+var CUSTOM_OVERLAY_CSS_PATH = "packages/docs/app/custom-themes.generated.css";
+var CUSTOM_OVERLAY_TS_PATH = "packages/docs/lib/theme-config.custom.generated.ts";
+var CUSTOM_OVERLAY_IMPORT_LINE = "@import './custom-themes.generated.css';";
 function scanThemeDir(dir) {
-  if (!existsSync9(dir)) return [];
-  return readdirSync2(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join10(dir, f));
+  if (!existsSync11(dir)) return [];
+  return readdirSync4(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join14(dir, f));
 }
 function extractGroup(yamlContent) {
   const parsed = parseYaml2(yamlContent);
   if (typeof parsed?.group === "string") return parsed.group;
   return void 0;
 }
+function extractLabel(yamlContent) {
+  const parsed = parseYaml2(yamlContent);
+  if (typeof parsed?.label === "string") return parsed.label;
+  return void 0;
+}
+function extractDefaultMode(yamlContent) {
+  const parsed = parseYaml2(yamlContent);
+  const v = parsed?.["default-mode"];
+  if (v === "dark" || v === "light") return v;
+  return void 0;
+}
 function sortGroups(groups) {
   return [...groups].sort((a, b) => {
     if (a === "Visor") return -1;
@@ -2032,9 +3107,60 @@ function sortGroups(groups) {
     return a.localeCompare(b);
   });
 }
-function generateThemeConfig(entries) {
+function updateGlobalsImports(content, stockSlugs) {
+  const importLines = [...stockSlugs].sort().map((slug2) => `@import './${slug2}-theme.css';`).join("\n");
+  const newBlock = `${GLOBALS_BEGIN_MARKER}
+${importLines}
+${GLOBALS_END_MARKER}`;
+  let updated;
+  const beginIdx = content.indexOf(GLOBALS_BEGIN_MARKER);
+  const endIdx = content.indexOf(GLOBALS_END_MARKER);
+  if (beginIdx !== -1 && endIdx !== -1) {
+    updated = content.slice(0, beginIdx) + newBlock + content.slice(endIdx + GLOBALS_END_MARKER.length);
+  } else {
+    const themeImportPattern = /^@import '\.\/[\w-]+-theme\.css';\n?/gm;
+    const lines = content.split("\n");
+    let firstThemeIdx = -1;
+    let lastThemeIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (/^@import '\.\/[\w-]+-theme\.css';/.test(lines[i])) {
+        if (firstThemeIdx === -1) firstThemeIdx = i;
+        lastThemeIdx = i;
+      }
+    }
+    if (firstThemeIdx !== -1) {
+      const before = lines.slice(0, firstThemeIdx);
+      const after = lines.slice(lastThemeIdx + 1);
+      updated = [...before, newBlock, ...after].join("\n");
+    } else {
+      void themeImportPattern;
+      const lastImportIdx = lines.reduce(
+        (last, line, i) => line.startsWith("@import") ? i : last,
+        -1
+      );
+      const insertAt = lastImportIdx + 1;
+      lines.splice(insertAt, 0, newBlock);
+      updated = lines.join("\n");
+    }
+  }
+  updated = ensureCustomOverlayImport(updated);
+  return updated;
+}
+function ensureCustomOverlayImport(content) {
+  const endMarkerIdx = content.indexOf(GLOBALS_END_MARKER);
+  if (endMarkerIdx === -1) return content;
+  const afterMarker = content.slice(endMarkerIdx + GLOBALS_END_MARKER.length);
+  if (afterMarker.trimStart().startsWith(CUSTOM_OVERLAY_IMPORT_LINE)) return content;
+  const withoutStale = content.replace(
+    new RegExp(`\\n?${CUSTOM_OVERLAY_IMPORT_LINE.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "g"),
+    ""
+  );
+  const markerEnd = withoutStale.indexOf(GLOBALS_END_MARKER) + GLOBALS_END_MARKER.length;
+  return withoutStale.slice(0, markerEnd) + "\n" + CUSTOM_OVERLAY_IMPORT_LINE + withoutStale.slice(markerEnd);
+}
+function updateStockThemeConfigBlock(content, stockEntries) {
   const groupMap = /* @__PURE__ */ new Map();
-  for (const entry of entries) {
+  for (const entry of stockEntries) {
     if (!groupMap.has(entry.group)) groupMap.set(entry.group, []);
     groupMap.get(entry.group).push(entry);
   }
@@ -2044,7 +3170,10 @@ function generateThemeConfig(entries) {
   }
   const groupsTs = sortedGroupNames.map((groupName) => {
     const groupEntries = groupMap.get(groupName);
-    const themesTs = groupEntries.map((e) => `    { value: "${e.slug}", label: "${e.label}", yamlFile: "${e.yamlFilename}" },`).join("\n");
+    const themesTs = groupEntries.map((e) => {
+      const modePart = e.defaultMode ? `, defaultMode: "${e.defaultMode}"` : "";
+      return `      { value: "${e.slug}", label: "${e.label}", yamlFile: "${e.yamlFilename}"${modePart} },`;
+    }).join("\n");
     return `  {
     label: "${groupName}",
     themes: [
@@ -2052,62 +3181,68 @@ ${themesTs}
     ],
   },`;
   }).join("\n");
-  return `${THEME_CONFIG_HEADER}
-export interface ThemeEntry {
-  value: string;
-  label: string;
-  /** Filename (without .visor.yaml extension) if a YAML config exists in /public/themes/ */
-  yamlFile?: string;
-}
-
-export interface ThemeGroup {
-  label: string;
-  themes: ThemeEntry[];
-}
-
-export const THEME_GROUPS: ThemeGroup[] = [
+  const newBlock = `${STOCK_GROUPS_BEGIN_MARKER}
+const STOCK_GROUPS: ThemeGroup[] = [
 ${groupsTs}
 ];
-
-export const ALL_THEMES = THEME_GROUPS.flatMap((g) => g.themes.map((t) => t.value));
-`;
+${STOCK_GROUPS_END_MARKER}`;
+  const beginIdx = content.indexOf(STOCK_GROUPS_BEGIN_MARKER);
+  const endIdx = content.indexOf(STOCK_GROUPS_END_MARKER);
+  if (beginIdx !== -1 && endIdx !== -1) {
+    return content.slice(0, beginIdx) + newBlock + content.slice(endIdx + STOCK_GROUPS_END_MARKER.length);
+  }
+  const themeGroupsExportIdx = content.indexOf("export const THEME_GROUPS");
+  if (themeGroupsExportIdx !== -1) {
+    return content.slice(0, themeGroupsExportIdx) + newBlock + "\n\n" + content.slice(themeGroupsExportIdx);
+  }
+  return content + "\n\n" + newBlock;
 }
-function updateGlobalsImports(content, slugs) {
-  const importLines = [...slugs].sort().map((slug) => `@import './${slug}-theme.css';`).join("\n");
-  const newBlock = `${GLOBALS_BEGIN_MARKER}
+function generateCustomOverlayCss(customEntries) {
+  if (customEntries.length === 0) {
+    return "/* generated by `visor theme sync` \u2014 empty when no custom themes are present */\n";
+  }
+  const importLines = [...customEntries].sort((a, b) => a.slug.localeCompare(b.slug)).map((e) => `@import './${e.slug}-theme.css';`).join("\n");
+  return `/* generated by \`visor theme sync\` \u2014 do not edit manually */
 ${importLines}
-${GLOBALS_END_MARKER}`;
-  const beginIdx = content.indexOf(GLOBALS_BEGIN_MARKER);
-  const endIdx = content.indexOf(GLOBALS_END_MARKER);
-  if (beginIdx !== -1 && endIdx !== -1) {
-    return content.slice(0, beginIdx) + newBlock + content.slice(endIdx + GLOBALS_END_MARKER.length);
+`;
+}
+function generateCustomOverlayTs(customEntries) {
+  if (customEntries.length === 0) {
+    return `import type { ThemeGroup } from "./theme-config";
+export const customThemeGroups: ThemeGroup[] = [];
+`;
   }
-  const themeImportPattern = /^@import '\.\/[\w-]+-theme\.css';\n?/gm;
-  const lines = content.split("\n");
-  let firstThemeIdx = -1;
-  let lastThemeIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^@import '\.\/[\w-]+-theme\.css';/.test(lines[i])) {
-      if (firstThemeIdx === -1) firstThemeIdx = i;
-      lastThemeIdx = i;
-    }
+  const groupMap = /* @__PURE__ */ new Map();
+  for (const entry of customEntries) {
+    if (!groupMap.has(entry.group)) groupMap.set(entry.group, []);
+    groupMap.get(entry.group).push(entry);
   }
-  if (firstThemeIdx !== -1) {
-    const before = lines.slice(0, firstThemeIdx);
-    const after = lines.slice(lastThemeIdx + 1);
-    return [...before, newBlock, ...after].join("\n");
+  const sortedGroupNames = sortGroups([...groupMap.keys()]);
+  for (const [, groupEntries] of groupMap) {
+    groupEntries.sort((a, b) => a.slug.localeCompare(b.slug));
   }
-  void themeImportPattern;
-  const lastImportIdx = lines.reduce(
-    (last, line, i) => line.startsWith("@import") ? i : last,
-    -1
-  );
-  const insertAt = lastImportIdx + 1;
-  lines.splice(insertAt, 0, newBlock);
-  return lines.join("\n");
+  const groupsTs = sortedGroupNames.map((groupName) => {
+    const groupEntries = groupMap.get(groupName);
+    const themesTs = groupEntries.map((e) => {
+      const modePart = e.defaultMode ? `, defaultMode: "${e.defaultMode}"` : "";
+      return `      { value: "${e.slug}", label: "${e.label}", yamlFile: "${e.yamlFilename}"${modePart} },`;
+    }).join("\n");
+    return `  {
+    label: "${groupName}",
+    themes: [
+${themesTs}
+    ],
+  },`;
+  }).join("\n");
+  return `import type { ThemeGroup } from "./theme-config";
+// generated by \`visor theme sync\` \u2014 do not edit manually
+export const customThemeGroups: ThemeGroup[] = [
+${groupsTs}
+];
+`;
 }
 function updateGitignoreBlock(content, customSlugs) {
-  const cssLines = customSlugs.sort().map((slug) => `packages/docs/app/${slug}-theme.css`).join("\n");
+  const cssLines = customSlugs.sort().map((slug2) => `packages/docs/app/${slug2}-theme.css`).join("\n");
   const newBlock = `${GITIGNORE_BEGIN_MARKER}
 ${cssLines}
 ${GITIGNORE_END_MARKER}`;
@@ -2130,13 +3265,16 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const themesDir = join10(repoRoot, "themes");
-  const customThemesDir = join10(repoRoot, "custom-themes");
-  const docsAppDir = join10(repoRoot, "packages", "docs", "app");
-  const docsPublicThemesDir = join10(repoRoot, "packages", "docs", "public", "themes");
-  const themeConfigPath = join10(repoRoot, "packages", "docs", "lib", "theme-config.ts");
-  const globalsPath = join10(docsAppDir, "globals.css");
-  const gitignorePath = join10(repoRoot, ".gitignore");
+  const themesDir = join14(repoRoot, "themes");
+  const customThemesDir = join14(repoRoot, "custom-themes");
+  const docsAppDir = join14(repoRoot, "packages", "docs", "app");
+  const docsLibDir = join14(repoRoot, "packages", "docs", "lib");
+  const docsPublicThemesDir = join14(repoRoot, "packages", "docs", "public", "themes");
+  const themeConfigPath = join14(repoRoot, "packages", "docs", "lib", "theme-config.ts");
+  const globalsPath = join14(docsAppDir, "globals.css");
+  const gitignorePath = join14(repoRoot, ".gitignore");
+  const customOverlayCssPath = join14(repoRoot, CUSTOM_OVERLAY_CSS_PATH);
+  const customOverlayTsPath = join14(repoRoot, CUSTOM_OVERLAY_TS_PATH);
   const stockFiles = scanThemeDir(themesDir);
   const customFiles = scanThemeDir(customThemesDir);
   if (stockFiles.length === 0 && customFiles.length === 0) {
@@ -2153,7 +3291,7 @@ function themeSyncCommand(cwd, options) {
   const processFile = (filePath, isCustom) => {
     let yamlContent;
     try {
-      yamlContent = readFileSync11(filePath, "utf-8");
+      yamlContent = readFileSync14(filePath, "utf-8");
     } catch {
       errors.push(`Could not read: ${filePath}`);
       return;
@@ -2165,12 +3303,13 @@ function themeSyncCommand(cwd, options) {
       errors.push(`Failed to parse ${basename2(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`);
       return;
     }
-    const slug = toSlug(data.config.name);
-    const label = toLabel(data.config.name);
+    const slug2 = toSlug(data.config.name);
+    const label = extractLabel(yamlContent) ?? toLabel(data.config.name);
     const group = extractGroup(yamlContent) ?? (isCustom ? "Custom" : "Visor");
+    const defaultMode = extractDefaultMode(yamlContent);
     const css = docsAdapter3({ primitives: data.primitives, tokens: data.tokens, config: data.config });
     const yamlFilename = basename2(filePath).replace(/\.visor\.yaml$/, "");
-    manifest.push({ slug, label, group, css, yamlFilename, isCustom });
+    manifest.push({ slug: slug2, label, group, defaultMode, css, yamlFilename, isCustom });
   };
   for (const f of stockFiles) processFile(f, false);
   for (const f of customFiles) processFile(f, true);
@@ -2183,14 +3322,18 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const newThemeConfig = generateThemeConfig(manifest);
+  const stockManifest = manifest.filter((e) => !e.isCustom);
+  const customManifest = manifest.filter((e) => e.isCustom);
+  const stockSlugs = stockManifest.map((e) => e.slug);
+  const customSlugs = customManifest.map((e) => e.slug);
   const allSlugs = manifest.map((e) => e.slug);
-  const customSlugs = manifest.filter((e) => e.isCustom).map((e) => e.slug);
   let globalsContent;
+  let themeConfigContent;
   let gitignoreContent;
   try {
-    globalsContent = readFileSync11(globalsPath, "utf-8");
-    gitignoreContent = existsSync9(gitignorePath) ? readFileSync11(gitignorePath, "utf-8") : "";
+    globalsContent = readFileSync14(globalsPath, "utf-8");
+    themeConfigContent = readFileSync14(themeConfigPath, "utf-8");
+    gitignoreContent = existsSync11(gitignorePath) ? readFileSync14(gitignorePath, "utf-8") : "";
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Could not read docs files";
     if (options.json) {
@@ -2201,12 +3344,17 @@ function themeSyncCommand(cwd, options) {
     process.exit(1);
     return;
   }
-  const newGlobals = updateGlobalsImports(globalsContent, allSlugs);
+  const newGlobals = updateGlobalsImports(globalsContent, stockSlugs);
+  const newThemeConfig = updateStockThemeConfigBlock(themeConfigContent, stockManifest);
   const newGitignore = customSlugs.length > 0 ? updateGitignoreBlock(gitignoreContent, customSlugs) : gitignoreContent;
-  const existingCssFiles = existsSync9(docsAppDir) ? readdirSync2(docsAppDir).filter((f) => f.endsWith("-theme.css")) : [];
+  const newCustomOverlayCss = generateCustomOverlayCss(customManifest);
+  const newCustomOverlayTs = generateCustomOverlayTs(customManifest);
+  const existingCssFiles = existsSync11(docsAppDir) ? readdirSync4(docsAppDir).filter(
+    (f) => f.endsWith("-theme.css") && f !== "custom-themes.generated.css"
+  ) : [];
   const newCssSet = new Set(allSlugs.map((s) => `${s}-theme.css`));
   const staleCssFiles = existingCssFiles.filter((f) => !newCssSet.has(f));
-  const existingPublicYamls = existsSync9(docsPublicThemesDir) ? readdirSync2(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
+  const existingPublicYamls = existsSync11(docsPublicThemesDir) ? readdirSync4(docsPublicThemesDir).filter((f) => f.endsWith(".visor.yaml")) : [];
   const newPublicYamlSet = new Set(manifest.map((e) => `${e.yamlFilename}.visor.yaml`));
   const stalePublicYamls = existingPublicYamls.filter((f) => !newPublicYamlSet.has(f));
   if (options.dryRun) {
@@ -2216,6 +3364,8 @@ function themeSyncCommand(cwd, options) {
       cssFilesDeleted: staleCssFiles.map((f) => `packages/docs/app/${f}`),
       themeConfig: themeConfigPath,
       globalsCSS: globalsPath,
+      customOverlayCss: CUSTOM_OVERLAY_CSS_PATH,
+      customOverlayTs: CUSTOM_OVERLAY_TS_PATH,
       gitignore: gitignorePath,
       publicYamlsCopied: manifest.map((e) => `packages/docs/public/themes/${e.yamlFilename}.visor.yaml`),
       publicYamlsDeleted: stalePublicYamls.map((f) => `packages/docs/public/themes/${f}`)
@@ -2224,7 +3374,7 @@ function themeSyncCommand(cwd, options) {
       console.log(JSON.stringify({ success: true, dryRun: true, changes }));
     } else {
       logger.info("Dry run \u2014 no files written");
-      logger.item(`Themes discovered: ${manifest.length} (${manifest.filter((e) => !e.isCustom).length} stock, ${manifest.filter((e) => e.isCustom).length} custom)`);
+      logger.item(`Themes discovered: ${manifest.length} (${stockManifest.length} stock, ${customManifest.length} custom)`);
       manifest.forEach((e) => logger.item(`  ${e.slug} \u2014 group: ${e.group}`));
       if (staleCssFiles.length > 0) logger.item(`CSS files to delete: ${staleCssFiles.join(", ")}`);
       if (stalePublicYamls.length > 0) logger.item(`Public YAMLs to delete: ${stalePublicYamls.join(", ")}`);
@@ -2233,25 +3383,28 @@ function themeSyncCommand(cwd, options) {
   }
   try {
     mkdirSync5(docsAppDir, { recursive: true });
+    mkdirSync5(docsLibDir, { recursive: true });
     mkdirSync5(docsPublicThemesDir, { recursive: true });
     for (const entry of manifest) {
-      writeFileSync8(join10(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
+      writeFileSync9(join14(docsAppDir, `${entry.slug}-theme.css`), entry.css, "utf-8");
     }
     for (const stale of staleCssFiles) {
-      unlinkSync2(join10(docsAppDir, stale));
+      unlinkSync2(join14(docsAppDir, stale));
     }
-    writeFileSync8(themeConfigPath, newThemeConfig, "utf-8");
-    writeFileSync8(globalsPath, newGlobals, "utf-8");
-    if (existsSync9(gitignorePath)) {
-      writeFileSync8(gitignorePath, newGitignore, "utf-8");
+    writeFileSync9(customOverlayCssPath, newCustomOverlayCss, "utf-8");
+    writeFileSync9(customOverlayTsPath, newCustomOverlayTs, "utf-8");
+    writeFileSync9(themeConfigPath, newThemeConfig, "utf-8");
+    writeFileSync9(globalsPath, newGlobals, "utf-8");
+    if (existsSync11(gitignorePath)) {
+      writeFileSync9(gitignorePath, newGitignore, "utf-8");
     }
     const allSourceFiles = [...stockFiles, ...customFiles];
     for (const srcFile of allSourceFiles) {
       const filename = basename2(srcFile);
-      copyFileSync(srcFile, join10(docsPublicThemesDir, filename));
+      copyFileSync(srcFile, join14(docsPublicThemesDir, filename));
     }
     for (const stale of stalePublicYamls) {
-      unlinkSync2(join10(docsPublicThemesDir, stale));
+      unlinkSync2(join14(docsPublicThemesDir, stale));
     }
   } catch (err) {
     const msg = err instanceof Error ? err.message : "Write failed";
@@ -2260,37 +3413,329 @@ function themeSyncCommand(cwd, options) {
     } else {
       logger.error(msg);
     }
-    process.exit(2);
+    process.exit(2);
+    return;
+  }
+  if (options.json) {
+    console.log(JSON.stringify({
+      success: true,
+      themes: manifest.length,
+      stock: stockManifest.length,
+      custom: customManifest.length,
+      staleCssDeleted: staleCssFiles.length,
+      staleYamlsDeleted: stalePublicYamls.length,
+      slugs: allSlugs
+    }));
+  } else {
+    logger.success(`Theme sync complete \u2014 ${manifest.length} themes registered`);
+    logger.item(`Stock: ${stockManifest.map((e) => e.slug).join(", ")}`);
+    if (customManifest.length > 0) {
+      logger.item(`Custom: ${customManifest.map((e) => e.slug).join(", ")}`);
+    }
+    if (staleCssFiles.length > 0) {
+      logger.item(`Removed stale CSS: ${staleCssFiles.join(", ")}`);
+    }
+  }
+}
+
+// src/commands/theme-batch-apply-flutter.ts
+import {
+  readFileSync as readFileSync15,
+  writeFileSync as writeFileSync10,
+  mkdirSync as mkdirSync6,
+  existsSync as existsSync12,
+  readdirSync as readdirSync5,
+  rmSync
+} from "fs";
+import { join as join15, basename as basename3, dirname as dirname6 } from "path";
+import { generateThemeData as generateThemeData5 } from "@loworbitstudio/visor-theme-engine";
+import { flutterAdapter as flutterAdapter2 } from "@loworbitstudio/visor-theme-engine/adapters";
+function scanThemeDir2(dir) {
+  if (!existsSync12(dir)) return [];
+  return readdirSync5(dir).filter((f) => f.endsWith(".visor.yaml")).map((f) => join15(dir, f)).sort();
+}
+function slugToCamel(slug2) {
+  return slug2.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+function mapAdapterPath(relPath) {
+  if (relPath === "pubspec.yaml") return null;
+  if (relPath === "lib/ui.dart") return null;
+  if (relPath.startsWith("lib/src/")) {
+    return relPath.slice("lib/src/".length);
+  }
+  return null;
+}
+function emitVisorThemesPubspec() {
+  return [
+    `name: visor_themes`,
+    `description: All Visor-generated Flutter ThemeData packages \u2014 4 stock + 7 custom themes. GENERATED \u2014 regenerate with \`npm run themes:apply-flutter\`.`,
+    `version: 0.1.0+1`,
+    `publish_to: none`,
+    ``,
+    `environment:`,
+    `  sdk: ^3.5.0`,
+    `  flutter: ^3.24.0`,
+    ``,
+    `dependencies:`,
+    `  flutter:`,
+    `    sdk: flutter`,
+    `  visor_core: ^0.1.0`,
+    ``,
+    `dev_dependencies:`,
+    `  flutter_test:`,
+    `    sdk: flutter`,
+    `  flutter_lints: ^5.0.0`,
+    ``,
+    `flutter:`,
+    `  uses-material-design: true`,
+    ``
+  ].join("\n");
+}
+function emitVisorThemesPubspecOverrides() {
+  return [
+    `# Path overrides for in-monorepo development.`,
+    `# visor_core is not yet published to pub.dev; this forces the local copy.`,
+    `dependency_overrides:`,
+    `  visor_core:`,
+    `    path: ../visor-flutter`,
+    ``
+  ].join("\n");
+}
+function emitAnalysisOptions() {
+  return [
+    `include: package:flutter_lints/flutter.yaml`,
+    ``,
+    `linter:`,
+    `  rules:`,
+    `    - avoid_print`,
+    ``
+  ].join("\n");
+}
+function slugToDartPrefix(slug2) {
+  return slug2.replace(/-/g, "_") + "_t";
+}
+function emitMetaBarrel(slugs) {
+  const lines = [
+    `// GENERATED BY visor \u2014 DO NOT EDIT.`,
+    `// Regenerate with \`npm run themes:apply-flutter\`.`,
+    `//`,
+    `// Aggregates Dart ThemeData for all Visor themes (4 stock + 7 custom).`,
+    `// Access themes via [VisorThemes], e.g. VisorThemes.blackout.light`,
+    ``,
+    `import 'package:flutter/material.dart';`,
+    ``,
+    `// Re-export visor_core so consumers access VisorColorsData etc. with`,
+    `// a single import of this package.`,
+    `export 'package:visor_core/visor_core.dart';`,
+    ``
+  ];
+  for (const slug2 of slugs) {
+    const prefix = slugToDartPrefix(slug2);
+    lines.push(`import 'src/${slug2}/theme/visor_theme.dart' as ${prefix};`);
+  }
+  lines.push(``);
+  lines.push(`/// A light/dark [ThemeData] pair for a single Visor theme.`);
+  lines.push(`class VisorThemePair {`);
+  lines.push(`  final ThemeData light;`);
+  lines.push(`  final ThemeData dark;`);
+  lines.push(`  const VisorThemePair({required this.light, required this.dark});`);
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`/// Static access to all Visor-generated Flutter themes.`);
+  lines.push(`///`);
+  lines.push(`/// Usage:`);
+  lines.push(`/// \`\`\`dart`);
+  lines.push(`/// MaterialApp(`);
+  lines.push(`///   theme: VisorThemes.blackout.light,`);
+  lines.push(`///   darkTheme: VisorThemes.blackout.dark,`);
+  lines.push(`/// );`);
+  lines.push(`/// \`\`\``);
+  lines.push(`sealed class VisorThemes {`);
+  for (const slug2 of slugs) {
+    const camel = slugToCamel(slug2);
+    const prefix = slugToDartPrefix(slug2);
+    lines.push(`  static VisorThemePair get ${camel} => VisorThemePair(`);
+    lines.push(`    light: ${prefix}.VisorAppTheme.light,`);
+    lines.push(`    dark: ${prefix}.VisorAppTheme.dark,`);
+    lines.push(`  );`);
+  }
+  lines.push(`}`);
+  lines.push(``);
+  return lines.join("\n");
+}
+function emitGitignore() {
+  return [
+    `.dart_tool/`,
+    `.packages`,
+    `build/`,
+    `pubspec.lock`,
+    `*.g.dart`,
+    ``
+  ].join("\n");
+}
+function themeBatchApplyFlutterCommand(cwd, options) {
+  const repoRoot = findRepoRoot(cwd);
+  if (!repoRoot) {
+    const msg = "Could not locate repo root (packages/docs/ not found). Run from within the visor repo.";
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: msg }));
+    } else {
+      logger.error(msg);
+    }
+    process.exit(1);
+    return;
+  }
+  const themesDir = join15(repoRoot, "themes");
+  const customThemesDir = join15(repoRoot, "custom-themes");
+  const outputDir = join15(repoRoot, "packages", "visor_themes");
+  const stockFiles = scanThemeDir2(themesDir);
+  const customFiles = scanThemeDir2(customThemesDir);
+  const allFiles = [...stockFiles, ...customFiles];
+  if (allFiles.length === 0) {
+    const msg = `No .visor.yaml files found in themes/ or custom-themes/. Nothing to generate.`;
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: msg }));
+    } else {
+      logger.warn(msg);
+    }
+    return;
+  }
+  if (!options.json) {
+    logger.info(`Found ${allFiles.length} theme YAML files (${stockFiles.length} stock, ${customFiles.length} custom)`);
+  }
+  const processed = [];
+  const errors = [];
+  for (const filePath of allFiles) {
+    let yamlContent;
+    try {
+      yamlContent = readFileSync15(filePath, "utf-8");
+    } catch {
+      errors.push(`Could not read: ${filePath}`);
+      continue;
+    }
+    let data;
+    try {
+      data = generateThemeData5(yamlContent);
+    } catch (err) {
+      errors.push(
+        `Failed to parse ${basename3(filePath)}: ${err instanceof Error ? err.message : "Unknown error"}`
+      );
+      continue;
+    }
+    const slug2 = data.config.name.toLowerCase().replace(/\s+/g, "-");
+    const camel = slugToCamel(slug2);
+    const flutterOptions = {
+      packageName: `visor_themes_${slug2.replace(/-/g, "_")}`,
+      themeClassName: "VisorAppTheme"
+    };
+    let fileMap;
+    try {
+      fileMap = flutterAdapter2(
+        {
+          primitives: data.primitives,
+          tokens: data.tokens,
+          config: data.config
+        },
+        flutterOptions
+      );
+    } catch (err) {
+      errors.push(
+        `Failed flutter adapter for ${slug2}: ${err instanceof Error ? err.message : "Unknown error"}`
+      );
+      continue;
+    }
+    const primsAsUnknown = data.primitives;
+    const primitivesMap = primsAsUnknown;
+    const primaryHex = typeof primitivesMap?.primary500 === "string" ? primitivesMap.primary500 : "#000000";
+    const tokenFiles = {};
+    for (const [relPath, content] of Object.entries(fileMap.files)) {
+      const mapped = mapAdapterPath(relPath);
+      if (mapped !== null) {
+        tokenFiles[mapped] = content;
+      }
+    }
+    if (tokenFiles["theme/visor_theme.dart"]) {
+      tokenFiles["theme/visor_theme.dart"] = tokenFiles["theme/visor_theme.dart"].replace(/import '\.\.\/colors\/visor_colors\.dart';/g, "import '../colors/visor_colors.dart';").replace(/import '\.\.\/typography\/visor_text_styles\.dart';/g, "import '../typography/visor_text_styles.dart';").replace(/import '\.\.\/spacing\/visor_spacing\.dart';/g, "import '../spacing/visor_spacing.dart';").replace(/import '\.\.\/radius\/visor_radius\.dart';/g, "import '../radius/visor_radius.dart';").replace(/import '\.\.\/shadows\/visor_shadows\.dart';/g, "import '../shadows/visor_shadows.dart';").replace(/import '\.\.\/strokes\/visor_stroke_widths\.dart';/g, "import '../strokes/visor_stroke_widths.dart';").replace(/import '\.\.\/opacity\/visor_opacity\.dart';/g, "import '../opacity/visor_opacity.dart';").replace(/import '\.\.\/motion\/visor_motion\.dart';/g, "import '../motion/visor_motion.dart';");
+    }
+    processed.push({ slug: slug2, camel, primaryHex, tokenFiles });
+  }
+  if (errors.length > 0) {
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, errors }));
+    } else {
+      errors.forEach((e) => logger.error(e));
+    }
+    process.exit(1);
+    return;
+  }
+  if (options.dryRun) {
+    if (!options.json) {
+      logger.info(`[dry-run] Would generate ${processed.length} theme packages in ${outputDir}`);
+      for (const { slug: slug2 } of processed) {
+        logger.item(`  packages/visor_themes/lib/src/${slug2}/`);
+      }
+    } else {
+      console.log(
+        JSON.stringify({
+          success: true,
+          dryRun: true,
+          themes: processed.map((p) => p.slug),
+          outputDir
+        })
+      );
+    }
     return;
   }
+  const slugs = processed.map((p) => p.slug);
+  const libSrcDir = join15(outputDir, "lib", "src");
+  if (existsSync12(libSrcDir)) {
+    rmSync(libSrcDir, { recursive: true, force: true });
+  }
+  const packageFiles = {
+    "pubspec.yaml": emitVisorThemesPubspec(),
+    "pubspec_overrides.yaml": emitVisorThemesPubspecOverrides(),
+    "analysis_options.yaml": emitAnalysisOptions(),
+    ".gitignore": emitGitignore(),
+    "lib/visor_themes.dart": emitMetaBarrel(slugs)
+  };
+  let totalFiles = 0;
+  for (const [relPath, content] of Object.entries(packageFiles)) {
+    const absPath = join15(outputDir, relPath);
+    mkdirSync6(dirname6(absPath), { recursive: true });
+    writeFileSync10(absPath, content, "utf-8");
+    totalFiles++;
+  }
+  for (const { slug: slug2, tokenFiles } of processed) {
+    const themeBaseDir = join15(outputDir, "lib", "src", slug2);
+    for (const [relPath, content] of Object.entries(tokenFiles)) {
+      const absPath = join15(themeBaseDir, relPath);
+      mkdirSync6(dirname6(absPath), { recursive: true });
+      writeFileSync10(absPath, content, "utf-8");
+      totalFiles++;
+    }
+  }
   if (options.json) {
-    console.log(JSON.stringify({
-      success: true,
-      themes: manifest.length,
-      stock: manifest.filter((e) => !e.isCustom).length,
-      custom: manifest.filter((e) => e.isCustom).length,
-      staleCssDeleted: staleCssFiles.length,
-      staleYamlsDeleted: stalePublicYamls.length,
-      slugs: allSlugs
-    }));
+    console.log(
+      JSON.stringify({
+        success: true,
+        outputDir,
+        themes: slugs,
+        totalFiles
+      })
+    );
   } else {
-    logger.success(`Theme sync complete \u2014 ${manifest.length} themes registered`);
-    logger.item(`Stock: ${manifest.filter((e) => !e.isCustom).map((e) => e.slug).join(", ")}`);
-    if (manifest.filter((e) => e.isCustom).length > 0) {
-      logger.item(`Custom: ${manifest.filter((e) => e.isCustom).map((e) => e.slug).join(", ")}`);
-    }
-    if (staleCssFiles.length > 0) {
-      logger.item(`Removed stale CSS: ${staleCssFiles.join(", ")}`);
-    }
+    logger.success(`Flutter theme package generated: ${outputDir}`);
+    logger.item(`Themes: ${slugs.join(", ")}`);
+    logger.item(`Total files written: ${totalFiles}`);
   }
 }
 
 // src/commands/fonts-add.ts
-import { existsSync as existsSync10, statSync as statSync2, readdirSync as readdirSync3, readFileSync as readFileSync12 } from "fs";
-import { resolve as resolve7, basename as basename3, extname as extname2 } from "path";
+import { existsSync as existsSync13, statSync as statSync4, readdirSync as readdirSync6, readFileSync as readFileSync16 } from "fs";
+import { resolve as resolve8, basename as basename4, extname as extname3 } from "path";
 import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
 function deriveFamilySlug(filename) {
-  const name = basename3(filename, extname2(filename));
+  const name = basename4(filename, extname3(filename));
   const WEIGHT_STYLE_SUFFIXES = /* @__PURE__ */ new Set([
     "thin",
     "hairline",
@@ -2331,28 +3776,28 @@ function deriveFamilySlug(filename) {
   return parts.join("-").toLowerCase();
 }
 function collectWoff2Files(inputPath) {
-  const resolved = resolve7(inputPath);
-  if (!existsSync10(resolved)) {
+  const resolved = resolve8(inputPath);
+  if (!existsSync13(resolved)) {
     throw new Error(`Path not found: ${resolved}`);
   }
-  const stat = statSync2(resolved);
+  const stat = statSync4(resolved);
   if (stat.isFile()) {
-    if (extname2(resolved).toLowerCase() !== ".woff2") {
+    if (extname3(resolved).toLowerCase() !== ".woff2") {
       throw new Error(
-        `Invalid file format: ${basename3(resolved)}. Only .woff2 files are accepted.`
+        `Invalid file format: ${basename4(resolved)}. Only .woff2 files are accepted.`
       );
     }
     return [resolved];
   }
   if (stat.isDirectory()) {
-    const files = readdirSync3(resolved).filter((f) => extname2(f).toLowerCase() === ".woff2").map((f) => resolve7(resolved, f));
+    const files = readdirSync6(resolved).filter((f) => extname3(f).toLowerCase() === ".woff2").map((f) => resolve8(resolved, f));
     if (files.length === 0) {
       throw new Error(
         `No .woff2 files found in directory: ${resolved}`
       );
     }
-    const nonWoff2Fonts = readdirSync3(resolved).filter((f) => {
-      const ext = extname2(f).toLowerCase();
+    const nonWoff2Fonts = readdirSync6(resolved).filter((f) => {
+      const ext = extname3(f).toLowerCase();
       return [".ttf", ".otf", ".woff", ".eot"].includes(ext);
     });
     return files.sort();
@@ -2360,12 +3805,12 @@ function collectWoff2Files(inputPath) {
   throw new Error(`Path is neither a file nor a directory: ${resolved}`);
 }
 function getNonWoff2Fonts(inputPath) {
-  const resolved = resolve7(inputPath);
-  if (!existsSync10(resolved) || !statSync2(resolved).isDirectory()) {
+  const resolved = resolve8(inputPath);
+  if (!existsSync13(resolved) || !statSync4(resolved).isDirectory()) {
     return [];
   }
-  return readdirSync3(resolved).filter((f) => {
-    const ext = extname2(f).toLowerCase();
+  return readdirSync6(resolved).filter((f) => {
+    const ext = extname3(f).toLowerCase();
     return [".ttf", ".otf", ".woff", ".eot"].includes(ext);
   });
 }
@@ -2398,7 +3843,7 @@ function createR2Client(config) {
   });
 }
 async function uploadFile(client, bucket, key, filePath) {
-  const body = readFileSync12(filePath);
+  const body = readFileSync16(filePath);
   await client.send(
     new PutObjectCommand({
       Bucket: bucket,
@@ -2413,9 +3858,9 @@ async function fontsAddCommand(inputPath, options) {
   try {
     const r2Config = getR2Config();
     const files = collectWoff2Files(inputPath);
-    const familySlug = options.family ?? deriveFamilySlug(basename3(files[0]));
-    const resolved = resolve7(inputPath);
-    const nonWoff2 = statSync2(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
+    const familySlug = options.family ?? deriveFamilySlug(basename4(files[0]));
+    const resolved = resolve8(inputPath);
+    const nonWoff2 = statSync4(resolved).isDirectory() ? getNonWoff2Fonts(resolved) : [];
     if (!json) {
       logger.heading("Visor Font Upload");
       logger.info(`Organization: ${org}`);
@@ -2433,13 +3878,13 @@ async function fontsAddCommand(inputPath, options) {
     const bucket = "visor-fonts";
     const results = [];
     for (const filePath of files) {
-      const filename = basename3(filePath);
+      const filename = basename4(filePath);
       const key = buildS3Key(org, familySlug, filename);
       if (!json) {
         logger.info(`Uploading ${filename}...`);
       }
       await uploadFile(client, bucket, key, filePath);
-      const size = statSync2(filePath).size;
+      const size = statSync4(filePath).size;
       results.push({ file: filename, key, size });
       if (!json) {
         logger.success(`Uploaded: ${key} (${formatBytes(size)})`);
@@ -2486,27 +3931,670 @@ function formatBytes(bytes) {
   return `${mb.toFixed(1)} MB`;
 }
 
+// src/commands/doctor.ts
+import * as fs from "fs";
+import * as path from "path";
+import { execFileSync as execFileSync3 } from "child_process";
+async function doctorCommand(cwd, options, cliVersion) {
+  const checks = [];
+  const visorJsonPath = path.join(cwd, "visor.json");
+  try {
+    const content = fs.readFileSync(visorJsonPath, "utf-8");
+    JSON.parse(content);
+    checks.push({ name: "visor.json", pass: true, severity: "error", message: "visor.json exists and is valid JSON" });
+  } catch {
+    checks.push({
+      name: "visor.json",
+      pass: false,
+      severity: "error",
+      message: "visor.json missing or invalid",
+      fix: "Run `npx visor init` to initialize Visor in this project"
+    });
+  }
+  const visorCorePath = path.join(cwd, "node_modules", "@loworbitstudio", "visor-core");
+  if (fs.existsSync(visorCorePath)) {
+    checks.push({ name: "visor-core", pass: true, severity: "error", message: "@loworbitstudio/visor-core is installed" });
+  } else {
+    checks.push({
+      name: "visor-core",
+      pass: false,
+      severity: "error",
+      message: "@loworbitstudio/visor-core not found in node_modules",
+      fix: "Run `npm install @loworbitstudio/visor-core`"
+    });
+  }
+  const cssFiles = findCssFiles(cwd);
+  const hasVisorImport = cssFiles.some((f) => {
+    try {
+      const content = fs.readFileSync(f, "utf-8");
+      return content.includes("visor-core") || content.includes("@loworbitstudio/visor-core");
+    } catch {
+      return false;
+    }
+  });
+  if (hasVisorImport) {
+    checks.push({ name: "css-import", pass: true, severity: "warning", message: "visor-core CSS import found" });
+  } else {
+    checks.push({
+      name: "css-import",
+      pass: false,
+      severity: "warning",
+      message: "No visor-core CSS import found in CSS files",
+      fix: 'Add `@import "@loworbitstudio/visor-core/tokens.css"` to your global CSS file'
+    });
+  }
+  const pkgJsonPath = path.join(cwd, "package.json");
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf-8"));
+    const reactVersion = pkg.dependencies?.react ?? pkg.devDependencies?.react ?? "";
+    const versionNum = parseFloat(reactVersion.replace(/[^0-9.]/g, ""));
+    if (!reactVersion) {
+      checks.push({
+        name: "react-version",
+        pass: false,
+        severity: "error",
+        message: "React not found in dependencies",
+        fix: "Install React: `npm install react@latest react-dom@latest`"
+      });
+    } else if (versionNum >= 17 || reactVersion.includes("18") || reactVersion.includes("19")) {
+      checks.push({ name: "react-version", pass: true, severity: "error", message: `React ${reactVersion} satisfies peer dep requirement (>=17)` });
+    } else {
+      checks.push({
+        name: "react-version",
+        pass: false,
+        severity: "error",
+        message: `React version ${reactVersion} may not satisfy peer dep requirement (>=17)`,
+        fix: "Upgrade React to v17 or higher: `npm install react@latest react-dom@latest`"
+      });
+    }
+  } catch {
+    checks.push({
+      name: "react-version",
+      pass: false,
+      severity: "warning",
+      message: "Could not read package.json to check React version",
+      fix: "Ensure package.json exists in the project root"
+    });
+  }
+  const componentsDir = path.join(cwd, "components", "ui");
+  if (fs.existsSync(componentsDir) && fs.readdirSync(componentsDir).length > 0) {
+    const count = fs.readdirSync(componentsDir).length;
+    checks.push({ name: "components", pass: true, severity: "info", message: `${count} component(s) found under components/ui/` });
+  } else {
+    checks.push({
+      name: "components",
+      pass: false,
+      severity: "info",
+      message: "No components found under components/ui/",
+      fix: "Add components with `npx visor add <component-name>` (e.g. `npx visor add button`)"
+    });
+  }
+  const manifestPaths = [
+    path.join(cwd, "public", "r", "index.json"),
+    path.join(cwd, "registry", "index.json")
+  ];
+  const foundManifest = manifestPaths.find((p) => fs.existsSync(p));
+  if (foundManifest) {
+    try {
+      const manifestContent = JSON.parse(fs.readFileSync(foundManifest, "utf-8"));
+      const isEmpty = manifestContent === null || Array.isArray(manifestContent) && manifestContent.length === 0 || typeof manifestContent === "object" && Object.keys(manifestContent).length === 0;
+      if (!isEmpty) {
+        checks.push({ name: "registry-manifest", pass: true, severity: "info", message: `Registry manifest found at ${path.relative(cwd, foundManifest)}` });
+      } else {
+        checks.push({
+          name: "registry-manifest",
+          pass: false,
+          severity: "info",
+          message: "Registry manifest is empty",
+          fix: "Run `npx visor build` to regenerate the registry manifest"
+        });
+      }
+    } catch {
+      checks.push({
+        name: "registry-manifest",
+        pass: false,
+        severity: "info",
+        message: "Registry manifest found but could not be parsed",
+        fix: "Run `npx visor build` to regenerate the registry manifest"
+      });
+    }
+  } else {
+    checks.push({
+      name: "registry-manifest",
+      pass: false,
+      severity: "info",
+      message: "No registry manifest found (this is normal for consumer projects)",
+      fix: "If building a design system, run `npx visor build` to generate the registry manifest"
+    });
+  }
+  if (process.platform !== "win32") {
+    try {
+      const globalPath = execFileSync3("which", ["visor"], { encoding: "utf-8" }).trim();
+      if (globalPath) {
+        const globalVersionRaw = execFileSync3(globalPath, ["--version"], { encoding: "utf-8" }).trim();
+        const globalVersion = globalVersionRaw.split(/\s+/).pop() ?? "";
+        if (isOlder(globalVersion, cliVersion)) {
+          checks.push({
+            name: "stale-global-cli",
+            pass: false,
+            severity: "warning",
+            message: `Global visor ${globalVersion} is older than running CLI ${cliVersion}`,
+            fix: "Run npm uninstall -g @loworbitstudio/visor to remove the stale global"
+          });
+        } else {
+          checks.push({
+            name: "stale-global-cli",
+            pass: true,
+            severity: "warning",
+            message: `Global visor ${globalVersion} matches running CLI`
+          });
+        }
+      }
+    } catch {
+    }
+  }
+  const hasErrors = checks.some((c) => !c.pass && c.severity === "error");
+  const hasWarnings = checks.some((c) => !c.pass && c.severity === "warning");
+  const result = {
+    status: hasErrors ? "error" : hasWarnings ? "warning" : "ok",
+    checks
+  };
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(hasErrors ? 1 : 0);
+    return;
+  }
+  console.log("\nVisor Doctor\n============");
+  for (const check of checks) {
+    const icon = check.pass ? "\u2713" : check.severity === "error" ? "\u2717" : "\u26A0";
+    console.log(`${icon} ${check.name}: ${check.message}`);
+    if (!check.pass && check.fix) {
+      console.log(`  Fix: ${check.fix}`);
+    }
+  }
+  console.log(`
+Status: ${result.status.toUpperCase()}`);
+  process.exit(hasErrors ? 1 : 0);
+}
+function isOlder(a, b) {
+  const pa = a.split(".").map((n) => parseInt(n, 10) || 0);
+  const pb = b.split(".").map((n) => parseInt(n, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va < vb) return true;
+    if (va > vb) return false;
+  }
+  return false;
+}
+function findCssFiles(dir, maxDepth = 3) {
+  const files = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith(".") || entry.name === "node_modules") continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isFile() && (entry.name.endsWith(".css") || entry.name.endsWith(".scss"))) {
+        files.push(fullPath);
+      } else if (entry.isDirectory() && maxDepth > 0) {
+        files.push(...findCssFiles(fullPath, maxDepth - 1));
+      }
+    }
+  } catch {
+  }
+  return files;
+}
+
+// src/utils/patterns.ts
+import { existsSync as existsSync15, readdirSync as readdirSync8, readFileSync as readFileSync18 } from "fs";
+import { join as join17 } from "path";
+import { parse as parseYAML } from "yaml";
+function loadPatternsFromYaml(repoRoot) {
+  const patternsDir = join17(repoRoot, "patterns");
+  if (!existsSync15(patternsDir)) return [];
+  const files = readdirSync8(patternsDir).filter(
+    (f) => f.endsWith(".visor-pattern.yaml")
+  );
+  return files.map((file) => {
+    const content = readFileSync18(join17(patternsDir, file), "utf-8");
+    return parseYAML(content);
+  }).filter(Boolean);
+}
+function findRepoRoot2(startDir) {
+  let current = startDir;
+  while (true) {
+    if (existsSync15(join17(current, "patterns"))) {
+      return current;
+    }
+    const parent = join17(current, "..");
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+// src/commands/pattern.ts
+function patternListCommand(cwd, options = {}) {
+  const json = options.json ?? false;
+  const repoRoot = findRepoRoot2(cwd);
+  if (!repoRoot) {
+    if (json) {
+      console.log(
+        JSON.stringify({ success: false, error: "Could not find patterns/ directory." }, null, 2)
+      );
+      process.exit(1);
+      return;
+    }
+    logger.error("Could not find patterns/ directory.");
+    process.exit(1);
+    return;
+  }
+  const patterns = loadPatternsFromYaml(repoRoot);
+  if (json) {
+    const output = patterns.map((p) => ({
+      name: p.name,
+      description: p.description,
+      components_used: p.components_used,
+      when_to_use: p.when_to_use
+    }));
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          patterns: output,
+          summary: { total: output.length }
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  logger.heading(`Composition Patterns (${patterns.length})`);
+  logger.blank();
+  for (const p of patterns) {
+    logger.info(`  ${p.name.padEnd(32)} ${p.description}`);
+  }
+  logger.blank();
+}
+function patternInfoCommand(name, cwd, options = {}) {
+  const json = options.json ?? false;
+  const repoRoot = findRepoRoot2(cwd);
+  if (!repoRoot) {
+    if (json) {
+      console.log(
+        JSON.stringify({ success: false, error: "Could not find patterns/ directory." }, null, 2)
+      );
+      process.exit(1);
+      return;
+    }
+    logger.error("Could not find patterns/ directory.");
+    process.exit(1);
+    return;
+  }
+  const patterns = loadPatternsFromYaml(repoRoot);
+  const pattern2 = patterns.find(
+    (p) => p.name.toLowerCase() === name.toLowerCase() || p.name.toLowerCase().replace(/\s+/g, "-") === name.toLowerCase()
+  );
+  if (!pattern2) {
+    if (json) {
+      console.log(
+        JSON.stringify({ success: false, error: `Pattern "${name}" not found.` }, null, 2)
+      );
+      process.exit(1);
+      return;
+    }
+    logger.error(`Pattern "${name}" not found.`);
+    process.exit(1);
+    return;
+  }
+  if (json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          pattern: {
+            name: pattern2.name,
+            description: pattern2.description,
+            components_used: pattern2.components_used,
+            ...pattern2.related_blocks ? { related_blocks: pattern2.related_blocks } : {},
+            when_to_use: pattern2.when_to_use,
+            structure: pattern2.structure,
+            notes: pattern2.notes
+          }
+        },
+        null,
+        2
+      )
+    );
+    process.exit(0);
+    return;
+  }
+  logger.heading(pattern2.name);
+  logger.blank();
+  logger.info(`Description: ${pattern2.description}`);
+  logger.blank();
+  logger.info(`Components used: ${pattern2.components_used.join(", ")}`);
+  logger.blank();
+  logger.info("When to use:");
+  for (const item of pattern2.when_to_use) {
+    logger.info(`  - ${item}`);
+  }
+  if (pattern2.related_blocks && pattern2.related_blocks.length > 0) {
+    logger.blank();
+    logger.info(`Related blocks: ${pattern2.related_blocks.join(", ")}`);
+  }
+  logger.blank();
+  logger.info("Structure:");
+  logger.blank();
+  console.log(pattern2.structure);
+  logger.blank();
+  logger.info("Notes:");
+  logger.blank();
+  console.log(pattern2.notes);
+  logger.blank();
+}
+
+// src/commands/suggest.ts
+var STOP_WORDS2 = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "the",
+  "with",
+  "for",
+  "and",
+  "or",
+  "to",
+  "in",
+  "of",
+  "is",
+  "that",
+  "this",
+  "it",
+  "as",
+  "at",
+  "by",
+  "on",
+  "be",
+  "are",
+  "was",
+  "were"
+]);
+function tokenize2(text) {
+  return text.toLowerCase().split(/[\s\-_,]+/).filter((t) => t.length > 1 && !STOP_WORDS2.has(t));
+}
+function scoreEntry(queryTokens, name, description, whenToUse) {
+  const searchText = [name, description, ...whenToUse].join(" ").toLowerCase();
+  const matchedTokens = queryTokens.filter((t) => searchText.includes(t));
+  return {
+    score: matchedTokens.length,
+    matchReason: matchedTokens.length > 0 ? `Matched: ${matchedTokens.join(", ")}` : ""
+  };
+}
+async function suggestCommand(_cwd, options) {
+  const query = options.for;
+  const queryTokens = tokenize2(query);
+  if (queryTokens.length === 0) {
+    const err = {
+      success: false,
+      error: "Query is too short or contains only stop words. Try more specific terms."
+    };
+    if (options.json) {
+      console.error(JSON.stringify(err));
+      process.exit(1);
+    }
+    console.error(err.error);
+    process.exit(1);
+  }
+  const manifest = loadManifest();
+  const results = [];
+  for (const [name, entry] of Object.entries(manifest.components)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      entry.when_to_use || []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "component",
+        category: entry.category,
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: `npx visor add ${name}`
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.blocks)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      entry.when_to_use || []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "block",
+        category: entry.category,
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: `npx visor add ${name} --block`
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.patterns)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      entry.when_to_use || []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "pattern",
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: null
+      });
+    }
+  }
+  for (const [name, entry] of Object.entries(manifest.hooks)) {
+    const { score, matchReason } = scoreEntry(
+      queryTokens,
+      name,
+      entry.description,
+      []
+    );
+    if (score >= 1) {
+      results.push({
+        name,
+        type: "hook",
+        score,
+        description: entry.description,
+        match_reason: matchReason,
+        install_command: `npx visor add ${name}`
+      });
+    }
+  }
+  results.sort((a, b) => b.score - a.score);
+  const topResults = results.slice(0, 10);
+  if (topResults.length === 0) {
+    const err = {
+      success: false,
+      error: `No matches found for "${query}". Try broader terms.`
+    };
+    if (options.json) {
+      console.error(JSON.stringify(err, null, 2));
+      process.exit(1);
+    }
+    console.error(err.error);
+    process.exit(1);
+  }
+  const totalSearched = Object.keys(manifest.components).length + Object.keys(manifest.blocks).length + Object.keys(manifest.patterns).length + Object.keys(manifest.hooks).length;
+  const output = {
+    success: true,
+    query,
+    results: topResults,
+    summary: {
+      total_searched: totalSearched,
+      total_matched: topResults.length
+    }
+  };
+  if (options.json) {
+    console.log(JSON.stringify(output, null, 2));
+    process.exit(0);
+  }
+  console.log(`
+Suggestions for "${query}":
+`);
+  for (const r of topResults) {
+    const cmd = r.install_command ? ` (${r.install_command})` : "";
+    console.log(`  ${r.name} [${r.type}]${cmd}`);
+    console.log(`    ${r.description.slice(0, 80)}`);
+  }
+  console.log(
+    `
+${topResults.length} result${topResults.length !== 1 ? "s" : ""} from ${totalSearched} entries
+`
+  );
+}
+
+// src/commands/tokens.ts
+async function tokensListCommand(_cwd, options) {
+  const manifest = loadManifest();
+  if (!manifest.tokens) {
+    const err = {
+      success: false,
+      error: "Tokens section not found in manifest. Run npm run build:manifest to rebuild."
+    };
+    if (options.json) {
+      console.error(JSON.stringify(err));
+    } else {
+      console.error(err.error);
+    }
+    process.exit(1);
+  }
+  const { primitives, semantic, adaptive, summary } = manifest.tokens;
+  let tokens2 = [...primitives, ...semantic, ...adaptive];
+  let categoryLabel = "all";
+  if (options.category) {
+    const cat = options.category.toLowerCase();
+    if (cat === "primitives") {
+      tokens2 = primitives;
+      categoryLabel = "primitives";
+    } else if (cat === "semantic") {
+      tokens2 = semantic;
+      categoryLabel = "semantic";
+    } else if (cat === "adaptive") {
+      tokens2 = adaptive;
+      categoryLabel = "adaptive";
+    } else {
+      const err = {
+        success: false,
+        error: `Unknown category "${options.category}". Use: primitives, semantic, adaptive`
+      };
+      if (options.json) {
+        console.error(JSON.stringify(err));
+      } else {
+        console.error(err.error);
+      }
+      process.exit(1);
+    }
+  }
+  if (options.json) {
+    console.log(
+      JSON.stringify(
+        {
+          success: true,
+          tokens: tokens2,
+          summary: {
+            total: tokens2.length,
+            category: categoryLabel,
+            allTotal: summary.total
+          }
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+  console.log(
+    `
+Visor Tokens (${categoryLabel}) \u2014 ${tokens2.length} tokens
+`
+  );
+  for (const t of tokens2) {
+    console.log(`  ${t.name}  [${t.tier}]`);
+    if (t.description) {
+      console.log(`    ${t.description}`);
+    }
+    console.log(`    Light: ${t.defaultLight}`);
+    console.log(`    Dark:  ${t.defaultDark}`);
+  }
+  console.log(
+    `
+  Total: ${tokens2.length} tokens shown${categoryLabel !== "all" ? ` (${summary.total} total across all tiers)` : ""}`
+  );
+}
+
 // src/index.ts
-var program = new Command();
-program.name("visor").description("CLI for the Visor design system").version("0.1.0");
-program.command("init").description("Initialize Visor in the current project").option("--template <name>", "scaffold a themed project (nextjs)").option("--json", "output structured JSON (for AI agents)").action((options) => {
+var program = new Command2();
+program.name("visor").description("CLI for the Visor design system").version("0.3.0");
+program.addCommand(checkCommand());
+program.command("init").description("Initialize Visor \u2014 with --template nextjs, scaffolds a complete runnable Borealis-native Next.js app in one command").option("--template <name>", "scaffold a complete runnable app (templates: nextjs)").option("--json", "output structured JSON (for AI agents)").action((options) => {
   initCommand(process.cwd(), options);
 });
 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("--json", "output structured JSON (for AI agents)").action((items, options) => {
-  addCommand(items, process.cwd(), { overwrite: options.overwrite, category: options.category, block: options.block, json: options.json });
+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) => {
+  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 });
 });
 program.command("diff").description(
   "Show differences between local files and the registry"
-).argument("[component]", "component name to diff (all if omitted)").option("--json", "output structured JSON (for AI agents)").action((component, options) => {
+).argument("[component]", "component name to diff (all installed if omitted)").option("--all", "check all registry components for upstream changes").option("--json", "output structured JSON (for AI agents)").action((component, options) => {
   diffCommand(component, process.cwd(), options);
 });
+program.command("info").description("Show detailed metadata for a component, hook, block, or pattern").argument("<component>", "Name of the component to look up").option("--json", "Output as JSON").action(async (component, options) => {
+  await infoCommand(component, process.cwd(), options);
+});
+program.command("doctor").description("Run diagnostics on a Visor installation").option("--json", "Output as JSON (for AI agents)").action(async (options) => {
+  await doctorCommand(process.cwd(), options, program.version() ?? "0.0.0");
+});
 var theme = program.command("theme").description("Theme management commands");
 theme.command("apply").description(
-  "Read a .visor.yaml file and generate full CSS token overrides"
-).argument("<file>", "path to .visor.yaml file").option("-o, --output <path>", "output CSS file path").option("--json", "output structured JSON (for AI agents)").option("--adapter <name>", "target adapter: nextjs, fumadocs, deck").action(
+  "Read a .visor.yaml file and generate token overrides (CSS or Flutter)"
+).argument("<file>", "path to .visor.yaml file").option(
+  "-o, --output <path>",
+  "output CSS file path (or directory for --adapter flutter)"
+).option("--json", "output structured JSON (for AI agents)").option(
+  "--adapter <name>",
+  "target adapter: nextjs, fumadocs, deck, docs, flutter"
+).option(
+  "--package-name <name>",
+  "(flutter) Dart package name for generated pubspec.yaml (default: ui)"
+).option(
+  "--tokens-only",
+  "(flutter) emit only token files \u2014 skip pubspec.yaml and theme scaffolding"
+).option(
+  "--light-only",
+  "(flutter) emit only the light-brightness theme getter"
+).option(
+  "--dark-only",
+  "(flutter) emit only the dark-brightness theme getter"
+).option(
+  "--theme-class-name <name>",
+  "(flutter) class name for generated theme (default: VisorAppTheme)"
+).action(
   (file, options) => {
     themeApplyCommand(file, process.cwd(), {
       ...options,
@@ -2550,8 +4638,8 @@ theme.command("register").description(
 theme.command("unregister").description(
   "Remove a theme from the docs site \u2014 deletes CSS file, removes globals.css import and theme-config.ts entry"
 ).argument("<slug>", "theme slug to unregister (e.g. entr, kaiah)").option("--json", "output structured JSON (for AI agents)").action(
-  (slug, options) => {
-    themeUnregisterCommand(slug, process.cwd(), options);
+  (slug2, options) => {
+    themeUnregisterCommand(slug2, process.cwd(), options);
   }
 );
 theme.command("sync").description(
@@ -2561,10 +4649,31 @@ theme.command("sync").description(
     themeSyncCommand(process.cwd(), options);
   }
 );
+theme.command("batch-apply-flutter").description(
+  "Batch-generate Dart ThemeData for all .visor.yaml themes (themes/ + custom-themes/) into packages/visor_themes/"
+).option("--dry-run", "show what would be generated without writing files").option("--json", "output structured JSON (for AI agents)").action(
+  (options) => {
+    themeBatchApplyFlutterCommand(process.cwd(), options);
+  }
+);
 var fonts = program.command("fonts").description("Font library management commands");
 fonts.command("add").description("Upload woff2 font files to the Visor Font Library on R2").argument("<path>", "path to a .woff2 file or directory containing .woff2 files").requiredOption("--org <org>", "organization namespace (e.g. low-orbit)").option("--family <name>", "font family slug (auto-inferred from filename if omitted)").option("--json", "output structured JSON (for AI agents)").action(
-  (path, options) => {
-    fontsAddCommand(path, options);
+  (path2, options) => {
+    fontsAddCommand(path2, options);
   }
 );
+var pattern = program.command("pattern").description("Work with composition patterns");
+pattern.command("list").description("List all composition patterns").option("--json", "Output as JSON").action((options) => {
+  patternListCommand(process.cwd(), options);
+});
+pattern.command("info").argument("<name>", "Pattern name").description("Show full details for a composition pattern").option("--json", "Output as JSON").action((name, options) => {
+  patternInfoCommand(name, process.cwd(), options);
+});
+program.command("suggest").description("Suggest components, blocks, and patterns for a use case").requiredOption("--for <useCase>", 'Use case description (e.g. "dropdown with search")').option("--json", "Output as JSON").action(async (options) => {
+  await suggestCommand(process.cwd(), options);
+});
+var tokens = program.command("tokens").description("Explore design tokens");
+tokens.command("list").description("List all design tokens").option("--json", "output as JSON (for AI agents)").option("--category <category>", "filter by tier: primitives, semantic, adaptive").action(async (options) => {
+  await tokensListCommand(process.cwd(), options);
+});
 program.parse();