@intelligo-dev/cli 1.0.0-beta.1 → 1.0.0-beta.14

package/templates/app-scaffold/workspace-bootstrap.ts.tpl

@@ -0,0 +1,30 @@
+import "server-only";
+
+import type { WorkspaceCreated } from "@intelligo-dev/auth";
+
+/**
+ * Runs once, when a user's personal workspace is created — at signup,
+ * or the first time the app finds the user without one: the place for
+ * trial credits, referral bonuses or any other one-time provisioning.
+ * `lib/intelligo.ts` sets it with `setWorkspaceCreatedHandler`, so
+ * `@intelligo-dev/auth` never imports billing.
+ *
+ * A failure is logged and does not fail the signup.
+ */
+export async function onWorkspaceCreated(
+  _created: WorkspaceCreated
+): Promise<void> {
+  // Provisions nothing by default.
+}
+
+// Example: grant the registered trial with `@intelligo-dev/billing`
+// (replace the export above):
+//
+// import { provisionTrialCredits } from "@intelligo-dev/billing";
+//
+// export async function onWorkspaceCreated({
+//   workspaceId,
+//   email,
+// }: WorkspaceCreated): Promise<void> {
+//   await provisionTrialCredits({ workspaceId, email });
+// }

package/templates/maintenance/maintenance-route.ts.tpl

@@ -0,0 +1,119 @@
+/**
+ * Maintenance route: the periodic work the framework relies on.
+ *
+ * Mount a scheduler at GET /api/cron/maintenance with
+ * `Authorization: Bearer $CRON_SECRET` every five minutes. A stale
+ * execution is reconciled once it is ten minutes old, so the cadence
+ * decides how long an abandoned run keeps its credit hold.
+ *
+ * On Vercel, `intelligo add maintenance` writes the `crons` entry to
+ * vercel.json (`0-59/5 * * * *`) when the app has none, and Vercel
+ * sends the header itself. Vercel Hobby runs a cron at most once a day
+ * and refuses a deployment that asks for more: on Hobby, or on any
+ * other host, drop the entry and call the route from a scheduler of
+ * your own —
+ *
+ *   curl -fsS -H "Authorization: Bearer $CRON_SECRET" \
+ *     https://your-app.example/api/cron/maintenance
+ *
+ * What one run does, and why each step exists:
+ *
+ * - **Reconcile stale executions.** A row still `running` or `settling`
+ *   past the chat route's `maxDuration` is usage nobody finished
+ *   accounting for. `executions.reconcile` confirms a charge the
+ *   ledger already holds, re-runs settlement from the recorded usage,
+ *   or fails an abandoned run and releases its hold.
+ * - **Drop expired reservations.** Admission already ignores them; this
+ *   is table hygiene.
+ * - **Drop old rate-limit buckets.** Same.
+ * - **Expire trials and send reminders.** `hasActiveTrial` checks the
+ *   end date inline, so admission is safe without this — feature
+ *   access and the reminder emails are what it drives.
+ * - **Prune finished jobs** older than a week.
+ *
+ * Draining the job queue is NOT done here: `drain` needs your handlers,
+ * so give it its own route (or call it below once you have some).
+ *
+ * This file is yours. Add product maintenance to it freely.
+ */
+
+import { timingSafeEqual } from "node:crypto";
+
+import {
+  cleanupExpiredReservations,
+  cleanupRateLimitEntries,
+  processTrialExpirations,
+} from "@intelligo-dev/billing";
+import { findStaleExecutions } from "@intelligo-dev/executions";
+import { pruneJobs } from "@intelligo-dev/jobs";
+import { createLogger } from "@intelligo-dev/core/logger";
+
+import { composeIntelligo, executions } from "@/lib/intelligo";
+
+const log = createLogger("cron.maintenance");
+
+export const maxDuration = 60;
+
+/** Executions older than this and still non-terminal are reconciled. */
+const STALE_AFTER_MS = 10 * 60_000;
+/** Finished jobs older than this are pruned. */
+const PRUNE_JOBS_AFTER_MS = 7 * 24 * 60 * 60_000;
+
+/** Constant-time bearer comparison; length is compared too. */
+function bearerMatches(header: string | null, secret: string): boolean {
+  if (!header?.startsWith("Bearer ")) return false;
+  const token = Buffer.from(header.slice("Bearer ".length));
+  const expected = Buffer.from(secret);
+  if (token.length !== expected.length) return false;
+  return timingSafeEqual(token, expected);
+}
+
+export async function GET(request: Request) {
+  const secret = process.env.CRON_SECRET;
+  if (!secret || secret.length < 32) {
+    log.error("CRON_SECRET missing or shorter than 32 chars — refusing");
+    return new Response("Forbidden", { status: 403 });
+  }
+  if (!bearerMatches(request.headers.get("authorization"), secret)) {
+    return new Response("Unauthorized", { status: 401 });
+  }
+
+  composeIntelligo();
+  const errors: string[] = [];
+  const step = async <T>(name: string, run: () => Promise<T>): Promise<T | null> => {
+    try {
+      return await run();
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      log.error(`${name} failed`, { error: message });
+      errors.push(`${name}: ${message}`);
+      return null;
+    }
+  };
+
+  const stale = await step("findStaleExecutions", () =>
+    findStaleExecutions(new Date(Date.now() - STALE_AFTER_MS))
+  );
+  const reconciled: Record<string, number> = {};
+  for (const row of stale ?? []) {
+    const result = await step(`reconcile ${row.id}`, () =>
+      executions.reconcile(row.id, { abandonRunningAfterMs: STALE_AFTER_MS })
+    );
+    if (result) reconciled[result.action] = (reconciled[result.action] ?? 0) + 1;
+  }
+
+  const summary = {
+    staleExecutions: stale?.length ?? 0,
+    reconciled,
+    expiredReservationsDeleted: await step("cleanupExpiredReservations", cleanupExpiredReservations),
+    rateLimitEntriesDeleted: await step("cleanupRateLimitEntries", cleanupRateLimitEntries),
+    trials: await step("processTrialExpirations", processTrialExpirations),
+    jobsPruned: await step("pruneJobs", () =>
+      pruneJobs(new Date(Date.now() - PRUNE_JOBS_AFTER_MS))
+    ),
+    errors,
+  };
+
+  log.info("Maintenance run", summary);
+  return Response.json(summary, { status: errors.length ? 207 : 200 });
+}

package/templates/manifest.json

@@ -1,18 +1,18 @@
 {
   "usage-page": {
-    "templateVersion": "1.0.0",
+    "templateVersion": "1.0.1",
     "description": "A usage page listing executions and cost for the current workspace",
     "files": [
       {
         "template": "usage-page/usage-page.tsx.tpl",
-        "target": "app/usage/page.tsx"
+        "target": "app/[locale]/usage/page.tsx"
       }
     ],
     "deprecated": "Superseded by the `usage` registry item \u2014 install it with the shadcn CLI from the Intelligo registry instead; it ships a full page, components and thin actions as consumer-owned source."
   },
   "app-scaffold": {
-    "templateVersion": "1.4.0",
-    "description": "A new application: composition root, plans, an assistant route, config, next-intl i18n plumbing, and a registry-consuming shadcn/Tailwind setup",
+    "templateVersion": "1.14.0",
+    "description": "A new application: composition root (run once per server process from instrumentation.ts), plans, an assistant route, a Stripe webhook endpoint, config, a drizzle config for the tables you own, next-intl i18n plumbing, and a registry-consuming shadcn base-nova setup with the intelligo design tokens",
     "files": [
       {
         "template": "app-scaffold/package.json.tpl",
@@ -34,10 +34,22 @@
         "template": "app-scaffold/intelligo.ts.tpl",
         "target": "lib/intelligo.ts"
       },
+      {
+        "template": "app-scaffold/instrumentation.ts.tpl",
+        "target": "instrumentation.ts"
+      },
       {
         "template": "app-scaffold/plans.ts.tpl",
         "target": "lib/plans.ts"
       },
+      {
+        "template": "app-scaffold/workspace-bootstrap.ts.tpl",
+        "target": "lib/workspace-bootstrap.ts"
+      },
+      {
+        "template": "app-scaffold/auth-route.ts.tpl",
+        "target": "app/api/auth/[...all]/route.ts"
+      },
       {
         "template": "app-scaffold/assistant-route.ts.tpl",
         "target": "app/api/assistant/route.ts"
@@ -58,10 +70,18 @@
         "template": "app-scaffold/lib-utils.ts.tpl",
         "target": "lib/utils.ts"
       },
+      {
+        "template": "app-scaffold/use-mobile.ts.tpl",
+        "target": "hooks/use-mobile.ts"
+      },
       {
         "template": "app-scaffold/layout.tsx.tpl",
         "target": "app/[locale]/layout.tsx"
       },
+      {
+        "template": "app-scaffold/page.tsx.tpl",
+        "target": "app/[locale]/page.tsx"
+      },
       {
         "template": "app-scaffold/theme-provider.tsx.tpl",
         "target": "components/shell/theme-provider.tsx"
@@ -83,34 +103,72 @@
         "target": "i18n/request.ts"
       },
       {
-        "template": "app-scaffold/middleware.ts.tpl",
-        "target": "middleware.ts"
+        "template": "app-scaffold/proxy.ts.tpl",
+        "target": "proxy.ts"
       },
       {
         "template": "app-scaffold/messages-en-app.json.tpl",
         "target": "messages/en/app.json"
+      },
+      {
+        "template": "app-scaffold/drizzle.config.ts.tpl",
+        "target": "drizzle.config.ts"
+      },
+      {
+        "template": "app-scaffold/db-schema.ts.tpl",
+        "target": "lib/db/schema.ts"
+      },
+      {
+        "template": "app-scaffold/drizzle-journal.json.tpl",
+        "target": "drizzle/meta/_journal.json"
+      },
+      {
+        "template": "app-scaffold/stripe-webhook-route.ts.tpl",
+        "target": "app/api/webhooks/stripe/route.ts"
       }
     ]
   },
-  "billing-page": {
-    "templateVersion": "1.0.0",
-    "description": "A billing page reading your registered plan catalogue",
+  "admin-page": {
+    "templateVersion": "1.1.0",
+    "description": "Mount the Intelligo operational console at /admin",
     "files": [
       {
-        "template": "billing-page/billing-page.tsx.tpl",
-        "target": "app/billing/page.tsx"
+        "template": "admin-page/admin-page.tsx.tpl",
+        "target": "app/[locale]/admin/page.tsx"
       }
-    ],
-    "deprecated": "Superseded by the `pricing` and `billing-settings` registry items \u2014 install them with the shadcn CLI from the Intelligo registry instead."
+    ]
   },
-  "admin-page": {
+  "maintenance": {
+    "templateVersion": "1.1.0",
+    "description": "A CRON_SECRET-gated GET /api/cron/maintenance that reconciles stale executions, drops expired reservations and rate-limit buckets, expires trials and prunes old jobs \u2014 scheduled every five minutes, in vercel.json when the app has none",
+    "cron": {
+      "path": "/api/cron/maintenance",
+      "schedule": "0-59/5 * * * *"
+    },
+    "files": [
+      {
+        "template": "maintenance/maintenance-route.ts.tpl",
+        "target": "app/api/cron/maintenance/route.ts"
+      }
+    ]
+  },
+  "vitest": {
     "templateVersion": "1.0.0",
-    "description": "Mount the Intelligo operational console at /admin",
+    "description": "A Vitest setup for the app's own tests: the `@` alias, a `server-only` stub, and the `@intelligo-dev/*` packages inlined so the stub reaches them",
     "files": [
       {
-        "template": "admin-page/admin-page.tsx.tpl",
-        "target": "app/admin/page.tsx"
+        "template": "vitest/vitest.config.ts.tpl",
+        "target": "vitest.config.ts"
+      },
+      {
+        "template": "vitest/server-only.ts.tpl",
+        "target": "tests/stubs/server-only.ts"
       }
+    ],
+    "nextSteps": [
+      "Install the runner: pnpm add -D vitest",
+      "Add a script to package.json: \"test\": \"vitest run\"",
+      "Write tests beside the code as *.test.ts; mock @ai-sdk/* providers so CI makes no model calls"
     ]
   }
 }

package/templates/registry/ai-agent-activity.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "ai-agent-activity",
+  "title": "AI Agent Activity",
+  "description": "One adaptive stream of what the agent is doing: reasoning text, plan steps, web searches with results, tool calls and structured traces, gliding while it works and folding into a summary when done.",
+  "dependencies": [
+    "motion",
+    "lucide-react"
+  ],
+  "registryDependencies": [
+    "@intelligo/ai-motion",
+    "@intelligo/ai-shimmer-text"
+  ],
+  "files": [
+    {
+      "path": "base/ui/ai-agent-activity/ai-agent-activity.tsx",
+      "content": "\"use client\";\n\n/*\n * One adaptive stream of what the agent is doing: reasoning text, plan\n * steps, web searches with their results, tool calls and structured\n * traces. While the run is working the newest rows glide up under a fade;\n * once complete the stream folds into a one-line summary that opens on\n * demand.\n */\n\nimport * as React from \"react\";\nimport {\n  CheckIcon,\n  ChevronDownIcon,\n  CircleAlertIcon,\n  CircleIcon,\n  FileTextIcon,\n  Globe2Icon,\n  ImageIcon,\n  MessageSquareIcon,\n  PencilLineIcon,\n  SearchIcon,\n  SparklesIcon,\n  SquareTerminalIcon,\n  WrenchIcon,\n} from \"lucide-react\";\nimport { AnimatePresence, motion, useReducedMotion } from \"motion/react\";\n\nimport {\n  EASE_OUT,\n  Disclosure,\n  SPRING_LAYOUT,\n  SPRING_SWAP,\n} from \"@/components/ui/ai-motion\";\nimport { ShimmerText } from \"@/components/ui/ai-shimmer-text\";\nimport { cn } from \"@/lib/utils\";\n\n/* ----------------------------------------------------------------------------\n * Items\n * ------------------------------------------------------------------------- */\n\nexport type AgentActivityStatus = \"working\" | \"complete\";\nexport type AgentStepStatus = \"pending\" | \"active\" | \"complete\";\n\nexport interface AgentActivityStep {\n  id: string;\n  type: \"step\";\n  label: React.ReactNode;\n  status?: AgentStepStatus;\n  meta?: React.ReactNode;\n}\n\nexport interface AgentActivityText {\n  id: string;\n  type: \"text\";\n  content: React.ReactNode;\n}\n\nexport interface AgentSearchResult {\n  id: string;\n  title: React.ReactNode;\n  domain?: React.ReactNode;\n  url?: string;\n  icon?: React.ReactNode;\n}\n\n/** A row's own state inside the stream; rows are complete by default. */\nexport type AgentRowStatus = \"running\" | \"complete\" | \"error\";\n\nexport interface AgentActivitySearch {\n  id: string;\n  type: \"search\";\n  query: React.ReactNode;\n  results?: AgentSearchResult[];\n  moreCount?: number;\n  status?: AgentRowStatus;\n  /** Shown under the row when the reader opens it — the raw call, say. */\n  details?: React.ReactNode;\n}\n\nexport interface AgentActivityTool {\n  id: string;\n  type: \"tool\";\n  action: \"read\" | \"edit\" | \"run\" | (string & {});\n  target?: React.ReactNode;\n  additions?: number;\n  deletions?: number;\n  status?: AgentRowStatus;\n  /** Shown under the row when the reader opens it — the raw call, say. */\n  details?: React.ReactNode;\n}\n\nexport type AgentTraceKind =\n  | \"thinking\"\n  | \"message\"\n  | \"write\"\n  | \"run\"\n  | \"read\"\n  | (string & {});\n\nexport interface AgentActivityTrace {\n  id: string;\n  type: \"trace\";\n  kind: AgentTraceKind;\n  label: React.ReactNode;\n  detail?: React.ReactNode;\n  icon?: React.ReactNode;\n}\n\nexport type AgentActivityItem =\n  | AgentActivityStep\n  | AgentActivityText\n  | AgentActivitySearch\n  | AgentActivityTool\n  | AgentActivityTrace;\n\nexport type AgentActivityContentType = AgentActivityItem[\"type\"] | \"mixed\";\n\n/* ----------------------------------------------------------------------------\n * Labels — every visible string, with an English default.\n * ------------------------------------------------------------------------- */\n\nexport interface AgentActivitySummaryLabels {\n  /** Step- or text-only runs: `duration` is already formatted. */\n  thought: (duration: string) => React.ReactNode;\n  searched: string;\n  tools: (count: number) => string;\n  trace: (toolCalls: number, messages: number) => string;\n  steps: (count: number) => string;\n}\n\nconst DEFAULT_ACTIVE_LABELS: Record<AgentActivityContentType, string> = {\n  step: \"Thinking…\",\n  text: \"Thinking…\",\n  search: \"Searching the web…\",\n  tool: \"Running tools…\",\n  trace: \"Working through the run…\",\n  mixed: \"Working through it…\",\n};\n\nconst DEFAULT_SUMMARY_LABELS: AgentActivitySummaryLabels = {\n  thought: (duration) => (\n    <>\n      Thought for <span className=\"tabular-nums\">{duration}</span>\n    </>\n  ),\n  searched: \"Searched the web\",\n  tools: (count) => `Ran ${count} ${count === 1 ? \"tool\" : \"tools\"}`,\n  trace: (toolCalls, messages) =>\n    `${toolCalls} ${toolCalls === 1 ? \"tool call\" : \"tool calls\"}, ${messages} ${messages === 1 ? \"message\" : \"messages\"}`,\n  steps: (count) => `Completed ${count} ${count === 1 ? \"step\" : \"steps\"}`,\n};\n\nfunction defaultFormatDuration(duration: number) {\n  const seconds = Math.max(0, Math.round(duration));\n  if (seconds < 60) return `${seconds}s`;\n\n  const minutes = Math.floor(seconds / 60);\n  const remainder = seconds % 60;\n  return remainder === 0 ? `${minutes}m` : `${minutes}m ${remainder}s`;\n}\n\nfunction defaultMoreLabel(count: number) {\n  return `+${count} more`;\n}\n\nfunction defaultActionLabel(action: string) {\n  return action.charAt(0).toUpperCase() + action.slice(1);\n}\n\n/* ----------------------------------------------------------------------------\n * Rows\n * ------------------------------------------------------------------------- */\n\nfunction StepRow({ item }: { item: AgentActivityStep }) {\n  const reduce = useReducedMotion() ?? false;\n  const state = item.status ?? \"complete\";\n\n  return (\n    <div\n      data-slot=\"agent-activity-step\"\n      data-status={state}\n      className=\"flex min-h-7 items-start gap-2.5 rounded-md px-1.5 py-1\"\n    >\n      <span\n        aria-hidden=\"true\"\n        className=\"mt-0.5 grid size-4 shrink-0 place-items-center text-muted-foreground/70\"\n      >\n        {state === \"complete\" ? (\n          <CheckIcon className=\"size-4\" strokeWidth={1.8} />\n        ) : state === \"active\" ? (\n          <span className=\"relative grid size-3 place-items-center\">\n            <motion.span\n              className=\"absolute inset-0 rounded-full bg-foreground/10\"\n              animate={\n                reduce ? { opacity: 0.6 } : { opacity: [0.35, 0.8, 0.35] }\n              }\n              transition={\n                reduce\n                  ? { duration: 0 }\n                  : { duration: 1.5, repeat: Number.POSITIVE_INFINITY }\n              }\n            />\n            <span className=\"size-1.5 rounded-full bg-foreground/60\" />\n          </span>\n        ) : (\n          <CircleIcon className=\"size-3\" strokeWidth={1.5} />\n        )}\n      </span>\n      <span\n        className={cn(\n          \"min-w-0 flex-1 leading-5\",\n          state === \"pending\"\n            ? \"text-muted-foreground/55\"\n            : \"text-foreground/90\"\n        )}\n      >\n        {item.label}\n      </span>\n      {item.meta ? (\n        <span className=\"shrink-0 leading-5 text-muted-foreground/55\">\n          {item.meta}\n        </span>\n      ) : null}\n    </div>\n  );\n}\n\nfunction TextRow({ item }: { item: AgentActivityText }) {\n  return (\n    <div\n      data-slot=\"agent-activity-text\"\n      className=\"rounded-md px-1.5 py-1 leading-5 text-muted-foreground\"\n    >\n      {item.content}\n    </div>\n  );\n}\n\nfunction SearchResultRow({ result }: { result: AgentSearchResult }) {\n  const content = (\n    <>\n      <span\n        aria-hidden=\"true\"\n        className=\"grid size-5 shrink-0 place-items-center text-muted-foreground\"\n      >\n        {result.icon ?? <Globe2Icon className=\"size-3\" strokeWidth={2} />}\n      </span>\n      <span className=\"min-w-0 truncate font-medium text-foreground/90\">\n        {result.title}\n      </span>\n      {result.domain ? (\n        <span className=\"min-w-0 truncate text-muted-foreground/55\">\n          {result.domain}\n        </span>\n      ) : null}\n    </>\n  );\n  const className = cn(\n    \"flex min-h-7 items-center gap-2 rounded-md px-1.5 py-1 text-left outline-none transition-colors\",\n    result.url && \"hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-ring\"\n  );\n\n  return result.url ? (\n    <a\n      data-slot=\"agent-activity-search-result\"\n      href={result.url}\n      target=\"_blank\"\n      rel=\"noreferrer noopener\"\n      className={className}\n    >\n      {content}\n    </a>\n  ) : (\n    <div data-slot=\"agent-activity-search-result\" className={className}>\n      {content}\n    </div>\n  );\n}\n\n/** A row's glyph, pulsing while its call runs; an alert once it failed. */\nfunction RowStatusIcon({\n  status,\n  children,\n}: {\n  status: AgentRowStatus;\n  children: React.ReactNode;\n}) {\n  const reduce = useReducedMotion() ?? false;\n  if (status === \"error\") {\n    return <CircleAlertIcon className=\"size-4 text-destructive\" strokeWidth={1.8} />;\n  }\n  if (status === \"running\") {\n    return (\n      <motion.span\n        className=\"grid size-4 place-items-center\"\n        animate={reduce ? { opacity: 0.7 } : { opacity: [0.4, 1, 0.4] }}\n        transition={\n          reduce\n            ? { duration: 0 }\n            : { duration: 1.4, repeat: Number.POSITIVE_INFINITY }\n        }\n      >\n        {children}\n      </motion.span>\n    );\n  }\n  return <>{children}</>;\n}\n\n/** A row that opens onto its details, when it has any. */\nfunction RowWithDetails({\n  details,\n  className,\n  children,\n  ...props\n}: Omit<React.ComponentProps<\"div\">, \"children\" | \"className\"> & {\n  details?: React.ReactNode;\n  className: string;\n  children: React.ReactNode;\n}) {\n  const reduce = useReducedMotion() ?? false;\n  const [open, setOpen] = React.useState(false);\n  const detailsId = React.useId();\n\n  if (!details) {\n    return (\n      <div className={className} {...props}>\n        {children}\n      </div>\n    );\n  }\n\n  return (\n    <div {...props}>\n      <button\n        type=\"button\"\n        aria-expanded={open}\n        aria-controls={detailsId}\n        onClick={() => setOpen(!open)}\n        className={cn(\n          className,\n          \"group/row w-full text-left outline-none transition-colors hover:bg-muted/60 focus-visible:ring-2 focus-visible:ring-ring\"\n        )}\n      >\n        {children}\n        <motion.span\n          aria-hidden=\"true\"\n          animate={{ rotate: open ? 180 : 0 }}\n          transition={reduce ? { duration: 0 } : SPRING_SWAP}\n          className={cn(\n            \"inline-flex shrink-0 text-muted-foreground/60 transition-opacity group-hover/row:opacity-100 group-focus-visible/row:opacity-100\",\n            open ? \"opacity-100\" : \"opacity-0\"\n          )}\n        >\n          <ChevronDownIcon className=\"size-3.5\" />\n        </motion.span>\n      </button>\n      <Disclosure id={detailsId} open={open}>\n        <div data-slot=\"agent-activity-details\" className=\"pt-1 pr-1.5 pb-2 pl-8\">\n          {details}\n        </div>\n      </Disclosure>\n    </div>\n  );\n}\n\nfunction SearchRow({\n  item,\n  moreLabel,\n}: {\n  item: AgentActivitySearch;\n  moreLabel: (count: number) => string;\n}) {\n  const reduce = useReducedMotion() ?? false;\n  const enter = reduce ? { opacity: 1 } : { opacity: 0, y: 6 };\n  const visible = { opacity: 1, y: 0 };\n  const exit = reduce ? { opacity: 0 } : { opacity: 0, y: -3 };\n  const transition = reduce\n    ? { duration: 0 }\n    : {\n        opacity: { duration: 0.18, ease: EASE_OUT },\n        y: SPRING_LAYOUT,\n        layout: SPRING_LAYOUT,\n      };\n\n  return (\n    <div\n      data-slot=\"agent-activity-search\"\n      data-status={item.status ?? \"complete\"}\n      className=\"space-y-0.5\"\n    >\n      <RowWithDetails\n        details={item.details}\n        className=\"flex min-h-7 items-center gap-2.5 rounded-md px-1.5 py-1 text-muted-foreground\"\n      >\n        <span aria-hidden=\"true\" className=\"grid size-4 shrink-0 place-items-center\">\n          <RowStatusIcon status={item.status ?? \"complete\"}>\n            <SearchIcon className=\"size-4\" strokeWidth={1.7} />\n          </RowStatusIcon>\n        </span>\n        <span className=\"min-w-0 flex-1 truncate\">{item.query}</span>\n      </RowWithDetails>\n      {item.results?.length ? (\n        <div className=\"space-y-0.5 pl-4\">\n          <AnimatePresence initial mode=\"popLayout\">\n            {item.results.map((result) => (\n              <motion.div\n                layout=\"position\"\n                key={result.id}\n                initial={enter}\n                animate={visible}\n                exit={exit}\n                transition={transition}\n              >\n                <SearchResultRow result={result} />\n              </motion.div>\n            ))}\n          </AnimatePresence>\n        </div>\n      ) : null}\n      <AnimatePresence initial>\n        {item.moreCount ? (\n          <motion.div\n            key=\"more-results\"\n            initial={enter}\n            animate={visible}\n            exit={exit}\n            transition={transition}\n            className=\"px-1.5 py-1 pl-8 text-muted-foreground/55\"\n          >\n            {moreLabel(item.moreCount)}\n          </motion.div>\n        ) : null}\n      </AnimatePresence>\n    </div>\n  );\n}\n\nfunction ActionIcon({ action }: { action: string }) {\n  if (action === \"read\") return <FileTextIcon className=\"size-4\" />;\n  if (action === \"edit\" || action === \"write\") {\n    return <PencilLineIcon className=\"size-4\" />;\n  }\n  if (action === \"run\") return <SquareTerminalIcon className=\"size-4\" />;\n  return <WrenchIcon className=\"size-4\" />;\n}\n\nfunction ToolRow({\n  item,\n  actionLabels,\n}: {\n  item: AgentActivityTool;\n  actionLabels?: Record<string, string>;\n}) {\n  const action = actionLabels?.[item.action] ?? defaultActionLabel(item.action);\n  const status = item.status ?? \"complete\";\n\n  return (\n    <RowWithDetails\n      data-slot=\"agent-activity-tool\"\n      data-action={item.action}\n      data-status={status}\n      details={item.details}\n      className=\"flex min-h-8 min-w-0 items-center gap-2.5 rounded-md px-1.5 py-0.5 leading-5\"\n    >\n      <span\n        aria-hidden=\"true\"\n        className=\"grid size-4 shrink-0 place-items-center text-muted-foreground/70\"\n      >\n        <RowStatusIcon status={status}>\n          <ActionIcon action={item.action} />\n        </RowStatusIcon>\n      </span>\n      <span className=\"shrink-0 font-medium text-foreground/90\">{action}</span>\n      {item.target ? (\n        <span\n          className={cn(\n            \"min-w-0 flex-1 truncate rounded-lg bg-muted/80 px-2.5 py-1 font-mono text-xs text-muted-foreground\",\n            status === \"error\" && \"bg-transparent px-0 font-sans text-destructive\"\n          )}\n        >\n          {item.target}\n        </span>\n      ) : (\n        <span className=\"flex-1\" />\n      )}\n      {typeof item.additions === \"number\" ||\n      typeof item.deletions === \"number\" ? (\n        <span className=\"flex shrink-0 items-center gap-2 font-mono tabular-nums\">\n          {typeof item.additions === \"number\" ? (\n            <span className=\"text-success\">+{item.additions}</span>\n          ) : null}\n          {typeof item.deletions === \"number\" ? (\n            <span className=\"text-destructive\">−{item.deletions}</span>\n          ) : null}\n        </span>\n      ) : null}\n    </RowWithDetails>\n  );\n}\n\nfunction TraceIcon({ kind }: { kind: AgentTraceKind }) {\n  if (kind === \"thinking\") return <SparklesIcon className=\"size-4\" />;\n  if (kind === \"message\") return <MessageSquareIcon className=\"size-4\" />;\n  if (kind === \"write\") return <PencilLineIcon className=\"size-4\" />;\n  if (kind === \"run\") return <SquareTerminalIcon className=\"size-4\" />;\n  if (kind === \"read\") return <ImageIcon className=\"size-4\" />;\n  return <WrenchIcon className=\"size-4\" />;\n}\n\nfunction TraceRow({ item }: { item: AgentActivityTrace }) {\n  return (\n    <div\n      data-slot=\"agent-activity-trace\"\n      data-kind={item.kind}\n      className=\"grid min-h-8 items-center gap-2.5 rounded-md px-1.5 py-0.5\"\n      style={{ gridTemplateColumns: \"1rem auto minmax(0, 1fr)\" }}\n    >\n      <span\n        aria-hidden=\"true\"\n        className=\"grid size-4 place-items-center text-muted-foreground/70\"\n      >\n        {item.icon ?? <TraceIcon kind={item.kind} />}\n      </span>\n      <span className=\"font-medium text-foreground/90\">{item.label}</span>\n      {item.detail ? (\n        <span className=\"min-w-0 truncate rounded-lg bg-muted/80 px-2.5 py-1 font-mono text-xs text-muted-foreground/70\">\n          {item.detail}\n        </span>\n      ) : (\n        <span />\n      )}\n    </div>\n  );\n}\n\nexport interface AgentActivityRowProps {\n  item: AgentActivityItem;\n  /** \"+3 more\" under a search's results. */\n  moreLabel?: (count: number) => string;\n  /** The word shown for a tool action (`read` → \"Read\"); capitalised by default. */\n  actionLabels?: Record<string, string>;\n}\n\nfunction AgentActivityRow({\n  item,\n  moreLabel = defaultMoreLabel,\n  actionLabels,\n}: AgentActivityRowProps) {\n  if (item.type === \"text\") return <TextRow item={item} />;\n  if (item.type === \"search\")\n    return <SearchRow item={item} moreLabel={moreLabel} />;\n  if (item.type === \"tool\")\n    return <ToolRow item={item} actionLabels={actionLabels} />;\n  if (item.type === \"trace\") return <TraceRow item={item} />;\n  return <StepRow item={item} />;\n}\n\n/* ----------------------------------------------------------------------------\n * The stream\n * ------------------------------------------------------------------------- */\n\nexport interface AgentActivityProps extends Omit<\n  React.ComponentProps<\"div\">,\n  \"children\"\n> {\n  /** Chronological activity entries. Append or update items as events stream. */\n  items: AgentActivityItem[];\n  /** Expected activity kind before the first streamed item arrives. */\n  contentType?: AgentActivityContentType;\n  /** Current run phase. Active runs always stay expanded. */\n  status?: AgentActivityStatus;\n  /** Elapsed run time, in seconds. Used by the step-only summary. */\n  duration?: number;\n  /** Controlled expanded state used after the run completes. */\n  open?: boolean;\n  /** Initial expanded state used after the run completes. */\n  defaultOpen?: boolean;\n  /** Called when the completed activity disclosure changes state. */\n  onOpenChange?: (open: boolean) => void;\n  /** Collapse the disclosure when status changes from working to complete. */\n  collapseOnComplete?: boolean;\n  /** The status line while the run is active; overrides `activeLabels`. */\n  activeLabel?: string;\n  /** The status line per content kind while the run is active. */\n  activeLabels?: Partial<Record<AgentActivityContentType, string>>;\n  /** The completed summary; overrides `summaryLabels`. */\n  summary?: React.ReactNode;\n  /** The completed summary per content kind. */\n  summaryLabels?: Partial<AgentActivitySummaryLabels>;\n  /** \"45s\", \"2m 5s\" — for the step-only summary. */\n  formatDuration?: (seconds: number) => string;\n  /** \"+3 more\" under a search's results. */\n  moreLabel?: (count: number) => string;\n  /** The word shown for a tool action (`read` → \"Read\"); capitalised by default. */\n  actionLabels?: Record<string, string>;\n  /** Optional renderer for the contents of the active status row. */\n  renderWorkingStatus?: (context: {\n    label: string;\n    duration: number;\n  }) => React.ReactNode;\n  /** Optional renderer for the contents before the built-in disclosure chevron. */\n  renderCompletedStatus?: (context: {\n    summary: React.ReactNode;\n    duration: number;\n  }) => React.ReactNode;\n  /** Maximum visible activity height before the stream begins gliding. */\n  maxHeight?: number;\n  contentClassName?: string;\n}\n\nfunction useControllableOpen({\n  open,\n  defaultOpen,\n  onOpenChange,\n}: {\n  open?: boolean;\n  defaultOpen: boolean;\n  onOpenChange?: (open: boolean) => void;\n}) {\n  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);\n  const controlled = open !== undefined;\n  const currentOpen = open ?? internalOpen;\n\n  const setOpen = React.useCallback(\n    (next: boolean) => {\n      if (!controlled) setInternalOpen(next);\n      onOpenChange?.(next);\n    },\n    [controlled, onOpenChange]\n  );\n\n  return [currentOpen, setOpen] as const;\n}\n\nfunction getContentType(items: AgentActivityItem[]): AgentActivityContentType {\n  const first = items[0]?.type;\n  return first && items.every((item) => item.type === first) ? first : \"mixed\";\n}\n\nfunction getSummary(\n  type: AgentActivityContentType,\n  items: AgentActivityItem[],\n  duration: string,\n  labels: AgentActivitySummaryLabels\n): React.ReactNode {\n  if (type === \"step\" || type === \"text\") return labels.thought(duration);\n  if (type === \"search\") return labels.searched;\n  if (type === \"tool\") return labels.tools(items.length);\n  if (type === \"trace\") {\n    const messages = items.filter(\n      (item) =>\n        item.type === \"trace\" &&\n        (item.kind === \"thinking\" || item.kind === \"message\")\n    ).length;\n    return labels.trace(items.length - messages, messages);\n  }\n  return labels.steps(items.length);\n}\n\nfunction AgentActivity({\n  items,\n  contentType: initialContentType,\n  status = \"working\",\n  duration = 0,\n  open,\n  defaultOpen = false,\n  onOpenChange,\n  collapseOnComplete = true,\n  activeLabel,\n  activeLabels,\n  summary,\n  summaryLabels,\n  formatDuration = defaultFormatDuration,\n  moreLabel = defaultMoreLabel,\n  actionLabels,\n  renderWorkingStatus,\n  renderCompletedStatus,\n  maxHeight = 208,\n  className,\n  contentClassName,\n  ...props\n}: AgentActivityProps) {\n  const reduce = useReducedMotion() ?? false;\n  const baseId = React.useId();\n  const triggerId = `${baseId}-trigger`;\n  const contentId = `${baseId}-content`;\n  const contentRef = React.useRef<HTMLDivElement>(null);\n  const viewportRef = React.useRef<HTMLDivElement>(null);\n  const previousStatus = React.useRef(status);\n  const [contentHeight, setContentHeight] = React.useState(0);\n  const [currentOpen, setOpen] = useControllableOpen({\n    open,\n    defaultOpen,\n    onOpenChange,\n  });\n  const working = status === \"working\";\n  const expanded = working || currentOpen;\n  const contentType = items.length\n    ? getContentType(items)\n    : (initialContentType ?? \"mixed\");\n  // While working the viewport is a fixed window the content glides up\n  // through; once complete it shrinks to fit (capped) and scrolls.\n  const cappedHeight = Math.min(contentHeight, Math.max(0, maxHeight));\n  const viewportHeight = working ? Math.max(0, maxHeight) : cappedHeight;\n  const capped = contentHeight > maxHeight;\n  const streamOffset = working\n    ? Math.min(0, viewportHeight - contentHeight)\n    : 0;\n\n  React.useLayoutEffect(() => {\n    const node = contentRef.current;\n    if (!node) return;\n\n    const measure = () => setContentHeight(node.offsetHeight);\n    measure();\n\n    if (typeof ResizeObserver === \"undefined\") return;\n    const observer = new ResizeObserver(measure);\n    observer.observe(node);\n    return () => observer.disconnect();\n  }, []);\n\n  React.useEffect(() => {\n    if (previousStatus.current === \"working\" && status === \"complete\") {\n      setOpen(!collapseOnComplete);\n    }\n    previousStatus.current = status;\n  }, [collapseOnComplete, setOpen, status]);\n\n  const toggle = () => {\n    const next = !currentOpen;\n    setOpen(next);\n    if (next) {\n      requestAnimationFrame(() => viewportRef.current?.scrollTo({ top: 0 }));\n    }\n  };\n\n  const liveLabel =\n    activeLabel ??\n    activeLabels?.[contentType] ??\n    DEFAULT_ACTIVE_LABELS[contentType];\n  const completedSummary =\n    summary ??\n    getSummary(contentType, items, formatDuration(duration), {\n      ...DEFAULT_SUMMARY_LABELS,\n      ...summaryLabels,\n    });\n  // Alpha-only masks: the colour words never paint.\n  const maskImage = capped\n    ? working\n      ? \"linear-gradient(to bottom, transparent, black 12px)\"\n      : \"linear-gradient(to bottom, transparent, black 12px, black calc(100% - 12px), transparent)\"\n    : undefined;\n\n  return (\n    <div\n      data-slot=\"agent-activity\"\n      data-state={working ? \"working\" : expanded ? \"open\" : \"closed\"}\n      data-content={contentType}\n      aria-busy={working}\n      className={cn(\"w-full text-sm\", className)}\n      {...props}\n    >\n      {working ? (\n        <div\n          data-slot=\"agent-activity-status\"\n          id={triggerId}\n          role=\"status\"\n          className=\"flex h-7 min-w-0 items-center text-muted-foreground\"\n        >\n          {renderWorkingStatus ? (\n            renderWorkingStatus({ label: liveLabel, duration })\n          ) : (\n            // This row is the live region; the shimmer must not nest a second one.\n            <ShimmerText role={undefined} className=\"font-medium\">\n              {liveLabel}\n            </ShimmerText>\n          )}\n        </div>\n      ) : (\n        <button\n          data-slot=\"agent-activity-trigger\"\n          id={triggerId}\n          type=\"button\"\n          aria-expanded={expanded}\n          aria-controls={contentId}\n          onClick={toggle}\n          className=\"group flex h-7 min-w-0 items-center gap-1.5 rounded-md text-left font-medium text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background\"\n        >\n          <span className=\"truncate\">\n            {renderCompletedStatus\n              ? renderCompletedStatus({ summary: completedSummary, duration })\n              : completedSummary}\n          </span>\n          <motion.span\n            aria-hidden=\"true\"\n            animate={{ rotate: expanded ? 180 : 0 }}\n            transition={reduce ? { duration: 0 } : SPRING_SWAP}\n            className=\"inline-flex shrink-0 text-muted-foreground/70 group-hover:text-foreground\"\n          >\n            <ChevronDownIcon className=\"size-3.5\" />\n          </motion.span>\n        </button>\n      )}\n\n      <Disclosure\n        id={contentId}\n        role=\"region\"\n        aria-labelledby={triggerId}\n        open={expanded}\n        openHeight={viewportHeight}\n      >\n        <div\n          data-slot=\"agent-activity-viewport\"\n          ref={viewportRef}\n          className={cn(\n            \"pr-1 [scrollbar-width:none] [&::-webkit-scrollbar]:hidden\",\n            capped && expanded && !working\n              ? \"overflow-y-auto\"\n              : \"overflow-y-hidden\"\n          )}\n          style={{\n            height: viewportHeight,\n            maskImage,\n            WebkitMaskImage: maskImage,\n          }}\n        >\n          <motion.div\n            data-slot=\"agent-activity-list\"\n            ref={contentRef}\n            role=\"list\"\n            initial={false}\n            animate={{ y: streamOffset }}\n            transition={reduce ? { duration: 0 } : SPRING_LAYOUT}\n            className={cn(\"space-y-0.5 py-2\", contentClassName)}\n          >\n            <AnimatePresence mode=\"popLayout\">\n              {items.map((item) => (\n                <motion.div\n                  data-slot=\"agent-activity-item\"\n                  data-type={item.type}\n                  layout=\"position\"\n                  key={item.id}\n                  role=\"listitem\"\n                  initial={reduce ? { opacity: 1 } : { opacity: 0, y: 6 }}\n                  animate={{ opacity: 1, y: 0 }}\n                  exit={reduce ? { opacity: 0 } : { opacity: 0, y: -3 }}\n                  transition={\n                    reduce\n                      ? { duration: 0 }\n                      : {\n                          opacity: { duration: 0.18, ease: EASE_OUT },\n                          y: SPRING_LAYOUT,\n                          layout: SPRING_LAYOUT,\n                        }\n                  }\n                >\n                  <AgentActivityRow\n                    item={item}\n                    moreLabel={moreLabel}\n                    actionLabels={actionLabels}\n                  />\n                </motion.div>\n              ))}\n            </AnimatePresence>\n          </motion.div>\n        </div>\n      </Disclosure>\n    </div>\n  );\n}\n\nexport { AgentActivity, AgentActivityRow };\n",
+      "type": "registry:ui",
+      "target": "components/ui/ai-agent-activity.tsx"
+    }
+  ],
+  "type": "registry:ui"
+}

package/templates/registry/ai-agent-progress.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "ai-agent-progress",
+  "title": "AI Agent Progress",
+  "description": "A long-running step: a pulsing grid beside the verb and an elapsed-time counter.",
+  "dependencies": [
+    "motion"
+  ],
+  "registryDependencies": [
+    "@intelligo/ai-motion"
+  ],
+  "files": [
+    {
+      "path": "base/ui/ai-agent-progress/ai-agent-progress.tsx",
+      "content": "\"use client\";\n\n/*\n * A long-running step: a 3×3 grid pulses in sequence beside the verb and\n * an elapsed-time counter.\n */\n\nimport * as React from \"react\";\nimport { motion, useReducedMotion } from \"motion/react\";\n\nimport { EASE_IN_OUT } from \"@/components/ui/ai-motion\";\nimport { cn } from \"@/lib/utils\";\n\nconst GRID_CELLS = [\n  { id: \"top-left\", delay: 0 },\n  { id: \"top-center\", delay: 0.14 },\n  { id: \"top-right\", delay: 0.28 },\n  { id: \"middle-left\", delay: 0.42 },\n  { id: \"middle-center\", delay: 0.56 },\n  { id: \"middle-right\", delay: 0.7 },\n  { id: \"bottom-left\", delay: 0.84 },\n  { id: \"bottom-center\", delay: 0.98 },\n  { id: \"bottom-right\", delay: 1.12 },\n];\n\nexport interface AgentProgressProps\n  extends Omit<React.ComponentProps<\"span\">, \"children\"> {\n  /** Verb describing the agent's current activity. */\n  label?: string;\n  /** Assistive-tech name; defaults to \"{label}, in progress\". */\n  statusLabel?: string;\n  /** Controlled elapsed time in seconds. */\n  elapsedSeconds?: number;\n  /** Starting time for the internal timer, in seconds. */\n  initialSeconds?: number;\n  /** Whether the internal timer should advance. Ignored when elapsedSeconds is provided. */\n  running?: boolean;\n  /** Renders the counter; \"1m 4.2s\" by default. */\n  formatElapsed?: (totalSeconds: number) => string;\n}\n\nfunction defaultFormatElapsed(totalSeconds: number) {\n  const safeSeconds = Math.max(0, totalSeconds);\n  const minutes = Math.floor(safeSeconds / 60);\n  const seconds = (safeSeconds % 60).toFixed(1);\n  return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;\n}\n\nfunction AgentProgress({\n  label = \"Churning\",\n  statusLabel,\n  elapsedSeconds,\n  initialSeconds = 0,\n  running = true,\n  formatElapsed = defaultFormatElapsed,\n  className,\n  ...props\n}: AgentProgressProps) {\n  const reduced = useReducedMotion() ?? false;\n  const [internalSeconds, setInternalSeconds] = React.useState(initialSeconds);\n\n  React.useEffect(() => {\n    if (elapsedSeconds !== undefined || !running) return;\n\n    const startedAt = performance.now() - initialSeconds * 1000;\n    const timer = window.setInterval(() => {\n      setInternalSeconds((performance.now() - startedAt) / 1000);\n    }, 100);\n\n    return () => window.clearInterval(timer);\n  }, [elapsedSeconds, initialSeconds, running]);\n\n  const elapsed = elapsedSeconds ?? internalSeconds;\n\n  return (\n    <span\n      data-slot=\"agent-progress\"\n      role=\"status\"\n      aria-label={statusLabel ?? `${label}, in progress`}\n      className={cn(\n        \"inline-flex items-center gap-3 font-mono text-sm text-muted-foreground\",\n        className\n      )}\n      {...props}\n    >\n      <span\n        data-slot=\"agent-progress-grid\"\n        aria-hidden=\"true\"\n        className=\"grid size-5 shrink-0 grid-cols-3 gap-0.5\"\n      >\n        {GRID_CELLS.map(({ id, delay }) => (\n          <motion.span\n            key={id}\n            className=\"rounded-xs bg-current\"\n            animate={\n              reduced\n                ? { opacity: [0.35, 0.8, 0.35] }\n                : {\n                    opacity: [0.28, 1, 0.28],\n                    scale: [0.72, 1, 0.72],\n                  }\n            }\n            transition={{\n              duration: 1.55,\n              ease: EASE_IN_OUT,\n              repeat: Infinity,\n              delay,\n            }}\n          />\n        ))}\n      </span>\n      <span data-slot=\"agent-progress-label\" className=\"font-sans font-medium\">\n        {label}\n      </span>\n      <span\n        data-slot=\"agent-progress-elapsed\"\n        aria-hidden=\"true\"\n        className=\"tabular-nums text-muted-foreground/70\"\n      >\n        {formatElapsed(elapsed)}\n      </span>\n    </span>\n  );\n}\n\nexport { AgentProgress };\n",
+      "type": "registry:ui",
+      "target": "components/ui/ai-agent-progress.tsx"
+    }
+  ],
+  "type": "registry:ui"
+}

package/templates/registry/ai-approval-card.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "ai-approval-card",
+  "title": "AI Approval Card",
+  "description": "A decision surface: approve, reject or request changes, or step through single-choice, multiple-choice and freeform questions and submit the answers.",
+  "dependencies": [
+    "lucide-react",
+    "motion"
+  ],
+  "registryDependencies": [
+    "@intelligo/ai-motion",
+    "@intelligo/button",
+    "@intelligo/checkbox",
+    "@intelligo/input",
+    "@intelligo/radio-group",
+    "@intelligo/spinner"
+  ],
+  "files": [
+    {
+      "path": "base/ui/ai-approval-card/ai-approval-card.tsx",
+      "content": "\"use client\";\n\n/*\n * A decision surface the agent hands to the user: approve / reject /\n * request changes, or a short run of questions (single choice, multiple\n * choice, freeform) answered one step at a time and submitted together.\n */\n\nimport * as React from \"react\";\nimport {\n  ArrowLeftIcon,\n  ArrowRightIcon,\n  CheckIcon,\n  CircleHelpIcon,\n  MessageSquareTextIcon,\n  XIcon,\n} from \"lucide-react\";\nimport { AnimatePresence, motion, useReducedMotion } from \"motion/react\";\n\nimport {\n  Disclosure,\n  EASE_OUT,\n  SPRING_SWAP,\n  SwapText,\n} from \"@/components/ui/ai-motion\";\nimport { Button } from \"@/components/ui/button\";\nimport { Checkbox } from \"@/components/ui/checkbox\";\nimport { Input } from \"@/components/ui/input\";\nimport { RadioGroup, RadioGroupItem } from \"@/components/ui/radio-group\";\nimport { Spinner } from \"@/components/ui/spinner\";\nimport { cn } from \"@/lib/utils\";\n\nexport type ApprovalCardStatus =\n  | \"pending\"\n  | \"submitting\"\n  | \"approved\"\n  | \"rejected\"\n  | \"changes-requested\"\n  | \"answered\";\n\nexport interface ApprovalCardOption {\n  value: string;\n  label: string;\n  disabled?: boolean;\n}\n\nexport interface ApprovalCardQuestion {\n  id: string;\n  title: React.ReactNode;\n  description?: React.ReactNode;\n  options?: ApprovalCardOption[];\n  /** Several options may be chosen; otherwise a single choice. */\n  multiple?: boolean;\n  /** Move on shortly after a single choice (default true). */\n  autoAdvance?: boolean;\n  /** Offer a freeform answer beside (or instead of) the options. */\n  allowCustom?: boolean;\n  customPlaceholder?: string;\n}\n\nexport interface ApprovalCardAnswer {\n  selected: string[];\n  custom?: string;\n}\n\nexport type ApprovalCardAnswers = Record<string, ApprovalCardAnswer>;\n\nexport interface ApprovalCardProps\n  extends Omit<React.ComponentProps<\"div\">, \"title\" | \"onSubmit\"> {\n  title?: React.ReactNode;\n  description?: React.ReactNode;\n  questions?: ApprovalCardQuestion[];\n  status?: ApprovalCardStatus;\n  answers?: ApprovalCardAnswers;\n  defaultAnswers?: ApprovalCardAnswers;\n  onAnswersChange?: (answers: ApprovalCardAnswers) => void;\n  step?: number;\n  defaultStep?: number;\n  onStepChange?: (step: number) => void;\n  onSubmit?: (answers: ApprovalCardAnswers) => void;\n  onApprove?: () => void;\n  onReject?: () => void;\n  onRequestChanges?: () => void;\n  onDismiss?: () => void;\n  /** What to show once the decision has landed; defaults to the status label. */\n  result?: React.ReactNode;\n  approveLabel?: React.ReactNode;\n  rejectLabel?: React.ReactNode;\n  requestChangesLabel?: React.ReactNode;\n  submitLabel?: React.ReactNode;\n  dismissLabel?: string;\n  previousLabel?: string;\n  nextLabel?: string;\n  customPlaceholder?: string;\n  /** Screen-reader progress, e.g. \"Question 2 of 5\". */\n  progressLabel?: (current: number, total: number) => string;\n  statusLabels?: Partial<Record<ApprovalCardStatus, string>>;\n}\n\nconst EMPTY_ANSWER: ApprovalCardAnswer = { selected: [], custom: \"\" };\n\nconst DEFAULT_STATUS_LABELS: Record<ApprovalCardStatus, string> = {\n  pending: \"Input required\",\n  submitting: \"Submitting\",\n  approved: \"Approved\",\n  rejected: \"Rejected\",\n  \"changes-requested\": \"Changes requested\",\n  answered: \"Response submitted\",\n};\n\nconst ICON_CLASS: Partial<Record<ApprovalCardStatus, string>> = {\n  approved: \"text-success\",\n  answered: \"text-success\",\n  rejected: \"text-destructive\",\n  \"changes-requested\": \"text-warning\",\n};\n\nconst BADGE_CLASS: Record<ApprovalCardStatus, string> = {\n  pending: \"border-warning/30 bg-warning/10 text-warning\",\n  \"changes-requested\": \"border-warning/30 bg-warning/10 text-warning\",\n  submitting: \"border-info/30 bg-info/10 text-info\",\n  approved: \"border-success/30 bg-success/10 text-success\",\n  answered: \"border-success/30 bg-success/10 text-success\",\n  rejected: \"border-destructive/30 bg-destructive/10 text-destructive\",\n};\n\nfunction isAnswered(answer: ApprovalCardAnswer) {\n  return answer.selected.length > 0 || Boolean(answer.custom?.trim());\n}\n\n/* ----------------------------------------------------------------------------\n * One question's controls: checkboxes, radios and/or a freeform input.\n * ------------------------------------------------------------------------- */\n\nconst OPTION_ROW =\n  \"flex min-h-9 items-center gap-3 rounded-lg px-1.5 py-1 text-sm text-foreground select-none\";\n\nfunction OptionRow({\n  disabled,\n  children,\n}: {\n  disabled: boolean;\n  children: React.ReactNode;\n}) {\n  return (\n    <label\n      data-slot=\"approval-card-option\"\n      className={cn(\n        OPTION_ROW,\n        disabled ? \"cursor-not-allowed opacity-60\" : \"cursor-pointer\"\n      )}\n    >\n      {children}\n    </label>\n  );\n}\n\nfunction QuestionOptions({\n  question,\n  answer,\n  disabled,\n  customPlaceholder,\n  onChange,\n  onSingleSelect,\n}: {\n  question: ApprovalCardQuestion;\n  answer: ApprovalCardAnswer;\n  disabled: boolean;\n  customPlaceholder: string;\n  onChange: (answer: ApprovalCardAnswer) => void;\n  onSingleSelect?: () => void;\n}) {\n  const custom = answer.custom ?? \"\";\n\n  return (\n    <div data-slot=\"approval-card-question\" className=\"mt-3\">\n      {question.options?.length ? (\n        question.multiple ? (\n          <div className=\"grid gap-0.5\">\n            {question.options.map((option) => {\n              const rowDisabled = disabled || Boolean(option.disabled);\n              return (\n                <OptionRow key={option.value} disabled={rowDisabled}>\n                  <Checkbox\n                    checked={answer.selected.includes(option.value)}\n                    disabled={rowDisabled}\n                    onCheckedChange={(checked) =>\n                      onChange({\n                        ...answer,\n                        selected: checked\n                          ? [...answer.selected, option.value]\n                          : answer.selected.filter(\n                              (value) => value !== option.value\n                            ),\n                      })\n                    }\n                  />\n                  <span>{option.label}</span>\n                </OptionRow>\n              );\n            })}\n          </div>\n        ) : (\n          <RadioGroup\n            value={answer.selected[0] ?? \"\"}\n            onValueChange={(value) => {\n              onChange({ selected: [String(value)], custom: \"\" });\n              onSingleSelect?.();\n            }}\n            className=\"gap-0.5\"\n          >\n            {question.options.map((option) => {\n              const rowDisabled = disabled || Boolean(option.disabled);\n              return (\n                <OptionRow key={option.value} disabled={rowDisabled}>\n                  <RadioGroupItem value={option.value} disabled={rowDisabled} />\n                  <span>{option.label}</span>\n                </OptionRow>\n              );\n            })}\n          </RadioGroup>\n        )\n      ) : null}\n\n      {question.allowCustom ? (\n        <Input\n          data-slot=\"approval-card-custom\"\n          value={custom}\n          disabled={disabled}\n          placeholder={question.customPlaceholder ?? customPlaceholder}\n          aria-label={question.customPlaceholder ?? customPlaceholder}\n          onChange={(event) =>\n            onChange({\n              selected: question.multiple ? answer.selected : [],\n              custom: event.target.value,\n            })\n          }\n          className={cn(\n            \"h-10 rounded-lg border-0 bg-background/70 px-3 text-sm focus-visible:bg-background\",\n            question.options?.length && \"mt-1.5\"\n          )}\n        />\n      ) : null}\n    </div>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * Progress dots: one per question, the current one full size.\n * ------------------------------------------------------------------------- */\n\nfunction ProgressDots({\n  current,\n  ids,\n  label,\n}: {\n  current: number;\n  ids: string[];\n  label: string;\n}) {\n  const reduced = useReducedMotion() ?? false;\n\n  return (\n    <span data-slot=\"approval-card-progress\" className=\"flex gap-1.5\">\n      <span className=\"sr-only\">{label}</span>\n      {ids.map((id, index) => (\n        <motion.span\n          key={id}\n          aria-hidden=\"true\"\n          initial={false}\n          animate={{\n            scale: reduced ? 1 : index === current ? 1 : 0.75,\n            opacity: index <= current ? 1 : 0.35,\n          }}\n          transition={reduced ? { duration: 0 } : SPRING_SWAP}\n          className=\"size-1.5 rounded-full bg-foreground\"\n        />\n      ))}\n    </span>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * ApprovalCard: the card.\n * ------------------------------------------------------------------------- */\n\nfunction ApprovalCard({\n  title = \"Approval required\",\n  description,\n  children,\n  questions = [],\n  status = \"pending\",\n  answers,\n  defaultAnswers = {},\n  onAnswersChange,\n  step,\n  defaultStep = 0,\n  onStepChange,\n  onSubmit,\n  onApprove,\n  onReject,\n  onRequestChanges,\n  onDismiss,\n  result,\n  approveLabel = \"Approve\",\n  rejectLabel = \"Reject\",\n  requestChangesLabel = \"Request changes\",\n  submitLabel = \"Submit response\",\n  dismissLabel = \"Dismiss\",\n  previousLabel = \"Previous question\",\n  nextLabel = \"Next question\",\n  customPlaceholder = \"Add another response…\",\n  progressLabel = (current, total) => `Question ${current} of ${total}`,\n  statusLabels,\n  className,\n  ...props\n}: ApprovalCardProps) {\n  const reduced = useReducedMotion() ?? false;\n  const [internalAnswers, setInternalAnswers] =\n    React.useState<ApprovalCardAnswers>(defaultAnswers);\n  const [internalStep, setInternalStep] = React.useState(defaultStep);\n  const autoAdvanceTimer = React.useRef<number | undefined>(undefined);\n  const currentAnswers = answers ?? internalAnswers;\n  const currentStep = Math.min(\n    Math.max(0, step ?? internalStep),\n    Math.max(0, questions.length - 1)\n  );\n  const question = questions[currentStep];\n  const questionMode = questions.length > 0;\n  const lastStep = currentStep === questions.length - 1;\n  const pending = status === \"pending\";\n  const busy = status === \"submitting\";\n  const interactive = pending || busy;\n  const currentAnswer = question\n    ? (currentAnswers[question.id] ?? EMPTY_ANSWER)\n    : EMPTY_ANSWER;\n  const displayTitle = question?.title ?? title;\n  const titleKey = question?.id ?? String(status);\n  const statusLabel = statusLabels?.[status] ?? DEFAULT_STATUS_LABELS[status];\n\n  const clearAutoAdvance = React.useCallback(() => {\n    if (autoAdvanceTimer.current === undefined) return;\n    window.clearTimeout(autoAdvanceTimer.current);\n    autoAdvanceTimer.current = undefined;\n  }, []);\n\n  React.useEffect(() => clearAutoAdvance, [clearAutoAdvance]);\n\n  const setAnswers = React.useCallback(\n    (next: ApprovalCardAnswers) => {\n      if (answers === undefined) setInternalAnswers(next);\n      onAnswersChange?.(next);\n    },\n    [answers, onAnswersChange]\n  );\n\n  const setStep = (next: number) => {\n    clearAutoAdvance();\n    if (step === undefined) setInternalStep(next);\n    onStepChange?.(next);\n  };\n\n  const updateCurrentAnswer = (next: ApprovalCardAnswer) => {\n    if (!question) return;\n    setAnswers({ ...currentAnswers, [question.id]: next });\n  };\n\n  const continueQuestion = () => {\n    if (currentStep < questions.length - 1) {\n      setStep(currentStep + 1);\n      return;\n    }\n    onSubmit?.(currentAnswers);\n  };\n\n  // A single choice reads as \"done\"; the next question follows after a beat\n  // so the selection is seen before the panel slides.\n  const queueAutoAdvance = () => {\n    if (\n      !question ||\n      question.multiple ||\n      question.autoAdvance === false ||\n      currentStep >= questions.length - 1 ||\n      busy\n    ) {\n      return;\n    }\n\n    clearAutoAdvance();\n    autoAdvanceTimer.current = window.setTimeout(() => {\n      setStep(currentStep + 1);\n    }, 240);\n  };\n\n  return (\n    <div\n      data-slot=\"approval-card\"\n      data-state={status}\n      aria-busy={busy || undefined}\n      className={cn(\n        \"w-full overflow-hidden rounded-xl bg-muted p-4 text-sm\",\n        className\n      )}\n      {...props}\n    >\n      <div className=\"flex items-start gap-3\">\n        <span\n          data-slot=\"approval-card-icon\"\n          aria-hidden=\"true\"\n          className={cn(\n            \"grid size-5 shrink-0 place-items-center text-muted-foreground\",\n            ICON_CLASS[status]\n          )}\n        >\n          {busy ? (\n            <Spinner className=\"size-4\" />\n          ) : interactive ? (\n            questionMode ? (\n              <CircleHelpIcon className=\"size-4\" />\n            ) : (\n              <MessageSquareTextIcon className=\"size-4\" />\n            )\n          ) : status === \"rejected\" ? (\n            <XIcon className=\"size-4\" />\n          ) : (\n            <CheckIcon className=\"size-4\" />\n          )}\n        </span>\n\n        <div className=\"min-w-0 flex-1\">\n          <div data-slot=\"approval-card-header\" className=\"flex min-w-0 items-start gap-3\">\n            <h3\n              data-slot=\"approval-card-title\"\n              className=\"min-w-0 flex-1 text-base leading-5 font-medium text-foreground\"\n            >\n              <SwapText value={titleKey}>{displayTitle}</SwapText>\n            </h3>\n            {questionMode && interactive ? (\n              <span\n                data-slot=\"approval-card-counter\"\n                className=\"shrink-0 text-xs text-muted-foreground/65 tabular-nums\"\n              >\n                {currentStep + 1}/{questions.length}\n              </span>\n            ) : (\n              <span\n                data-slot=\"approval-card-status\"\n                className={cn(\n                  \"shrink-0 rounded-full border px-2 py-0.5 text-xs font-medium transition-colors\",\n                  BADGE_CLASS[status]\n                )}\n              >\n                {statusLabel}\n              </span>\n            )}\n            {onDismiss ? (\n              <Button\n                type=\"button\"\n                variant=\"ghost\"\n                size=\"icon-xs\"\n                aria-label={dismissLabel}\n                onClick={onDismiss}\n                className=\"-mt-0.5 shrink-0 text-muted-foreground hover:text-foreground\"\n              >\n                <XIcon className=\"size-4\" />\n              </Button>\n            ) : null}\n          </div>\n\n          <Disclosure open={interactive}>\n            {questionMode && question ? (\n              <AnimatePresence initial={false} mode=\"wait\">\n                <motion.div\n                  key={question.id}\n                  data-slot=\"approval-card-step\"\n                  initial={reduced ? { opacity: 1 } : { opacity: 0, x: 8 }}\n                  animate={{ opacity: 1, x: 0 }}\n                  exit={reduced ? { opacity: 0 } : { opacity: 0, x: -6 }}\n                  transition={{ duration: reduced ? 0 : 0.2, ease: EASE_OUT }}\n                >\n                  {question.description ? (\n                    <p className=\"mt-1 leading-5 text-muted-foreground\">\n                      {question.description}\n                    </p>\n                  ) : null}\n                  <QuestionOptions\n                    question={question}\n                    answer={currentAnswer}\n                    disabled={busy}\n                    customPlaceholder={customPlaceholder}\n                    onChange={updateCurrentAnswer}\n                    onSingleSelect={queueAutoAdvance}\n                  />\n                </motion.div>\n              </AnimatePresence>\n            ) : (\n              <div data-slot=\"approval-card-content\">\n                {description ? (\n                  <p className=\"mt-1 leading-5 text-muted-foreground\">\n                    {description}\n                  </p>\n                ) : null}\n                {children ? <div className=\"mt-3\">{children}</div> : null}\n              </div>\n            )}\n\n            {questionMode ? (\n              <div\n                data-slot=\"approval-card-actions\"\n                className=\"mt-4 flex items-center gap-3\"\n              >\n                <Button\n                  type=\"button\"\n                  variant=\"ghost\"\n                  size=\"icon\"\n                  aria-label={previousLabel}\n                  disabled={busy || currentStep === 0}\n                  onClick={() => setStep(currentStep - 1)}\n                >\n                  <ArrowLeftIcon className=\"size-4\" />\n                </Button>\n                <ProgressDots\n                  current={currentStep}\n                  ids={questions.map((item) => item.id)}\n                  label={progressLabel(currentStep + 1, questions.length)}\n                />\n                <Button\n                  type=\"button\"\n                  size={lastStep ? \"sm\" : \"icon\"}\n                  aria-label={lastStep ? undefined : nextLabel}\n                  disabled={busy || !isAnswered(currentAnswer)}\n                  aria-busy={busy || undefined}\n                  onClick={continueQuestion}\n                  className=\"ml-auto\"\n                >\n                  {busy ? (\n                    <Spinner className=\"size-4\" />\n                  ) : lastStep ? (\n                    <>\n                      {submitLabel}\n                      <ArrowRightIcon className=\"size-3.5\" />\n                    </>\n                  ) : (\n                    <ArrowRightIcon className=\"size-4\" />\n                  )}\n                </Button>\n              </div>\n            ) : (\n              <div\n                data-slot=\"approval-card-actions\"\n                className=\"mt-4 flex flex-wrap items-center gap-2\"\n              >\n                <Button\n                  type=\"button\"\n                  size=\"sm\"\n                  disabled={busy}\n                  aria-busy={busy || undefined}\n                  onClick={onApprove}\n                >\n                  {approveLabel}\n                </Button>\n                {onRequestChanges ? (\n                  <Button\n                    type=\"button\"\n                    variant=\"secondary\"\n                    size=\"sm\"\n                    disabled={busy}\n                    onClick={onRequestChanges}\n                  >\n                    {requestChangesLabel}\n                  </Button>\n                ) : null}\n                {onReject ? (\n                  <Button\n                    type=\"button\"\n                    variant=\"ghost\"\n                    size=\"sm\"\n                    disabled={busy}\n                    onClick={onReject}\n                    className=\"text-muted-foreground hover:text-destructive\"\n                  >\n                    {rejectLabel}\n                  </Button>\n                ) : null}\n              </div>\n            )}\n          </Disclosure>\n\n          {!interactive ? (\n            <p\n              data-slot=\"approval-card-result\"\n              className=\"mt-1 text-sm text-muted-foreground\"\n            >\n              {result ?? statusLabel}\n            </p>\n          ) : null}\n        </div>\n      </div>\n    </div>\n  );\n}\n\nexport { ApprovalCard };\n",
+      "type": "registry:ui",
+      "target": "components/ui/ai-approval-card.tsx"
+    }
+  ],
+  "type": "registry:ui"
+}

package/templates/registry/ai-artifact.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "ai-artifact",
+  "title": "AI Artifact",
+  "description": "A generated document's frame: header, actions and content.",
+  "dependencies": [
+    "lucide-react"
+  ],
+  "registryDependencies": [
+    "@intelligo/button",
+    "@intelligo/tooltip"
+  ],
+  "files": [
+    {
+      "path": "base/ui/ai-artifact/ai-artifact.tsx",
+      "content": "\"use client\";\n\nimport * as React from \"react\";\nimport { type LucideIcon, XIcon } from \"lucide-react\";\n\nimport { Button } from \"@/components/ui/button\";\nimport {\n  Tooltip,\n  TooltipContent,\n  TooltipTrigger,\n} from \"@/components/ui/tooltip\";\nimport { cn } from \"@/lib/utils\";\n\nfunction Artifact({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"artifact\"\n      className={cn(\n        \"flex flex-col overflow-hidden rounded-lg border bg-background shadow-sm\",\n        className\n      )}\n      {...props}\n    />\n  );\n}\n\nfunction ArtifactHeader({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"artifact-header\"\n      className={cn(\n        \"flex items-center justify-between gap-2 border-b bg-muted/50 px-4 py-3\",\n        className\n      )}\n      {...props}\n    />\n  );\n}\n\nfunction ArtifactTitle({ className, ...props }: React.ComponentProps<\"p\">) {\n  return (\n    <p\n      data-slot=\"artifact-title\"\n      className={cn(\"text-sm font-medium text-foreground\", className)}\n      {...props}\n    />\n  );\n}\n\nfunction ArtifactDescription({\n  className,\n  ...props\n}: React.ComponentProps<\"p\">) {\n  return (\n    <p\n      data-slot=\"artifact-description\"\n      className={cn(\"text-sm text-muted-foreground\", className)}\n      {...props}\n    />\n  );\n}\n\nfunction ArtifactActions({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"artifact-actions\"\n      className={cn(\"flex items-center gap-1\", className)}\n      {...props}\n    />\n  );\n}\n\nfunction ArtifactClose({\n  label,\n  children,\n  variant = \"ghost\",\n  size = \"icon-sm\",\n  ...props\n}: React.ComponentProps<typeof Button> & {\n  /** Accessible name, e.g. \"Close\". */\n  label: string;\n}) {\n  return (\n    <Button\n      data-slot=\"artifact-close\"\n      aria-label={label}\n      size={size}\n      type=\"button\"\n      variant={variant}\n      {...props}\n    >\n      {children ?? <XIcon />}\n    </Button>\n  );\n}\n\nfunction ArtifactAction({\n  label,\n  tooltip,\n  icon: Icon,\n  children,\n  variant = \"ghost\",\n  size = \"icon-sm\",\n  ...props\n}: React.ComponentProps<typeof Button> & {\n  /** Accessible name. */\n  label: string;\n  /** Shown on hover and focus when given. */\n  tooltip?: string;\n  icon?: LucideIcon;\n}) {\n  const button = (\n    <Button\n      data-slot=\"artifact-action\"\n      aria-label={label}\n      size={size}\n      type=\"button\"\n      variant={variant}\n      {...props}\n    >\n      {Icon ? <Icon /> : children}\n    </Button>\n  );\n\n  if (!tooltip) return button;\n\n  return (\n    <Tooltip>\n      <TooltipTrigger render={button} />\n      <TooltipContent>{tooltip}</TooltipContent>\n    </Tooltip>\n  );\n}\n\nfunction ArtifactContent({ className, ...props }: React.ComponentProps<\"div\">) {\n  return (\n    <div\n      data-slot=\"artifact-content\"\n      className={cn(\"flex-1 overflow-auto p-4\", className)}\n      {...props}\n    />\n  );\n}\n\nexport {\n  Artifact,\n  ArtifactHeader,\n  ArtifactTitle,\n  ArtifactDescription,\n  ArtifactActions,\n  ArtifactClose,\n  ArtifactAction,\n  ArtifactContent,\n};\n",
+      "type": "registry:ui",
+      "target": "components/ui/ai-artifact.tsx"
+    }
+  ],
+  "type": "registry:ui"
+}

package/templates/registry/ai-branch.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "ai-branch",
+  "title": "AI Branch",
+  "description": "A pager over the versions of a reply or an edited message — previous, next, `2 / 3`.",
+  "dependencies": [
+    "lucide-react"
+  ],
+  "registryDependencies": [
+    "@intelligo/button"
+  ],
+  "files": [
+    {
+      "path": "base/ui/ai-branch/ai-branch.tsx",
+      "content": "\"use client\";\n\n/*\n * For a thread that owns which version is on screen: this is a pager over\n * versions the thread keeps, not a component that clones its children per\n * branch.\n */\n\nimport * as React from \"react\";\nimport { ChevronLeftIcon, ChevronRightIcon } from \"lucide-react\";\n\nimport { Button } from \"@/components/ui/button\";\nimport { cn } from \"@/lib/utils\";\n\ntype BranchContextValue = {\n  index: number;\n  count: number;\n  onIndexChange: (index: number) => void;\n};\n\nconst BranchContext = React.createContext<BranchContextValue | null>(null);\n\nfunction useBranch() {\n  const context = React.useContext(BranchContext);\n  if (!context) {\n    throw new Error(\"Branch components must be used within Branch\");\n  }\n  return context;\n}\n\n/**\n * Versions of one reply — or one edited message — with the thread in\n * charge of `index`. Renders nothing when there is only one.\n */\nfunction Branch({\n  index,\n  count,\n  onIndexChange,\n  className,\n  children,\n  ...props\n}: React.ComponentProps<\"div\"> & {\n  /** Zero-based; the version on screen. */\n  index: number;\n  count: number;\n  onIndexChange: (index: number) => void;\n}) {\n  const value = React.useMemo(\n    () => ({ index, count, onIndexChange }),\n    [index, count, onIndexChange]\n  );\n  if (count < 2) return null;\n  return (\n    <BranchContext.Provider value={value}>\n      <div\n        data-slot=\"branch\"\n        className={cn(\"flex items-center gap-0.5\", className)}\n        {...props}\n      >\n        {children}\n      </div>\n    </BranchContext.Provider>\n  );\n}\n\nfunction BranchPrevious({\n  label,\n  className,\n  ...props\n}: Omit<React.ComponentProps<typeof Button>, \"onClick\"> & {\n  /** Accessible name, e.g. \"Previous version\". */\n  label: string;\n}) {\n  const { index, onIndexChange } = useBranch();\n  return (\n    <Button\n      data-slot=\"branch-previous\"\n      type=\"button\"\n      variant=\"ghost\"\n      size=\"icon-xs\"\n      aria-label={label}\n      disabled={index <= 0}\n      onClick={() => onIndexChange(index - 1)}\n      className={cn(\"text-muted-foreground\", className)}\n      {...props}\n    >\n      <ChevronLeftIcon />\n    </Button>\n  );\n}\n\nfunction BranchNext({\n  label,\n  className,\n  ...props\n}: Omit<React.ComponentProps<typeof Button>, \"onClick\"> & {\n  /** Accessible name, e.g. \"Next version\". */\n  label: string;\n}) {\n  const { index, count, onIndexChange } = useBranch();\n  return (\n    <Button\n      data-slot=\"branch-next\"\n      type=\"button\"\n      variant=\"ghost\"\n      size=\"icon-xs\"\n      aria-label={label}\n      disabled={index >= count - 1}\n      onClick={() => onIndexChange(index + 1)}\n      className={cn(\"text-muted-foreground\", className)}\n      {...props}\n    >\n      <ChevronRightIcon />\n    </Button>\n  );\n}\n\n/** \"2 / 3\". Digits only, so it needs no copy. */\nfunction BranchPage({ className, ...props }: React.ComponentProps<\"span\">) {\n  const { index, count } = useBranch();\n  return (\n    <span\n      data-slot=\"branch-page\"\n      className={cn(\n        \"min-w-8 text-center text-xs tabular-nums text-muted-foreground\",\n        className\n      )}\n      aria-live=\"polite\"\n      {...props}\n    >\n      {index + 1} / {count}\n    </span>\n  );\n}\n\nexport { Branch, BranchPrevious, BranchNext, BranchPage, useBranch };\n",
+      "type": "registry:ui",
+      "target": "components/ui/ai-branch.tsx"
+    }
+  ],
+  "type": "registry:ui"
+}

package/templates/registry/ai-citations.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "ai-citations",
+  "title": "AI Citations",
+  "description": "The sources an answer leans on: inline source pills with a hover preview, favicon stacks, a sources sheet and a collapsible reference list.",
+  "dependencies": [
+    "lucide-react",
+    "motion"
+  ],
+  "registryDependencies": [
+    "@intelligo/ai-motion",
+    "hover-card",
+    "@intelligo/sheet"
+  ],
+  "files": [
+    {
+      "path": "base/ui/ai-citations/ai-citations.tsx",
+      "content": "\"use client\";\n\n/*\n * The sources an answer leans on: an inline pill naming the site a claim\n * came from, with a preview on hover; favicon stacks; a sources button\n * that opens the full list in a sheet; and the older numbered marker and\n * collapsible list.\n */\n\nimport * as React from \"react\";\nimport {\n  BookOpenTextIcon,\n  ChevronDownIcon,\n  ExternalLinkIcon,\n  Globe2Icon,\n} from \"lucide-react\";\nimport { AnimatePresence, motion, useReducedMotion } from \"motion/react\";\n\nimport {\n  Disclosure,\n  EASE_OUT,\n  SPRING_LAYOUT,\n  SPRING_SWAP,\n} from \"@/components/ui/ai-motion\";\nimport {\n  HoverCard,\n  HoverCardContent,\n  HoverCardTrigger,\n} from \"@/components/ui/hover-card\";\nimport {\n  Sheet,\n  SheetContent,\n  SheetHeader,\n  SheetTitle,\n  SheetTrigger,\n} from \"@/components/ui/sheet\";\nimport { cn } from \"@/lib/utils\";\n\nexport interface CitationItem {\n  id: string;\n  title: React.ReactNode;\n  /** The site, as shown: `wikipedia.org`. */\n  domain?: string;\n  url?: string;\n  /** A line or two from the page. */\n  snippet?: React.ReactNode;\n}\n\n/** The 10px index badges; the type scale has no step this small. */\nconst TINY_TEXT: React.CSSProperties = { fontSize: \"0.625rem\" };\n\n/* ----------------------------------------------------------------------------\n * Favicons. Resolve a site's conventional `/favicon.ico` and drop it once\n * it is known to be unusable, so a glyph is drawn instead of a broken\n * image. Plenty of sites answer with a 403 or 404, and `onError` is not\n * enough to catch it: an image the browser starts loading from\n * server-rendered HTML usually fails before React attaches a handler, and\n * that event is never replayed. `decode()` settles on the image's final\n * state instead of relying on an event firing at the right moment.\n * ------------------------------------------------------------------------- */\n\nfunction getFaviconUrl(value: string) {\n  try {\n    return new URL(\"/favicon.ico\", value).toString();\n  } catch {\n    return null;\n  }\n}\n\nfunction useFavicon(url?: string) {\n  const resolved = url ? getFaviconUrl(url) : null;\n  const [failedSrc, setFailedSrc] = React.useState<string | null>(null);\n  const src = resolved && resolved !== failedSrc ? resolved : null;\n\n  const ref = React.useCallback(\n    (img: HTMLImageElement | null) => {\n      if (!img || !src) return;\n\n      let released = false;\n      img.decode().catch(() => {\n        if (!released) setFailedSrc(src);\n      });\n\n      // The node is going away or the source changed; a late rejection then\n      // describes an image we are no longer showing.\n      return () => {\n        released = true;\n      };\n    },\n    [src]\n  );\n\n  return { src, ref };\n}\n\nfunction citationTargetId(prefix: string, citationId: string) {\n  return `${prefix}-${citationId.replace(/[^a-zA-Z0-9_-]/g, \"-\")}`;\n}\n\n/** What a citation reads as when it has to be short: its site, else its title. */\nfunction shortName(citation: CitationItem): React.ReactNode {\n  return citation.domain ?? citation.title;\n}\n\n/* ----------------------------------------------------------------------------\n * Citation: the numbered inline marker that jumps to its reference.\n * ------------------------------------------------------------------------- */\n\nexport interface CitationProps\n  extends Omit<React.ComponentProps<\"a\">, \"href\" | \"children\"> {\n  citationId: string;\n  index: number;\n  /** Must match the related Citations idPrefix. */\n  idPrefix: string;\n  /** Assistive-tech name; defaults to \"View citation {index}\". */\n  label?: string;\n}\n\nfunction Citation({\n  citationId,\n  index,\n  idPrefix,\n  label,\n  className,\n  style,\n  ...props\n}: CitationProps) {\n  return (\n    <a\n      data-slot=\"citation\"\n      href={`#${citationTargetId(idPrefix, citationId)}`}\n      aria-label={label ?? `View citation ${index}`}\n      className={cn(\n        \"mx-0.5 inline-flex min-w-4 -translate-y-0.5 items-center justify-center rounded-md bg-muted/60 px-1 py-0.5 font-semibold leading-none text-muted-foreground no-underline outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring\",\n        className\n      )}\n      style={{ ...TINY_TEXT, ...style }}\n      {...props}\n    >\n      {index}\n    </a>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * CitationFavicon and CitationStack.\n * ------------------------------------------------------------------------- */\n\nfunction CitationFavicon({\n  url,\n  domain,\n  className,\n}: {\n  url?: string;\n  /** Used when there is no url to read the site from. */\n  domain?: string;\n  className?: string;\n}) {\n  const favicon = useFavicon(url ?? (domain ? `https://${domain}` : undefined));\n\n  return (\n    <span\n      data-slot=\"citation-favicon\"\n      aria-hidden=\"true\"\n      className={cn(\n        \"grid size-5 shrink-0 place-items-center text-muted-foreground\",\n        className\n      )}\n    >\n      {favicon.src ? (\n        // Dynamic cross-site favicons: a plain img keeps the item portable.\n        <img\n          ref={favicon.ref}\n          src={favicon.src}\n          alt=\"\"\n          width={16}\n          height={16}\n          referrerPolicy=\"no-referrer\"\n          className=\"size-4 rounded-sm object-contain\"\n        />\n      ) : (\n        <Globe2Icon className=\"size-3.5\" />\n      )}\n    </span>\n  );\n}\n\nexport interface CitationStackProps {\n  citations: CitationItem[];\n  limit?: number;\n  className?: string;\n}\n\nfunction CitationStack({ citations, limit = 3, className }: CitationStackProps) {\n  return (\n    <span\n      data-slot=\"citation-stack\"\n      aria-hidden=\"true\"\n      className={cn(\"flex -space-x-1.5\", className)}\n    >\n      {citations.slice(0, limit).map((citation) => (\n        <CitationFavicon\n          key={citation.id}\n          url={citation.url}\n          domain={citation.domain}\n          className=\"size-6 rounded-full bg-background ring-2 ring-background\"\n        />\n      ))}\n    </span>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * CitationCard: one source, read at a glance — site, title, snippet.\n * ------------------------------------------------------------------------- */\n\nfunction CitationCard({\n  citation,\n  index,\n  className,\n}: {\n  citation: CitationItem;\n  index?: number;\n  className?: string;\n}) {\n  const content = (\n    <>\n      <span className=\"flex min-w-0 items-center gap-1.5 text-xs text-muted-foreground\">\n        <CitationFavicon\n          url={citation.url}\n          domain={citation.domain}\n          className=\"size-4 [&_img]:size-3.5 [&_svg]:size-3\"\n        />\n        <span className=\"min-w-0 truncate\">{shortName(citation)}</span>\n        {index !== undefined ? (\n          <span\n            className=\"ml-auto grid size-4 shrink-0 place-items-center rounded bg-foreground/5 font-semibold tabular-nums\"\n            style={TINY_TEXT}\n          >\n            {index}\n          </span>\n        ) : null}\n      </span>\n      {citation.domain && citation.title !== citation.domain ? (\n        <span className=\"line-clamp-2 text-sm leading-5 font-medium text-foreground\">\n          {citation.title}\n        </span>\n      ) : null}\n      {citation.snippet ? (\n        <span className=\"line-clamp-2 text-xs leading-4 text-muted-foreground\">\n          {citation.snippet}\n        </span>\n      ) : null}\n    </>\n  );\n  const classes = cn(\n    \"grid gap-1 rounded-md p-2 text-left outline-none transition-colors\",\n    citation.url && \"hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring\",\n    className\n  );\n\n  return citation.url ? (\n    <a\n      data-slot=\"citation-card\"\n      href={citation.url}\n      target=\"_blank\"\n      rel=\"noreferrer noopener\"\n      className={classes}\n    >\n      {content}\n    </a>\n  ) : (\n    <div data-slot=\"citation-card\" className={classes}>\n      {content}\n    </div>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * CitationPill: the inline source — `wikipedia.org +2` — with the sources\n * it stands for on hover. Clicking it opens the first source.\n * ------------------------------------------------------------------------- */\n\nexport interface CitationPillProps {\n  /** The sources this claim cites, in order; the first names the pill. */\n  citations: CitationItem[];\n  /** Assistive-tech name, e.g. \"Source: wikipedia.org\". */\n  label?: string;\n  className?: string;\n}\n\nfunction CitationPill({ citations, label, className }: CitationPillProps) {\n  const [first, ...rest] = citations;\n  if (!first) return null;\n\n  const pillClass = cn(\n    \"mx-0.5 inline-flex max-w-44 -translate-y-px items-center gap-1 rounded-full bg-muted px-1.5 align-middle text-xs leading-5 font-medium text-muted-foreground no-underline! outline-none transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:ring-2 focus-visible:ring-ring\",\n    className\n  );\n  const pill = (\n    <>\n      <CitationFavicon\n        url={first.url}\n        domain={first.domain}\n        className=\"size-3.5 [&_img]:size-3 [&_svg]:size-3\"\n      />\n      <span className=\"min-w-0 truncate\">{shortName(first)}</span>\n      {rest.length > 0 ? (\n        <span className=\"shrink-0 tabular-nums opacity-70\">+{rest.length}</span>\n      ) : null}\n    </>\n  );\n\n  return (\n    <HoverCard>\n      <HoverCardTrigger\n        data-slot=\"citation-pill\"\n        delay={150}\n        aria-label={label}\n        className={pillClass}\n        render={\n          first.url ? (\n            <a href={first.url} target=\"_blank\" rel=\"noreferrer noopener\" />\n          ) : (\n            <span tabIndex={0} />\n          )\n        }\n      >\n        {pill}\n      </HoverCardTrigger>\n      <HoverCardContent side=\"top\" align=\"start\" className=\"grid w-80 gap-0.5 p-1\">\n        {citations.map((citation) => (\n          <CitationCard key={citation.id} citation={citation} />\n        ))}\n      </HoverCardContent>\n    </HoverCard>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * CitationSources: the favicons and a count under an answer; the full\n * list opens in a sheet beside it.\n * ------------------------------------------------------------------------- */\n\nexport interface CitationSourcesProps {\n  citations: CitationItem[];\n  /** The button's text, e.g. \"5 sources\". */\n  label: React.ReactNode;\n  /** The sheet's heading, e.g. \"Sources\". */\n  title: React.ReactNode;\n  className?: string;\n}\n\nfunction CitationSources({\n  citations,\n  label,\n  title,\n  className,\n}: CitationSourcesProps) {\n  if (citations.length === 0) return null;\n\n  return (\n    <Sheet>\n      <SheetTrigger\n        data-slot=\"citation-sources\"\n        render={<button type=\"button\" />}\n        className={cn(\n          \"inline-flex h-8 w-fit items-center gap-2 rounded-full border bg-background py-1 pr-3 pl-1 text-sm text-muted-foreground outline-none transition-colors hover:bg-muted hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring\",\n          className\n        )}\n      >\n        <CitationStack citations={citations} className=\"[&>span]:size-5.5\" />\n        <span className=\"font-medium\">{label}</span>\n      </SheetTrigger>\n      <SheetContent side=\"right\" className=\"w-full gap-0 p-0 sm:max-w-md\">\n        <SheetHeader className=\"border-b pr-12\">\n          <SheetTitle>{title}</SheetTitle>\n        </SheetHeader>\n        <div className=\"grid min-h-0 flex-1 content-start gap-0.5 overflow-y-auto p-2\">\n          {citations.map((citation) => (\n            <CitationCard\n              key={citation.id}\n              citation={citation}\n              index={Number.isNaN(Number(citation.id)) ? undefined : Number(citation.id)}\n              className=\"p-2.5\"\n            />\n          ))}\n        </div>\n      </SheetContent>\n    </Sheet>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * CitationList: the numbered references.\n * ------------------------------------------------------------------------- */\n\nfunction CitationRow({\n  citation,\n  index,\n  idPrefix,\n}: {\n  citation: CitationItem;\n  index: number;\n  idPrefix: string;\n}) {\n  const content = (\n    <>\n      <CitationFavicon url={citation.url} domain={citation.domain} />\n      <span className=\"flex min-w-0 flex-1 flex-wrap items-baseline gap-x-2 gap-y-0.5\">\n        <span className=\"truncate text-sm font-medium text-foreground/80 transition-colors group-hover/citation:text-foreground\">\n          {citation.title}\n        </span>\n        {citation.domain ? (\n          <span className=\"min-w-0 truncate text-xs text-muted-foreground/60\">\n            {citation.domain}\n          </span>\n        ) : null}\n      </span>\n      <span className=\"flex shrink-0 items-center gap-1.5\">\n        <span\n          className=\"grid size-5 place-items-center rounded-md bg-foreground/5 font-semibold tabular-nums text-muted-foreground\"\n          style={TINY_TEXT}\n        >\n          {index}\n        </span>\n        {citation.url ? (\n          <ExternalLinkIcon className=\"size-3.5 text-muted-foreground/40 transition-colors group-hover/citation:text-muted-foreground\" />\n        ) : null}\n      </span>\n    </>\n  );\n  const className =\n    \"group/citation flex items-center gap-2 rounded-md px-1.5 py-1 outline-none focus-visible:ring-2 focus-visible:ring-ring\";\n  const id = citationTargetId(idPrefix, citation.id);\n\n  return citation.url ? (\n    <a\n      data-slot=\"citation-row\"\n      id={id}\n      href={citation.url}\n      target=\"_blank\"\n      rel=\"noreferrer noopener\"\n      className={className}\n    >\n      {content}\n    </a>\n  ) : (\n    <div data-slot=\"citation-row\" id={id} className={className}>\n      {content}\n    </div>\n  );\n}\n\nexport interface CitationListProps {\n  citations: CitationItem[];\n  idPrefix?: string;\n  className?: string;\n}\n\nfunction CitationList({ citations, idPrefix, className }: CitationListProps) {\n  const reduced = useReducedMotion() ?? false;\n  const baseId = React.useId();\n  const resolvedPrefix =\n    idPrefix ?? `citation-list-${baseId.replace(/:/g, \"\")}`;\n\n  return (\n    <div data-slot=\"citation-list\" className={cn(\"grid gap-0.5\", className)}>\n      <AnimatePresence mode=\"popLayout\">\n        {citations.map((citation, index) => (\n          <motion.div\n            layout=\"position\"\n            key={citation.id}\n            initial={reduced ? { opacity: 1 } : { opacity: 0, y: 6 }}\n            animate={{ opacity: 1, y: 0 }}\n            exit={reduced ? { opacity: 0 } : { opacity: 0, y: -3 }}\n            transition={\n              reduced\n                ? { duration: 0 }\n                : {\n                    opacity: { duration: 0.18, ease: EASE_OUT },\n                    y: SPRING_LAYOUT,\n                    layout: SPRING_LAYOUT,\n                  }\n            }\n          >\n            <CitationRow\n              citation={citation}\n              index={index + 1}\n              idPrefix={resolvedPrefix}\n            />\n          </motion.div>\n        ))}\n      </AnimatePresence>\n    </div>\n  );\n}\n\n/* ----------------------------------------------------------------------------\n * Citations: the collapsible reference collection.\n * ------------------------------------------------------------------------- */\n\nexport interface CitationsProps {\n  citations: CitationItem[];\n  title?: React.ReactNode;\n  open?: boolean;\n  defaultOpen?: boolean;\n  onOpenChange?: (open: boolean) => void;\n  idPrefix?: string;\n  className?: string;\n}\n\nfunction Citations({\n  citations,\n  title = \"Sources\",\n  open,\n  defaultOpen = false,\n  onOpenChange,\n  idPrefix,\n  className,\n}: CitationsProps) {\n  const reduced = useReducedMotion() ?? false;\n  const baseId = React.useId();\n  const contentId = `${baseId}-content`;\n  const resolvedPrefix = idPrefix ?? `citation-${baseId.replace(/:/g, \"\")}`;\n  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);\n  const currentOpen = open ?? internalOpen;\n  const setOpen = React.useCallback(\n    (next: boolean) => {\n      if (open === undefined) setInternalOpen(next);\n      onOpenChange?.(next);\n    },\n    [onOpenChange, open]\n  );\n\n  return (\n    <div\n      data-slot=\"citations\"\n      data-state={currentOpen ? \"open\" : \"closed\"}\n      className={cn(\"w-full text-sm\", className)}\n    >\n      <button\n        data-slot=\"citations-trigger\"\n        type=\"button\"\n        aria-expanded={currentOpen}\n        aria-controls={contentId}\n        onClick={() => setOpen(!currentOpen)}\n        className=\"group -ml-1 flex min-h-8 items-center gap-2 rounded-lg px-1 text-left text-muted-foreground outline-none transition-colors hover:text-foreground focus-visible:ring-2 focus-visible:ring-ring\"\n      >\n        <BookOpenTextIcon className=\"size-4\" />\n        <span className=\"font-medium\">{title}</span>\n        <span\n          className=\"rounded-full bg-muted px-1.5 py-0.5 font-semibold tabular-nums\"\n          style={TINY_TEXT}\n        >\n          {citations.length}\n        </span>\n        <motion.span\n          aria-hidden=\"true\"\n          animate={{ rotate: currentOpen ? 180 : 0 }}\n          transition={reduced ? { duration: 0 } : SPRING_SWAP}\n          className=\"text-muted-foreground/60\"\n        >\n          <ChevronDownIcon className=\"size-3.5\" />\n        </motion.span>\n      </button>\n\n      <Disclosure id={contentId} open={currentOpen}>\n        <CitationList\n          citations={citations}\n          idPrefix={resolvedPrefix}\n          className=\"mt-1\"\n        />\n      </Disclosure>\n    </div>\n  );\n}\n\nexport {\n  Citation,\n  CitationCard,\n  CitationFavicon,\n  CitationList,\n  CitationPill,\n  Citations,\n  CitationSources,\n  CitationStack,\n};\n",
+      "type": "registry:ui",
+      "target": "components/ui/ai-citations.tsx"
+    }
+  ],
+  "type": "registry:ui"
+}