inventive-ui 0.0.1 → 0.0.3

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/index.ts
-import path25 from "path";
+import path27 from "path";
 import { Command } from "commander";
 
 // src/utils/ui.ts
@@ -190,7 +190,7 @@ var BANNER_COMPACT = [
 var FULL_BANNER_WIDTH = 101;
 function resolveCliVersion() {
   try {
-    return true ? "0.0.1" : "1.0.0";
+    return true ? "0.0.3" : "1.0.0";
   } catch {
     return "1.0.0";
   }
@@ -373,8 +373,8 @@ function resolveApiBaseUrl() {
     );
   }
   if (parsed.pathname && parsed.pathname !== "/" && parsed.pathname !== "") {
-    const path26 = parsed.pathname.replace(/\/+$/, "");
-    if (path26 && !/^\/[a-zA-Z0-9._/-]+$/.test(path26)) {
+    const path28 = parsed.pathname.replace(/\/+$/, "");
+    if (path28 && !/^\/[a-zA-Z0-9._/-]+$/.test(path28)) {
       throw new CLIError(
         "IUI_API_URL path contains invalid characters.",
         "Use a simple path prefix such as /v1"
@@ -633,8 +633,8 @@ var ASSET_CATEGORY_LABELS = {
 };
 
 // src/utils/filesystem.ts
-import path9 from "path";
-import { fileURLToPath } from "url";
+import path10 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import os3 from "os";
 import fs8 from "fs-extra";
 
@@ -1046,8 +1046,8 @@ function listIuiInitializedPackages(startCwd) {
     );
     if (initialized.length > 0) return initialized;
   }
-  const iuiRoot = findIuiProjectRoot(startCwd);
-  return iuiRoot ? [iuiRoot] : [];
+  const iuiRoot2 = findIuiProjectRoot(startCwd);
+  return iuiRoot2 ? [iuiRoot2] : [];
 }
 function resolveSetupDoctorTargets(cwd) {
   const resolved = path5.resolve(cwd);
@@ -1412,6 +1412,37 @@ function parseAndValidateRegistryManifest(raw, source) {
   return result.data;
 }
 
+// src/utils/theme-config-scaffold.ts
+import { existsSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { createJiti } from "jiti";
+var __dirname2 = dirname(fileURLToPath(import.meta.url));
+function resolveFrameworkScriptsDir(startCwd) {
+  const searchRoots = [startCwd, process.cwd(), join(__dirname2, "../..")];
+  for (const root of searchRoots) {
+    const frameworkDir = resolvePackageDir(FRAMEWORK_PACKAGE, root);
+    if (!frameworkDir) continue;
+    const scriptsDir = join(frameworkDir, "scripts");
+    const loader = join(scriptsDir, "load-framework-theme-defaults.mjs");
+    if (existsSync(loader)) return scriptsDir;
+  }
+  throw new CLIError(
+    `Cannot scaffold iui.config.ts: ${FRAMEWORK_PACKAGE} is not installed or is missing scripts/load-framework-theme-defaults.mjs.`
+  );
+}
+function buildProjectConfigSource(cwd = process.cwd()) {
+  const scriptsDir = resolveFrameworkScriptsDir(cwd);
+  const jiti = createJiti(import.meta.url, { interopDefault: true });
+  const loader = jiti(
+    join(scriptsDir, "load-framework-theme-defaults.mjs")
+  );
+  const defaults = loader.loadFrameworkThemeDefaults(scriptsDir);
+  return loader.buildThemeScaffoldConfig(defaults, {
+    configType: "IUIThemeConfig"
+  });
+}
+
 // src/utils/security/identifiers.ts
 var SLUG_RE = /^[a-z][a-z0-9-]*$/;
 var JS_IDENTIFIER_RE = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
@@ -2527,6 +2558,19 @@ var ComponentConfigEntrySchema = z2.object({
   presets: z2.record(z2.unknown()).optional()
 }).catchall(z2.unknown());
 var ComponentConfigSchema = z2.record(ComponentConfigEntrySchema);
+var ProjectMetaSchema = z2.object({
+  projectId: z2.string().min(1),
+  repoUrl: z2.string().min(1),
+  createdAt: z2.string().min(1),
+  initScope: z2.enum(["package", "workspace"]).optional(),
+  configs: z2.object({
+    theme: z2.string().min(1),
+    assets: z2.string().min(1),
+    components: z2.string().min(1)
+  }).strict().optional()
+}).strict().refine((data) => !("theme" in data) && !("assets" in data), {
+  message: "project.json must not contain config values \u2014 use configs paths only"
+});
 function formatZodIssues(error) {
   return error.issues.slice(0, 8).map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
 }
@@ -2647,6 +2691,30 @@ function checkAssetsConfigValidity(cwd = process.cwd()) {
       details: "Run iui init or merge CLI defaults so @alias icons resolve."
     };
   }
+  const logo = assets2.logo;
+  if (assets2.logo && (!logo?.globalLogos || Object.keys(logo.globalLogos).length === 0)) {
+    return {
+      ok: false,
+      summary: "assets.config.json is missing logo.globalLogos",
+      details: "Run iui init or merge CLI defaults so @alias logos resolve."
+    };
+  }
+  const emoji = assets2.emoji;
+  if (assets2.emoji && (!emoji?.globalEmojis || Object.keys(emoji.globalEmojis).length === 0)) {
+    return {
+      ok: false,
+      summary: "assets.config.json is missing emoji.globalEmojis",
+      details: "Run iui init or merge CLI defaults so @alias emojis resolve."
+    };
+  }
+  const colorLogo = assets2.colorLogo;
+  if (assets2.colorLogo && (!colorLogo?.globalColorLogos || Object.keys(colorLogo.globalColorLogos).length === 0)) {
+    return {
+      ok: false,
+      summary: "assets.config.json is missing colorLogo.globalColorLogos",
+      details: "Run iui init or merge CLI defaults so @alias color logos resolve."
+    };
+  }
   return { ok: true, summary: "assets.config.json is valid" };
 }
 function checkComponentConfigTierBleed(cwd = process.cwd()) {
@@ -2671,12 +2739,59 @@ function checkComponentConfigTierBleed(cwd = process.cwd()) {
   };
 }
 
+// src/services/iui-paths.ts
+import path9 from "path";
+var IUI_CACHE_SEGMENT = "cache";
+var IUI_CACHE_FILES = {
+  scan: "scan.cache.json",
+  styles: "styles.css",
+  manifest: "manifest.js",
+  stylesInject: "styles.inject.js",
+  stylesInline: "styles.inline.js",
+  slotState: "slot-state.json",
+  slotLock: "slot.lock",
+  utilities: "utilities.css",
+  manifestJson: "manifest.json",
+  slotWarmup: "slot-warmup.mjs"
+};
+function iuiProjectRoot(cwd = process.cwd()) {
+  return resolveIuiProjectRoot(cwd);
+}
+function iuiRoot(cwd = process.cwd()) {
+  return path9.join(iuiProjectRoot(cwd), IUI_DIR);
+}
+function iuiCacheDir(cwd = process.cwd()) {
+  return path9.join(iuiRoot(cwd), IUI_CACHE_SEGMENT);
+}
+function iuiCacheFile(cwd, name) {
+  return path9.join(iuiCacheDir(cwd), IUI_CACHE_FILES[name]);
+}
+var IUI_CACHE_GITIGNORE_LINES = [
+  "",
+  "# IUI disposable cache (.iui/generated/ stays committed)",
+  `${IUI_DIR}/${IUI_CACHE_SEGMENT}/`,
+  `${IUI_DIR}/slot-registration-state.json`,
+  `${IUI_DIR}/slot-registration.lock`,
+  `${IUI_DIR}/classes.cache.json`,
+  `${IUI_DIR}/utilities.css`,
+  `${IUI_DIR}/build-styles.generated.css`,
+  `${IUI_DIR}/build-styles.generated.js`,
+  `${IUI_DIR}/build-manifest.generated.js`,
+  `${IUI_DIR}/build-css-inline.js`,
+  `${IUI_DIR}/build-manifest.json`,
+  `${IUI_DIR}/slot-warmup.generated.mjs`,
+  ".iui-bootstrap-client.js",
+  ".iui-bootstrap-server.js",
+  ".iui-bootstrap.js",
+  "public/iui/"
+];
+
 // src/utils/filesystem.ts
 function globalConfigPath() {
-  return path9.join(os3.homedir(), GLOBAL_CONFIG_DIR, "config.json");
+  return path10.join(os3.homedir(), GLOBAL_CONFIG_DIR, "config.json");
 }
 function globalSecretsPath() {
-  return path9.join(os3.homedir(), GLOBAL_CONFIG_DIR, "secrets.json");
+  return path10.join(os3.homedir(), GLOBAL_CONFIG_DIR, "secrets.json");
 }
 function readSecretsFile() {
   const p = globalSecretsPath();
@@ -2731,10 +2846,10 @@ function removeGlobalConfig() {
   if (fs8.existsSync(s)) fs8.removeSync(s);
 }
 function iuiDir(cwd = process.cwd()) {
-  return path9.join(resolveIuiProjectRoot(cwd), IUI_DIR);
+  return path10.join(resolveIuiProjectRoot(cwd), IUI_DIR);
 }
 function metaPath(file, cwd) {
-  return path9.join(iuiDir(cwd ?? process.cwd()), file);
+  return path10.join(iuiDir(cwd ?? process.cwd()), file);
 }
 function projectMetaPath(cwd) {
   return metaPath("project.json", cwd);
@@ -2794,10 +2909,10 @@ function writePackageManifest(manifest, cwd) {
   writeJson(packageManifestPath(cwd), manifest);
 }
 function getCliTemplatesDir() {
-  return path9.join(path9.dirname(fileURLToPath(import.meta.url)), "..", "templates");
+  return path10.join(path10.dirname(fileURLToPath2(import.meta.url)), "..", "templates");
 }
 function loadAssetsConfigTemplate() {
-  const templatePath = path9.join(getCliTemplatesDir(), "assets.config.defaults.json");
+  const templatePath = path10.join(getCliTemplatesDir(), "assets.config.defaults.json");
   if (!fs8.existsSync(templatePath)) return {};
   try {
     return fs8.readJsonSync(templatePath);
@@ -2806,7 +2921,7 @@ function loadAssetsConfigTemplate() {
   }
 }
 function loadComponentConfigPresetsTemplate() {
-  const templatePath = path9.join(getCliTemplatesDir(), "component.config.presets.json");
+  const templatePath = path10.join(getCliTemplatesDir(), "component.config.presets.json");
   if (!fs8.existsSync(templatePath)) return {};
   try {
     return fs8.readJsonSync(templatePath);
@@ -2821,12 +2936,19 @@ function mergeAssetSlotWithTemplate(slot, templateSlot) {
     "globalIcons",
     "globalEmojis",
     "globalLogos",
-    "globalColorLogos"
+    "globalColorLogos",
+    "globalLoaders",
+    "globalIllustrations",
+    "globalFlags",
+    "globalFileTypes"
   ]) {
     const tplMap = templateSlot[mapKey];
     const userMap = slot?.[mapKey];
-    if (tplMap && typeof tplMap === "object" && (!userMap || Object.keys(userMap).length === 0)) {
-      out[mapKey] = tplMap;
+    if (tplMap && typeof tplMap === "object") {
+      out[mapKey] = {
+        ...tplMap,
+        ...userMap ?? {}
+      };
     }
   }
   return out;
@@ -2856,7 +2978,7 @@ function seedAssetsOutputFromTemplate(output) {
   }
 }
 function assetsConfigPath(cwd) {
-  return path9.join(resolveIuiProjectRoot(cwd ?? process.cwd()), ASSETS_CONFIG_FILE);
+  return path10.join(resolveIuiProjectRoot(cwd ?? process.cwd()), ASSETS_CONFIG_FILE);
 }
 function readExistingAssetsConfigRaw(cwd) {
   const p = assetsConfigPath(cwd);
@@ -3019,7 +3141,7 @@ function writeAssetsConfig(cwd = process.cwd()) {
   seedAssetsOutputFromTemplate(output);
   writeJson(assetsConfigPath(cwd), output);
   try {
-    const legacyIconDefaults = path9.join(cwd ?? process.cwd(), IUI_DIR, "icon-defaults.json");
+    const legacyIconDefaults = path10.join(cwd ?? process.cwd(), IUI_DIR, "icon-defaults.json");
     if (fs8.existsSync(legacyIconDefaults)) fs8.removeSync(legacyIconDefaults);
   } catch {
   }
@@ -3035,7 +3157,7 @@ function writeSlotManifest(manifest, cwd) {
 function readComponentPackageManifest(cwd = process.cwd()) {
   const pkgDir = resolvePackageDir("@inventive-ui/components", cwd);
   if (!pkgDir) return null;
-  const p = path9.join(pkgDir, "iui-manifest.json");
+  const p = path10.join(pkgDir, "iui-manifest.json");
   if (!fs8.existsSync(p)) return null;
   try {
     const raw = fs8.readJsonSync(p);
@@ -3051,7 +3173,7 @@ function readComponentPackageManifest(cwd = process.cwd()) {
 function getInstalledPackageVersion(packageName, cwd = process.cwd()) {
   const pkgDir = resolvePackageDir(packageName, cwd);
   if (!pkgDir) return null;
-  const pkgPath = path9.join(pkgDir, "package.json");
+  const pkgPath = path10.join(pkgDir, "package.json");
   if (!fs8.existsSync(pkgPath)) return null;
   try {
     const pkg = fs8.readJsonSync(pkgPath);
@@ -3069,121 +3191,11 @@ function registryItemsMap(manifest) {
   return map;
 }
 function writeProjectConfig(cwd = process.cwd()) {
-  const configPath = path9.join(cwd, PROJECT_CONFIG_FILE);
-  const content = `import type { IUIThemeConfig } from "@inventive-ui/framework/config";
-
-const config: IUIThemeConfig = {
-  theme: {
-    mode: {
-      default: "light",
-      allowSystem: true,
-    },
-
-    direction: "ltr",
-
-    colors: {
-      semantic: {
-        success: "green",
-        warning: "amber",
-        danger: "red",
-        info: "blue",
-      },
-
-      neutral: {
-        base: "gray",
-        warm: "stone",
-        cool: "slate",
-      },
-
-      brand: {
-        set: "indigo",
-      },
-
-      accent: {
-        "accent-1": "fuchsia",
-      },
-
-      gradients: {
-        sunset: {
-          from: "success",
-          to: "blue",
-          direction: "to end",
-        },
-        glass: {
-          from: "red",
-          to: "yellow",
-          direction: "to end",
-        },
-      },
-    },
-
-    typography: {
-      provider: "system",
-      set: "inter",
-    },
-
-    spacing: {
-      set: "compact",
-    },
-
-    radius: {
-      set: "none",
-    },
-  },
-
-  states: {
-    focused: {
-      mode: "native",
-      shades: { light: "600", dark: "400" },
-      style: {
-        width: 2,
-        offset: 2,
-        offsetColor: { light: "white", dark: "black" },
-      },
-      accessibility: { minContrast: 3, highContrastSupport: false },
-    },
-    disabled: {
-      style: "fade",
-      opacity: 0.5,
-    },
-    loading: {
-      style: "fade",
-      opacity: 0.5,
-      spinner: true,
-      cursor: "wait",
-      label: "Loading",
-    },
-  },
-
-  core: {
-    important: false,
-  },
-
-  /**
-   * Compile-first CSS \u2014 scanned at build time by the Vite/Webpack/Next plugin.
-   * Do not import style-map ".generated" files into the browser graph.
-   * scanDirs / scanPackages default in Framework \u2014 override only when needed.
-   * See Framework docs/01-compile-first-guide.md for all build options.
-   */
-  build: {
-    safelist: [],
-    packageSafelist: false,
-    includeShadeMatrix: false,
-    includeThemePresets: true,
-    resolvePalettePatterns: true,
-    includeArbitraryScan: true,
-    writeFiles: false,
-    minify: true,
-    useAst: true,
-  },
-};
-
-export default config;
-`;
-  atomicWriteFile(configPath, content);
+  const configPath = path10.join(cwd, PROJECT_CONFIG_FILE);
+  atomicWriteFile(configPath, buildProjectConfigSource(cwd));
 }
 function ensureProjectConfigBuildBlock(cwd = process.cwd()) {
-  const configPath = path9.join(resolveIuiProjectRoot(cwd), PROJECT_CONFIG_FILE);
+  const configPath = path10.join(resolveIuiProjectRoot(cwd), PROJECT_CONFIG_FILE);
   if (!fs8.existsSync(configPath)) return false;
   const before = fs8.readFileSync(configPath, "utf-8");
   const result = patchProjectConfigBuildBlock(before);
@@ -3193,7 +3205,7 @@ function ensureProjectConfigBuildBlock(cwd = process.cwd()) {
 }
 function ensureProjectConfig(cwd = process.cwd()) {
   const root = resolveIuiProjectRoot(cwd);
-  const configPath = path9.join(root, PROJECT_CONFIG_FILE);
+  const configPath = path10.join(root, PROJECT_CONFIG_FILE);
   if (!fs8.existsSync(configPath)) {
     writeProjectConfig(root);
     return "scaffolded";
@@ -3221,7 +3233,7 @@ function isIuiManagedOrMinimalScaffold(content) {
 function removeStaleIuiViteConfig(cwd = process.cwd()) {
   if (projectHasViteTooling(cwd)) return false;
   let removed = false;
-  const configPath = path9.join(cwd, "vite.config.ts");
+  const configPath = path10.join(cwd, "vite.config.ts");
   if (fs8.existsSync(configPath)) {
     const existing = fs8.readFileSync(configPath, "utf-8");
     if (isIuiManagedOrMinimalScaffold(existing)) {
@@ -3229,7 +3241,7 @@ function removeStaleIuiViteConfig(cwd = process.cwd()) {
       removed = true;
     }
   }
-  const nodeTsPath = path9.join(cwd, "tsconfig.node.json");
+  const nodeTsPath = path10.join(cwd, "tsconfig.node.json");
   if (fs8.existsSync(nodeTsPath)) {
     try {
       const nodeTs = fs8.readJsonSync(nodeTsPath);
@@ -3244,7 +3256,7 @@ function removeStaleIuiViteConfig(cwd = process.cwd()) {
   return removed;
 }
 function writeTsConfigNode(cwd = process.cwd()) {
-  const nodeTsPath = path9.join(cwd, "tsconfig.node.json");
+  const nodeTsPath = path10.join(cwd, "tsconfig.node.json");
   const content = {
     compilerOptions: {
       target: "ES2022",
@@ -3264,7 +3276,7 @@ function writeTsConfigNode(cwd = process.cwd()) {
   atomicWriteJson(nodeTsPath, content);
 }
 function writeTsConfig(framework, cwd = process.cwd()) {
-  const tsconfigPath = path9.join(cwd, "tsconfig.json");
+  const tsconfigPath = path10.join(cwd, "tsconfig.json");
   let existing = {};
   if (fs8.existsSync(tsconfigPath)) {
     try {
@@ -3332,7 +3344,7 @@ function writeTsConfig(framework, cwd = process.cwd()) {
   atomicWriteJson(tsconfigPath, output);
 }
 function writeComponentConfig(manifest, cwd = process.cwd()) {
-  const configPath = path9.join(cwd, COMPONENT_CONFIG_FILE);
+  const configPath = path10.join(cwd, COMPONENT_CONFIG_FILE);
   let entries = "";
   const typedEntries = [];
   const typeImports = [];
@@ -3385,7 +3397,7 @@ ${entries}};
   atomicWriteFile(configPath, content);
 }
 function ensureComponentConfig(manifest, cwd = process.cwd(), options = {}) {
-  const configPath = path9.join(cwd, COMPONENT_CONFIG_FILE);
+  const configPath = path10.join(cwd, COMPONENT_CONFIG_FILE);
   if (options.force || !fs8.existsSync(configPath)) {
     const existed = fs8.existsSync(configPath);
     writeComponentConfig(manifest, cwd);
@@ -3402,7 +3414,7 @@ function isInsideProject(cwd = process.cwd()) {
 }
 function detectRepoUrl(cwd = process.cwd()) {
   try {
-    const gitConfigPath = path9.join(cwd, ".git", "config");
+    const gitConfigPath = path10.join(cwd, ".git", "config");
     if (!fs8.existsSync(gitConfigPath)) return cwd;
     const gitConfig = fs8.readFileSync(gitConfigPath, "utf-8");
     const match = gitConfig.match(/url\s*=\s*(.+)/);
@@ -3412,11 +3424,11 @@ function detectRepoUrl(cwd = process.cwd()) {
   }
 }
 function hasPackageJson(cwd = process.cwd()) {
-  return fs8.existsSync(path9.join(cwd, "package.json"));
+  return fs8.existsSync(path10.join(cwd, "package.json"));
 }
 function cleanupLegacyFrameworkMeta(cwd = process.cwd()) {
   try {
-    const legacyPath = path9.join(cwd, IUI_DIR, "framework.json");
+    const legacyPath = path10.join(cwd, IUI_DIR, "framework.json");
     if (fs8.existsSync(legacyPath)) fs8.removeSync(legacyPath);
   } catch {
   }
@@ -3433,7 +3445,7 @@ var LOCKFILES = [
 ];
 var PM_PRIORITY = ["bun", "pnpm", "yarn", "npm"];
 function readPackageManagerField(cwd) {
-  const pkgPath = path9.join(cwd, "package.json");
+  const pkgPath = path10.join(cwd, "package.json");
   if (!fs8.existsSync(pkgPath)) return null;
   try {
     const pkg = fs8.readJsonSync(pkgPath);
@@ -3449,11 +3461,11 @@ function readPackageManagerField(cwd) {
 }
 function detectPackageManagerWithMeta(cwd = process.cwd()) {
   const warnings = [];
-  const root = findWorkspaceRoot(cwd) ?? path9.resolve(cwd);
+  const root = findWorkspaceRoot(cwd) ?? path10.resolve(cwd);
   const declared = readPackageManagerField(root);
   const presentLockPms = [
     ...new Set(
-      LOCKFILES.filter(({ file }) => fs8.existsSync(path9.join(root, file))).map(
+      LOCKFILES.filter(({ file }) => fs8.existsSync(path10.join(root, file))).map(
         ({ pm }) => pm
       )
     )
@@ -3497,7 +3509,7 @@ function installCmd(pm, pkg, cwd) {
   if (cwd) {
     const { commandCwd, workspaceName } = resolveWorkspaceInstallRouting(cwd);
     if (workspaceName) {
-      const fromRoot = path9.resolve(commandCwd) !== path9.resolve(cwd) ? ` (run from ${commandCwd})` : "";
+      const fromRoot = path10.resolve(commandCwd) !== path10.resolve(cwd) ? ` (run from ${commandCwd})` : "";
       switch (pm) {
         case "yarn":
           return `yarn workspace ${workspaceName} add ${pkg}${fromRoot}`;
@@ -3534,7 +3546,7 @@ function installDevCmd(pm, pkg) {
   }
 }
 function runTarballInstall(pm, tarballPath, cwd) {
-  const resolvedTarball = path9.resolve(tarballPath);
+  const resolvedTarball = path10.resolve(tarballPath);
   if (!fs8.existsSync(resolvedTarball)) {
     throw new CLIError(`Tarball not found: ${resolvedTarball}`);
   }
@@ -3549,7 +3561,7 @@ function runSyncInstall2(pm, cwd) {
   runSyncInstall(pm, resolveDependencyInstallRoot(cwd));
 }
 function fixTarballDep(packageName, version, cwd = process.cwd()) {
-  const pkgPath = path9.join(cwd, "package.json");
+  const pkgPath = path10.join(cwd, "package.json");
   if (!fs8.existsSync(pkgPath)) return;
   try {
     const pkg = fs8.readJsonSync(pkgPath);
@@ -3571,7 +3583,7 @@ function npmrcAuthLine(token) {
 }
 function ensureProjectNpmrc(cwd = process.cwd()) {
   const configRoot = resolveProjectConfigRoot(cwd);
-  const npmrcPath = path9.join(configRoot, ".npmrc");
+  const npmrcPath = path10.join(configRoot, ".npmrc");
   let content = "";
   if (fs8.existsSync(npmrcPath)) {
     content = fs8.readFileSync(npmrcPath, "utf-8");
@@ -3590,7 +3602,7 @@ function ensureProjectNpmrc(cwd = process.cwd()) {
   atomicWriteFile(npmrcPath, result);
 }
 function writeGlobalNpmrcAuth(token) {
-  const globalNpmrc = path9.join(os3.homedir(), ".npmrc");
+  const globalNpmrc = path10.join(os3.homedir(), ".npmrc");
   let content = "";
   if (fs8.existsSync(globalNpmrc)) {
     content = fs8.readFileSync(globalNpmrc, "utf-8");
@@ -3606,7 +3618,7 @@ function writeGlobalNpmrcAuth(token) {
   writeFileRestricted(globalNpmrc, result);
 }
 function removeGlobalNpmrcAuth() {
-  const globalNpmrc = path9.join(os3.homedir(), ".npmrc");
+  const globalNpmrc = path10.join(os3.homedir(), ".npmrc");
   if (!fs8.existsSync(globalNpmrc)) return;
   const content = fs8.readFileSync(globalNpmrc, "utf-8");
   const url = new URL(`${API_BASE_URL}/registry/npm`);
@@ -3624,7 +3636,7 @@ function removeGlobalNpmrcAuth() {
 }
 function ensureGitignoreHasNpmrc(cwd = process.cwd()) {
   const configRoot = resolveProjectConfigRoot(cwd);
-  const giPath = path9.join(configRoot, ".gitignore");
+  const giPath = path10.join(configRoot, ".gitignore");
   if (!fs8.existsSync(giPath)) return;
   const content = fs8.readFileSync(giPath, "utf-8");
   if (content.split("\n").some((l) => l.trim() === ".npmrc")) return;
@@ -3633,25 +3645,10 @@ function ensureGitignoreHasNpmrc(cwd = process.cwd()) {
 .npmrc
 `);
 }
-var IUI_BUILD_CACHE_GITIGNORE_LINES = [
-  "",
-  "# IUI compile-first build cache (generated slot files under .iui/generated/ stay committed)",
-  ".iui/slot-registration-state.json",
-  ".iui/slot-registration.lock",
-  ".iui/classes.cache.json",
-  ".iui/utilities.css",
-  ".iui/build-styles.generated.css",
-  ".iui/build-styles.generated.js",
-  ".iui/build-manifest.generated.js",
-  ".iui/build-css-inline.js",
-  ".iui/build-manifest.json",
-  ".iui-bootstrap-client.js",
-  ".iui-bootstrap-server.js",
-  "public/iui/"
-];
+var IUI_BUILD_CACHE_GITIGNORE_LINES = IUI_CACHE_GITIGNORE_LINES;
 function ensureGitignoreHasIuiBuildCache(cwd = process.cwd()) {
   const configRoot = resolveProjectConfigRoot(cwd);
-  const giPath = path9.join(configRoot, ".gitignore");
+  const giPath = path10.join(configRoot, ".gitignore");
   if (!fs8.existsSync(giPath)) return;
   const content = fs8.readFileSync(giPath, "utf-8");
   const lines = content.split("\n");
@@ -3665,7 +3662,7 @@ function ensureGitignoreHasIuiBuildCache(cwd = process.cwd()) {
 `);
 }
 function detectReactVersion(cwd = process.cwd()) {
-  const pkgPath = path9.join(cwd, "package.json");
+  const pkgPath = path10.join(cwd, "package.json");
   if (!fs8.existsSync(pkgPath)) return { status: "not-installed" };
   try {
     const pkg = fs8.readJsonSync(pkgPath);
@@ -3683,7 +3680,7 @@ function detectReactVersion(cwd = process.cwd()) {
 }
 function getInstalledReactVersion(cwd) {
   try {
-    const reactPkgPath = path9.join(cwd, "node_modules", "react", "package.json");
+    const reactPkgPath = path10.join(cwd, "node_modules", "react", "package.json");
     if (!fs8.existsSync(reactPkgPath)) return null;
     const reactPkg = fs8.readJsonSync(reactPkgPath);
     return reactPkg.version ?? null;
@@ -3697,7 +3694,7 @@ function isReact19(version) {
   return major === 19;
 }
 function detectReactDomVersion(cwd = process.cwd()) {
-  const pkgPath = path9.join(cwd, "package.json");
+  const pkgPath = path10.join(cwd, "package.json");
   if (!fs8.existsSync(pkgPath)) return { status: "not-installed" };
   try {
     const pkg = fs8.readJsonSync(pkgPath);
@@ -3715,7 +3712,7 @@ function detectReactDomVersion(cwd = process.cwd()) {
 }
 function getInstalledReactDomVersion(cwd) {
   try {
-    const reactDomPkgPath = path9.join(cwd, "node_modules", "react-dom", "package.json");
+    const reactDomPkgPath = path10.join(cwd, "node_modules", "react-dom", "package.json");
     if (!fs8.existsSync(reactDomPkgPath)) return null;
     const reactDomPkg = fs8.readJsonSync(reactDomPkgPath);
     return reactDomPkg.version ?? null;
@@ -3724,7 +3721,7 @@ function getInstalledReactDomVersion(cwd) {
   }
 }
 function detectViteVersion(cwd = process.cwd()) {
-  const pkgPath = path9.join(cwd, "package.json");
+  const pkgPath = path10.join(cwd, "package.json");
   if (!fs8.existsSync(pkgPath)) return { status: "not-installed" };
   try {
     const pkg = fs8.readJsonSync(pkgPath);
@@ -3742,7 +3739,7 @@ function detectViteVersion(cwd = process.cwd()) {
 }
 function getInstalledViteVersion(cwd) {
   try {
-    const vitePkgPath = path9.join(cwd, "node_modules", "vite", "package.json");
+    const vitePkgPath = path10.join(cwd, "node_modules", "vite", "package.json");
     if (!fs8.existsSync(vitePkgPath)) return null;
     const vitePkg = fs8.readJsonSync(vitePkgPath);
     return vitePkg.version ?? null;
@@ -3765,7 +3762,7 @@ function isViteSupported(version) {
 }
 function ensureInventiveUiViteConfig(cwd = process.cwd()) {
   if (!projectHasViteTooling(cwd)) return "skipped";
-  const configPath = path9.join(cwd, "vite.config.ts");
+  const configPath = path10.join(cwd, "vite.config.ts");
   if (!fs8.existsSync(configPath)) {
     atomicWriteFile(configPath, MINIMAL_VITE_SCAFFOLD);
     return "scaffolded";
@@ -3779,13 +3776,13 @@ function ensureInventiveUiViteConfig(cwd = process.cwd()) {
 }
 
 // src/services/auth.ts
-async function api(path26, opts) {
-  const res = await fetch(`${API_BASE_URL}${path26}`, {
+async function api(path28, opts) {
+  const res = await fetch(`${API_BASE_URL}${path28}`, {
     ...opts,
     signal: opts?.signal ?? AbortSignal.timeout(API_REQUEST_TIMEOUT_MS),
     headers: { "Content-Type": "application/json", ...opts?.headers }
   });
-  throwIfRateLimited(res, `calling ${path26}`);
+  throwIfRateLimited(res, `calling ${path28}`);
   if (!res.ok) {
     const body = await res.text().catch(() => "");
     throw new CLIError(`API error ${res.status}: ${body || res.statusText}`);
@@ -4233,7 +4230,7 @@ async function promptText(title, hint2, placeholder, validate) {
 }
 
 // src/commands/init.ts
-import path21 from "path";
+import path23 from "path";
 import ora3 from "ora";
 
 // src/services/license.ts
@@ -4571,7 +4568,7 @@ async function fetchLatestCliVersion(token) {
 }
 
 // src/services/framework.ts
-import path12 from "path";
+import path13 from "path";
 import fs10 from "fs-extra";
 import ora from "ora";
 
@@ -4580,7 +4577,7 @@ import { createWriteStream, mkdtempSync, unlinkSync, rmSync } from "fs";
 import { pipeline } from "stream/promises";
 import { Readable, Transform } from "stream";
 import os4 from "os";
-import path10 from "path";
+import path11 from "path";
 var MAX_TARBALL_BYTES = 250 * 1024 * 1024;
 async function downloadPackageTarball(token, packageShortName) {
   if (!/^[a-z0-9][a-z0-9._-]*$/.test(packageShortName)) {
@@ -4624,8 +4621,8 @@ async function downloadPackageTarball(token, packageShortName) {
       );
     }
   }
-  const tmpDir = mkdtempSync(path10.join(os4.tmpdir(), "iui-dl-"));
-  const tempPath = path10.join(tmpDir, `${packageShortName}.tgz`);
+  const tmpDir = mkdtempSync(path11.join(os4.tmpdir(), "iui-dl-"));
+  const tempPath = path11.join(tmpDir, `${packageShortName}.tgz`);
   const fileStream = createWriteStream(tempPath, { flags: "wx" });
   let bytesWritten = 0;
   const limiter = new Transform({
@@ -4655,7 +4652,7 @@ async function downloadPackageTarball(token, packageShortName) {
   return { path: tempPath, version };
 }
 function cleanupTempFile(filePath) {
-  const parent = path10.dirname(filePath);
+  const parent = path11.dirname(filePath);
   try {
     unlinkSync(filePath);
   } catch {
@@ -4669,7 +4666,7 @@ function cleanupTempFile(filePath) {
 }
 
 // src/utils/declared-deps.ts
-import path11 from "path";
+import path12 from "path";
 import fs9 from "fs-extra";
 function shouldSyncDeclaredDependency(declared, installed) {
   const desired = `^${installed}`;
@@ -4687,7 +4684,7 @@ function readDepField(pkg, packageName) {
   return { field, declared };
 }
 function syncDeclaredDependencyVersion(packageName, cwd = process.cwd()) {
-  const pkgPath = path11.join(cwd, "package.json");
+  const pkgPath = path12.join(cwd, "package.json");
   if (!fs9.existsSync(pkgPath)) return false;
   const installed = getInstalledPackageVersion(packageName, cwd);
   if (!installed) return false;
@@ -4701,8 +4698,14 @@ function syncDeclaredDependencyVersion(packageName, cwd = process.cwd()) {
   atomicWriteJson(pkgPath, pkg);
   return true;
 }
+function getDirectDeclaredVersionFloor(packageName, cwd = process.cwd()) {
+  const declared = isPackageInDirectDeps(packageName, cwd);
+  if (!declared) return null;
+  const floor = cleanVersionString(declared);
+  return floor || null;
+}
 function syncInventiveUiDeclaredDependencies(cwd = process.cwd()) {
-  const pkgPath = path11.join(cwd, "package.json");
+  const pkgPath = path12.join(cwd, "package.json");
   if (!fs9.existsSync(pkgPath)) return [];
   const pkg = fs9.readJsonSync(pkgPath);
   const names = /* @__PURE__ */ new Set();
@@ -4869,7 +4872,10 @@ async function notifyIfUpdateAvailable(token, shortName, currentVersion, label)
 // src/services/framework.ts
 var FRAMEWORK_PACKAGE2 = "@inventive-ui/framework";
 function hasYarnPnP(cwd) {
-  return fs10.existsSync(path12.join(cwd, ".pnp.cjs")) || fs10.existsSync(path12.join(cwd, ".pnp.js"));
+  return fs10.existsSync(path13.join(cwd, ".pnp.cjs")) || fs10.existsSync(path13.join(cwd, ".pnp.js"));
+}
+function getFrameworkUpdateBaselineVersion(cwd = process.cwd()) {
+  return getDirectDeclaredVersionFloor(FRAMEWORK_PACKAGE2, cwd) ?? getInstalledPackageVersion(FRAMEWORK_PACKAGE2, cwd);
 }
 function getFrameworkInstallStatus(cwd = process.cwd()) {
   cleanupLegacyFrameworkMeta(cwd);
@@ -5083,7 +5089,7 @@ function normalizeFrameworkChoice(choice) {
   return null;
 }
 function hasViteConfig(cwd) {
-  return fs10.existsSync(path12.join(cwd, "vite.config.ts")) || fs10.existsSync(path12.join(cwd, "vite.config.mts")) || fs10.existsSync(path12.join(cwd, "vite.config.js")) || fs10.existsSync(path12.join(cwd, "vite.config.mjs")) || fs10.existsSync(path12.join(cwd, "vite.config.cjs"));
+  return fs10.existsSync(path13.join(cwd, "vite.config.ts")) || fs10.existsSync(path13.join(cwd, "vite.config.mts")) || fs10.existsSync(path13.join(cwd, "vite.config.js")) || fs10.existsSync(path13.join(cwd, "vite.config.mjs")) || fs10.existsSync(path13.join(cwd, "vite.config.cjs"));
 }
 async function ensureReactRuntime(pm, cwd, autoApprove, react, reactDom) {
   if (react.status === "ok" && reactDom.status === "ok") {
@@ -5191,12 +5197,12 @@ function getMajorFromVersion(version) {
 import ora2 from "ora";
 
 // src/services/slot-registry.ts
-import fs17 from "fs-extra";
-import path20 from "path";
+import fs18 from "fs-extra";
+import path22 from "path";
 
 // src/services/registry-lock.ts
 import fs11 from "fs";
-import path13 from "path";
+import path14 from "path";
 var LOCK_STALE_MS = 2 * 60 * 1e3;
 var LOCK_RETRY_MS = 80;
 var LOCK_TIMEOUT_MS = 1e4;
@@ -5204,7 +5210,7 @@ function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 function lockPath(cwd) {
-  return path13.join(cwd, IUI_DIR, "slot-registration.lock");
+  return iuiCacheFile(cwd, "slotLock");
 }
 function readLockAge(filePath) {
   try {
@@ -5224,7 +5230,7 @@ function removeStaleLock(filePath) {
 }
 async function acquireRegistryLock(cwd) {
   const filePath = lockPath(cwd);
-  fs11.mkdirSync(path13.dirname(filePath), { recursive: true });
+  fs11.mkdirSync(path14.dirname(filePath), { recursive: true });
   const started = Date.now();
   while (Date.now() - started < LOCK_TIMEOUT_MS) {
     removeStaleLock(filePath);
@@ -5280,16 +5286,16 @@ async function withRegistryLock(cwd, operation) {
 
 // src/services/slots.ts
 import fs15 from "fs-extra";
-import path18 from "path";
+import path19 from "path";
 
 // src/utils/public-slot-contract.ts
-import path14 from "path";
+import path15 from "path";
 import fs12 from "fs-extra";
 var CONTRACT_FILENAME = "public-slot-contract.json";
 function loadPublicSlotContract(cwd = process.cwd()) {
   const pkgRoot = resolvePackageDir("@inventive-ui/components", cwd);
   if (!pkgRoot) return null;
-  const contractPath = path14.join(pkgRoot, CONTRACT_FILENAME);
+  const contractPath = path15.join(pkgRoot, CONTRACT_FILENAME);
   if (!fs12.existsSync(contractPath)) return null;
   try {
     return fs12.readJsonSync(contractPath);
@@ -5367,7 +5373,7 @@ function collectInstalledSlotEmitters(items, installedSlugs, cwd = process.cwd()
 
 // src/utils/security/fsSafe.ts
 import fs13 from "fs";
-import path15 from "path";
+import path16 from "path";
 function assertNotSymlink(filePath, label) {
   try {
     const stat = fs13.lstatSync(filePath);
@@ -5381,11 +5387,11 @@ function assertNotSymlink(filePath, label) {
   }
 }
 function safeWriteFile(filePath, content) {
-  const dir = path15.dirname(filePath);
+  const dir = path16.dirname(filePath);
   if (fs13.existsSync(dir)) {
     assertNotSymlink(dir, "directory");
   }
-  const parent = path15.dirname(filePath);
+  const parent = path16.dirname(filePath);
   fs13.mkdirSync(parent, { recursive: true });
   if (fs13.existsSync(filePath)) {
     assertNotSymlink(filePath, "file");
@@ -5395,22 +5401,22 @@ function safeWriteFile(filePath, content) {
 
 // src/services/asset-bound.ts
 import fs14 from "fs-extra";
-import path17 from "path";
+import path18 from "path";
 import { pathToFileURL } from "url";
 
 // src/services/generated-paths.ts
-import path16 from "path";
-function iuiProjectRoot(cwd) {
+import path17 from "path";
+function iuiProjectRoot2(cwd) {
   return resolveIuiProjectRoot(cwd);
 }
 function generatedIuiDir(cwd) {
-  return path16.join(iuiProjectRoot(cwd), ".iui", "generated");
+  return path17.join(iuiProjectRoot2(cwd), ".iui", "generated");
 }
 function generatedSlotsDir(cwd) {
-  return path16.join(generatedIuiDir(cwd), "slots");
+  return path17.join(generatedIuiDir(cwd), "slots");
 }
 function generatedAssetsDir(cwd) {
-  return path16.join(generatedIuiDir(cwd), "assets");
+  return path17.join(generatedIuiDir(cwd), "assets");
 }
 
 // src/services/asset-bound.ts
@@ -5507,21 +5513,21 @@ function resolveFrameworkModule(cwd, relativePath) {
   const searchRoots = /* @__PURE__ */ new Set();
   for (const candidate of [
     resolveDependencyInstallRoot(cwd),
-    path17.resolve(cwd),
-    iuiProjectRoot(cwd)
+    path18.resolve(cwd),
+    iuiProjectRoot2(cwd)
   ]) {
-    searchRoots.add(path17.resolve(candidate));
+    searchRoots.add(path18.resolve(candidate));
   }
   for (const start of searchRoots) {
     const frameworkDir = resolvePackageDir("@inventive-ui/framework", start);
     if (!frameworkDir) continue;
-    const installed = path17.join(frameworkDir, relativePath);
+    const installed = path18.join(frameworkDir, relativePath);
     if (fs14.existsSync(installed)) return installed;
   }
-  const root = iuiProjectRoot(cwd);
+  const root = iuiProjectRoot2(cwd);
   for (const candidate of [
-    path17.join(root, "..", "Framework", relativePath),
-    path17.join(root, "..", "..", "Framework", relativePath)
+    path18.join(root, "..", "Framework", relativePath),
+    path18.join(root, "..", "..", "Framework", relativePath)
   ]) {
     if (fs14.existsSync(candidate)) return candidate;
   }
@@ -5599,7 +5605,7 @@ function cleanupAssetBoundFiles(cwd) {
   if (!fs14.existsSync(assetsDir)) return;
   for (const file of fs14.readdirSync(assetsDir)) {
     if (file.endsWith(".bound.ts") || file === "register-bound.ts") {
-      fs14.removeSync(path17.join(assetsDir, file));
+      fs14.removeSync(path18.join(assetsDir, file));
     }
   }
   const remaining = fs14.readdirSync(assetsDir);
@@ -5608,10 +5614,10 @@ function cleanupAssetBoundFiles(cwd) {
   }
 }
 function hasAssetBoundRegistration(cwd) {
-  return fs14.existsSync(path17.join(generatedAssetsDir(cwd), "register-bound.ts"));
+  return fs14.existsSync(path18.join(generatedAssetsDir(cwd), "register-bound.ts"));
 }
 async function writeAssetBoundFiles(cwd = process.cwd()) {
-  const root = iuiProjectRoot(cwd);
+  const root = iuiProjectRoot2(cwd);
   const scanUtils = await loadScanUtils(cwd);
   const activeSpecs = BOUND_SPECS.filter(
     (spec) => scanUtils.isScannedAssetBindingEnabled(root, spec.slotType)
@@ -5667,7 +5673,7 @@ async function writeAssetBoundFiles(cwd = process.cwd()) {
   const existing = fs14.existsSync(assetsDir) ? fs14.readdirSync(assetsDir).filter((f) => f.endsWith(".bound.ts")) : [];
   for (const file of existing) {
     if (!generatedFiles.has(file)) {
-      fs14.removeSync(path17.join(assetsDir, file));
+      fs14.removeSync(path18.join(assetsDir, file));
     }
   }
   if (registrationSpecs.length === 0) {
@@ -5702,27 +5708,27 @@ function assetModuleCandidates(pkgRoot, moduleId) {
   const pkgId = pkgName.replace("@inventive-ui/", "");
   if (!subpath || subpath.includes("..")) return [];
   if (pkgId === "loaders") {
-    return [path17.join(pkgRoot, "dist", "loaders", `${subpath}.js`)];
+    return [path18.join(pkgRoot, "dist", "loaders", `${subpath}.js`)];
   }
   if (pkgId === "illustrations") {
     const [family, scene] = subpath.split("/");
     if (family && scene) {
-      return [path17.join(pkgRoot, "dist", family, `${scene}.js`)];
+      return [path18.join(pkgRoot, "dist", family, `${scene}.js`)];
     }
-    return [path17.join(pkgRoot, "dist", `${subpath}.js`)];
+    return [path18.join(pkgRoot, "dist", `${subpath}.js`)];
   }
   const prefix = PKG_LOOKUP_PREFIX[pkgId];
   if (prefix) {
     const dir = prefix.replace(/\/$/, "");
     return [
-      path17.join(pkgRoot, "dist", dir, `${subpath}.js`),
-      path17.join(pkgRoot, "dist", `${subpath}.js`),
-      path17.join(pkgRoot, "dist", subpath, "index.js")
+      path18.join(pkgRoot, "dist", dir, `${subpath}.js`),
+      path18.join(pkgRoot, "dist", `${subpath}.js`),
+      path18.join(pkgRoot, "dist", subpath, "index.js")
     ];
   }
   return [
-    path17.join(pkgRoot, "dist", `${subpath}.js`),
-    path17.join(pkgRoot, "dist", subpath, "index.js")
+    path18.join(pkgRoot, "dist", `${subpath}.js`),
+    path18.join(pkgRoot, "dist", subpath, "index.js")
   ];
 }
 function validateGeneratedAssetBoundImports(cwd = process.cwd()) {
@@ -5731,7 +5737,7 @@ function validateGeneratedAssetBoundImports(cwd = process.cwd()) {
   const issues = [];
   const boundFiles = fs14.readdirSync(assetsDir).filter((file) => file.endsWith(".bound.ts"));
   for (const file of boundFiles) {
-    const content = fs14.readFileSync(path17.join(assetsDir, file), "utf8");
+    const content = fs14.readFileSync(path18.join(assetsDir, file), "utf8");
     const importRe = /from\s+["'](@inventive-ui\/[^"']+)["']/g;
     let match;
     while ((match = importRe.exec(content)) !== null) {
@@ -5755,16 +5761,16 @@ function validateGeneratedAssetBoundImports(cwd = process.cwd()) {
 var SLOT_GROUP_CORE_FILE = "slot-core.generated.tsx";
 var SLOT_GROUP_OPTIONAL_FILE = "slot-optional.generated.tsx";
 function bridgeSlotFilePath(cwd) {
-  return path18.join(cwd, "src", "iui", "slot.tsx");
+  return path19.join(cwd, "src", "iui", "slot.tsx");
 }
 function cleanupLegacySourceSlotFiles(cwd) {
-  const legacySlotsDir = path18.join(cwd, "src", "iui", "slots");
+  const legacySlotsDir = path19.join(cwd, "src", "iui", "slots");
   if (!fs15.existsSync(legacySlotsDir)) return;
   try {
     const files = fs15.readdirSync(legacySlotsDir);
     for (const file of files) {
       if (file.endsWith(".slot.tsx")) {
-        fs15.removeSync(path18.join(legacySlotsDir, file));
+        fs15.removeSync(path19.join(legacySlotsDir, file));
       }
     }
     const remaining = fs15.readdirSync(legacySlotsDir);
@@ -5832,7 +5838,7 @@ function writeComponentSlotFiles(cwd = process.cwd()) {
       const existingSlots2 = fs15.readdirSync(slotsDir).filter((f) => f.endsWith(".slot.tsx"));
       for (const file of existingSlots2) {
         try {
-          fs15.removeSync(path18.join(slotsDir, file));
+          fs15.removeSync(path19.join(slotsDir, file));
         } catch {
         }
       }
@@ -5862,7 +5868,7 @@ function writeComponentSlotFiles(cwd = process.cwd()) {
     if (policy === "core") coreEmitters.push(emitter);
     else optionalEmitters.push(emitter);
   }
-  const root = iuiProjectRoot(cwd);
+  const root = iuiProjectRoot2(cwd);
   const renderedGroups = [
     { fileName: SLOT_GROUP_CORE_FILE, emitters: coreEmitters },
     { fileName: SLOT_GROUP_OPTIONAL_FILE, emitters: optionalEmitters }
@@ -5880,14 +5886,14 @@ function writeComponentSlotFiles(cwd = process.cwd()) {
     if (file === SLOT_GROUP_CORE_FILE || file === SLOT_GROUP_OPTIONAL_FILE) continue;
     if (file.endsWith(".slot.tsx")) {
       try {
-        fs15.removeSync(path18.join(slotsDir, file));
+        fs15.removeSync(path19.join(slotsDir, file));
       } catch {
       }
       continue;
     }
     if (file.endsWith(".generated.tsx")) {
       try {
-        fs15.removeSync(path18.join(slotsDir, file));
+        fs15.removeSync(path19.join(slotsDir, file));
       } catch {
       }
     }
@@ -5988,15 +5994,15 @@ function writeSlotHelperFile(cwd = process.cwd()) {
   }
   const typesArray = Array.from(slotTypes).sort();
   const slotImports = [];
-  const coreSlotsPath = path18.join(generatedSlotsDir(cwd), SLOT_GROUP_CORE_FILE);
-  const optionalSlotsPath = path18.join(generatedSlotsDir(cwd), SLOT_GROUP_OPTIONAL_FILE);
+  const coreSlotsPath = path19.join(generatedSlotsDir(cwd), SLOT_GROUP_CORE_FILE);
+  const optionalSlotsPath = path19.join(generatedSlotsDir(cwd), SLOT_GROUP_OPTIONAL_FILE);
   if (fs15.existsSync(coreSlotsPath)) slotImports.push(`import "./slots/${SLOT_GROUP_CORE_FILE.replace(/\.tsx$/, "")}";`);
   if (fs15.existsSync(optionalSlotsPath)) slotImports.push(`import "./slots/${SLOT_GROUP_OPTIONAL_FILE.replace(/\.tsx$/, "")}";`);
   const componentSlotImports = slotImports.join("\n");
   const includeAssetBindings = hasAssetBoundRegistration(cwd);
   const outDir = generatedIuiDir(cwd);
   fs15.ensureDirSync(outDir);
-  const outPath = path18.join(outDir, "slot.generated.tsx");
+  const outPath = path19.join(outDir, "slot.generated.tsx");
   const sections = [
     `// Managed by iui. Do not edit manually.`,
     `// Rebuilt automatically when the CLI validates the project.`
@@ -6029,11 +6035,11 @@ ${typesArray.map((t) => `  | "${t}"`).join("\n")};` : `export type IUISlotType =
   const content = sections.join("\n");
   safeWriteFile(outPath, content);
 }
-function writeSlotBridge(packageDir, iuiRoot) {
+function writeSlotBridge(packageDir, iuiRoot2) {
   const bridgePath = bridgeSlotFilePath(packageDir);
-  const generatedFile = path18.join(iuiRoot, ".iui", "generated", "slot.generated.tsx");
-  const importBase = relativeImportPath(path18.dirname(bridgePath), generatedFile);
-  fs15.ensureDirSync(path18.dirname(bridgePath));
+  const generatedFile = path19.join(iuiRoot2, ".iui", "generated", "slot.generated.tsx");
+  const importBase = relativeImportPath(path19.dirname(bridgePath), generatedFile);
+  fs15.ensureDirSync(path19.dirname(bridgePath));
   if (fs15.existsSync(bridgePath)) {
     const existing = fs15.readFileSync(bridgePath, "utf-8");
     if (existing.length > 0 && !/@iui-managed/.test(existing)) {
@@ -6052,19 +6058,158 @@ export type { IUISlotType } from "${importBase}";
 }
 
 // src/services/workspace-bootstrap.ts
-import path19 from "path";
+import path21 from "path";
+import fs17 from "fs-extra";
+
+// src/services/bootstrap.ts
 import fs16 from "fs-extra";
-function workspaceManifestPath(iuiRoot) {
-  return path19.join(iuiRoot, IUI_DIR, "workspace.json");
+import path20 from "path";
+var BOOTSTRAP_GENERATED_FILE = "bootstrap.generated.tsx";
+function bridgeBootstrapFilePath(cwd) {
+  return path20.join(cwd, "src", "iui", "bootstrap.ts");
+}
+function bootstrapGeneratedPath(cwd = process.cwd()) {
+  return path20.join(generatedIuiDir(cwd), BOOTSTRAP_GENERATED_FILE);
+}
+function resolveProjectConfigPaths(cwd) {
+  const meta = readProjectMeta(cwd);
+  const configs = meta?.configs;
+  if (configs?.theme && configs?.assets && configs?.components) {
+    return configs;
+  }
+  return {
+    theme: PROJECT_CONFIG_FILE,
+    assets: ASSETS_CONFIG_FILE,
+    components: COMPONENT_CONFIG_FILE
+  };
+}
+function configImportFromGenerated(cwd, configRel) {
+  const generatedDir = path20.dirname(bootstrapGeneratedPath(cwd));
+  const abs = path20.resolve(cwd, configRel.replace(/^\.\//, ""));
+  return relativeImportPath(generatedDir, abs);
 }
-function readWorkspaceManifest(iuiRoot) {
-  const p = workspaceManifestPath(iuiRoot);
-  if (!fs16.existsSync(p)) return null;
+function expectedBootstrapImportPaths(cwd) {
+  const configs = resolveProjectConfigPaths(cwd);
+  return {
+    theme: configImportFromGenerated(cwd, configs.theme),
+    assets: configImportFromGenerated(cwd, configs.assets),
+    components: configImportFromGenerated(cwd, configs.components)
+  };
+}
+function writeBootstrapGenerated(cwd = process.cwd()) {
+  const outPath = bootstrapGeneratedPath(cwd);
+  fs16.ensureDirSync(path20.dirname(outPath));
+  const imports = expectedBootstrapImportPaths(cwd);
+  const content = `// @iui-managed
+
+// Generated by iui CLI \u2014 do not edit manually.
+
+// Connects iui.config.ts + assets.config.json + component.config.ts for standard bootstrap.
+
+
+
+import theme from "${imports.theme}";
+
+import assets from "${imports.assets}";
+
+import { componentConfig as projectComponentConfig } from "${imports.components}";
+
+import {
+
+  mergeProjectConfig,
+
+  initFramework,
+
+  registerBootstrapState,
+
+} from "@inventive-ui/framework";
+
+import { initConfig as initSlotsConfig } from "@inventive-ui/framework/slots";
+
+import type { IUIAssetsConfig } from "@inventive-ui/framework/config";
+
+
+
+import "./slot.generated";
+
+
+
+const themeConfig = (theme as { default?: typeof theme }).default ?? theme;
+
+
+
+export const frameworkConfig = mergeProjectConfig(
+
+  themeConfig,
+
+  assets as IUIAssetsConfig,
+
+);
+
+
+
+registerBootstrapState({
+
+  frameworkConfig,
+
+  componentConfig: projectComponentConfig,
+
+});
+
+
+
+initFramework(frameworkConfig);
+
+initSlotsConfig(frameworkConfig);
+
+
+
+export { projectComponentConfig as componentConfig };
+
+`;
+  safeWriteFile(outPath, content);
+}
+function writeBootstrapBridge(packageDir, iuiRoot2) {
+  const bridgePath = bridgeBootstrapFilePath(packageDir);
+  const generatedFile = bootstrapGeneratedPath(iuiRoot2);
+  const importBase = relativeImportPath(path20.dirname(bridgePath), generatedFile);
+  fs16.ensureDirSync(path20.dirname(bridgePath));
+  if (fs16.existsSync(bridgePath)) {
+    const existing = fs16.readFileSync(bridgePath, "utf-8");
+    if (existing.length > 0 && !/@iui-managed/.test(existing)) {
+      return;
+    }
+  }
+  const bridgeContent = `// Managed by iui. Do not edit manually.
+
+// @iui-managed
+
+// Standard bootstrap: wires theme + assets + component configs before IUIProvider.
+
+
+
+import "${importBase}";
+
+`;
+  safeWriteFile(bridgePath, bridgeContent);
+}
+function writeProjectBootstrapArtifacts(packageDir, iuiRoot2) {
+  writeBootstrapGenerated(iuiRoot2);
+  writeBootstrapBridge(packageDir, iuiRoot2);
+}
+
+// src/services/workspace-bootstrap.ts
+function workspaceManifestPath(iuiRoot2) {
+  return path21.join(iuiRoot2, IUI_DIR, "workspace.json");
+}
+function readWorkspaceManifest(iuiRoot2) {
+  const p = workspaceManifestPath(iuiRoot2);
+  if (!fs17.existsSync(p)) return null;
   try {
-    const raw = fs16.readJsonSync(p);
+    const raw = fs17.readJsonSync(p);
     if (!Array.isArray(raw.packages)) return null;
     return {
-      iuiRoot: raw.iuiRoot ?? iuiRoot,
+      iuiRoot: raw.iuiRoot ?? iuiRoot2,
       packages: raw.packages.map(String),
       updatedAt: raw.updatedAt ?? ""
     };
@@ -6072,63 +6217,64 @@ function readWorkspaceManifest(iuiRoot) {
     return null;
   }
 }
-function writeWorkspaceManifest(iuiRoot, packageDirs) {
-  const unique = [...new Set(packageDirs.map((dir) => path19.resolve(dir)))];
-  atomicWriteJson(workspaceManifestPath(iuiRoot), {
-    iuiRoot,
-    packages: unique.map((dir) => path19.relative(iuiRoot, dir) || "."),
+function writeWorkspaceManifest(iuiRoot2, packageDirs) {
+  const unique = [...new Set(packageDirs.map((dir) => path21.resolve(dir)))];
+  atomicWriteJson(workspaceManifestPath(iuiRoot2), {
+    iuiRoot: iuiRoot2,
+    packages: unique.map((dir) => path21.relative(iuiRoot2, dir) || "."),
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   });
 }
-function resolveRegisteredPackageDirs(iuiRoot) {
-  const resolvedRoot = path19.resolve(iuiRoot);
+function resolveRegisteredPackageDirs(iuiRoot2) {
+  const resolvedRoot = path21.resolve(iuiRoot2);
   const manifest = readWorkspaceManifest(resolvedRoot);
   if (!manifest) return [resolvedRoot];
   const dirs = manifest.packages.map(
-    (rel) => path19.resolve(resolvedRoot, rel === "." ? "" : rel)
+    (rel) => path21.resolve(resolvedRoot, rel === "." ? "" : rel)
   );
-  if (!dirs.some((dir) => path19.resolve(dir) === resolvedRoot)) {
+  if (!dirs.some((dir) => path21.resolve(dir) === resolvedRoot)) {
     dirs.unshift(resolvedRoot);
   }
   return dirs;
 }
-function registerWorkspacePackage(iuiRoot, packageDir) {
-  const resolvedRoot = path19.resolve(iuiRoot);
-  const resolvedPackage = path19.resolve(packageDir);
+function registerWorkspacePackage(iuiRoot2, packageDir) {
+  const resolvedRoot = path21.resolve(iuiRoot2);
+  const resolvedPackage = path21.resolve(packageDir);
   const existing = resolveRegisteredPackageDirs(resolvedRoot);
-  if (!existing.some((dir) => path19.resolve(dir) === resolvedPackage)) {
+  if (!existing.some((dir) => path21.resolve(dir) === resolvedPackage)) {
     existing.push(resolvedPackage);
   }
   writeWorkspaceManifest(resolvedRoot, existing);
 }
-function registerAllWorkspacePackages(iuiRoot) {
-  const resolvedRoot = path19.resolve(iuiRoot);
+function registerAllWorkspacePackages(iuiRoot2) {
+  const resolvedRoot = path21.resolve(iuiRoot2);
   const workspaceRoot = findWorkspaceRoot(resolvedRoot);
   const targets = /* @__PURE__ */ new Set([resolvedRoot]);
   if (workspaceRoot) {
     for (const pkgDir of listWorkspacePackageDirs(workspaceRoot)) {
-      targets.add(path19.resolve(pkgDir));
+      targets.add(path21.resolve(pkgDir));
     }
   }
   const dirs = [...targets];
   writeWorkspaceManifest(resolvedRoot, dirs);
   return dirs;
 }
-function bootstrapRegisteredPackages(iuiRoot) {
-  const resolvedRoot = resolveIuiProjectRoot(iuiRoot);
+function bootstrapRegisteredPackages(iuiRoot2) {
+  const resolvedRoot = resolveIuiProjectRoot(iuiRoot2);
   const bootstrapped = [];
   for (const packageDir of resolveRegisteredPackageDirs(resolvedRoot)) {
-    if (!fs16.existsSync(path19.join(packageDir, "package.json"))) continue;
+    if (!fs17.existsSync(path21.join(packageDir, "package.json"))) continue;
     ensureProjectNpmrc(packageDir);
     writeSlotBridge(packageDir, resolvedRoot);
+    writeProjectBootstrapArtifacts(packageDir, resolvedRoot);
     bootstrapped.push(packageDir);
   }
   return bootstrapped;
 }
-async function bootstrapWorkspacePackage(packageDir, iuiRoot) {
-  const resolvedPackage = path19.resolve(packageDir);
-  const resolvedIuiRoot = resolveIuiProjectRoot(iuiRoot);
-  if (!fs16.existsSync(path19.join(resolvedPackage, "package.json"))) {
+async function bootstrapWorkspacePackage(packageDir, iuiRoot2) {
+  const resolvedPackage = path21.resolve(packageDir);
+  const resolvedIuiRoot = resolveIuiProjectRoot(iuiRoot2);
+  if (!fs17.existsSync(path21.join(resolvedPackage, "package.json"))) {
     throw new CLIError(
       `No package.json found in ${resolvedPackage}.`,
       "Run iui init from a workspace app directory that contains package.json."
@@ -6146,7 +6292,7 @@ async function bootstrapWorkspacePackage(packageDir, iuiRoot) {
     "This app is linked to an existing IUI setup \u2014 packages and configs stay at the IUI root."
   );
   nextSteps([
-    'import "./iui/slot" in your app entry',
+    'import "./iui/bootstrap" in your app entry (or rely on Vite auto-wiring)',
     "iui doctor            \u2014 Verify project health",
     "iui list              \u2014 View installed components"
   ]);
@@ -6154,9 +6300,8 @@ async function bootstrapWorkspacePackage(packageDir, iuiRoot) {
 
 // src/services/slot-registry.ts
 var STATE_SCHEMA_VERSION = 1;
-var STATE_FILE = "slot-registration-state.json";
 function statePath(cwd) {
-  return path20.join(cwd, IUI_DIR, STATE_FILE);
+  return iuiCacheFile(cwd, "slotState");
 }
 function now() {
   return (/* @__PURE__ */ new Date()).toISOString();
@@ -6165,17 +6310,17 @@ function checksumFor(components, slots) {
   return sha256(JSON.stringify({ components, slots }));
 }
 function backupCorruptFile(filePath) {
-  if (!fs17.existsSync(filePath)) return;
+  if (!fs18.existsSync(filePath)) return;
   const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
   try {
-    fs17.moveSync(filePath, `${filePath}.corrupt-${stamp}`, { overwrite: false });
+    fs18.moveSync(filePath, `${filePath}.corrupt-${stamp}`, { overwrite: false });
   } catch {
   }
 }
 function readJsonObject(filePath, fallback, issues, label) {
-  if (!fs17.existsSync(filePath)) return fallback;
+  if (!fs18.existsSync(filePath)) return fallback;
   try {
-    const value = fs17.readJsonSync(filePath);
+    const value = fs18.readJsonSync(filePath);
     if (value && typeof value === "object" && !Array.isArray(value)) {
       return value;
     }
@@ -6187,9 +6332,9 @@ function readJsonObject(filePath, fallback, issues, label) {
 }
 function readState(cwd, issues) {
   const filePath = statePath(cwd);
-  if (!fs17.existsSync(filePath)) return null;
+  if (!fs18.existsSync(filePath)) return null;
   try {
-    const raw = fs17.readJsonSync(filePath);
+    const raw = fs18.readJsonSync(filePath);
     if (raw.schemaVersion !== STATE_SCHEMA_VERSION) {
       issues.push("registration state schema was upgraded");
       return null;
@@ -6291,9 +6436,9 @@ async function ensureSlotRegistry(options = {}) {
   if (!isInsideProject(cwd)) {
     return { status: "skipped", packageVersion: null, repairedIssues: [] };
   }
-  const iuiRoot = resolveIuiProjectRoot(cwd);
-  return withRegistryLock(iuiRoot, async () => {
-    const iuiPath = path20.join(iuiRoot, IUI_DIR);
+  const iuiRoot2 = resolveIuiProjectRoot(cwd);
+  return withRegistryLock(iuiRoot2, async () => {
+    const iuiPath = path22.join(iuiRoot2, IUI_DIR);
     const issues = [];
     cleanupTempFiles(iuiPath);
     const registry = ensureInstalledManifest(
@@ -6304,23 +6449,23 @@ async function ensureSlotRegistry(options = {}) {
       return { status: "skipped", packageVersion: null, repairedIssues: [] };
     }
     const packageVersion = getInstalledPackageVersion(COMPONENTS_PACKAGE, cwd) ?? registry.version;
-    const previousState = readState(iuiRoot, issues);
+    const previousState = readState(iuiRoot2, issues);
     let state = null;
     try {
       const currentComponents = readJsonObject(
-        componentManifestPath(iuiRoot),
+        componentManifestPath(iuiRoot2),
         {},
         issues,
         ".iui/components.json"
       );
       const currentPackages = readJsonObject(
-        packageManifestPath(iuiRoot),
+        packageManifestPath(iuiRoot2),
         {},
         issues,
         ".iui/packages.json"
       );
       const currentSlots = readJsonObject(
-        slotManifestPath(iuiRoot),
+        slotManifestPath(iuiRoot2),
         {},
         issues,
         ".iui/slots.json"
@@ -6347,8 +6492,8 @@ async function ensureSlotRegistry(options = {}) {
       if (driftDetected) {
         issues.push("slot manifests drifted");
       }
-      const generationIssues = validateGeneratedSlotImports(iuiRoot);
-      const assetBoundIssues = validateGeneratedAssetBoundImports(iuiRoot);
+      const generationIssues = validateGeneratedSlotImports(iuiRoot2);
+      const assetBoundIssues = validateGeneratedAssetBoundImports(iuiRoot2);
       const integrityIssues = [...generationIssues, ...assetBoundIssues];
       if (shouldSkipWritesFastPath({
         mode,
@@ -6388,37 +6533,37 @@ async function ensureSlotRegistry(options = {}) {
         attempts: (previousState?.attempts ?? 0) + 1,
         repairedIssues: issues
       };
-      writeState(iuiRoot, state);
-      updateState(iuiRoot, state, "state-loaded");
+      writeState(iuiRoot2, state);
+      updateState(iuiRoot2, state, "state-loaded");
       await retry(() => {
-        writeComponentManifest(desired.components, iuiRoot);
-        writePackageManifest(currentPackages, iuiRoot);
-        writeSlotManifest(desired.slots, iuiRoot);
+        writeComponentManifest(desired.components, iuiRoot2);
+        writePackageManifest(currentPackages, iuiRoot2);
+        writeSlotManifest(desired.slots, iuiRoot2);
       });
-      let next = updateState(iuiRoot, state, "manifests-written", {
+      let next = updateState(iuiRoot2, state, "manifests-written", {
         checksum,
         repairedIssues: issues
       });
       await retry(async () => {
-        writeComponentSlotFiles(iuiRoot);
-        writeAssetsConfig(iuiRoot);
-        ensureProjectConfig(iuiRoot);
-        await writeAssetBoundFiles(iuiRoot);
-        writeSlotHelperFile(iuiRoot);
+        writeComponentSlotFiles(iuiRoot2);
+        writeAssetsConfig(iuiRoot2);
+        ensureProjectConfig(iuiRoot2);
+        await writeAssetBoundFiles(iuiRoot2);
+        writeSlotHelperFile(iuiRoot2);
         if (projectHasViteTooling(cwd)) {
           ensureInventiveUiViteConfig(cwd);
         }
       });
-      bootstrapRegisteredPackages(iuiRoot);
-      next = updateState(iuiRoot, next, "slot-files-written", { repairedIssues: issues });
+      bootstrapRegisteredPackages(iuiRoot2);
+      next = updateState(iuiRoot2, next, "slot-files-written", { repairedIssues: issues });
       if (integrityIssues.length > 0) {
         throw new CLIError(
           "Slot registry integrity check failed.",
           integrityIssues.map((issue) => `- ${issue}`).join("\n")
         );
       }
-      next = updateState(iuiRoot, next, "integrity-verified", { repairedIssues: issues });
-      updateState(iuiRoot, next, "complete", {
+      next = updateState(iuiRoot2, next, "integrity-verified", { repairedIssues: issues });
+      updateState(iuiRoot2, next, "complete", {
         status: "complete",
         completedAt: now(),
         lastError: void 0,
@@ -6435,7 +6580,7 @@ async function ensureSlotRegistry(options = {}) {
     } catch (error) {
       const message = error instanceof Error ? error.message : "Slot registry update failed";
       if (state) {
-        updateState(iuiRoot, state, "state-loaded", {
+        updateState(iuiRoot2, state, "state-loaded", {
           status: "failed",
           lastError: message,
           repairedIssues: issues
@@ -6588,7 +6733,7 @@ async function initCommand(opts) {
   try {
     heading("Initialize Project");
     const existingIuiRoot = findIuiProjectRoot(invocationCwd);
-    if (existingIuiRoot && path21.resolve(existingIuiRoot) !== path21.resolve(invocationCwd)) {
+    if (existingIuiRoot && path23.resolve(existingIuiRoot) !== path23.resolve(invocationCwd)) {
       await bootstrapWorkspacePackage(invocationCwd, existingIuiRoot);
       return;
     }
@@ -6607,10 +6752,10 @@ async function initCommand(opts) {
       return;
     }
     const originalCwd = process.cwd();
-    if (path21.resolve(initRoot) !== path21.resolve(originalCwd)) {
+    if (path23.resolve(initRoot) !== path23.resolve(originalCwd)) {
       process.chdir(initRoot);
       hint(
-        `Monorepo --workspace: initializing at ${path21.relative(invocationCwd, initRoot) || initRoot}`
+        `Monorepo --workspace: initializing at ${path23.relative(invocationCwd, initRoot) || initRoot}`
       );
     } else if (!sharedWorkspace && findIuiProjectRoot(initRoot) === null) {
       hint("Initializing this package only \u2014 other monorepo apps are untouched.");
@@ -6669,7 +6814,12 @@ async function initCommand(opts) {
         projectId: project.project_id,
         repoUrl,
         createdAt: (/* @__PURE__ */ new Date()).toISOString(),
-        initScope: sharedWorkspace ? "workspace" : "package"
+        initScope: sharedWorkspace ? "workspace" : "package",
+        configs: {
+          theme: "./iui.config.ts",
+          assets: "./assets.config.json",
+          components: "./component.config.ts"
+        }
       };
       writeProjectMeta(meta, initRoot);
       step("Configuring npm registry\u2026");
@@ -7488,17 +7638,17 @@ async function deployTokenRevokeCommand(tokenId) {
 }
 
 // src/commands/setup.ts
-import path24 from "path";
-import fs19 from "fs-extra";
+import path26 from "path";
+import fs20 from "fs-extra";
 import ora6 from "ora";
 
 // src/commands/doctor.ts
-import path23 from "path";
+import path25 from "path";
 
 // src/services/health.ts
 import { execFileSync as execFileSync2 } from "child_process";
-import path22 from "path";
-import fs18 from "fs-extra";
+import path24 from "path";
+import fs19 from "fs-extra";
 function installDevTypeScript(cwd) {
   const pm = detectPackageManager(cwd);
   try {
@@ -7541,8 +7691,8 @@ function checkGeneratedSlotValidity(cwd = process.cwd()) {
   };
 }
 function checkComponentConfigValidity(cwd = process.cwd(), options = {}) {
-  const configPath = path22.join(cwd, COMPONENT_CONFIG_FILE);
-  if (!fs18.existsSync(configPath)) {
+  const configPath = path24.join(cwd, COMPONENT_CONFIG_FILE);
+  if (!fs19.existsSync(configPath)) {
     return {
       ok: false,
       summary: "component.config.ts not found",
@@ -7550,8 +7700,8 @@ function checkComponentConfigValidity(cwd = process.cwd(), options = {}) {
     };
   }
   const tsPkgDir = resolvePackageDir("typescript", cwd);
-  const tscPath = tsPkgDir ? path22.join(tsPkgDir, "bin", "tsc") : path22.join(cwd, "node_modules", "typescript", "bin", "tsc");
-  if (!fs18.existsSync(tscPath)) {
+  const tscPath = tsPkgDir ? path24.join(tsPkgDir, "bin", "tsc") : path24.join(cwd, "node_modules", "typescript", "bin", "tsc");
+  if (!fs19.existsSync(tscPath)) {
     if (!options.autoFix) {
       return {
         ok: false,
@@ -7619,9 +7769,9 @@ ${stderr}`.trim() };
 function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
   const warnings = [];
   const hints = [];
-  const configPath = path22.join(cwd, PROJECT_CONFIG_FILE);
-  if (fs18.existsSync(configPath)) {
-    const configContent = fs18.readFileSync(configPath, "utf-8");
+  const configPath = path24.join(cwd, PROJECT_CONFIG_FILE);
+  if (fs19.existsSync(configPath)) {
+    const configContent = fs19.readFileSync(configPath, "utf-8");
     if (!/\bbuild\s*:\s*\{/.test(configContent)) {
       warnings.push("iui.config.ts is missing a compile-first `build` block");
       hints.push(
@@ -7650,11 +7800,11 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
   }
   if (projectHasViteTooling(cwd)) {
     const viteCandidates = ["vite.config.ts", "vite.config.mjs", "vite.config.js"];
-    const vitePath = viteCandidates.map((name) => path22.join(cwd, name)).find((p) => fs18.existsSync(p));
+    const vitePath = viteCandidates.map((name) => path24.join(cwd, name)).find((p) => fs19.existsSync(p));
     if (!vitePath) {
       warnings.push("Vite tooling detected but no vite.config.* found");
     } else {
-      const viteContent = fs18.readFileSync(vitePath, "utf-8");
+      const viteContent = fs19.readFileSync(vitePath, "utf-8");
       if (!/inventiveUiVite\s*\(/.test(viteContent)) {
         warnings.push("vite.config is missing inventiveUiVite() \u2014 compile-first CSS will not generate");
         hints.push("Wire plugins: [...inventiveUiVite({ root: import.meta.dirname }), react()]");
@@ -7668,11 +7818,11 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
       "webpack.config.mjs",
       "webpack.config.ts"
     ];
-    const webpackPath = webpackCandidates.map((name) => path22.join(cwd, name)).find((p) => fs18.existsSync(p));
+    const webpackPath = webpackCandidates.map((name) => path24.join(cwd, name)).find((p) => fs19.existsSync(p));
     if (!webpackPath) {
       warnings.push("Webpack tooling detected but no webpack.config.* found");
     } else {
-      const webpackContent = fs18.readFileSync(webpackPath, "utf-8");
+      const webpackContent = fs19.readFileSync(webpackPath, "utf-8");
       if (!/inventiveUiWebpack\s*\(/.test(webpackContent)) {
         warnings.push("webpack.config is missing inventiveUiWebpack() \u2014 compile-first CSS will not generate");
         hints.push('Wire plugins: [...inventiveUiWebpack()] from "@inventive-ui/framework/webpack"');
@@ -7682,11 +7832,11 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
   }
   if (projectHasNextTooling(cwd)) {
     const nextCandidates = ["next.config.ts", "next.config.mjs", "next.config.js", "next.config.cjs"];
-    const nextPath = nextCandidates.map((name) => path22.join(cwd, name)).find((p) => fs18.existsSync(p));
+    const nextPath = nextCandidates.map((name) => path24.join(cwd, name)).find((p) => fs19.existsSync(p));
     if (!nextPath) {
       warnings.push("Next.js detected but no next.config.* found");
     } else {
-      const nextContent = fs18.readFileSync(nextPath, "utf-8");
+      const nextContent = fs19.readFileSync(nextPath, "utf-8");
       if (!/withIUI\s*\(/.test(nextContent)) {
         warnings.push("next.config is missing withIUI() \u2014 compile-first CSS will not generate");
         hints.push('Wrap config: export default withIUI({ ... }) from "@inventive-ui/framework/next"');
@@ -7699,11 +7849,26 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
       "src/app/layout.jsx",
       "app/providers.tsx",
       "src/app/providers.tsx"
-    ].map((rel) => path22.join(cwd, rel));
-    const hasRegistry = layoutCandidates.some((file) => {
-      if (!fs18.existsSync(file)) return false;
+    ].map((rel) => path24.join(cwd, rel));
+    const readableLayouts = layoutCandidates.filter((file) => fs19.existsSync(file));
+    const hasRegistry = readableLayouts.some((file) => {
+      try {
+        return /\bIUIRegistry\b/.test(fs19.readFileSync(file, "utf-8"));
+      } catch {
+        return false;
+      }
+    });
+    const hasBootstrapImport = readableLayouts.some((file) => {
+      try {
+        const content = fs19.readFileSync(file, "utf-8");
+        return /next\/bootstrap/.test(content) || /["']iui-bootstrap["']/.test(content) || /iui\/bootstrap/.test(content);
+      } catch {
+        return false;
+      }
+    });
+    const hasProvider = readableLayouts.some((file) => {
       try {
-        return /\bIUIRegistry\b/.test(fs18.readFileSync(file, "utf-8"));
+        return /\bIUIProvider\b/.test(fs19.readFileSync(file, "utf-8"));
       } catch {
         return false;
       }
@@ -7712,6 +7877,16 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
       warnings.push("Next.js app should wrap the root layout with <IUIRegistry>");
       hints.push('Import IUIRegistry from "@inventive-ui/framework/next/registry" in the root layout');
     }
+    if (!hasBootstrapImport) {
+      warnings.push("Next.js root layout should import bootstrap before render");
+      hints.push(
+        'Add `import "@inventive-ui/framework/next/bootstrap"` to the root layout (server) and client providers'
+      );
+    }
+    if (!hasProvider) {
+      warnings.push("Next.js app should use <IUIProvider> for bootstrap-state runtime");
+      hints.push('Wrap children with <IUIProvider> from "@inventive-ui/framework" inside IUIRegistry');
+    }
   }
   const entryCandidates = [
     "src/main.tsx",
@@ -7724,14 +7899,14 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
     "src/app/providers.tsx",
     "app/layout.tsx",
     "src/app/layout.tsx"
-  ].map((rel) => path22.join(cwd, rel));
+  ].map((rel) => path24.join(cwd, rel));
   for (const file of entryCandidates) {
-    if (!fs18.existsSync(file)) continue;
+    if (!fs19.existsSync(file)) continue;
     try {
-      const content = fs18.readFileSync(file, "utf-8");
+      const content = fs19.readFileSync(file, "utf-8");
       if (/from\s+['"][^'"]*\.generated['"]/.test(content) || /import\s+['"][^'"]*\.generated['"]/.test(content)) {
         warnings.push(
-          `Do not import .generated style-map files into the browser (${path22.relative(cwd, file)})`
+          `Do not import .generated style-map files into the browser (${path24.relative(cwd, file)})`
         );
         hints.push(
           "Keep style maps on the scanner path (default src/.iui, or override build.scanDirs) \u2014 see Framework compile-first docs"
@@ -7751,32 +7926,32 @@ function checkCompileFirstReadiness(cwd = process.cwd(), _options = {}) {
   hints.push(
     "Compile-first: avoid dynamic utility templates like `p-${n}` \u2014 use static strings, style maps, or safelist (ESLint: customPlugin/no-dynamic-utility-class)"
   );
-  const giPath = path22.join(cwd, ".gitignore");
-  if (fs18.existsSync(giPath)) {
-    const gi = fs18.readFileSync(giPath, "utf-8");
-    if (!gi.includes(".iui/classes.cache.json")) {
-      warnings.push(".gitignore missing IUI compile cache entries (.iui/classes.cache.json)");
-      hints.push("Run iui init or append compile cache paths from the IUI docs");
+  const giPath = path24.join(cwd, ".gitignore");
+  if (fs19.existsSync(giPath)) {
+    const gi = fs19.readFileSync(giPath, "utf-8");
+    if (!gi.includes(".iui/cache/")) {
+      warnings.push(".gitignore missing IUI cache directory (.iui/cache/)");
+      hints.push("Run iui init or append .iui/cache/ from the IUI docs");
     }
   }
   return { warnings, hints };
 }
 function checkAssetBoundBindings(cwd = process.cwd()) {
-  const assetsPath = path22.join(cwd, ASSETS_CONFIG_FILE);
-  if (!fs18.existsSync(assetsPath)) {
+  const assetsPath = path24.join(cwd, ASSETS_CONFIG_FILE);
+  if (!fs19.existsSync(assetsPath)) {
     return { ok: true, summary: "Asset binding check skipped (no assets.config.json)" };
   }
   let assets2;
   try {
-    assets2 = fs18.readJsonSync(assetsPath);
+    assets2 = fs19.readJsonSync(assetsPath);
   } catch {
     return { ok: false, summary: "assets.config.json is not valid JSON" };
   }
   if (assets2.binding !== "scanned") {
     return { ok: true, summary: "Asset slots use lazy binding (default)" };
   }
-  const registerBound = path22.join(generatedAssetsDir(cwd), "register-bound.ts");
-  if (!fs18.existsSync(registerBound)) {
+  const registerBound = path24.join(generatedAssetsDir(cwd), "register-bound.ts");
+  if (!fs19.existsSync(registerBound)) {
     return {
       ok: false,
       summary: 'binding is "scanned" but .iui/generated/assets/register-bound.ts is missing',
@@ -7785,6 +7960,76 @@ function checkAssetBoundBindings(cwd = process.cwd()) {
   }
   return { ok: true, summary: "Scanned asset bindings present" };
 }
+function checkBootstrapSync(cwd = process.cwd(), options = {}) {
+  const iuiRoot2 = resolveIuiProjectRoot(cwd);
+  const generatedPath = bootstrapGeneratedPath(iuiRoot2);
+  const bridgePath = path24.join(cwd, "src", "iui", "bootstrap.ts");
+  if (!fs19.existsSync(generatedPath)) {
+    if (options.autoFix) {
+      writeProjectBootstrapArtifacts(cwd, iuiRoot2);
+      if (fs19.existsSync(generatedPath)) {
+        return { ok: true, summary: "Generated bootstrap artifacts repaired" };
+      }
+    }
+    return {
+      ok: false,
+      summary: "Generated bootstrap missing",
+      details: "Expected .iui/generated/bootstrap.generated.tsx \u2014 run iui doctor --fix."
+    };
+  }
+  if (!fs19.existsSync(bridgePath)) {
+    if (options.autoFix) {
+      writeProjectBootstrapArtifacts(cwd, iuiRoot2);
+      if (fs19.existsSync(bridgePath)) {
+        return { ok: true, summary: "Bootstrap bridge repaired" };
+      }
+    }
+    return {
+      ok: false,
+      summary: "Bootstrap bridge missing",
+      details: "Expected src/iui/bootstrap.ts \u2014 run iui doctor --fix."
+    };
+  }
+  const configs = resolveProjectConfigPaths(iuiRoot2);
+  const missing = [];
+  for (const [key, rel] of Object.entries(configs)) {
+    const abs = path24.resolve(iuiRoot2, rel.replace(/^\.\//, ""));
+    if (!fs19.existsSync(abs)) missing.push(`${key}: ${rel}`);
+  }
+  if (missing.length > 0) {
+    return {
+      ok: false,
+      summary: "Bootstrap config paths from project.json are missing",
+      details: missing.map((line) => `- ${line}`).join("\n")
+    };
+  }
+  const expected = expectedBootstrapImportPaths(iuiRoot2);
+  const generated = fs19.readFileSync(generatedPath, "utf8");
+  const stale = [];
+  for (const [key, importPath] of Object.entries(expected)) {
+    if (!generated.includes(`"${importPath}"`)) {
+      stale.push(`${key} import should be "${importPath}"`);
+    }
+  }
+  if (stale.length > 0) {
+    if (options.autoFix) {
+      writeProjectBootstrapArtifacts(cwd, iuiRoot2);
+      const refreshed = fs19.readFileSync(bootstrapGeneratedPath(iuiRoot2), "utf8");
+      const stillStale = Object.entries(expected).filter(
+        ([, importPath]) => !refreshed.includes(`"${importPath}"`)
+      );
+      if (stillStale.length === 0) {
+        return { ok: true, summary: "Generated bootstrap refreshed from project.json" };
+      }
+    }
+    return {
+      ok: false,
+      summary: "Generated bootstrap is stale",
+      details: stale.map((line) => `- ${line}`).join("\n")
+    };
+  }
+  return { ok: true, summary: "Generated bootstrap matches project.json config paths" };
+}
 
 // src/commands/doctor.ts
 function runConfigTierDiagnostics(targetCwd, opts, counters, options = {}) {
@@ -7981,16 +8226,16 @@ async function runPackageDiagnostics(targetCwd, opts, counters) {
   }
   const auth = getAuthConfig();
   if (auth?.token) {
-    const fwInstalled = getInstalledPackageVersion(FRAMEWORK_PACKAGE, targetCwd);
+    const fwBaseline = getFrameworkUpdateBaselineVersion(targetCwd);
     const compInstalled = getInstalledPackageVersion(COMPONENTS_PACKAGE, targetCwd);
     const [latestFw, latestComp] = await Promise.all([
-      fwInstalled ? getLatestVersionSafe(auth.token, "framework") : Promise.resolve(null),
+      fwBaseline ? getLatestVersionSafe(auth.token, "framework") : Promise.resolve(null),
       compInstalled ? getLatestVersionSafe(auth.token, "components") : Promise.resolve(null)
     ]);
     let behind = false;
-    if (fwInstalled && latestFw && isVersionGreater(latestFw, fwInstalled)) {
+    if (fwBaseline && latestFw && isVersionGreater(latestFw, fwBaseline)) {
       behind = true;
-      warn(`Framework v${fwInstalled} is behind the latest v${latestFw}`);
+      warn(`Framework v${fwBaseline} is behind the latest v${latestFw}`);
     }
     if (compInstalled && latestComp && isVersionGreater(latestComp, compInstalled)) {
       behind = true;
@@ -7998,7 +8243,7 @@ async function runPackageDiagnostics(targetCwd, opts, counters) {
     }
     if (behind) {
       hint("Run iui update to move to the latest versions.");
-    } else if (fwInstalled && latestFw || compInstalled && latestComp) {
+    } else if (fwBaseline && latestFw || compInstalled && latestComp) {
       pass("Inventive UI packages are on the latest version");
     }
   }
@@ -8014,6 +8259,22 @@ async function runPackageDiagnostics(targetCwd, opts, counters) {
     }
     hint("Fix: reinstall @inventive-ui/components and rerun iui doctor");
   }
+  const bootstrapSync = checkBootstrapSync(targetCwd, {
+    autoFix: opts?.fix === true
+  });
+  if (bootstrapSync.ok) {
+    pass(bootstrapSync.summary);
+  } else {
+    fail2(bootstrapSync.summary);
+    if (bootstrapSync.details) {
+      for (const line of bootstrapSync.details.split("\n")) {
+        hint(line);
+      }
+    }
+    if (!opts?.fix) {
+      hint("Fix: run iui doctor --fix to regenerate bootstrap artifacts");
+    }
+  }
   runConfigTierDiagnostics(targetCwd, opts, counters, {
     includePackageJson: false,
     includeSlotCheck: false
@@ -8022,7 +8283,7 @@ async function runPackageDiagnostics(targetCwd, opts, counters) {
 async function doctorCommand(opts) {
   try {
     const invocationCwd = process.cwd();
-    const targets = opts?.cwd ? [path23.resolve(opts.cwd)] : resolveSetupDoctorTargets(invocationCwd);
+    const targets = opts?.cwd ? [path25.resolve(opts.cwd)] : resolveSetupDoctorTargets(invocationCwd);
     const installRoot = resolveDependencyInstallRoot(invocationCwd);
     const multiPackage = targets.length > 1;
     heading("Diagnostics");
@@ -8065,7 +8326,7 @@ async function doctorCommand(opts) {
     for (const targetCwd of targets) {
       if (multiPackage) {
         newline();
-        const label = path23.relative(installRoot, targetCwd) || path23.basename(targetCwd);
+        const label = path25.relative(installRoot, targetCwd) || path25.basename(targetCwd);
         kv("Package", label);
       }
       await runPackageDiagnostics(targetCwd, opts, counters);
@@ -8093,9 +8354,9 @@ async function doctorCommand(opts) {
 
 // src/commands/setup.ts
 function detectDevScript(cwd) {
-  const pkgPath = path24.join(cwd, "package.json");
+  const pkgPath = path26.join(cwd, "package.json");
   try {
-    const pkg = fs19.readJsonSync(pkgPath);
+    const pkg = fs20.readJsonSync(pkgPath);
     if (pkg.scripts?.dev) return "npm run dev";
     if (pkg.scripts?.start) return "npm run start";
   } catch {
@@ -8104,8 +8365,8 @@ function detectDevScript(cwd) {
   return null;
 }
 function relativePackageLabel(installRoot, packageDir) {
-  const rel = path24.relative(installRoot, packageDir);
-  return rel && rel !== "." ? rel : path24.basename(packageDir);
+  const rel = path26.relative(installRoot, packageDir);
+  return rel && rel !== "." ? rel : path26.basename(packageDir);
 }
 async function setupCommand(opts) {
   try {
@@ -8114,7 +8375,7 @@ async function setupCommand(opts) {
     const installRoot = resolveDependencyInstallRoot(cwd);
     const workspaceRoot = findWorkspaceRoot(cwd);
     const inMonorepo = workspaceRoot !== null;
-    const installFromChild = inMonorepo && path24.resolve(installRoot) !== path24.resolve(cwd);
+    const installFromChild = inMonorepo && path26.resolve(installRoot) !== path26.resolve(cwd);
     if (!hasPackageJson(cwd) && !hasPackageJson(installRoot)) {
       throw new CLIError(
         "No package.json found in the current directory.",
@@ -8148,7 +8409,7 @@ async function setupCommand(opts) {
     for (const w of warnings) warn(w);
     kv("Package manager", `${pm} (${source})`);
     if (installFromChild) {
-      const rel = path24.relative(cwd, installRoot) || ".";
+      const rel = path26.relative(cwd, installRoot) || ".";
       kv("Install directory", rel === ".." || rel.includes("..") ? installRoot : rel);
     }
     const installCmd2 = syncInstallCommand(pm);
@@ -8162,7 +8423,7 @@ async function setupCommand(opts) {
     } catch (err) {
       installSpinner.fail("Dependency install failed");
       const detail = formatExecSyncError(err);
-      const manual = path24.resolve(installRoot) === path24.resolve(cwd) ? installCmd2 : `cd ${JSON.stringify(installRoot)} && ${installCmd2}`;
+      const manual = path26.resolve(installRoot) === path26.resolve(cwd) ? installCmd2 : `cd ${JSON.stringify(installRoot)} && ${installCmd2}`;
       throw new CLIError(
         detail ? `Could not install project dependencies.
 ${detail}` : "Could not install project dependencies.",
@@ -8320,7 +8581,7 @@ async function updateCommand(opts = {}) {
     const auth = await ensureAuthSession();
     await ensureLicenseSession();
     const inProject = isInsideProject();
-    const currentCliVersion = true ? "0.0.1" : "unknown";
+    const currentCliVersion = true ? "0.0.3" : "unknown";
     const latestCliVersion = await fetchLatestCliVersion(auth.token);
     const cliUpdateAvailable = latestCliVersion !== null && isVersionGreater(latestCliVersion, currentCliVersion);
     if (latestCliVersion && cliUpdateAvailable) {
@@ -8385,15 +8646,16 @@ async function updateCommand(opts = {}) {
       }
     }
     const frameworkStatus = getFrameworkInstallStatus(installCwd);
+    const frameworkBaselineVersion = getFrameworkUpdateBaselineVersion(installCwd);
     const latestFrameworkVersion = await fetchLatestScopedPackageVersion(auth.token, "framework");
-    const frameworkUpdateAvailable = frameworkStatus.installed && frameworkStatus.version && latestFrameworkVersion && isVersionGreater(latestFrameworkVersion, frameworkStatus.version);
+    const frameworkUpdateAvailable = frameworkStatus.installed && frameworkBaselineVersion && latestFrameworkVersion && isVersionGreater(latestFrameworkVersion, frameworkBaselineVersion);
     let shouldUpdateFramework = false;
     if (frameworkUpdateAvailable) {
       subheading("Framework update");
       newline();
       updateRow(
         "Inventive UI Framework",
-        frameworkStatus.version ?? "unknown",
+        frameworkBaselineVersion ?? "unknown",
         latestFrameworkVersion ?? "unknown",
         true
       );
@@ -8447,6 +8709,7 @@ async function updateCommand(opts = {}) {
       info("No asset package updates available.");
     }
     const hasAnyUpdates = cliUpdateAvailable || available.length > 0 || assetUpdates.length > 0 || Boolean(frameworkUpdateAvailable);
+    const alignDeclaredDependencies = () => syncInventiveUiDeclaredDependencies(installCwd);
     if (opts.check === true) {
       if (hasAnyUpdates) {
         done("Updates are available.");
@@ -8457,6 +8720,14 @@ async function updateCommand(opts = {}) {
       return;
     }
     if (!hasAnyUpdates) {
+      const synced2 = alignDeclaredDependencies();
+      if (synced2.length > 0) {
+        ok(
+          `Aligned package.json with hoisted installs (${synced2.length} @inventive-ui package${synced2.length === 1 ? "" : "s"})`
+        );
+        done("Workspace dependency declarations are now in sync.");
+        return;
+      }
       done("Everything is up to date.");
       return;
     }
@@ -8509,6 +8780,12 @@ async function updateCommand(opts = {}) {
         updatedAssets += 1;
       }
     }
+    const synced = alignDeclaredDependencies();
+    if (synced.length > 0) {
+      ok(
+        `Aligned package.json with installed versions (${synced.length} @inventive-ui package${synced.length === 1 ? "" : "s"})`
+      );
+    }
     done(
       `Update complete: ${updatedFramework} framework, ${updatedComponents} component${updatedComponents === 1 ? "" : "s"}, ${updatedAssets} asset package${updatedAssets === 1 ? "" : "s"}.`
     );
@@ -8586,7 +8863,7 @@ var AUTH_EXEMPT_COMMANDS = /* @__PURE__ */ new Set([
   "doctor",
   "list"
 ]);
-program.name("iui").description("The official CLI for the Inventive UI Design System").version(true ? "0.0.1" : "1.0.0").option("-C, --cwd <dir>", "Run as if started in the given directory").option("-q, --quiet", "Minimal output (also respects IUI_QUIET=1)").option("--no-color", "Disable ANSI colors");
+program.name("iui").description("The official CLI for the Inventive UI Design System").version(true ? "0.0.3" : "1.0.0").option("-C, --cwd <dir>", "Run as if started in the given directory").option("-q, --quiet", "Minimal output (also respects IUI_QUIET=1)").option("--no-color", "Disable ANSI colors");
 program.command("login").description("Authenticate with GitHub and link your license").option("-f, --force", "Force re-authentication and register this device").option("--bootstrap", "After login, run optional setup prompts").action((opts) => loginCommand(opts));
 program.command("logout").description("Remove stored credentials").action(logoutCommand);
 program.command("whoami").description("Show authenticated identity and license details").action(whoamiCommand);
@@ -8684,7 +8961,7 @@ program.hook("preAction", async (_thisCommand, actionCommand) => {
   const root = topLevelCommandName(actionCommand);
   const globalOpts = program.opts();
   if (globalOpts.cwd) {
-    process.chdir(path25.resolve(globalOpts.cwd));
+    process.chdir(path27.resolve(globalOpts.cwd));
   }
   if (isInsideProject()) {
     try {