@expokit/cli 0.2.0 → 0.4.0

package/bin/lib.mjs

@@ -2,6 +2,8 @@
  * Pure helpers for the expo-kit CLI (no I/O, no dependencies) — kept separate so they can be unit-tested.
  */
 
+import path from 'node:path';
+
 /** Thrown for user-facing errors; the CLI entry point prints `message` and exits 1. */
 export class CliError extends Error {}
 
@@ -269,6 +271,27 @@ export function isValidItemName(name) {
   return typeof name === 'string' && /^[a-z0-9][a-z0-9-]{0,99}$/.test(name);
 }
 
+/**
+ * Tab names from the user's tabs.ts become route files in app/(tabs)/: letters, digits and route punctuation
+ * (`-_.()[]`) only, so a name can never be a path like `../../x`.
+ */
+export function isSafeTabName(name) {
+  return typeof name === 'string' && name.length <= 100 && /^[A-Za-z0-9_.()[\]-]+$/.test(name) && !/^\.+$/.test(name);
+}
+
+// ---------------------------------------------------------------------------
+// Project paths
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether `rel` (a components.json `paths` value) stays inside `root` once joined to it the way the CLI
+ * writes files: `../x` escapes, while `/src/lib` is re-rooted by path.join and stays inside.
+ */
+export function isInsideDir(root, rel) {
+  const r = path.relative(root, path.join(root, rel));
+  return r === '' || (r !== '..' && !r.startsWith(`..${path.sep}`) && !path.isAbsolute(r));
+}
+
 /**
  * npm package name, optionally with a simple version (`@1.2.3`, `@~14.0.0`, `@^2`). It reaches
  * `npx expo install` through a shell on Windows, so no `< > | =` or spaces — ranges like `>=1` are out.
@@ -288,6 +311,46 @@ export function kitVersion(text) {
   return /export function KitProvider\b/.test(text) ? 1 : null;
 }
 
+/**
+ * Packages a registry item may depend on that work in the Expo Go app (SDK 58): native modules Expo Go
+ * ships, plus pure-JS packages. Anything else needs a development build (`npx expo run:ios|android`).
+ * Keep in sync with the Expo Go module list when the SDK moves.
+ */
+export const EXPO_GO_PACKAGES = new Set([
+  '@expo/vector-icons',
+  '@shopify/react-native-skia',
+  'expo-blur',
+  'expo-charts',
+  'expo-glass-effect',
+  'expo-haptics',
+  'expo-router',
+  'expo-splash-screen',
+  'react-native-gesture-handler',
+  'react-native-reanimated',
+  'react-native-safe-area-context',
+  'react-native-screens',
+  'react-native-svg',
+  'react-native-worklets',
+]);
+
+/** Which of `deps` keep an item out of Expo Go (bare names; `pkg@1.2` is read as `pkg`). Empty: runs in Expo Go. */
+export function needsDevBuild(deps) {
+  return (deps ?? [])
+    .map((spec) => spec.replace(/^(@?[^@]+)@.*$/, '$1'))
+    .filter((name) => !EXPO_GO_PACKAGES.has(name));
+}
+
+/**
+ * The component a file is named for: the PascalCase export matching one of `names` ("Grain Gradient" or
+ * "grain-gradient" → GrainGradient), else the first PascalCase export (never a CONSTANT).
+ */
+export function pickMainExport(source, names = []) {
+  const exports = [...source.matchAll(/export (?:function|const) ([A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*)\b/g)].map((m) => m[1]);
+  const pascal = (s) => String(s ?? '').split(/[^A-Za-z0-9]+/).filter(Boolean).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+  const wanted = names.map(pascal).map((n) => n.toLowerCase());
+  return exports.find((e) => wanted.includes(e.toLowerCase())) ?? exports[0] ?? null;
+}
+
 /** Union of dependency lists, order preserved. */
 export function mergeDependencies(...lists) {
   const out = [];
@@ -301,7 +364,7 @@ export function mergeDependencies(...lists) {
 // Site URL + token guard
 // ---------------------------------------------------------------------------
 
-export const DEFAULT_SITE_URL = 'https://expokit.karandev.in';
+export const DEFAULT_SITE_URL = 'https://expokit.in';
 
 export function isLoopbackHost(hostname) {
   return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
@@ -341,3 +404,49 @@ export function canSendToken({ siteUrl, credsUrl, fromEnv = false, defaultUrl =
   if (fromEnv) return isLoopbackHost(new URL(siteUrl).hostname);
   return Boolean(credsUrl) && target === originOf(credsUrl);
 }
+
+/**
+ * `env` without EXPO_KIT_TOKEN, for child processes: `npx expo install` runs third-party install scripts,
+ * and none of them needs the Pro token. Case-insensitive, as Windows env names are.
+ */
+export function envWithoutToken(env) {
+  return Object.fromEntries(Object.entries(env).filter(([key]) => key.toUpperCase() !== 'EXPO_KIT_TOKEN'));
+}
+
+// ---------------------------------------------------------------------------
+// 429 / 503: wait once, then give up
+// ---------------------------------------------------------------------------
+
+/** The longest the CLI waits before its one retry of a 429 / 503. */
+export const RETRY_MAX_WAIT_MS = 10_000;
+
+/** A Retry-After header (delta-seconds or an HTTP date) in whole seconds from `now`; null when missing or unreadable. */
+export function parseRetryAfter(value, now = Date.now()) {
+  if (value === null || value === undefined) return null;
+  const text = String(value).trim();
+  if (/^\d+$/.test(text)) return Number(text);
+  if (!/[A-Za-z]/.test(text)) return null; // an HTTP date always names its day / month
+  const at = Date.parse(text);
+  return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - now) / 1000));
+}
+
+/**
+ * Milliseconds to wait before retrying a 429 / 503 once: what the server asked (3 s when it didn't say).
+ * null when it asked for longer than RETRY_MAX_WAIT_MS: retrying sooner than that just earns another 429 / 503.
+ */
+export function retryDelayMs(retryAfter, now = Date.now()) {
+  const secs = parseRetryAfter(retryAfter, now);
+  if (secs === null) return 3000;
+  if (secs * 1000 > RETRY_MAX_WAIT_MS) return null;
+  return secs * 1000;
+}
+
+/** "in 30 s" / "in 5 min" / "in about 2 h" for a "try again …" message; "in a minute" when the server didn't say. */
+export function retryHint(retryAfter, now = Date.now()) {
+  const secs = parseRetryAfter(retryAfter, now);
+  if (secs === null) return 'in a minute';
+  if (secs < 90) return `in ${Math.max(1, secs)} s`;
+  if (secs < 90 * 60) return `in ${Math.round(secs / 60)} min`;
+  if (secs < 48 * 3600) return `in about ${Math.round(secs / 3600)} h`;
+  return 'later';
+}

package/bin/mcp.mjs

@@ -10,6 +10,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { needsDevBuild } from './lib.mjs';
+
 /** Newest first; we answer with the client's version when we know it, else our newest. */
 export const PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
 
@@ -21,7 +23,7 @@ Items are copied into the user's app as source files by the expo-kit CLI — the
 Workflow: search_items or list_items → view_item (props, import line, examples) → get_add_command, then run that command in the app's root folder.
 The CLI creates components.json, adds the @/* tsconfig alias, copies files under src/ (or the root app layout) and installs npm deps with \`npx expo install\`.
 Import components from '@/components/...' and wrap the app in <KitProvider> from '@/lib/kit' (added with the first item).
-Pro items need an ExpoKit Pro plan: the user runs \`npx ${PACKAGE}@latest login\` once (token from https://expokit.karandev.in/account). Never ask the user to paste a token into chat.`;
+Pro items need an ExpoKit Pro plan: the user runs \`npx ${PACKAGE}@latest login\` once (token from https://expokit.in/account). Never ask the user to paste a token into chat.`;
 
 // ---------------------------------------------------------------------------
 // Registry access (bundled JSON)
@@ -179,7 +181,7 @@ function searchItems(catalog, { query }) {
 function viewItem(catalog, registryDir, { name, include_source: includeSource = false }) {
   const it = requireItem(catalog, name);
   const doc = catalog.docs.get(it.name);
-  const out = [`# ${it.title} (${it.name})`, '', it.description, ''];
+  const out = [`# ${it.title} (${it.name})`, '', ...(doc?.summary ? [doc.summary, ''] : []), it.description, ''];
   out.push(`Type: ${it.type} · Tier: ${it.tier === 'pro' ? 'PRO (needs an ExpoKit Pro plan)' : 'free'}${doc?.category ? ` · Category: ${doc.category}` : ''}`);
   if (doc?.aliases?.length) out.push(`Aliases: ${doc.aliases.join(', ')}`);
   out.push('', `Add: \`${addCommand([it.name])}\``);
@@ -187,6 +189,8 @@ function viewItem(catalog, registryDir, { name, include_source: includeSource =
   if (imp) out.push(`Import: \`${imp}\``);
   if (doc?.files?.length) out.push(`Files it adds: ${doc.files.join(', ')}`);
   if (it.dependencies.length) out.push(`npm deps (installed by the CLI): ${it.dependencies.join(', ')}`);
+  const native = needsDevBuild(it.dependencies);
+  out.push(native.length ? `Runs in Expo Go: no, needs a development build (${native.join(', ')})` : 'Runs in Expo Go: yes');
   if (it.registryDependencies.length) out.push(`Also adds: ${it.registryDependencies.join(', ')}`);
 
   if (doc?.props?.length) {
@@ -195,11 +199,18 @@ function viewItem(catalog, registryDir, { name, include_source: includeSource =
     for (const [prop, type, def, desc] of doc.props) out.push(`| ${cell(prop)} | ${cell(type)} | ${cell(def)} | ${cell(desc)} |`);
   }
 
+  if (doc?.behavior?.length) {
+    out.push('', '## Behaviour & accessibility', '');
+    for (const [label, text] of doc.behavior) out.push(`- **${label}:** ${text}`);
+  }
+
+  if (doc?.usage) out.push('', '## Usage', '', '```tsx', doc.usage.trimEnd(), '```');
+
   if (doc?.examples?.length) {
     out.push('', '## Examples');
     for (const ex of doc.examples) out.push('', `### ${ex.title}`, '', '```tsx', ex.code.trimEnd(), '```');
   } else if (it.tier === 'pro') {
-    out.push('', 'Usage examples and source for Pro items are on https://expokit.karandev.in after signing in, and in the files the add command copies.');
+    out.push('', 'Usage examples and source for Pro items are on https://expokit.in after signing in, and in the files the add command copies.');
   }
 
   if (includeSource) {
@@ -233,7 +244,7 @@ function getAddCommand(catalog, { names }) {
   ];
   if (pro.length)
     lines.push(
-      `- PRO: ${pro.join(', ')} ${pro.length === 1 ? 'needs' : 'need'} an ExpoKit Pro plan. If the command reports "not logged in", ask the user to run \`npx ${PACKAGE}@latest login\` themselves (token from https://expokit.karandev.in/account). Never ask for the token in chat.`
+      `- PRO: ${pro.join(', ')} ${pro.length === 1 ? 'needs' : 'need'} an ExpoKit Pro plan. If the command reports "not logged in", ask the user to run \`npx ${PACKAGE}@latest login\` themselves (token from https://expokit.in/account). Never ask for the token in chat.`
     );
   return lines.join('\n');
 }
@@ -258,15 +269,19 @@ export function callTool(catalog, registryDir, name, args = {}) {
 // ---------------------------------------------------------------------------
 
 const rpcError = (id, code, message) => ({ jsonrpc: '2.0', id, error: { code, message } });
+const isObject = (v) => Boolean(v) && typeof v === 'object' && !Array.isArray(v);
 
 /** One incoming JSON-RPC message → the response object, or null for notifications. */
 export function handleMessage(msg, ctx) {
-  if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
-    return msg && 'id' in msg ? rpcError(msg.id ?? null, -32600, 'Invalid request') : null;
+  if (!isObject(msg) || msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+    // A stray `5`, "abc" or nested array has no id to answer; an object with one gets an error back.
+    return isObject(msg) && 'id' in msg ? rpcError(msg.id ?? null, -32600, 'Invalid request') : null;
   }
   const isRequest = 'id' in msg && msg.id !== null;
   if (!isRequest) return null; // notifications/initialized, notifications/cancelled, …
-  const { id, method, params = {} } = msg;
+  const { id, method } = msg;
+  // `params: null` skips a destructuring default, and params.name would then throw.
+  const params = isObject(msg.params) ? msg.params : {};
   const ok = (result) => ({ jsonrpc: '2.0', id, result });
 
   switch (method) {
@@ -306,6 +321,30 @@ export function handleMessage(msg, ctx) {
   }
 }
 
+/**
+ * One stdin line → what to write back: a reply, an array of replies for a batch, or null. Never throws —
+ * it runs inside the stdin listener, where one bad line would otherwise kill the server for the session.
+ */
+export function handleLine(line, ctx) {
+  let msg;
+  try {
+    msg = JSON.parse(line);
+  } catch {
+    return rpcError(null, -32700, 'Parse error');
+  }
+  const reply = (m) => {
+    try {
+      return handleMessage(m, ctx);
+    } catch {
+      return isObject(m) && 'id' in m && m.id !== null ? rpcError(m.id, -32603, 'Internal error') : null;
+    }
+  };
+  if (!Array.isArray(msg)) return reply(msg);
+  // Batches came and went in 2025-03-26; answer them anyway.
+  const replies = msg.map(reply).filter(Boolean);
+  return replies.length ? replies : null;
+}
+
 /** Serves MCP on stdin/stdout until stdin closes. */
 export function startMcpServer({ registryDir, version, aliases }) {
   const ctx = { registryDir, version, catalog: loadCatalog(registryDir, aliases) };
@@ -319,18 +358,8 @@ export function startMcpServer({ registryDir, version, aliases }) {
       const line = buffer.slice(0, nl).trim();
       buffer = buffer.slice(nl + 1);
       if (!line) continue;
-      let msg;
-      try {
-        msg = JSON.parse(line);
-      } catch {
-        send(rpcError(null, -32700, 'Parse error'));
-        continue;
-      }
-      // Batches came and went in 2025-03-26; answer them anyway.
-      const replies = (Array.isArray(msg) ? msg : [msg]).map((m) => handleMessage(m, ctx)).filter(Boolean);
-      if (Array.isArray(msg)) {
-        if (replies.length) send(replies);
-      } else if (replies[0]) send(replies[0]);
+      const reply = handleLine(line, ctx);
+      if (reply) send(reply);
     }
   });
   process.stdin.on('end', () => process.exit(0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expokit/cli",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "shadcn-style CLI for Expo — add native UI blocks and components to your app",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,8 @@
     "bin",
     "registry",
     "schema",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "keywords": [
     "expo",
@@ -26,7 +27,7 @@
   "engines": {
     "node": ">=18"
   },
-  "homepage": "https://expokit.karandev.in",
+  "homepage": "https://expokit.in",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Anshkaran7/expokit.git",
@@ -35,7 +36,11 @@
   "bugs": {
     "url": "https://github.com/Anshkaran7/expokit/issues"
   },
-  "author": "anshkaran7",
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Anshkaran7"
+  },
+  "author": "Karan (anshkaran7) <work@karandev.in>",
   "publishConfig": {
     "access": "public"
   },

package/registry/_docs/accordion.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/accordion.tsx"
   ],
+  "summary": "Sections spring open to their measured height while the chevron turns.",
   "props": [
     [
       "type",
@@ -74,6 +75,21 @@
       "Style for the Accordion's root view (the card in the bordered variant); AccordionItem takes its own."
     ]
   ],
+  "behavior": [
+    [
+      "Touch",
+      "Tap a header to open or close its section. In single mode, opening one closes the other; disabled items don't respond."
+    ],
+    [
+      "Motion",
+      "Content height springs to its measured size, so any content animates smoothly. The chevron turns 180° on the native driver."
+    ],
+    [
+      "Screen readers",
+      "Each header is a button with expanded and disabled state. Content of closed sections is hidden from assistive tech."
+    ]
+  ],
+  "usage": "import { Accordion, AccordionItem } from '@/components/ui/accordion';\n\n<Accordion defaultValue={['shipping']}>\n  <AccordionItem value=\"shipping\" title=\"How long does shipping take?\">\n    Orders leave our warehouse within 24 hours.\n  </AccordionItem>\n  <AccordionItem value=\"returns\" title=\"Can I return an item?\">\n    You have 30 days to send anything back for a full refund.\n  </AccordionItem>\n</Accordion>",
   "examples": [
     {
       "name": "Default",

package/registry/_docs/action-sheet.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/action-sheet.tsx"
   ],
+  "summary": "An iOS-style action sheet that follows your finger and flings away to dismiss.",
   "props": [
     [
       "open / defaultOpen",
@@ -80,6 +81,33 @@
       "Sheet container style."
     ]
   ],
+  "behavior": [
+    [
+      "Touch",
+      "Drag anywhere on the sheet. Pull past a third of its height or flick down to dismiss; pulling up rubber-bands."
+    ],
+    [
+      "Motion",
+      "Springs up over a fading scrim. The exit is quicker than the entry and keeps a fling's momentum."
+    ],
+    [
+      "Reduced motion",
+      "The sheet fades in and out in place instead of sliding up from the bottom."
+    ],
+    [
+      "Haptics",
+      "A light impact when it opens and a selection tick when you pick an action. Turn off with haptics={false}."
+    ],
+    [
+      "Screen readers",
+      "The sheet is a modal view, the title is a header and each row is a button with its label and disabled state."
+    ],
+    [
+      "Keyboard",
+      "Escape closes it on web; the Android back button closes it too."
+    ]
+  ],
+  "usage": "import { useState } from 'react';\nimport { ActionSheet } from '@/components/ui/action-sheet';\n\nconst [open, setOpen] = useState(false);\n<ActionSheet\n  open={open}\n  onOpenChange={setOpen}\n  title=\"Profile photo\"\n  actions={[{ label: 'Take photo' }, { label: 'Remove photo', destructive: true }]}\n/>",
   "examples": [
     {
       "name": "Photo",

package/registry/_docs/alert.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/alert.tsx"
   ],
+  "summary": "An inline banner whose icon draws itself inside a halo, with an optional draining timer.",
   "props": [
     [
       "variant",
@@ -92,6 +93,33 @@
       "Style for the outer animated wrapper (its height collapses on dismiss)."
     ]
   ],
+  "behavior": [
+    [
+      "Motion",
+      "On appear the icon outline draws, the glyph springs in and the halo ripples once. Dismissing collapses the height so content below glides up."
+    ],
+    [
+      "Touch",
+      "With duration set, a hairline drains along the bottom to show the time left. Pressing the alert pauses it."
+    ],
+    [
+      "Reduced motion",
+      "The icon draw, glyph pop and halo ripple jump straight to their finished state."
+    ],
+    [
+      "Haptics",
+      "Success, warning and danger alerts play the matching notification haptic when they appear; info stays silent."
+    ],
+    [
+      "Screen readers",
+      "The card has the alert role in a polite live region. The close button is labelled Dismiss and actions are buttons named by their label."
+    ],
+    [
+      "Web",
+      "Hovering also pauses the auto-dismiss timer."
+    ]
+  ],
+  "usage": "import { Alert } from '@/components/ui/alert';\n\n<Alert\n  variant=\"warning\"\n  title=\"Storage almost full\"\n  description=\"You've used 9.4 GB of your 10 GB plan.\"\n  dismissible\n/>",
   "examples": [
     {
       "name": "Soft",

package/registry/_docs/assistant-app.json

@@ -0,0 +1,47 @@
+{
+  "name": "assistant-app",
+  "category": "Templates",
+  "aliases": [],
+  "exportName": null,
+  "files": [
+    "src/app/(tabs)/_layout.tsx",
+    "src/app/(tabs)/history.tsx",
+    "src/app/(tabs)/index.tsx",
+    "src/app/(tabs)/profile.tsx",
+    "src/app/_layout.tsx",
+    "src/app/onboarding.tsx",
+    "src/app/settings.tsx",
+    "src/app/sign-in.tsx",
+    "src/components/assistant-app/tabs.tsx",
+    "src/lib/assistant-app/assistant.ts",
+    "src/lib/assistant-app/conversations.tsx",
+    "src/lib/assistant-app/data.ts",
+    "src/lib/assistant-app/session.tsx"
+  ],
+  "summary": null,
+  "props": [],
+  "behavior": [
+    [
+      "Flow",
+      "Onboarding shows once, then sign in (Apple, Google or a 6-digit email code), then the tabs. Signing out returns to sign in. The session is saved on the device (AsyncStorage) and guarded with Expo Router’s Stack.Protected."
+    ],
+    [
+      "Chat",
+      "Fully controlled: your message goes in, the reply streams in word by word with a Stop button, and suggestion chips fill the empty state. The tab bar steps aside while the keyboard is up."
+    ],
+    [
+      "History",
+      "Every conversation, newest first. Tap to reopen it in Chat, swipe to delete, or compose a new one."
+    ],
+    [
+      "Settings",
+      "Pushed from Profile. Appearance (System / Light / Dark) re-themes every kit component instantly."
+    ],
+    [
+      "Your model",
+      "lib/assistant-app/assistant.ts streams a canned answer so the app runs with no backend. Replace `reply` with a call to your server, which calls the model API — never ship an API key in the app."
+    ]
+  ],
+  "usage": null,
+  "examples": []
+}

package/registry/_docs/avatar.json

@@ -6,6 +6,7 @@
   "files": [
     "src/components/ui/avatar.tsx"
   ],
+  "summary": "A photo over hashed-colour initials, with presence dots and badges cut into the edge.",
   "props": [
     [
       "src",
@@ -158,11 +159,34 @@
       "Style for the avatar root; AvatarGroup applies it to its row."
     ]
   ],
+  "behavior": [
+    [
+      "Motion",
+      "The photo fades in over the initials, a story ring cross-fades to a hairline once seen, and AvatarGroup springs its faces in with a stagger."
+    ],
+    [
+      "Touch",
+      "With onPress it becomes a button that springs down while pressed."
+    ],
+    [
+      "Reduced motion",
+      "The status pulse, ring spin, press squish and group stagger are skipped, and the seen cross-fade is instant."
+    ],
+    [
+      "Haptics",
+      "A light impact on press when onPress is set. Turn off with haptics={false}."
+    ],
+    [
+      "Screen readers",
+      "Read as an image (or a button when pressable) labelled with the name plus verified, status, notification and story details. A group reads its first names and \"and N more\"."
+    ]
+  ],
+  "usage": "import { Avatar, AvatarGroup } from '@/components/ui/avatar';\n\n<Avatar name=\"Ava Rossi\" src=\"https://i.pravatar.cc/240?img=47\" size=\"lg\" status=\"online\" />\n<AvatarGroup max={3} total={12}>\n  <Avatar name=\"Noah Kim\" />\n  <Avatar name=\"Priya Patel\" />\n  <Avatar name=\"Diego Alvarez\" />\n</AvatarGroup>",
   "examples": [
     {
       "name": "ProfileHeader",
       "title": "Profile Header",
-      "code": "import { Pressable, ScrollView, Text, View } from 'react-native';\nimport { Avatar, AvatarGroup } from '@/components/ui/avatar';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function ProfileHeader() {\n  const { colors, radius, dark } = useKit();\n  return (\n    <View\n      style={{\n        alignItems: 'center',\n        gap: 12,\n        paddingVertical: 20,\n        paddingHorizontal: 16,\n        borderRadius: radius.xl,\n        backgroundColor: colors.card,\n        borderWidth: 1,\n        borderColor: alpha(colors.foreground, dark ? 0.1 : 0.06),\n      }}\n    >\n      <Avatar\n        size={88}\n        src=\"https://i.pravatar.cc/240?img=47\"\n        name=\"Ava Rossi\"\n        ring=\"story\"\n        verified\n        surface={colors.card}\n        elevated\n      />\n      <View style={{ alignItems: 'center', gap: 2 }}>\n        <Text style={{ fontSize: 19, fontWeight: '400', letterSpacing: -0.3, color: colors.foreground }}>Ava Rossi</Text>\n        <Text style={{ fontSize: 14, color: colors.mutedForeground }}>Product designer · Milan</Text>\n      </View>\n      <View style={{ flexDirection: 'row', gap: 24, marginTop: 4 }}>\n        {[\n          ['248', 'Posts'],\n          ['12.4k', 'Followers'],\n          ['311', 'Following'],\n        ].map(([n, l]) => (\n          <View key={l} style={{ alignItems: 'center' }}>\n            <Text style={{ fontSize: 16, color: colors.foreground, fontVariant: ['tabular-nums'] }}>{n}</Text>\n            <Text style={{ fontSize: 12, color: colors.mutedForeground }}>{l}</Text>\n          </View>\n        ))}\n      </View>\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, ScrollView, Text, View } from 'react-native';\nimport { Avatar, AvatarGroup } from '@/components/ui/avatar';\nimport { alpha, useKit } from '@/lib/kit';\n\n/** From the Expo Go viewer: `screen` = this IS the phone screen, so no mock frame; `bottomInset` = home indicator. */\ntype DemoProps = { screen?: boolean; bottomInset?: number };\n\nexport default function ProfileHeader({ screen }: DemoProps) {\n  const { colors, radius, dark } = useKit();\n  return (\n    <View\n      style={[\n        { alignItems: 'center', gap: 12, paddingVertical: 20, paddingHorizontal: 16 },\n        screen\n          ? { flex: 1, justifyContent: 'center', backgroundColor: colors.background }\n          : { borderRadius: radius.xl, backgroundColor: colors.card, borderWidth: 1, borderColor: alpha(colors.foreground, dark ? 0.1 : 0.06) },\n      ]}\n    >\n      <Avatar\n        size={88}\n        src=\"https://i.pravatar.cc/240?img=47\"\n        name=\"Ava Rossi\"\n        ring=\"story\"\n        verified\n        surface={screen ? colors.background : colors.card}\n        elevated\n      />\n      <View style={{ alignItems: 'center', gap: 2 }}>\n        <Text style={{ fontSize: 19, fontWeight: '400', letterSpacing: -0.3, color: colors.foreground }}>Ava Rossi</Text>\n        <Text style={{ fontSize: 14, color: colors.mutedForeground }}>Product designer · Milan</Text>\n      </View>\n      <View style={{ flexDirection: 'row', gap: 24, marginTop: 4 }}>\n        {[\n          ['248', 'Posts'],\n          ['12.4k', 'Followers'],\n          ['311', 'Following'],\n        ].map(([n, l]) => (\n          <View key={l} style={{ alignItems: 'center' }}>\n            <Text style={{ fontSize: 16, color: colors.foreground, fontVariant: ['tabular-nums'] }}>{n}</Text>\n            <Text style={{ fontSize: 12, color: colors.mutedForeground }}>{l}</Text>\n          </View>\n        ))}\n      </View>\n    </View>\n  );\n}\n"
     },
     {
       "name": "ChatList",

package/registry/_docs/badge.json

@@ -2,10 +2,11 @@
   "name": "badge",
   "category": "Display",
   "aliases": [],
-  "exportName": "BadgeIcon",
+  "exportName": "Badge",
   "files": [
     "src/components/ui/badge.tsx"
   ],
+  "summary": "Status pills in four styles that roll, pop and re-tint when their status changes.",
   "props": [
     [
       "variant",
@@ -49,6 +50,12 @@
       "false",
       "Pulsing dot for live states (dot variant)."
     ],
+    [
+      "animateChanges",
+      "boolean",
+      "true",
+      "Roll the label, pop the icon, cross-fade colours and spring the width when they change. Never on mount."
+    ],
     [
       "NotificationBadge.count",
       "number",
@@ -92,26 +99,50 @@
       "Style for the badge pill; NotificationBadge applies it to the anchor wrapper or bare bubble wrapper."
     ]
   ],
+  "behavior": [
+    [
+      "Motion",
+      "On a change the old label rolls up and out as the new one rolls in (per letter for short Latin text), the icon swaps with a scale-and-rotate pop and the pill width springs to fit. Rolls and pops use the native driver; colour and width run on the JS driver on separate views. Nothing animates on mount; animateChanges={false} swaps instantly."
+    ],
+    [
+      "Reduced motion",
+      "Changes swap instantly: no roll, pop, colour fade or width spring. The dot variant's pulse still loops."
+    ],
+    [
+      "Screen readers",
+      "Text labels are one accessible element whose label is always the current text; on Android it is a polite live region so status changes are announced."
+    ],
+    [
+      "Platforms",
+      "React Native Animated and react-native-svg only — iOS, Android, Expo Go and web."
+    ]
+  ],
+  "usage": "import { Badge } from '@/components/ui/badge';\n\nexport function BuildStatus({ done }: { done: boolean }) {\n  return (\n    <Badge tone={done ? 'success' : 'warning'}>{done ? 'Deployed' : 'Building'}</Badge>\n  );\n}",
   "examples": [
     {
       "name": "Variants",
       "title": "Variants",
-      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\n\nconst TONES = ['neutral', 'accent', 'success', 'warning', 'danger'] as const;\n\nexport default function Variants() {\n  return (\n    <View style={{ gap: 10 }}>\n      {(['solid', 'soft', 'outline', 'dot'] as const).map((variant) => (\n        <View key={variant} style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 6 }}>\n          {TONES.map((tone) => (\n            <Badge key={tone} variant={variant} tone={tone}>\n              {tone[0].toUpperCase() + tone.slice(1)}\n            </Badge>\n          ))}\n        </View>\n      ))}\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\n\nconst TONES = ['neutral', 'accent', 'success', 'warning', 'danger'] as const;\n\nexport default function Variants() {\n  return (\n    <View style={{ gap: 10 }}>\n      {(['solid', 'soft', 'outline', 'dot'] as const).map((variant) => (\n        <View key={variant} style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 6 }}>\n          {TONES.map((tone) => (\n            <Badge key={tone} variant={variant} tone={tone}>\n              {tone[0].toUpperCase() + tone.slice(1)}\n            </Badge>\n          ))}\n        </View>\n      ))}\n    </View>\n  );\n}\n"
     },
     {
       "name": "Statuses",
       "title": "Statuses",
-      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Statuses() {\n  const { colors } = useKit();\n  return (\n    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }}>\n      <Badge variant=\"dot\" tone=\"success\" pulse>Live</Badge>\n      <Badge variant=\"soft\" tone=\"success\" icon={<BadgeIcon name=\"package\" color={colors.success} size={14} />}>Paid</Badge>\n      <Badge variant=\"soft\" tone=\"warning\">Pending review</Badge>\n      <Badge variant=\"outline\" tone=\"danger\">Overdue</Badge>\n      <Badge variant=\"solid\" tone=\"accent\" shape=\"rounded\">PRO</Badge>\n      <Badge variant=\"soft\" tone=\"accent\" icon={<BadgeIcon name=\"heart\" color={colors.accent} size={14} />}>Saved</Badge>\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Statuses() {\n  const { colors } = useKit();\n  return (\n    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 8 }}>\n      <Badge variant=\"dot\" tone=\"success\" pulse>Live</Badge>\n      <Badge variant=\"soft\" tone=\"success\" icon={<BadgeIcon name=\"package\" color={colors.success} size={14} />}>Paid</Badge>\n      <Badge variant=\"soft\" tone=\"warning\">Pending review</Badge>\n      <Badge variant=\"outline\" tone=\"danger\">Overdue</Badge>\n      <Badge variant=\"solid\" tone=\"accent\" shape=\"rounded\">PRO</Badge>\n      <Badge variant=\"soft\" tone=\"accent\" icon={<BadgeIcon name=\"heart\" color={colors.accent} size={14} />}>Saved</Badge>\n    </View>\n  );\n}\n"
+    },
+    {
+      "name": "LiveStatus",
+      "title": "Live Status",
+      "code": "import React, { useEffect, useState } from 'react';\nimport { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nconst DEPLOY: { label: string; tone: BadgeTone; icon: BadgeIconName }[] = [\n  { label: 'Queued', tone: 'neutral', icon: 'clock' },\n  { label: 'Building', tone: 'warning', icon: 'refresh' },\n  { label: 'Deployed', tone: 'success', icon: 'check' },\n  { label: 'Failed', tone: 'danger', icon: 'alert' },\n];\n\nexport default function LiveStatus() {\n  const { colors } = useKit();\n  const [step, setStep] = useState(0);\n  useEffect(() => {\n    const id = setInterval(() => setStep((i) => (i + 1) % DEPLOY.length), 1800);\n    return () => clearInterval(id);\n  }, []);\n  const { label, tone, icon } = DEPLOY[step];\n  const tint = { neutral: colors.mutedForeground, accent: colors.accent, success: colors.success, warning: colors.warning, danger: colors.danger }[tone];\n  return (\n    <View style={{ gap: 12 }}>\n      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 10 }}>\n        <Text style={{ fontSize: 15, color: colors.foreground }}>web-checkout #482</Text>\n        <Badge tone={tone} icon={<BadgeIcon name={icon} color={tint} size={14} />}>\n          {label}\n        </Badge>\n      </View>\n      <View style={{ flexDirection: 'row', alignItems: 'center', gap: 10 }}>\n        <Text style={{ fontSize: 15, color: colors.foreground }}>api-gateway #117</Text>\n        <Badge variant=\"solid\" tone={tone} size=\"lg\">\n          {label}\n        </Badge>\n        <Badge variant=\"dot\" tone={tone} pulse={tone === 'warning'}>\n          {label}\n        </Badge>\n      </View>\n    </View>\n  );\n}\n"
     },
     {
       "name": "Sizes",
       "title": "Sizes",
-      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\n\nexport default function Sizes() {\n  return (\n    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>\n      <Badge size=\"sm\" tone=\"accent\">Small</Badge>\n      <Badge size=\"md\" tone=\"accent\">Medium</Badge>\n      <Badge size=\"lg\" tone=\"accent\">Large</Badge>\n    </View>\n  );\n}\n"
+      "code": "import { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\n\nexport default function Sizes() {\n  return (\n    <View style={{ flexDirection: 'row', alignItems: 'center', gap: 8 }}>\n      <Badge size=\"sm\" tone=\"accent\">Small</Badge>\n      <Badge size=\"md\" tone=\"accent\">Medium</Badge>\n      <Badge size=\"lg\" tone=\"accent\">Large</Badge>\n    </View>\n  );\n}\n"
     },
     {
       "name": "Notifications",
       "title": "Notifications",
-      "code": "import React, { useState } from 'react';\nimport { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Notifications() {\n  const { colors, radius } = useKit();\n  const [count, setCount] = useState(3);\n  return (\n    <View style={{ gap: 18 }}>\n      <View style={{ flexDirection: 'row', gap: 26 }}>\n        <NotificationBadge count={count}>\n          <BadgeIconTile name=\"bell\" backgroundColor={alpha(colors.accent, 0.12)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count * 37} tone=\"accent\">\n          <BadgeIconTile name=\"message\" backgroundColor={alpha(colors.accent, 0.1)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count} dot tone=\"success\">\n          <BadgeIconTile name=\"package\" backgroundColor={alpha(colors.success, 0.12)} color={colors.success} />\n        </NotificationBadge>\n      </View>\n      <View style={{ flexDirection: 'row', gap: 10 }}>\n        {[\n          ['+ New', () => setCount((c) => c + 1)],\n          ['Mark all read', () => setCount(0)],\n        ].map(([label, onPress]) => (\n          <Pressable\n            key={label as string}\n            onPress={onPress as () => void}\n            style={{ paddingHorizontal: 14, height: 36, borderRadius: radius.capsule(36), justifyContent: 'center', backgroundColor: colors.muted }}\n          >\n            <Text style={{ fontWeight: '400', color: colors.foreground }}>{label as string}</Text>\n          </Pressable>\n        ))}\n      </View>\n    </View>\n  );\n}\n"
+      "code": "import React, { useEffect, useState } from 'react';\nimport { Pressable, Text, View } from 'react-native';\nimport { Badge, BadgeIcon, BadgeIconTile, NotificationBadge, type BadgeIconName, type BadgeTone } from '@/components/ui/badge';\nimport { alpha, useKit } from '@/lib/kit';\n\nexport default function Notifications() {\n  const { colors, radius } = useKit();\n  const [count, setCount] = useState(3);\n  return (\n    <View style={{ gap: 18 }}>\n      <View style={{ flexDirection: 'row', gap: 26 }}>\n        <NotificationBadge count={count}>\n          <BadgeIconTile name=\"bell\" backgroundColor={alpha(colors.accent, 0.12)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count * 37} tone=\"accent\">\n          <BadgeIconTile name=\"message\" backgroundColor={alpha(colors.accent, 0.1)} color={colors.accent} />\n        </NotificationBadge>\n        <NotificationBadge count={count} dot tone=\"success\">\n          <BadgeIconTile name=\"package\" backgroundColor={alpha(colors.success, 0.12)} color={colors.success} />\n        </NotificationBadge>\n      </View>\n      <View style={{ flexDirection: 'row', gap: 10 }}>\n        {[\n          ['+ New', () => setCount((c) => c + 1)],\n          ['Mark all read', () => setCount(0)],\n        ].map(([label, onPress]) => (\n          <Pressable\n            key={label as string}\n            onPress={onPress as () => void}\n            style={{ paddingHorizontal: 14, height: 36, borderRadius: radius.capsule(36), justifyContent: 'center', backgroundColor: colors.muted }}\n          >\n            <Text style={{ fontWeight: '400', color: colors.foreground }}>{label as string}</Text>\n          </Pressable>\n        ))}\n      </View>\n    </View>\n  );\n}\n"
     }
   ]
 }