@expokit/cli 0.4.4 → 0.5.0

package/bin/expo-kit.js

@@ -20,23 +20,37 @@ import {
   CliError,
   DEFAULT_SITE_URL,
   addTsconfigPathAlias,
+  aliasRootFromTsconfig,
+  aliasTargetForDir,
   canSendToken,
+  caseClash,
+  contentHash,
   envWithoutToken,
+  fileStatus,
   hasJsoncExtras,
   isInsideDir,
   isSafePackageSpec,
   isSafeTabName,
   isValidItemName,
+  kitThemeSource,
   kitVersion,
+  looksLikeKitFile,
   mergeDependencies,
+  missingPackages,
+  normalizeInstalled,
   parseJsonc,
   parseSiteUrl,
   retryDelayMs,
+  recordedHash,
   retryHint,
+  rewriteKitImports,
+  suggestItemNames,
   tabComponentName,
   telemetryEnabled,
+  themeOptions,
   needsDevBuild,
   pickMainExport,
+  unifiedDiff,
 } from './lib.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -61,12 +75,14 @@ const DEFAULT_ALIASES = {
 const SRC_PATHS = {
   components: 'src/components',
   lib: 'src/lib',
+  hooks: 'src/hooks',
   app: 'src/app',
 };
 
 const ROOT_PATHS = {
   components: 'components',
   lib: 'lib',
+  hooks: 'hooks',
   app: 'app',
 };
 
@@ -111,7 +127,12 @@ function warn(msg) {
   console.warn(`\x1b[33mexpo-kit\x1b[0m ${msg}`);
 }
 
+/** Stops the current command with a user-facing message (main prints it and exits 1; a batch `add` records it per item). */
 function fail(msg) {
+  throw new CliError(msg);
+}
+
+function die(msg) {
   console.error(`\x1b[31mexpo-kit\x1b[0m ${msg}`);
   process.exit(1);
 }
@@ -163,13 +184,30 @@ function planTsconfigAlias(projectRoot, aliasTarget) {
   }
 }
 
+/** Flags that take a value (`--dir x` or `--dir=x`), with the example shown when it's missing. */
+const VALUE_FLAGS = {
+  dir: '--dir components/kit',
+  brand: '--brand "#6366f1"',
+  font: '--font Inter',
+  radius: '--radius 14',
+  scheme: '--scheme dark',
+};
+
 function parseFlags(argv) {
-  const flags = { dryRun: false, force: false };
+  const flags = { dryRun: false, force: false, format: true, dir: null, yes: false };
   const positional = [];
-  for (const arg of argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const name = /^--([a-z]+)(=|$)/.exec(arg)?.[1];
     if (arg === '--dry-run') flags.dryRun = true;
     else if (arg === '--force') flags.force = true;
-    else if (arg === '--list' || arg === '-l') positional.push('--list');
+    else if (arg === '--no-format') flags.format = false;
+    else if (arg === '--yes' || arg === '-y') flags.yes = true;
+    else if (name && Object.hasOwn(VALUE_FLAGS, name)) {
+      const value = arg === `--${name}` ? argv[(i += 1)] : arg.slice(name.length + 3);
+      if (!value || value.startsWith('--')) fail(`--${name} needs a value, e.g. ${VALUE_FLAGS[name]}`);
+      flags[name] = value;
+    } else if (arg === '--list' || arg === '-l') positional.push('--list');
     else positional.push(arg);
   }
   return { flags, positional };
@@ -215,6 +253,7 @@ function loadConfig(projectRoot) {
     return { ...defaults, configPath };
   }
   const user = readJsonFile(configPath, 'components.json');
+  if (!user || typeof user !== 'object' || Array.isArray(user)) throw new CliError('components.json must contain a JSON object. Fix it and re-run.');
   const paths = { ...defaults.paths, ...user.paths };
   // Every write goes to path.join(projectRoot, paths.*): a "../" from a cloned repo would land outside the app.
   for (const [key, value] of Object.entries(paths)) {
@@ -223,27 +262,35 @@ function loadConfig(projectRoot) {
       throw new CliError(`components.json paths.${key} (${JSON.stringify(value)}) must be a folder inside the project. Fix it and re-run.`);
     }
   }
+  const aliases = { ...defaults.aliases, ...user.aliases };
+  // Aliases are written into the copied files' import lines: a quote or space would be code, not a path.
+  for (const [key, value] of Object.entries(aliases)) {
+    if (typeof value !== 'string' || !/^[@~#$]?[A-Za-z0-9_.\/-]*$/.test(value) || value.length > 100) {
+      throw new CliError(`components.json aliases.${key} (${JSON.stringify(value)}) must be an import alias like "@/components". Fix it and re-run.`);
+    }
+  }
   return {
     ...defaults,
     ...user,
-    aliases: { ...defaults.aliases, ...user.aliases },
+    aliases,
     paths,
-    installed: { ...user.installed },
+    installed: normalizeInstalled(user.installed),
+    files: cleanFileHashes(user.files),
     configPath,
   };
 }
 
+/** components.json `files` (project path → sha256 of the file as the CLI last wrote it), malformed entries dropped. */
+function cleanFileHashes(files) {
+  if (!files || typeof files !== 'object' || Array.isArray(files)) return {};
+  return Object.fromEntries(Object.keys(files).flatMap((rel) => (recordedHash(files, rel) ? [[rel, files[rel]]] : [])));
+}
+
 function saveConfig(projectRoot, config) {
   const { configPath, ...data } = config;
   fs.writeFileSync(configPath, `${JSON.stringify(data, null, 2)}\n`);
 }
 
-function markTemplateInstalled(projectRoot, config, resolved) {
-  config.installed ??= {};
-  config.installed[resolved] = getPackageVersion();
-  saveConfig(projectRoot, config);
-}
-
 function detectInstalledTemplates(projectRoot, config) {
   const installed = new Set(Object.keys(config.installed ?? {}));
 
@@ -258,43 +305,57 @@ function detectInstalledTemplates(projectRoot, config) {
   return [...installed];
 }
 
-function registryPathToProjectPath(registryRel, config, projectRoot) {
-  const [folder, ...rest] = registryRel.split('/');
-  const folderDest = {
+/** Project folder (relative) each registry src/<folder> lands in. */
+function folderDest(config, folder) {
+  const dest = {
     app: config.paths.app ?? 'src/app',
     components: config.paths.components ?? 'src/components',
     lib: config.paths.lib ?? 'src/lib',
     constants: config.paths.constants ?? 'src/constants',
     hooks: config.paths.hooks ?? 'src/hooks',
   };
-  return path.join(projectRoot, folderDest[folder] ?? `src/${folder}`, ...rest);
+  return dest[folder] ?? `src/${folder}`;
 }
 
-function copyRegistryFiles(filesRoot, projectRoot, config, registryPaths, options) {
-  for (const registryRel of registryPaths) {
-    const srcPath = path.join(filesRoot, 'src', registryRel);
-    const destPath = registryPathToProjectPath(registryRel, config, projectRoot);
-    const rel = path.relative(projectRoot, destPath);
+function registryPathToProjectPath(registryRel, config, projectRoot) {
+  const [folder, ...rest] = registryRel.split('/');
+  return path.join(projectRoot, folderDest(config, folder), ...rest);
+}
 
-    if (!fs.existsSync(srcPath)) {
-      warn(`Registry file missing: ${registryRel}`);
-      continue;
-    }
+/** A registry file as it lands in this project: its @/components and @/lib imports follow components.json aliases. */
+function registryText(srcPath, config) {
+  const text = fs.readFileSync(srcPath, 'utf8');
+  return /\.(tsx?|jsx?)$/.test(srcPath) ? rewriteKitImports(text, config.aliases) : text;
+}
 
-    if (options.dryRun) {
-      log(`  would write ${rel}`);
-      continue;
-    }
+let aliasIndex = null;
 
-    fs.mkdirSync(path.dirname(destPath), { recursive: true });
-    fs.writeFileSync(destPath, fs.readFileSync(srcPath, 'utf8'));
-    log(`  + ${rel}`);
+/** alias → item name: the built-in ones plus every item's `aliases` (grain-gradient → grain). */
+function localAliases() {
+  if (aliasIndex) return aliasIndex;
+  aliasIndex = new Map(Object.entries(ALIASES));
+  for (const file of fs.readdirSync(REGISTRY_DIR).filter((f) => f.endsWith('.json'))) {
+    const meta = tryReadJsonFile(path.join(REGISTRY_DIR, file));
+    for (const alias of Array.isArray(meta?.aliases) ? meta.aliases : []) {
+      if (isValidItemName(alias) && !aliasIndex.has(alias)) aliasIndex.set(alias, meta.name);
+    }
   }
+  return aliasIndex;
 }
 
 function resolveRegistryName(name) {
-  const key = name.toLowerCase();
-  return ALIASES[key] ?? key;
+  const key = String(name).toLowerCase();
+  if (isValidItemName(key) && readMeta(key)) return key;
+  return localAliases().get(key) ?? key;
+}
+
+/** " Did you mean: button?" for a name this CLI doesn't know, or "". */
+function didYouMean(name) {
+  const items = fs.readdirSync(REGISTRY_DIR).filter((f) => f.endsWith('.json')).map((f) => f.slice(0, -'.json'.length));
+  const aliases = localAliases();
+  const close = suggestItemNames(name, [...items, ...aliases.keys()]).map((n) => aliases.get(n) ?? n);
+  const unique = [...new Set(close)];
+  return unique.length ? ` Did you mean: ${unique.join(', ')}?` : '';
 }
 
 function readMeta(resolved) {
@@ -317,10 +378,15 @@ async function loadRegistryItem(name) {
   const resolved = resolveRegistryName(name);
   const meta = isValidItemName(resolved) ? readMeta(resolved) : null;
   if (!meta) {
-    if (!isValidItemName(resolved)) fail(`Unknown item "${name}". Run: ${RUN} add --list`);
+    if (!isValidItemName(resolved)) fail(`Unknown item "${name}".${didYouMean(resolved)} Run: ${RUN} add --list`);
     // Not in this package's registry — it may be newer than this CLI. Ask the site before giving up.
     const remoteMeta = { name: resolved, title: resolved, tier: 'pro', dependencies: [], unknownLocally: true };
-    return stageRemoteItem(remoteMeta, resolved);
+    try {
+      return await stageRemoteItem(remoteMeta, resolved);
+    } catch (e) {
+      if (e instanceof CliError) e.message += didYouMean(resolved);
+      throw e;
+    }
   }
   const filesRoot = bundledFilesRoot(meta);
   if (filesRoot) return { meta, filesRoot, resolved };
@@ -666,101 +732,229 @@ function collectFiles(src, dest, files = []) {
   return files;
 }
 
-function identicalToRegistry(destFile, filesRoot, projectRoot, config) {
+/** Every file an item writes: its registry source, where it lands, and its path under src/ in the registry. */
+function registryFiles(filesRoot, projectRoot, config) {
   const registrySrc = path.join(filesRoot, 'src');
-  for (const folder of fs.readdirSync(registrySrc)) {
-    const destRoot = path.join(projectRoot, config.paths[folder] ?? (folder === 'app' ? 'src/app' : `src/${folder}`));
-    if (destFile.startsWith(destRoot + path.sep)) {
-      const src = path.join(registrySrc, folder, path.relative(destRoot, destFile));
-      return fs.existsSync(src) && fs.readFileSync(src, 'utf8') === fs.readFileSync(destFile, 'utf8');
+  if (!fs.existsSync(registrySrc)) fail('Registry layout must include src/ folder.');
+  const files = [];
+  for (const entry of fs.readdirSync(registrySrc, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const from = path.join(registrySrc, entry.name);
+    for (const src of collectFiles(from, from)) {
+      const registryRel = path.relative(registrySrc, src).split(path.sep).join('/');
+      files.push({ src, registryRel, dest: registryPathToProjectPath(registryRel, config, projectRoot) });
     }
   }
-  return false;
+  return files;
 }
 
-function planRegistryFiles(filesRoot, projectRoot, config) {
-  const registrySrc = path.join(filesRoot, 'src');
-  if (!fs.existsSync(registrySrc)) {
-    fail('Registry layout must include src/ folder.');
+/**
+ * The existing path that differs from `dest` (or one of its folders) only by case — `components/ui/Skeleton.tsx`
+ * for `components/ui/skeleton.tsx` — or null. Read from the folder listings, so it's the same answer on every OS.
+ */
+function caseClashOf(projectRoot, dest) {
+  let dir = projectRoot;
+  for (const seg of path.relative(projectRoot, dest).split(path.sep)) {
+    let names;
+    try {
+      names = fs.readdirSync(dir);
+    } catch {
+      return null; // folder doesn't exist yet: nothing below it can clash
+    }
+    const twin = caseClash(names, seg);
+    if (twin) return path.join(dir, twin);
+    dir = path.join(dir, seg);
   }
+  return null;
+}
 
-  const folderDest = {
-    app: config.paths.app ?? 'src/app',
-    components: config.paths.components ?? 'src/components',
-    lib: config.paths.lib ?? 'src/lib',
-    constants: config.paths.constants ?? 'src/constants',
-    hooks: config.paths.hooks ?? 'src/hooks',
+const posixRel = (projectRoot, file) => path.relative(projectRoot, file).split(path.sep).join('/');
+
+/** Whether diffs get colour: a terminal, and NO_COLOR unset. */
+const COLOR = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+/** At most this many lines of one file's diff are printed; `diff <item>` is the place for the rest. */
+const DIFF_LINE_LIMIT = 120;
+
+/** A unified diff as printable lines (coloured in a terminal), cut at DIFF_LINE_LIMIT. */
+function diffLines(diff, more = '') {
+  const lines = diff.replace(/\n$/, '').split('\n');
+  const paint = (line) => {
+    if (!COLOR || /^(---|\+\+\+) /.test(line)) return line;
+    if (line.startsWith('+')) return `\x1b[32m${line}\x1b[0m`;
+    if (line.startsWith('-')) return `\x1b[31m${line}\x1b[0m`;
+    if (line.startsWith('@@')) return `\x1b[36m${line}\x1b[0m`;
+    return line;
   };
+  const shown = lines.slice(0, DIFF_LINE_LIMIT).map(paint);
+  if (lines.length > DIFF_LINE_LIMIT) shown.push(`… ${lines.length - DIFF_LINE_LIMIT} more line(s)${more}`);
+  return shown;
+}
 
-  const planned = [];
-  for (const entry of fs.readdirSync(registrySrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const destRel = folderDest[entry.name] ?? `src/${entry.name}`;
-    planned.push(
-      ...collectFiles(
-        path.join(registrySrc, entry.name),
-        path.join(projectRoot, destRel)
-      )
+/**
+ * What `add` / `update` would do with each file of an item, decided before anything is written:
+ *   write (new) · same (already identical) · refresh (ours and untouched since: components.json's hash matches) ·
+ *   keep (shared kit file you edited) · overwrite (--force)
+ * plus `problems` that stop the whole item: a different-case twin (never replaced, --force included), a file of
+ * yours where the item needs one of ours, a file you changed since it was installed, or a kept kit.tsx that is too old.
+ * `flags.update`: liquidglass-tab only refreshes its framework files (tabs.ts and screens are yours), and changed
+ * files are reported with their diff.
+ */
+function planItem(item, projectRoot, config, flags) {
+  const { meta, filesRoot, resolved } = item;
+  const shared = new Set(meta.sharedFiles ?? []);
+  const files = [];
+  const problems = [];
+  const theirs = [];
+  const conflicts = [];
+  const componentsDir = posixRel(projectRoot, path.join(projectRoot, config.paths.components ?? 'src/components'));
+  const kitDir = `${componentsDir}/kit`;
+  const frameworkOnly = flags.update && !flags.force && resolved === 'liquidglass-tab';
+
+  for (const { src, dest, registryRel } of registryFiles(filesRoot, projectRoot, config)) {
+    if (frameworkOnly && !LIQUIDGLASS_FRAMEWORK_PATHS.includes(registryRel)) continue;
+    const rel = posixRel(projectRoot, dest);
+    const twin = caseClashOf(projectRoot, dest);
+    if (twin) {
+      const inComponents = registryRel.startsWith('components/');
+      problems.push(
+        `${rel} clashes with your ${posixRel(projectRoot, twin)} (macOS and Windows treat them as one file, so it would replace yours).`,
+        inComponents
+          ? `  • Install it next to yours: ${RUN} add ${resolved} --dir ${kitDir}`
+          : `  • Rename or move your ${posixRel(projectRoot, twin)}, then add ${resolved} again.`,
+        `  • Or keep yours as it is: nothing was written for ${resolved}.`
+      );
+      continue;
+    }
+    const text = registryText(src, config);
+    let stat = null;
+    try {
+      stat = fs.lstatSync(dest);
+    } catch {
+      // doesn't exist yet
+    }
+    if (!stat) {
+      files.push({ rel, dest, text, registryRel, action: 'write' });
+      continue;
+    }
+    // Never write through a link (it could point anywhere, e.g. from a cloned repo) or over a folder.
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+      problems.push(`${rel} is a ${stat.isSymbolicLink() ? 'symlink' : 'folder'}, so it isn't replaced (not even with --force). Move it, then add ${resolved} again.`);
+      continue;
+    }
+    const have = fs.readFileSync(dest, 'utf8');
+    const status = fileStatus(recordedHash(config.files, rel), have, text);
+    if (status === 'current') {
+      files.push({ rel, dest, text, registryRel, action: 'same' });
+    } else if (status === 'pristine') {
+      // Written by the CLI and untouched since (its hash is the one components.json recorded): safe to refresh.
+      files.push({ rel, dest, text, registryRel, action: 'refresh' });
+    } else if (shared.has(registryRel) && looksLikeKitFile(have)) {
+      // A kit file you edited: kept, unless it's too old for this item (missing kit API would crash at runtime).
+      const need = kitVersion(text);
+      const got = kitVersion(have);
+      if (!flags.force && need !== null && got !== null && got < need) {
+        problems.push(
+          `${meta.title} needs a newer kit than your edited ${rel} (kit v${got}, needs v${need}).`,
+          `  • Re-run with --force to replace it (your edits to it are lost — back it up first), or merge the new version by hand.`
+        );
+      }
+      files.push({ rel, dest, text, registryRel, action: flags.force ? 'overwrite' : 'keep' });
+    } else if (flags.force) {
+      files.push({ rel, dest, text, registryRel, action: 'overwrite' });
+    } else if (shared.has(registryRel)) {
+      theirs.push(rel);
+    } else {
+      conflicts.push({ rel, have, text, status });
+    }
+  }
+
+  if (theirs.length) {
+    problems.push(
+      `${theirs.join(', ')} already exist${theirs.length === 1 ? 's' : ''} and isn't an ExpoKit file, but ${meta.title} imports ExpoKit's version from there.`,
+      ...(theirs.some((r) => r.startsWith(`${componentsDir}/`)) ? [`  • Install the kit's copy elsewhere: ${RUN} add ${resolved} --dir ${kitDir}`] : []),
+      `  • Or replace yours (it is lost): ${RUN} add ${resolved} --force`
+    );
+  }
+  if (conflicts.length && flags.update) {
+    problems.push(
+      `${conflicts.length} file(s) changed since ${meta.title} was installed, so none of it was updated:`,
+      ...conflicts.flatMap((c) => [
+        `  • ${c.rel}${c.status === 'untracked' ? ' (no install record: added by an older CLI)' : ''}`,
+        ...diffLines(unifiedDiff(c.have, c.text, { from: `${c.rel} (yours)`, to: `${c.rel} (upstream)` }), ` — see: ${RUN} diff ${resolved}`).map(
+          (line) => `      ${line}`
+        ),
+      ]),
+      `  • Keep yours: nothing was changed. Copy the upstream lines (+) you want into your file; update lists it until it matches.`,
+      `  • Take upstream (your changes are lost): ${RUN} update ${resolved} --force`
+    );
+  } else if (conflicts.length) {
+    problems.push(
+      `Would overwrite ${conflicts.length} file(s) that differ from ${meta.title}:`,
+      ...conflicts.map((c) => `  • ${c.rel}`),
+      `  • See what differs: ${RUN} diff ${resolved}`,
+      `  • Replace them (your changes are lost): ${RUN} add ${resolved} --force`
     );
   }
-  return planned;
+  return { files, problems };
 }
 
-function copyDir(src, dest, projectRoot, options) {
-  const { dryRun } = options;
-  if (!fs.existsSync(dest) && !dryRun) fs.mkdirSync(dest, { recursive: true });
-
-  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
-    const srcPath = path.join(src, entry.name);
-    const destPath = path.join(dest, entry.name);
-    if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, projectRoot, options);
-    } else {
-      const rel = path.relative(projectRoot, destPath);
-      const exists = fs.existsSync(destPath);
-      const same = exists && fs.readFileSync(destPath, 'utf8') === fs.readFileSync(srcPath, 'utf8');
-      const keep = exists && !same && !options.force && options.shared?.has(destPath);
-      if (dryRun) {
-        log(`  would ${same ? 'keep (unchanged)' : keep ? 'keep (shared, yours)' : 'write'} ${rel}${exists && !same && !keep ? ' (overwrite)' : ''}`);
-        continue;
-      }
-      if (same) continue;
-      if (keep) {
-        log(`  = ${rel} (shared file kept — use --force to replace)`);
-        continue;
-      }
-      if (exists) warn(`Overwriting ${rel}`);
-      fs.mkdirSync(path.dirname(destPath), { recursive: true });
-      fs.writeFileSync(destPath, fs.readFileSync(srcPath, 'utf8'));
-      log(`  + ${rel}`);
+/** Writes a planned item. Returns the project files it wrote (for Prettier). */
+function applyPlan(plan) {
+  const written = [];
+  for (const file of plan.files) {
+    if (file.action === 'same') continue;
+    if (file.action === 'keep') {
+      log(`  = ${file.rel} (shared file kept — use --force to replace)`);
+      continue;
     }
+    if (file.action === 'overwrite') warn(`Overwriting ${file.rel}`);
+    fs.mkdirSync(path.dirname(file.dest), { recursive: true });
+    fs.writeFileSync(file.dest, file.text);
+    written.push(file.dest);
+    log(`  ${file.action === 'refresh' ? '~' : '+'} ${file.rel}${file.action === 'refresh' ? ' (updated)' : ''}`);
   }
+  return written;
 }
 
-function mapRegistryToProject(filesRoot, projectRoot, config, options) {
-  const registrySrc = path.join(filesRoot, 'src');
-  if (!fs.existsSync(registrySrc)) {
-    fail('Registry layout must include src/ folder.');
+function printPlan(plan) {
+  for (const file of plan.files) {
+    const what = {
+      write: 'would write',
+      same: 'unchanged',
+      refresh: 'would update',
+      keep: 'would keep (shared, yours)',
+      overwrite: 'would overwrite',
+    }[file.action];
+    log(`  ${what} ${file.rel}`);
   }
+}
 
-  const folderDest = {
-    app: config.paths.app ?? 'src/app',
-    components: config.paths.components ?? 'src/components',
-    lib: config.paths.lib ?? 'src/lib',
-    constants: config.paths.constants ?? 'src/constants',
-    hooks: config.paths.hooks ?? 'src/hooks',
-  };
-
-  for (const entry of fs.readdirSync(registrySrc, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const destRel = folderDest[entry.name] ?? `src/${entry.name}`;
-    copyDir(
-      path.join(registrySrc, entry.name),
-      path.join(projectRoot, destRel),
-      projectRoot,
-      options
-    );
+/**
+ * After a write: components.json remembers each file's hash as it now is on disk (after Prettier), so the next
+ * `update` / `add` can tell "ours, untouched" from "you changed it". Kept files (your edits) keep their old record.
+ */
+function recordInstall(config, name, plan, dir) {
+  for (const file of plan.files) {
+    if (file.action === 'keep') continue;
+    try {
+      config.files[file.rel] = contentHash(fs.readFileSync(file.dest, 'utf8'));
+    } catch {
+      delete config.files[file.rel];
+    }
   }
+  const entry = { version: getPackageVersion() };
+  const kit = plan.files.find((f) => f.registryRel === 'lib/kit.tsx');
+  if (kit) {
+    try {
+      const v = kitVersion(fs.readFileSync(kit.dest, 'utf8'));
+      if (v !== null) entry.kitVersion = v;
+    } catch {
+      // unreadable: no version to record
+    }
+  }
+  if (dir) entry.dir = dir;
+  config.installed[name] = entry;
 }
 
 function ensureExpoRouterMain(projectRoot, dryRun) {
@@ -842,21 +1036,57 @@ function runExpoInstall(projectRoot, packages, dryRun) {
     log(`  would run: npx expo install ${packages.join(' ')}`);
     return true;
   }
-  log(`Installing: ${packages.join(', ')}`);
+  log(`Installing ${packages.join(', ')}…`);
+  // npm's own output (engine warnings, audit notes) stays hidden unless the install fails.
   const result = spawnSync('npx', ['expo', 'install', ...packages], {
     cwd: projectRoot,
     env: childEnv,
-    stdio: 'inherit',
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
     shell: process.platform === 'win32',
   });
   if (result.status !== 0) {
-    warn('expo install failed — run manually:');
+    const lines = `${result.stdout ?? ''}\n${result.stderr ?? ''}`
+      .split(/\r?\n/)
+      .filter((line) => line.trim() && !/\bEBADENGINE\b|^npm warn (engine|  )/i.test(line));
+    if (lines.length) console.log(lines.slice(-25).join('\n'));
+    warn(`expo install failed${result.error ? ` (${result.error.message})` : ''} — run it yourself:`);
     console.log(`  npx expo install ${packages.join(' ')}`);
     return false;
   }
   return true;
 }
 
+/** The project's own Prettier (node_modules/.bin), when package.json lists it; never a download. */
+function projectPrettier(projectRoot, pkg) {
+  if (!pkg?.dependencies?.prettier && !pkg?.devDependencies?.prettier) return null;
+  const bin = path.join(projectRoot, 'node_modules', '.bin', process.platform === 'win32' ? 'prettier.cmd' : 'prettier');
+  return fs.existsSync(bin) ? bin : null;
+}
+
+/** Formats the files `add` wrote with the project's Prettier config, so `npm run lint` / `format --check` pass. */
+function formatWritten(projectRoot, pkg, files, flags) {
+  // Windows runs prettier.cmd through a shell: only plain paths go on its command line.
+  const rels = files.map((f) => path.relative(projectRoot, f)).filter((rel) => /^[A-Za-z0-9_.()[\]\/\\-]+$/.test(rel));
+  if (!flags.format || !rels.length) return;
+  const bin = projectPrettier(projectRoot, pkg);
+  if (!bin) return;
+  if (flags.dryRun) {
+    log('  would format the new files with your Prettier config (--no-format to skip)');
+    return;
+  }
+  const result = spawnSync(bin, ['--write', '--log-level', 'warn', ...rels], {
+    cwd: projectRoot,
+    env: childEnv,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    shell: process.platform === 'win32',
+  });
+  if (result.status === 0) log(`Formatted ${rels.length} file(s) with your Prettier config.`);
+  else warn(`Prettier couldn't format the new files: ${(result.stderr || result.stdout || result.error?.message || '').trim().split('\n')[0]}`);
+}
+
 /** After an add: can the item run in Expo Go, or does it need a development build? */
 function printRunHint(deps) {
   const native = needsDevBuild(deps);
@@ -894,12 +1124,105 @@ function createExpoApp(cwd, dir, flags) {
   return target;
 }
 
-function cmdInit(cwd, flags, dir) {
+/** Asks one theme question until the answer passes `check` (Enter keeps the default). */
+async function ask(rl, question, check) {
+  for (;;) {
+    const answer = (await new Promise((resolve) => rl.question(question, resolve))).trim();
+    try {
+      check(answer);
+      return answer;
+    } catch (e) {
+      if (!(e instanceof CliError)) throw e;
+      warn(e.message.replace(/^--\w+ /, 'It '));
+    }
+  }
+}
+
+/** `init` in a terminal: brand colour, font, radius and light / dark, each skippable with Enter. */
+async function askTheme() {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  rl.on('SIGINT', () => {
+    rl.close();
+    process.stdout.write('\n');
+    process.exit(130);
+  });
+  try {
+    log('Theme (Enter keeps the default; change it later in the file init writes):');
+    const brand = await ask(rl, '  Brand colour, hex (Enter: monochrome) › ', (v) => themeOptions({ brand: v }));
+    const font = await ask(rl, '  Font family (Enter: system font) › ', (v) => themeOptions({ font: v }));
+    const radius = await ask(rl, '  Corner radius in points (Enter: 12) › ', (v) => themeOptions({ radius: v }));
+    const scheme = await ask(rl, '  light, dark or system (Enter: system) › ', (v) => themeOptions({ scheme: v }));
+    return themeOptions({ brand, font, radius, scheme });
+  } finally {
+    rl.close();
+  }
+}
+
+const THEME_FLAGS = ['brand', 'font', 'radius', 'scheme'];
+
+/**
+ * The theme step of `init`: adds kit.tsx (tracked like any add) and writes <lib>/kit-theme.tsx, an `AppTheme`
+ * wrapper around KitProvider with the chosen values. An existing kit-theme.tsx is never replaced: the snippet is
+ * printed instead.
+ */
+function writeTheme(projectRoot, config, theme, flags) {
+  const pkg = readJsonFile(path.join(projectRoot, 'package.json'), 'package.json');
+  const kitMeta = readMeta('kit');
+  const kit = { meta: kitMeta, filesRoot: bundledFilesRoot(kitMeta), resolved: 'kit' };
+  const plan = planItem(kit, projectRoot, config, { force: false });
+  const written = [];
+  if (plan.problems.length) {
+    warn(`Couldn't add lib/kit.tsx, so no theme file was written:`);
+    for (const line of plan.problems) console.log(`    ${line}`);
+    return;
+  }
+  const source = kitThemeSource(theme, config.aliases.lib);
+  const themePath = path.join(projectRoot, folderDest(config, 'lib'), 'kit-theme.tsx');
+  const themeRel = posixRel(projectRoot, themePath);
+  const exists = (() => {
+    try {
+      fs.lstatSync(themePath);
+      return true;
+    } catch {
+      return false;
+    }
+  })();
+  if (flags.dryRun) {
+    printPlan(plan);
+    log(exists ? `  would keep your ${themeRel}` : `  would write ${themeRel}`);
+    return;
+  }
+  written.push(...applyPlan(plan));
+  recordInstall(config, 'kit', plan, null);
+  saveConfig(projectRoot, config);
+  if (exists) {
+    warn(`${themeRel} already exists, so it was kept. The theme you picked, to merge by hand:`);
+    console.log(`\n${source}`);
+  } else {
+    fs.mkdirSync(path.dirname(themePath), { recursive: true });
+    fs.writeFileSync(themePath, source);
+    written.push(themePath);
+    log(`  + ${themeRel}`);
+  }
+  formatWritten(projectRoot, pkg, written, flags);
+  const lib = String(config.aliases.lib).replace(/\/+$/, '');
+  log('Wrap your root layout (app/_layout.tsx) in it:');
+  console.log(`  import { AppTheme } from "${lib}/kit-theme";`);
+  console.log('  <AppTheme><Stack /></AppTheme>');
+  console.log(`  Bring your own design system: ${SITE_URL}/docs/design-tokens`);
+}
+
+/**
+ * `init`: components.json, the `@/*` alias and package.json "main", then the theme (flags, or questions in a
+ * terminal). `theme: false` for the quiet init `add` runs on a project without components.json.
+ */
+async function cmdInit(cwd, flags, dir, { theme = true } = {}) {
   if (dir) {
     // Already inside an Expo app: `init <dir>` still means "create a new one there".
+    themeOptions(flags); // a bad --brand fails before create-expo-app runs
     const target = createExpoApp(cwd, dir, flags);
     if (!target) return;
-    cmdInit(target, flags);
+    await cmdInit(target, flags);
     log('');
     log(`Next: cd ${dir} && npx expo start — then scan the QR with Expo Go.`);
     return;
@@ -907,9 +1230,17 @@ function cmdInit(cwd, flags, dir) {
   const projectRoot = findProjectRoot(cwd);
   if (!projectRoot) fail(`Not inside an Expo project (expo dependency not found). Start a new app with: ${RUN} init my-app`);
 
+  // Checked before anything is written: these values end up in a .tsx file.
+  const themeGiven = THEME_FLAGS.some((k) => flags[k] !== undefined);
+  let picked = themeOptions(flags);
+
   const configPath = path.join(projectRoot, 'components.json');
   if (fs.existsSync(configPath)) {
-    warn('components.json already exists.');
+    if (!theme || !themeGiven) {
+      warn(`components.json already exists.${theme ? ` To (re)write the theme: ${RUN} init --brand "#6366f1"` : ''}`);
+      return;
+    }
+    writeTheme(projectRoot, loadConfig(projectRoot), picked, flags);
     return;
   }
 
@@ -923,10 +1254,15 @@ function cmdInit(cwd, flags, dir) {
   // Plan the tsconfig edit first: a broken tsconfig must not leave a half-initialised project.
   const tsPlan = planTsconfigAlias(projectRoot, aliasTarget);
 
+  if (theme && !themeGiven && !flags.yes && !flags.dryRun && process.stdin.isTTY && process.stdout.isTTY) {
+    picked = await askTheme();
+  }
+
   if (flags.dryRun) {
     log(`Would create components.json (${layout} layout)`);
     if (tsPlan?.changed) log(`Would add @/* → ${aliasTarget[0]} in tsconfig.json`);
     ensureExpoRouterMain(projectRoot, true);
+    if (theme) writeTheme(projectRoot, loadConfig(projectRoot), picked, flags);
     return;
   }
 
@@ -940,6 +1276,7 @@ function cmdInit(cwd, flags, dir) {
   log(`Created components.json (${layout} layout)`);
 
   ensureExpoRouterMain(projectRoot, false);
+  if (theme) writeTheme(projectRoot, loadConfig(projectRoot), picked, flags);
   log(`Done. Add items with: ${RUN} add <name>`);
 }
 
@@ -947,209 +1284,311 @@ function cmdInit(cwd, flags, dir) {
  * After a successful add: tells the site which item was installed — just its name, no token or project
  * data (README "Privacy"). Off with DO_NOT_TRACK=1 / EXPO_KIT_TELEMETRY=0 and in CI. Never fails the add.
  */
-async function reportInstalled(name) {
-  if (!telemetryEnabled(process.env)) return;
+async function reportInstalled(names) {
+  if (!telemetryEnabled(process.env) || !names.length) return;
   try {
     parseSiteUrl(SITE_URL);
-    const res = await fetch(`${SITE_URL}/api/cli/installed`, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ items: [name] }),
-      signal: AbortSignal.timeout(1500),
-    });
-    await res.arrayBuffer();
+    // The site takes small bodies (2 KB): a long batch goes in a few posts.
+    for (let i = 0; i < names.length; i += 20) {
+      const res = await fetch(`${SITE_URL}/api/cli/installed`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ items: names.slice(i, i + 20) }),
+        signal: AbortSignal.timeout(1500),
+      });
+      await res.arrayBuffer();
+    }
   } catch {
-    // offline, slow or blocked: the count just misses this one
+    // offline, slow or blocked: the count just misses these
   }
 }
 
-/** `report: false` for re-adds that aren't new installs (`update --force`). */
-async function cmdAdd(args, cwd, { report = true } = {}) {
-  const { flags, positional } = parseFlags(args);
-  // `add a b c` → add each in turn with the same flags.
-  if (positional.length > 1 && !positional.includes('--list')) {
-    const flagArgs = args.filter((a) => a.startsWith('--'));
-    for (const item of positional) await cmdAdd([item, ...flagArgs], cwd, { report });
-    return;
+/**
+ * `add --dir <folder>`: this run's config with the registry's components/ going to <folder>, and their
+ * `@/components/…` imports pointing there. The folder must be reachable through the project's `@/*` alias.
+ */
+function withComponentsDir(projectRoot, config, dir) {
+  let aliasRoot = null;
+  try {
+    aliasRoot = aliasRootFromTsconfig(parseJsonc(fs.readFileSync(path.join(projectRoot, 'tsconfig.json'), 'utf8')));
+  } catch {
+    // no / unreadable tsconfig: fall back to the layout init would set up
   }
-  const name = positional[0];
-
-  if (!name || name === '--list') {
-    listRegistry();
-    return;
+  if (aliasRoot === null) aliasRoot = detectProjectLayout(projectRoot).layout === 'src' ? 'src' : '';
+  const alias = aliasTargetForDir(dir, aliasRoot);
+  const example = `${aliasRoot ? `${aliasRoot}/` : ''}components/kit`;
+  if (!alias || !isInsideDir(projectRoot, dir)) {
+    fail(`--dir ${dir}: use a folder inside ${aliasRoot ? `${aliasRoot}/` : 'the project'} so "@/…" imports reach it, e.g. --dir ${example}`);
   }
+  const folder = dir.replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '');
+  return { ...config, paths: { ...config.paths, components: folder }, aliases: { ...config.aliases, components: alias } };
+}
 
-  const projectRoot = findProjectRoot(cwd);
-  if (!projectRoot) fail('Not inside an Expo project. Run from your app root.');
+/** `import { X } from "…"` for an item's main component, or null when it has none (templates, lib-only items). */
+function importLine(item, config) {
+  const { filesRoot, resolved, meta } = item;
+  const folder = ['ui', 'blocks', 'charts'].find((f) => fs.existsSync(path.join(filesRoot, 'src', 'components', f, `${resolved}.tsx`)));
+  if (!folder) return null;
+  const exported = pickMainExport(fs.readFileSync(path.join(filesRoot, 'src', 'components', folder, `${resolved}.tsx`), 'utf8'), [
+    meta.title,
+    resolved,
+  ]);
+  return exported ? `import { ${exported} } from "${(config.aliases.components ?? '@/components').replace(/\/+$/, '')}/${folder}/${resolved}";` : null;
+}
 
-  const configPath = path.join(projectRoot, 'components.json');
-  if (!fs.existsSync(configPath)) {
-    warn('No components.json — running init first.');
-    cmdInit(cwd, flags);
-  }
+/**
+ * The config an item is written with: `--dir` (this run), else the folder it was installed into (components.json,
+ * untrusted, so it goes through the same checks as --dir), else components.json's paths.
+ */
+function targetFor(projectRoot, config, name, flags) {
+  const dir = flags.dir ?? (flags.update ? config.installed[name]?.dir : undefined);
+  if (!dir) return { target: config, dir: null };
+  const target = withComponentsDir(projectRoot, config, dir);
+  return { target, dir: target.paths.components };
+}
 
-  const config = loadConfig(projectRoot);
-  const { meta, filesRoot, resolved } = await loadRegistryItem(name);
+/** Items components.json says were added (plus a liquidglass-tab set up before it kept records). */
+function installedNames(projectRoot, config) {
+  return [...new Set([...Object.keys(config.installed), ...detectInstalledTemplates(projectRoot, config)])];
+}
 
-  const shared = new Set(
-    (meta.sharedFiles ?? []).map((rel) => registryPathToProjectPath(rel, config, projectRoot))
-  );
-  const planned = planRegistryFiles(filesRoot, projectRoot, config);
-  const srcOf = (file) => {
-    const rel = (meta.sharedFiles ?? []).find((r) => registryPathToProjectPath(r, config, projectRoot) === file);
-    return rel ? path.join(filesRoot, 'src', rel) : null;
-  };
-  const conflicts = planned.filter((file) => {
-    if (!fs.existsSync(file) || shared.has(file)) return false;
-    return !identicalToRegistry(file, filesRoot, projectRoot, config) && !srcOf(file);
-  });
+/**
+ * Whether `name` is in this project: recorded in components.json, or (for projects from before the records) a
+ * bundled item whose own files are there. Pro items need the record, so nothing is downloaded to find out.
+ */
+function isInstalled(projectRoot, config, name) {
+  if (installedNames(projectRoot, config).includes(name)) return true;
+  const meta = isValidItemName(name) ? readMeta(name) : null;
+  const root = meta && bundledFilesRoot(meta);
+  if (!root) return false;
+  const shared = new Set(meta.sharedFiles ?? []);
+  return registryFiles(root, projectRoot, config).some((f) => !shared.has(f.registryRel) && fs.existsSync(f.dest));
+}
 
-  // A kept (edited) shared kit.tsx older than this item needs would crash at runtime (missing kit API).
-  const outdated = [...shared].flatMap((file) => {
-    const src = srcOf(file);
-    if (!src || !fs.existsSync(file)) return [];
-    const need = kitVersion(fs.readFileSync(src, 'utf8'));
-    const have = kitVersion(fs.readFileSync(file, 'utf8'));
-    return need !== null && have !== null && have < need ? [{ file, have, need }] : [];
-  });
-  if (outdated.length && !flags.force) {
-    console.log('');
-    fail(
-      `${meta.title} needs a newer kit than your edited copy:\n` +
-        outdated.map((o) => `  • ${path.relative(projectRoot, o.file)} (kit v${o.have}, needs v${o.need})`).join('\n') +
-        `\nRe-run with --force to replace it (your edits to it are lost — back it up first), or merge the new version by hand.`
-    );
-  }
+/**
+ * `add a b c` / `update a b c`: every item is planned and written on its own (one that can't be added doesn't stop
+ * the rest), then one `npx expo install` for the packages the items need and package.json doesn't list yet, then
+ * the install records and a summary. Exits 1 when any item wasn't written. `flags.update`: only installed items,
+ * and files you changed stop the item with their diff (unless --force).
+ */
+async function runBatch(names, projectRoot, config, flags, { report }) {
+  const results = [];
+  const written = [];
 
-  if (flags.dryRun) {
-    log(`Dry run — ${meta.title} (${resolved})\n`);
-    for (const file of planned) {
-      const rel = path.relative(projectRoot, file);
-      const exists = fs.existsSync(file);
-      const same = exists && identicalToRegistry(file, filesRoot, projectRoot, config);
-      const isShared = (meta.sharedFiles ?? []).some((r) => registryPathToProjectPath(r, config, projectRoot) === file);
-      log(
-        same
-          ? `  unchanged ${rel}`
-          : `  would write ${rel}${exists ? (isShared ? ' (shared — kept unless --force)' : ' (overwrite with --force)') : ''}`
-      );
+  for (const name of names) {
+    console.log('');
+    let item;
+    let plan;
+    let dir;
+    try {
+      if (flags.update && !isInstalled(projectRoot, config, resolveRegistryName(name))) {
+        fail(`${resolveRegistryName(name)} isn't installed here. Add it: ${RUN} add ${resolveRegistryName(name)}`);
+      }
+      item = await loadRegistryItem(name);
+      const where = targetFor(projectRoot, config, item.resolved, flags);
+      dir = where.dir;
+      item.target = where.target;
+      plan = planItem(item, projectRoot, item.target, flags);
+    } catch (e) {
+      if (!(e instanceof CliError)) throw e;
+      results.push({ name: item?.resolved ?? name, ok: false, lines: [e.message] });
+      continue;
     }
-    if (conflicts.length && !flags.force) {
-      console.log('');
-      fail(
-        `Would overwrite ${conflicts.length} file(s). Re-run with --force:\n` +
-          conflicts.map((f) => `  • ${path.relative(projectRoot, f)}`).join('\n')
-      );
+    const { meta, resolved } = item;
+    const verb = flags.update ? 'Updating' : 'Adding';
+    log(`${flags.dryRun ? 'Dry run — ' : `${verb} `}${meta.title} (${resolved})…`);
+    if (flags.dryRun) printPlan(plan);
+    if (plan.problems.length) {
+      results.push({ name: resolved, ok: false, lines: plan.problems });
+      continue;
     }
+    if (!flags.dryRun) written.push(...applyPlan(plan));
+    if (flags.update && !flags.dryRun && plan.files.every((f) => f.action === 'same' || f.action === 'keep')) log('  already up to date');
     if (resolved === 'liquidglass-tab') {
-      syncTabRoutes(projectRoot, config, flags);
-      ensureExpoRouterMain(projectRoot, true);
+      syncTabRoutes(projectRoot, item.target, flags);
+      ensureExpoRouterMain(projectRoot, flags.dryRun);
     }
-    runExpoInstall(projectRoot, meta.dependencies ?? [], true);
-    if (resolved !== 'liquidglass-tab') printRunHint(meta.dependencies);
-    return;
+    results.push({ name: resolved, ok: true, item, plan, dir, importLine: importLine(item, item.target) });
   }
 
-  const copyOptions = { dryRun: false, force: flags.force, shared };
-
-  if (conflicts.length && !flags.force) {
-    console.log('');
-    fail(
-      `Would overwrite ${conflicts.length} file(s). Re-run with --force:\n` +
-        conflicts.map((f) => `  • ${path.relative(projectRoot, f)}`).join('\n')
-    );
-  }
+  const added = results.filter((r) => r.ok);
+  const failed = results.filter((r) => !r.ok);
+  const pkg = readJsonFile(path.join(projectRoot, 'package.json'), 'package.json');
+  const deps = mergeDependencies(...added.map((r) => r.item.meta.dependencies ?? []));
+  const missing = missingPackages(deps, pkg);
+  const present = deps.filter((d) => !missing.includes(d));
 
-  log(`Adding ${meta.title} (${resolved})…\n`);
-  mapRegistryToProject(filesRoot, projectRoot, config, copyOptions);
+  console.log('');
+  formatWritten(projectRoot, pkg, written, flags);
+  runExpoInstall(projectRoot, missing, flags.dryRun);
+  if (present.length && !flags.update) log(`${flags.dryRun ? '  ' : ''}already in package.json: ${present.join(', ')}`);
 
-  if (resolved === 'liquidglass-tab') {
-    syncTabRoutes(projectRoot, config, copyOptions);
-    ensureExpoRouterMain(projectRoot, false);
+  if (!flags.dryRun && added.length) {
+    // Hashes are taken after Prettier, from the files as they are now. A one-off --dir is recorded per item,
+    // never as the components.json default.
+    for (const r of added) recordInstall(config, r.name, r.plan, r.dir);
+    saveConfig(projectRoot, config);
+    if (report) await reportInstalled(added.map((r) => r.name));
   }
 
-  const depsOk = runExpoInstall(projectRoot, meta.dependencies ?? [], false);
-
-  if (depsOk) markTemplateInstalled(projectRoot, config, resolved);
-  if (report) await reportInstalled(resolved);
-
   console.log('');
-  if (resolved === 'liquidglass-tab') {
-    log('Next steps:');
-    console.log('  • Edit src/lib/tabs.ts — labels, icon presets, colors, screen text');
-    console.log(`  • Run: ${RUN} doctor`);
-    console.log('  • Build a dev client: npx expo run:ios (iOS 26 shows real Liquid Glass,');
-    console.log('    iOS 18 and older, Android and web get the glass fallback bar)');
-    console.log('  • After package updates: npx @expokit/cli@latest update');
-  } else {
-    const folder = ['ui', 'blocks', 'charts'].find((f) =>
-      fs.existsSync(path.join(filesRoot, 'src', 'components', f, `${resolved}.tsx`))
-    );
-    const main = folder ? path.join(filesRoot, 'src', 'components', folder, `${resolved}.tsx`) : null;
-    const exported = main ? pickMainExport(fs.readFileSync(main, 'utf8'), [meta.title, resolved]) : null;
-    if (exported) log(`Import: import { ${exported} } from "@/components/${folder}/${resolved}";`);
-    printRunHint(meta.dependencies);
+  for (const r of results) {
+    if (r.ok) {
+      log(`✓ ${r.name}${r.importLine && !flags.update ? `   ${r.importLine}` : ''}`);
+    } else {
+      log(`✗ ${r.name} — ${r.lines[0]}`);
+      for (const line of r.lines.slice(1)) console.log(`    ${line}`);
+    }
+  }
+  if (added.length && !flags.update) {
+    console.log('');
+    if (added.some((r) => r.name === 'liquidglass-tab')) {
+      log('Next steps for liquidglass-tab:');
+      console.log('  • Edit src/lib/tabs.ts — labels, icon presets, colors, screen text');
+      console.log(`  • Run: ${RUN} doctor`);
+      console.log('  • Build a dev client: npx expo run:ios (iOS 26 shows real Liquid Glass,');
+      console.log('    iOS 18 and older, Android and web get the glass fallback bar)');
+      console.log('  • After package updates: npx @expokit/cli@latest update');
+    }
+    if (added.some((r) => r.name !== 'liquidglass-tab')) printRunHint(deps);
+  }
+  if (written.length && flags.update) {
+    console.log('');
+    if (added.some((r) => r.name === 'liquidglass-tab') && !flags.force) log('Your tabs.ts and tab screens were kept — only framework files refresh.');
+    log('Reload Metro (or rebuild the native app) to see the changes.');
+  }
+  if (failed.length) {
+    const verb = flags.update ? 'updated' : 'added';
+    fail(`${failed.length} of ${results.length} item(s) not ${verb} (${failed.map((r) => r.name).join(', ')}).${added.length ? ' The others were.' : ''}`);
   }
 }
 
-async function cmdUpdate(args, cwd) {
-  const { flags, positional } = parseFlags(args);
-  const name = positional[0];
-
+/** Project root + components.json for a command that needs both. */
+function openProject(cwd, { needConfig }) {
   const projectRoot = findProjectRoot(cwd);
   if (!projectRoot) fail('Not inside an Expo project. Run from your app root.');
+  if (needConfig && !fs.existsSync(path.join(projectRoot, 'components.json'))) fail(`No components.json — run: ${RUN} init`);
+  return { projectRoot, config: loadConfig(projectRoot) };
+}
 
-  const configPath = path.join(projectRoot, 'components.json');
-  if (!fs.existsSync(configPath)) {
-    fail('No components.json — run: npx @expokit/cli@latest init');
-  }
-
-  const config = loadConfig(projectRoot);
-  const pkgVersion = getPackageVersion();
-  const targets = name ? [resolveRegistryName(name)] : detectInstalledTemplates(projectRoot, config);
+async function cmdAdd(args, cwd) {
+  const { flags, positional } = parseFlags(args);
+  const names = [...new Set(positional.filter((p) => p !== '--list'))];
 
-  if (!targets.length) {
-    fail('No templates found. Run: npx @expokit/cli@latest add liquidglass-tab');
+  if (!names.length) {
+    listRegistry();
+    return;
   }
 
-  if (flags.force) {
-    for (const resolved of targets) {
-      log(`Full overwrite ${resolved} (--force${flags.dryRun ? ', dry run' : ''})…\n`);
-      await cmdAdd([resolved, '--force', ...(flags.dryRun ? ['--dry-run'] : [])], cwd, { report: false });
-    }
-    return;
+  const projectRoot = findProjectRoot(cwd);
+  if (!projectRoot) fail('Not inside an Expo project. Run from your app root.');
+
+  if (!fs.existsSync(path.join(projectRoot, 'components.json'))) {
+    warn('No components.json — running init first.');
+    await cmdInit(cwd, flags, undefined, { theme: false });
   }
 
-  log(`Updating template files (expo-kit@${pkgVersion})…`);
-  log('Your src/lib/tabs.ts is kept — only framework files refresh.\n');
+  await runBatch(names, projectRoot, loadConfig(projectRoot), flags, { report: true });
+}
 
-  for (const resolved of targets) {
-    if (resolved !== 'liquidglass-tab') {
-      warn(
-        `Smart update only supports liquidglass-tab today. For "${resolved}" run: npx @expokit/cli@latest add ${resolved} --force`
-      );
-      continue;
-    }
-    const { meta, filesRoot } = await loadRegistryItem(resolved);
+/**
+ * `update [names]`: every installed item (or the named ones) brought to this CLI's version. Files the CLI wrote and
+ * nobody touched refresh; a file you changed stops its item and shows the diff, unless --force takes upstream.
+ */
+async function cmdUpdate(args, cwd) {
+  const { flags, positional } = parseFlags(args);
+  const { projectRoot, config } = openProject(cwd, { needConfig: true });
+  const names = positional.length ? [...new Set(positional.map(resolveRegistryName))] : installedNames(projectRoot, config);
+  if (!names.length) fail(`Nothing to update: components.json lists no installed items. Add one: ${RUN} add <name>`);
+  log(`Updating ${names.join(', ')} to expo-kit@${getPackageVersion()}${flags.force ? ' (--force: your changes are replaced)' : ''}…`);
+  await runBatch(names, projectRoot, config, { ...flags, update: true }, { report: false });
+}
 
-    if (flags.dryRun) {
-      log(`Dry run — ${meta.title} (${resolved})\n`);
-    } else {
-      log(`${meta.title} (${resolved})`);
-    }
+/** Files bigger than this aren't diffed (a component is a few dozen KB). */
+const MAX_DIFF_BYTES = 2 * 1024 * 1024;
 
-    copyRegistryFiles(filesRoot, projectRoot, config, LIQUIDGLASS_FRAMEWORK_PATHS, flags);
-    syncTabRoutes(projectRoot, config, flags);
-    ensureExpoRouterMain(projectRoot, flags.dryRun);
+/**
+ * `diff [names]`: each file of an installed item against what was installed and what this CLI ships. With only a
+ * hash on record, "as installed" can be shown when upstream hasn't moved since; otherwise yours vs upstream.
+ */
+async function cmdDiff(args, cwd) {
+  const { flags, positional } = parseFlags(args);
+  const { projectRoot, config } = openProject(cwd, { needConfig: true });
+  const names = positional.length ? [...new Set(positional.map(resolveRegistryName))] : installedNames(projectRoot, config);
+  if (!names.length) fail(`Nothing to compare: components.json lists no installed items. Add one: ${RUN} add <name>`);
+  const counts = { current: 0, pristine: 0, modified: 0, both: 0, untracked: 0, other: 0 };
+  const show = (diff) => {
+    for (const line of diffLines(diff)) console.log(`      ${line}`);
+  };
 
-    if (!flags.dryRun) {
-      markTemplateInstalled(projectRoot, config, resolved);
+  for (const name of names) {
+    const item = await loadRegistryItem(name);
+    const { target } = targetFor(projectRoot, config, item.resolved, { ...flags, update: true });
+    const entry = config.installed[item.resolved];
+    console.log('');
+    log(
+      `${item.meta.title} (${item.resolved}) — ${entry?.version ? `installed with expo-kit ${entry.version}` : 'no install record'}` +
+        `${entry?.kitVersion ? `, kit v${entry.kitVersion}` : ''}; this CLI is ${getPackageVersion()}`
+    );
+    for (const { src, dest, registryRel } of registryFiles(item.filesRoot, projectRoot, target)) {
+      const rel = posixRel(projectRoot, dest);
+      const say = (what) => console.log(`  ${rel.padEnd(42)} ${what}`);
+      const upstream = registryText(src, target);
+      let stat = null;
+      try {
+        stat = fs.lstatSync(dest);
+      } catch {
+        // not there
+      }
+      if (!stat) {
+        counts.other += 1;
+        say('not in your project (update adds it)');
+        continue;
+      }
+      if (!stat.isFile()) {
+        counts.other += 1;
+        say(`skipped — it's a ${stat.isSymbolicLink() ? 'symlink' : 'folder'}, not read`);
+        continue;
+      }
+      if (stat.size > MAX_DIFF_BYTES) {
+        counts.other += 1;
+        say('skipped — larger than 2 MB');
+        continue;
+      }
+      if (item.resolved === 'liquidglass-tab' && !LIQUIDGLASS_FRAMEWORK_PATHS.includes(registryRel)) {
+        counts.other += 1;
+        say('starter file — yours to edit; update keeps it');
+        continue;
+      }
+      const have = fs.readFileSync(dest, 'utf8');
+      const recorded = recordedHash(config.files, rel);
+      const status = fileStatus(recorded, have, upstream);
+      const both = status === 'modified' && recorded !== contentHash(upstream);
+      counts[both ? 'both' : status] += 1;
+      if (status === 'current') {
+        say('up to date');
+      } else if (status === 'pristine') {
+        say('changed upstream — yours is untouched; update refreshes it');
+        show(unifiedDiff(have, upstream, { from: `${rel} (yours, as installed)`, to: `${rel} (upstream)` }));
+      } else if (status === 'modified' && !both) {
+        say('changed by you');
+        show(unifiedDiff(upstream, have, { from: `${rel} (as installed)`, to: `${rel} (yours)` }));
+      } else if (status === 'modified') {
+        say(`changed by you and upstream — update stops here (--force takes upstream)`);
+        show(unifiedDiff(have, upstream, { from: `${rel} (yours)`, to: `${rel} (upstream)` }));
+      } else {
+        say('differs from upstream (no install record)');
+        show(unifiedDiff(have, upstream, { from: `${rel} (yours)`, to: `${rel} (upstream)` }));
+      }
     }
   }
-
   console.log('');
-  log('Update complete. Reload Metro or rebuild the native app to see changes.');
-  log('To overwrite tabs.ts too: npx @expokit/cli@latest update --force');
+  log(
+    `${counts.current} up to date · ${counts.pristine} changed upstream · ${counts.modified} changed by you` +
+      `${counts.both ? ` · ${counts.both} changed by you and upstream` : ''}` +
+      `${counts.untracked ? ` · ${counts.untracked} without a record` : ''}${counts.other ? ` · ${counts.other} other` : ''}`
+  );
+  if (counts.pristine || counts.both || counts.untracked) console.log(`  Bring in upstream: ${RUN} update ${positional.length ? names.join(' ') : ''}`.trimEnd());
 }
 
 function cmdDoctor(cwd) {
@@ -1178,14 +1617,14 @@ function cmdDoctor(cwd) {
   }
 
   const tabsPath = path.join(projectRoot, config.paths.lib ?? 'src/lib', 'tabs.ts');
-  const usesLiquidGlass = fs.existsSync(tabsPath) || config.installed?.['liquidglass-tab'];
+  const usesLiquidGlass = fs.existsSync(tabsPath) || Object.hasOwn(config.installed, 'liquidglass-tab');
   if (usesLiquidGlass) {
     if (!fs.existsSync(tabsPath)) {
       warn(`No src/lib/tabs.ts — run: ${RUN} add liquidglass-tab`);
       issues += 1;
     } else {
       log('  ✓ src/lib/tabs.ts');
-      const installedVersion = config.installed?.['liquidglass-tab'];
+      const installedVersion = config.installed['liquidglass-tab']?.version;
       const pkgVersion = getPackageVersion();
       if (installedVersion && installedVersion !== pkgVersion) {
         warn(
@@ -1307,9 +1746,10 @@ function printHelp() {
 expo-kit — copy-paste Expo UI (shadcn-style)
 
 Usage:
-  npx @expokit/cli@latest init [my-app] [--dry-run]
-  npx @expokit/cli@latest add <name...> [--dry-run] [--force]
-  npx @expokit/cli@latest update [name] [--dry-run] [--force]
+  npx @expokit/cli@latest init [my-app] [--brand <hex>] [--font <name>] [--radius <pt>] [--scheme light|dark|system] [--yes] [--dry-run]
+  npx @expokit/cli@latest add <name...> [--dry-run] [--force] [--dir <folder>] [--no-format]
+  npx @expokit/cli@latest diff [name...]
+  npx @expokit/cli@latest update [name...] [--dry-run] [--force]
   npx @expokit/cli@latest doctor
   npx @expokit/cli@latest add --list
   npx @expokit/cli@latest login
@@ -1320,17 +1760,35 @@ Usage:
 
 Examples:
   npx @expokit/cli@latest init my-app        new Expo app with ExpoKit set up
+  npx @expokit/cli@latest init --brand "#0ea5e9" --radius 16 --scheme dark
   npx @expokit/cli@latest add liquidglass-tab --dry-run
   npx @expokit/cli@latest add liquidglass-tab --force
+  npx @expokit/cli@latest add toast skeleton bottom-sheet
+  npx @expokit/cli@latest add skeleton --dir src/components/kit   next to your own Skeleton.tsx
+  npx @expokit/cli@latest diff toast          your changes and upstream's, per file
   npx @expokit/cli@latest update
-  npx @expokit/cli@latest update liquidglass-tab
+  npx @expokit/cli@latest update toast --force
   npx @expokit/cli@latest doctor
 
 Note: expo-kit copies files into your app (like shadcn). npm updates do NOT
 auto-sync — run \`update\` after upgrading the package.
 
-\`update\` currently has smart refresh paths only for liquidglass-tab (framework
-files; tabs.ts kept). Other items: use \`add <name> --force\` to overwrite.
+\`add\` with several names adds each one on its own (one that can't be added doesn't stop
+the rest), runs one \`npx expo install\` for packages package.json doesn't list yet,
+and formats the new files with your Prettier when the project has it (--no-format).
+It never replaces a file of yours that differs only by case (Skeleton.tsx vs
+skeleton.tsx), not even with --force: --dir <folder> puts the components somewhere
+else (inside the folder @/ points at) and points their imports there.
+
+\`init\` asks for a brand colour, font, radius and light / dark (or takes the
+flags; --yes skips the questions), adds lib/kit.tsx and writes lib/kit-theme.tsx,
+an <AppTheme> wrapper around KitProvider for your root layout.
+
+components.json remembers a hash of every file add / update wrote. \`diff\` shows
+what you changed since and what changed upstream. \`update\` (every installed
+item, or the ones named) refreshes the files nobody touched and stops on files
+you patched, showing the diff — \`--force\` takes upstream. liquidglass-tab keeps
+your tabs.ts and screens.
 
 Pro items (marked PRO in \`add --list\`): create a token at ${SITE_URL}/account,
 run \`login\` and paste it, then \`add\` them like any other item. In scripts, pipe
@@ -1354,7 +1812,7 @@ async function main(command, rest) {
     case 'init': {
       const { flags, positional } = parseFlags(rest);
       if (positional.length > 1) fail(`init takes one folder name: ${RUN} init my-app`);
-      cmdInit(process.cwd(), flags, positional[0]);
+      await cmdInit(process.cwd(), flags, positional[0]);
       break;
     }
     case '--version':
@@ -1367,6 +1825,9 @@ async function main(command, rest) {
     case 'update':
       await cmdUpdate(rest, process.cwd());
       break;
+    case 'diff':
+      await cmdDiff(rest, process.cwd());
+      break;
     case 'login':
       await cmdLogin(rest);
       break;
@@ -1389,7 +1850,7 @@ async function main(command, rest) {
       printHelp();
       break;
     default:
-      fail(`Unknown command "${command}". Use: init | add | update | doctor | login | logout | whoami | mcp`);
+      fail(`Unknown command "${command}". Use: init | add | diff | update | doctor | login | logout | whoami | mcp`);
   }
 }
 
@@ -1397,6 +1858,6 @@ const [, , command, ...rest] = process.argv;
 try {
   await main(command, rest);
 } catch (e) {
-  if (e instanceof CliError) fail(e.message);
-  fail(`Unexpected error: ${e?.stack ?? e?.message ?? e}`);
+  if (e instanceof CliError) die(e.message);
+  die(`Unexpected error: ${e?.stack ?? e?.message ?? e}`);
 }