@hex-core/components 1.9.0 → 1.10.0

package/dist/schemas.js

@@ -6147,7 +6147,7 @@ var citationSchema = {
 var markdownSchema = {
   name: "markdown",
   displayName: "Markdown",
-  description: "Streaming-safe markdown renderer wrapping Vercel's streamdown. Handles partial input mid-stream without throwing.",
+  description: "Streaming-safe markdown renderer with AI-aware element slots. Native pipeline (react-markdown + remark-gfm + rehype-raw + rehype-sanitize) with slot wiring for fenced code, footnote citations, tool-call elements, and [!think] admonitions.",
   category: "ai",
   subcategory: "content",
   props: [
@@ -6174,11 +6174,17 @@ var markdownSchema = {
     }
   ],
   dependencies: {
-    npm: ["streamdown", "clsx", "tailwind-merge"],
-    internal: ["lib/utils"],
+    npm: ["react-markdown", "remark-gfm", "rehype-raw", "rehype-sanitize", "unist-util-visit", "clsx", "tailwind-merge"],
+    internal: [
+      "lib/utils",
+      "components/inline-citation/inline-citation",
+      "components/sources/sources",
+      "components/tool-call/tool-call",
+      "components/reasoning/reasoning"
+    ],
     peer: ["react", "react-dom"]
   },
-  tokensUsed: ["foreground", "primary"],
+  tokensUsed: ["foreground", "primary", "muted", "muted-foreground", "border"],
   examples: [
     {
       title: "Streaming assistant turn",
@@ -6187,25 +6193,45 @@ var markdownSchema = {
       composition: ["chat", "streaming", "markdown"]
     },
     {
-      title: "Custom rendering: drop down to Streamdown",
-      description: "For per-element overrides, use streamdown directly with our CodeBlock primitive.",
-      code: 'import { Streamdown } from "streamdown";\nimport { CodeBlock } from "@hex-core/components";\n\n<Streamdown components={{ pre: ({ children }) => <CodeBlock code={extractCode(children)} /> }}>\n  {markdown}\n</Streamdown>',
-      composition: ["chat", "code", "override"]
+      title: "Fenced code preserves the language class",
+      description: 'Triple-backtick fences render as `<pre><code class="language-ts">` so consumer-side highlighters (or Tailwind Typography styles) can target them. For server-side Shiki highlighting in an RSC tree, compose `<CodeBlock>` separately \u2014 Markdown stays client-safe so it works mid-stream.',
+      code: 'const md = "```ts\\nconst x = 1;\\n```";\n<Markdown>{md}</Markdown>',
+      composition: ["chat", "code"]
+    },
+    {
+      title: "Footnote-style links route to Citation",
+      description: "Link text matching `[N]` with a URL renders as a citation chip with the index preserved.",
+      code: 'const md = "[1](https://anthropic.com/research) [2](https://openai.com)";\n<Markdown>{md}</Markdown>',
+      composition: ["rag", "citations"]
+    },
+    {
+      title: "[!think] admonition routes to Reasoning",
+      description: "GitHub-style admonition blockquotes wrap the body in the in-house Reasoning primitive.",
+      code: 'const md = "> [!think]\\n> Let me work through the steps.";\n<Markdown>{md}</Markdown>',
+      composition: ["chat", "reasoning"]
+    },
+    {
+      title: "<tool-call> element routes to ToolCall",
+      description: "The custom tool-call element survives sanitize and wires to the ToolCall primitive with name/state/args/result.",
+      code: `const md = \`<tool-call name="searchDocs" state="result" args='{"q":"x"}' result='{"hits":3}' />\`;
+<Markdown>{md}</Markdown>`,
+      composition: ["chat", "tool-use"]
     }
   ],
   ai: {
-    whenToUse: "Render any markdown content from an LLM \u2014 assistant turns, system messages with formatting, RAG citations with inline links. Required for streaming because raw markdown parsers throw on unfinished input.",
-    whenNotToUse: "Don't use for plain text without formatting (just render the string). Don't bypass it for streamed content \u2014 partial input WILL break a non-streaming parser.",
+    whenToUse: "Render any markdown content from an LLM \u2014 assistant turns, system messages with formatting, RAG citations with inline links, tool-call placeholders, [!think] reasoning traces. Required for streaming because raw markdown parsers throw on unfinished input.",
+    whenNotToUse: "Don't use for plain text without formatting (just render the string). Don't bypass it for streamed content \u2014 partial input WILL break a non-streaming parser. Don't compose Markdown inside Markdown.",
     commonMistakes: [
       "Passing JSX children instead of a markdown string \u2014 Markdown only accepts strings",
-      "Trying to override per-element renderers via Markdown \u2014 drop down to `Streamdown` directly for that (we keep our public surface minimal so the DTS bundle doesn't drag in shiki's giant language union)",
-      "Forgetting Tailwind Typography (`prose`) classes are required to style the output"
+      "Forgetting Tailwind Typography (`prose`) classes are required to style the output",
+      "Reaching for an `overrides` / `components` prop \u2014 slot wiring is built in (fenced code, footnotes, <tool-call>, [!think]); compose those primitives instead of overriding renderers",
+      "Embedding JSON in <tool-call> attrs without quoting the value (use single-quoted args/result so embedded double quotes survive HTML parsing)"
     ],
-    relatedComponents: ["message", "code-block", "citation"],
-    accessibilityNotes: "Inherits semantics from streamdown: real headings, lists, links. Verify Tailwind Typography (prose) is enabled in your CSS \u2014 without it, output renders unstyled.",
-    tokenBudget: 280
+    relatedComponents: ["message", "code-block", "citation", "inline-citation", "sources", "tool-call", "reasoning"],
+    accessibilityNotes: "Renders real semantic HTML (headings, lists, links, blockquotes). Verify Tailwind Typography (`prose`) is enabled in your CSS. Slot wiring preserves a11y semantics: Reasoning ships its own collapsible disclosure, Citation ships an inline link with a labeled index, ToolCall ships a labeled status region.",
+    tokenBudget: 320
   },
-  tags: ["ai", "markdown", "streaming", "content", "renderer"]
+  tags: ["ai", "markdown", "streaming", "content", "renderer", "slots"]
 };
 
 // src/ai/code-block/code-block.schema.ts
@@ -6286,6 +6312,737 @@ var codeBlockSchema = {
   tags: ["ai", "code", "shiki", "highlight", "copy", "rsc"]
 };
 
+// src/ai/sources/sources.schema.ts
+var sourcesSchema = {
+  name: "sources",
+  displayName: "Sources",
+  description: "Bordered card listing 1\u2013N citation chips for a RAG response. Re-uses Citation per row inside a Radix Collapsible so consumers can collapse the list when the response references many sources.",
+  category: "ai",
+  subcategory: "rag",
+  props: [
+    {
+      name: "sources",
+      type: "object",
+      required: true,
+      description: "Array of `SourceRef` objects ({ title: string; url?: string; page?: number }). Each becomes a Citation chip."
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Whether the list is expanded by default."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-collapsible", "clsx", "tailwind-merge"],
+    internal: ["lib/utils", "components/citation/citation"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "border", "muted-foreground", "foreground", "ring"],
+  examples: [
+    {
+      title: "RAG response sources",
+      description: "Three retrieved sources for a question about auth.",
+      code: 'const refs = [\n  { title: "Auth research", url: "https://example.com/auth", page: 3 },\n  { title: "OAuth 2.1 spec", url: "https://oauth.net/2.1" },\n  { title: "Internal RFC #42", url: "https://example.com/rfc-42" },\n];\n<Sources sources={refs} />',
+      composition: ["rag", "citations", "sources"]
+    },
+    {
+      title: "Streamed via <sources> markdown element",
+      description: "Render an LLM response that emits <sources data='[\u2026]' /> via the Markdown slot wiring.",
+      code: 'const md = `<sources data=\'[{"title":"Auth research","url":"https://example.com/auth","page":3}]\' />`;\n<Markdown>{md}</Markdown>',
+      composition: ["chat", "rag", "streaming"]
+    }
+  ],
+  ai: {
+    whenToUse: "At the bottom of a RAG-style assistant response, listing every source the model cited. Pair with InlineCitation in the body text so the inline refs and the bottom-of-card list reference the same sources by index.",
+    whenNotToUse: "Don't use for a single-source attribution (drop in a plain Citation). Don't use as navigation \u2014 Sources is reference-only; for query history use a sidebar or breadcrumb.",
+    commonMistakes: [
+      "Passing strings instead of `{ title, url? }` objects in the `sources` array",
+      "Composing inline citations with `Citation` (block-level) when `InlineCitation` (inline + hover popover) is the right choice",
+      "Setting `defaultOpen={false}` on a chat surface \u2014 users miss provenance information by default",
+      "Embedding raw URLs as titles (use the source's display name; URL hostname is a fallback Citation already provides)"
+    ],
+    relatedComponents: ["citation", "inline-citation", "markdown", "message"],
+    accessibilityNotes: "Wraps Radix Collapsible \u2014 the trigger is a real <button> with aria-expanded; content gets aria-hidden when closed. Each Citation chip is keyboard-focusable when its url is set.",
+    tokenBudget: 240
+  },
+  tags: ["ai", "rag", "citations", "sources", "collapsible"]
+};
+
+// src/ai/inline-citation/inline-citation.schema.ts
+var inlineCitationSchema = {
+  name: "inline-citation",
+  displayName: "InlineCitation",
+  description: "Inline footnote-style reference with a hover-preview popover. Pairs with Sources for the bottom-of-card list; fills the inline-text gap that the block Citation chip can't.",
+  category: "ai",
+  subcategory: "rag",
+  props: [
+    {
+      name: "index",
+      type: "number",
+      required: true,
+      description: "Footnote number (1-based). Renders inside the visible <sup>."
+    },
+    {
+      name: "title",
+      type: "string",
+      required: true,
+      description: "Source title shown in the hover preview."
+    },
+    {
+      name: "url",
+      type: "string",
+      required: false,
+      description: "Optional URL \u2014 when set, the trigger becomes a focusable anchor."
+    },
+    {
+      name: "excerpt",
+      type: "string",
+      required: false,
+      description: "Optional excerpt or context shown under the title in the preview."
+    },
+    {
+      name: "openDelay",
+      type: "number",
+      required: false,
+      default: 200,
+      description: "Hover open delay in ms."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the trigger."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-hover-card", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["primary", "popover", "popover-foreground", "border", "muted-foreground", "foreground", "ring"],
+  examples: [
+    {
+      title: "Inline reference in a sentence",
+      description: "Drop a citation in the middle of an assistant turn.",
+      code: '<p>\n  The frontier models all publish reasoning evals\n  <InlineCitation\n    index={1}\n    title="Anthropic \u2014 Claude Sonnet 4.5"\n    url="https://anthropic.com/claude"\n  />.\n</p>',
+      composition: ["chat", "rag", "inline"]
+    },
+    {
+      title: "Pair with Sources for the bottom-of-card list",
+      description: "Same source surfaces inline AND in the sources panel \u2014 same index in both places.",
+      code: 'const refs = [\n  { title: "Auth research", url: "https://example.com/auth", page: 3 },\n];\n<>\n  <p>Studies on this <InlineCitation index={1} title={refs[0].title} url={refs[0].url} /> agree.</p>\n  <Sources sources={refs} />\n</>',
+      composition: ["rag", "citations", "sources"]
+    },
+    {
+      title: "Streamed via Markdown [N](url) shape",
+      description: "Markdown's footnote-style link slot routes [1](url) to InlineCitation automatically.",
+      code: 'const md = "Reasoning quality scales [1](https://anthropic.com/research) with compute.";\n<Markdown>{md}</Markdown>',
+      composition: ["chat", "streaming", "markdown"]
+    }
+  ],
+  ai: {
+    whenToUse: "In the body of an assistant message when you want to reference a source mid-sentence without breaking flow. Pair with Sources at the end of the message to give the user a scannable list.",
+    whenNotToUse: "Don't use as a primary navigation element (it's a reference, not a link). Don't use for a single source attribution at the end of a message \u2014 just use Citation instead.",
+    commonMistakes: [
+      "Using `<Citation index={...}>` for inline references \u2014 that's the block-level chip; use InlineCitation for inline-text refs",
+      "Mismatched `index` between the inline ref and the corresponding row in the Sources panel \u2014 keep them aligned",
+      "Setting `openDelay={0}` \u2014 the hover popover triggers on accidental mouseover and feels noisy; the 200ms default keeps a calm hover cadence",
+      "Missing `url` AND missing `excerpt` \u2014 leaves the popover with just a title; provide one of the two for context"
+    ],
+    relatedComponents: ["citation", "sources", "markdown", "message"],
+    accessibilityNotes: "Wraps Radix HoverCard. The trigger is a real anchor (with `url`) or button; both carry an `aria-label` exposing the index + title to screen readers and are in the keyboard tab order. HoverCard content opens on focus AND hover so keyboard users get the same preview.",
+    tokenBudget: 200
+  },
+  tags: ["ai", "rag", "citations", "inline", "popover", "footnote"]
+};
+
+// src/ai/task/task.schema.ts
+var taskSchema = {
+  name: "task",
+  displayName: "Task",
+  description: "Multi-step task progress card. Each step's state re-uses the canonical ToolCallState vocabulary; the header tracks aggregate progress.",
+  category: "ai",
+  subcategory: "agent",
+  props: [
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      description: "Optional title shown above the step list."
+    },
+    {
+      name: "steps",
+      type: "object",
+      required: true,
+      description: "Array of `TaskStep` objects ({ id: string; label: string; state: ToolCallState; detail?: string }). State enum matches ToolCall: pending / running / result / error."
+    },
+    {
+      name: "durationMs",
+      type: "number",
+      required: false,
+      description: "Total time spent on the task. Renders 'Done in X.Xs' when all steps complete."
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: true,
+      description: "Whether the step list is expanded by default."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["@radix-ui/react-collapsible", "clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "border", "muted", "muted-foreground", "foreground", "primary", "destructive", "ring"],
+  examples: [
+    {
+      title: "Refactor task in progress",
+      description: "Three steps \u2014 first is done, second is running, third is pending.",
+      code: 'const steps = [\n  { id: "read", label: "Read existing auth", state: "result" },\n  { id: "write", label: "Apply changes", state: "running" },\n  { id: "test", label: "Run tests", state: "pending" },\n];\n<Task label="Refactoring auth" steps={steps} />',
+      composition: ["agent", "task", "progress"]
+    },
+    {
+      title: "Completed task with duration",
+      description: "All steps done; header shows total time.",
+      code: 'const steps = [\n  { id: "a", label: "Plan", state: "result" },\n  { id: "b", label: "Apply", state: "result" },\n  { id: "c", label: "Verify", state: "result" },\n];\n<Task label="Migrate users table" steps={steps} durationMs={12_400} />',
+      composition: ["agent", "task", "complete"]
+    },
+    {
+      title: "Compose with Reasoning per step",
+      description: "Wrap a step's detail prop with Reasoning when the model wants to expose a thinking trace inline.",
+      code: 'const steps = [\n  { id: "plan", label: "Plan migration", state: "result", detail: "Identified 4 tables, 2 with existing indexes." },\n];\n<Task steps={steps} />',
+      composition: ["agent", "task", "reasoning"]
+    }
+  ],
+  ai: {
+    whenToUse: "To show an agent's multi-step plan execution. Each step should map to a discrete unit of work the model claims it's doing \u2014 read, write, run, verify. Pair with ToolCall when a step actually invokes a tool, and Reasoning when the step exposes thinking.",
+    whenNotToUse: "Don't use for a flat list of facts (use a real list). Don't use for a single-step operation (just render the result directly). Don't use as a navigation surface \u2014 it's a status display, not an interactive component.",
+    commonMistakes: [
+      "Mixing `state` strings \u2014 use the canonical `ToolCallState` (`pending` / `running` / `result` / `error`); novel states like 'in-progress' or 'finished' will render with the pending icon",
+      "Setting all steps to `pending` upfront and never updating \u2014 the component is a status display, not a planner; consumers must update step state as the agent progresses",
+      "Using `Task` for stateful wizard flows (use `Stepper` instead \u2014 Stepper is interactive, Task is read-only)",
+      "Putting agent reasoning in `step.label` \u2014 keep labels short; put thinking in `step.detail` or compose Reasoning separately"
+    ],
+    relatedComponents: ["tool-call", "reasoning", "stepper", "message"],
+    accessibilityNotes: "Wraps Radix Collapsible \u2014 trigger is a real <button> with aria-expanded; content gets aria-hidden when closed. Each step icon carries an aria-label so screen readers announce status (e.g. 'Done', 'Running', 'Error', 'Pending'). The 'running' spinner is gated on `motion-safe:` \u2014 users with `prefers-reduced-motion: reduce` see a static circle.",
+    tokenBudget: 280
+  },
+  tags: ["ai", "agent", "task", "progress", "collapsible", "tool-use"]
+};
+
+// src/ai/shimmer/shimmer.schema.ts
+var shimmerSchema = {
+  name: "shimmer",
+  displayName: "Shimmer",
+  description: "Single-line streaming placeholder. Used during the dead-time between user submission and first stream token. Renders a motion-safe pulsing bar (Tailwind animate-pulse) that gates on `prefers-reduced-motion`.",
+  category: "ai",
+  subcategory: "feedback",
+  props: [
+    {
+      name: "width",
+      type: "string",
+      required: false,
+      default: "100%",
+      description: "CSS width \u2014 accepts any width value."
+    },
+    {
+      name: "height",
+      type: "string",
+      required: false,
+      default: "1.5rem",
+      description: "CSS height \u2014 defaults to a single line."
+    },
+    {
+      name: "durationMs",
+      type: "number",
+      required: false,
+      default: 1500,
+      description: "Sweep cycle duration in milliseconds."
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      default: "Loading\u2026",
+      description: "Accessible label announced to screen readers."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "foreground"],
+  examples: [
+    {
+      title: "Streaming placeholder before first token",
+      description: "Shows up between user submit and first model token; replaces with the streaming Markdown once tokens arrive.",
+      code: '{isStreaming && firstTokenAt === null ? <Shimmer width="80%" /> : null}',
+      composition: ["chat", "streaming", "loading"]
+    },
+    {
+      title: "Compose with MessageList for the assistant placeholder row",
+      description: "Render a Shimmer inside a Message while waiting for the first chunk.",
+      code: '<MessageList>\n  {messages.map((m) => <Message key={m.id} role={m.role}>{m.content}</Message>)}\n  {isStreaming ? (\n    <Message role="assistant"><Shimmer width="60%" /></Message>\n  ) : null}\n</MessageList>',
+      composition: ["chat", "streaming"]
+    }
+  ],
+  ai: {
+    whenToUse: "In the conversation pane during the dead-time between a user prompt submission and the first streaming token. Pair with Message so the placeholder occupies the same visual slot the streamed content will land in.",
+    whenNotToUse: "Don't use for whole-screen loading (use Loading). Don't use for arbitrary skeleton shapes (use Skeleton). Don't use after the first token has arrived \u2014 once the model is streaming, render the partial content directly.",
+    commonMistakes: [
+      "Showing Shimmer through the entire response \u2014 once the first token arrives, swap to a Markdown render of the partial buffer",
+      "Sizing the bar too short (width < 30%) \u2014 the sweep cycle becomes visually jittery; keep at ~60\u201380% of message-row width",
+      "Using Shimmer for a whole-card placeholder (use Skeleton or Loading)",
+      "Setting `durationMs` < 800 \u2014 feels nervous; the 1500ms default matches a calm waiting cadence"
+    ],
+    relatedComponents: ["loading", "loading-indicator", "skeleton", "message"],
+    accessibilityNotes: 'Renders with `role="status"` and `aria-live="polite"`, so screen readers announce the loading label without preempting other content. The pulse animation is gated on `motion-safe:` \u2014 users with `prefers-reduced-motion: reduce` see a static bar rather than the pulsing one.',
+    tokenBudget: 160
+  },
+  tags: ["ai", "loading", "streaming", "placeholder", "feedback"]
+};
+
+// src/ai/branch/branch.schema.ts
+var branchSchema = {
+  name: "branch",
+  displayName: "Branch",
+  description: "Headless alternate-response navigator. Renders one active branch with a prev/next control chip beneath it. Stateless \u2014 consumer owns `current` and `total`.",
+  category: "ai",
+  subcategory: "agent",
+  props: [
+    {
+      name: "current",
+      type: "number",
+      required: true,
+      description: "Zero-indexed active branch."
+    },
+    {
+      name: "total",
+      type: "number",
+      required: true,
+      description: "Total number of branches."
+    },
+    {
+      name: "onCurrentChange",
+      type: "function",
+      required: false,
+      description: "Called with the next index when the user steps prev/next. Omit to render the controls disabled (read-only)."
+    },
+    {
+      name: "children",
+      type: "ReactNode",
+      required: true,
+      description: "The active branch's content \u2014 typically a `<Message>` wrapping `<Markdown>`."
+    },
+    {
+      name: "aria-label",
+      type: "string",
+      required: false,
+      default: "Response branches",
+      description: "Accessible name for the navigator landmark."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "children",
+      description: "The active branch's content. Render any node \u2014 typically `<Message>` + `<Markdown>`.",
+      required: true,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge"],
+    internal: ["lib/utils"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["muted", "muted-foreground", "foreground", "ring"],
+  examples: [
+    {
+      title: "Switch between alternate model responses",
+      description: "Three response candidates; arrow keys + chip step through them.",
+      code: 'const [i, setI] = useState(0);\n<Branch current={i} total={alternatives.length} onCurrentChange={setI}>\n  <Message role="assistant"><Markdown>{alternatives[i]}</Markdown></Message>\n</Branch>',
+      composition: ["chat", "branch", "alternates"]
+    },
+    {
+      title: "Read-only single-branch view",
+      description: "Omit `onCurrentChange` to render the chip disabled \u2014 for archived conversations or when the model only produced one response.",
+      code: '<Branch current={0} total={1}>\n  <Message role="assistant"><Markdown>{response}</Markdown></Message>\n</Branch>',
+      composition: ["chat", "branch", "read-only"]
+    }
+  ],
+  ai: {
+    whenToUse: "When a model returns multiple alternate responses (regenerate, n>1, ensemble) and the user should be able to navigate between them. Pair with `<Message>` + `<Markdown>` for the body and let the consumer own the active index.",
+    whenNotToUse: "Don't use for sequential chat history (use `<MessageList>`). Don't use for unrelated tabs (use `<Tabs>`). Don't use to gate streaming \u2014 render the in-flight response directly.",
+    commonMistakes: [
+      "Passing `current` outside `[0, total - 1]` \u2014 the prev/next controls disable at the boundaries; out-of-range values render the controls but show the wrong index in the chip",
+      "Treating Branch as stateful \u2014 it's headless, the consumer must keep `current` in their own state and react to `onCurrentChange`",
+      "Rendering all branches inside `children` \u2014 Branch shows ONE branch at a time; the consumer slices to the active branch before passing in",
+      "Using Branch for tabs or steppers \u2014 they're separate primitives with different semantics (Tabs = labeled regions, Stepper = ordered progress)"
+    ],
+    relatedComponents: ["pagination", "tabs", "message", "markdown"],
+    accessibilityNotes: 'Wraps the body in a `role="group"` with a labelled landmark. Prev/next are real `<button>`s with aria-labels ("Previous response" / "Next response") and disabled state at boundaries. The N-of-M chip is `aria-live="polite"` + `aria-atomic="true"` only when interactive (so AT announces the new position as one unit when the user steps); read-only branches drop the live-region to avoid initial-mount noise on chat surfaces with many `<Branch>` blocks. Arrow keys (Left/Right) step through branches when focus is anywhere inside the group; the wrapper itself is not focusable, so the prev/next buttons or any focusable descendant carry the keys.',
+    tokenBudget: 220
+  },
+  tags: ["ai", "agent", "branch", "navigation", "alternates"]
+};
+
+// src/ai/plan/plan.schema.ts
+var planSchema = {
+  name: "plan",
+  displayName: "Plan",
+  description: "Pre-execution multi-step plan card with an optional approval gate. Distinct from `<Task>` \u2014 Task is during/post-execution status; Plan is pre-execution intent.",
+  category: "ai",
+  subcategory: "agent",
+  props: [
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      description: "Optional title shown above the step list."
+    },
+    {
+      name: "description",
+      type: "string",
+      required: false,
+      description: "Optional secondary description shown under the label."
+    },
+    {
+      name: "steps",
+      type: "object",
+      required: true,
+      description: "Array of `PlanStep` objects ({ id: string; label: string; detail?: string }). Steps don't carry state \u2014 flip the rendered Plan into a Task once approved."
+    },
+    {
+      name: "onApprove",
+      type: "function",
+      required: false,
+      description: "Called when the user clicks Approve. When provided, the footer renders an Approve button."
+    },
+    {
+      name: "onCancel",
+      type: "function",
+      required: false,
+      description: "Called when the user clicks Cancel. When provided, the footer renders a Cancel button."
+    },
+    {
+      name: "approveLabel",
+      type: "string",
+      required: false,
+      default: "Approve",
+      description: "Override the approve button label."
+    },
+    {
+      name: "cancelLabel",
+      type: "string",
+      required: false,
+      default: "Cancel",
+      description: "Override the cancel button label."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge", "class-variance-authority", "@radix-ui/react-slot"],
+    internal: ["lib/utils", "primitives/button/button"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "border", "input", "muted", "muted-foreground", "foreground", "background"],
+  examples: [
+    {
+      title: "Approval-gated plan",
+      description: "Three steps with Approve/Cancel buttons in the footer.",
+      code: '<Plan\n  label="Refactor auth"\n  steps={[\n    { id: "read", label: "Read existing auth" },\n    { id: "apply", label: "Apply changes" },\n    { id: "test", label: "Run tests" },\n  ]}\n  onApprove={() => execute()}\n  onCancel={() => discard()}\n/>',
+      composition: ["agent", "plan", "approval"]
+    },
+    {
+      title: "Read-only plan (no footer)",
+      description: "Omit both onApprove and onCancel for a display-only plan.",
+      code: '<Plan\n  label="Migration plan"\n  description="Three-table migration with backfill."\n  steps={[\n    { id: "users", label: "Migrate users", detail: "1.2M rows, batched" },\n    { id: "orders", label: "Migrate orders", detail: "8M rows, dual-write window" },\n    { id: "verify", label: "Verify integrity" },\n  ]}\n/>',
+      composition: ["agent", "plan", "read-only"]
+    },
+    {
+      title: "Flip Plan \u2192 Task once approved",
+      description: "Plan renders pre-execution; once the user approves, swap to a Task driven by the running agent.",
+      code: 'const [approved, setApproved] = useState(false);\n{approved ? (\n  <Task label="Refactor auth" steps={runningSteps} />\n) : (\n  <Plan label="Refactor auth" steps={proposedSteps} onApprove={() => setApproved(true)} />\n)}',
+      composition: ["agent", "plan", "task", "lifecycle"]
+    }
+  ],
+  ai: {
+    whenToUse: "To show an agent's proposed multi-step plan BEFORE it executes \u2014 typically gated on user approval. Pair with `<Task>` for the execution phase. Use the optional description prop to summarize tradeoffs the user is approving.",
+    whenNotToUse: "Don't use `<Plan>` for the execution phase (use `<Task>` \u2014 its steps carry lifecycle state). Don't use it as a stateful wizard (use `<Stepper>` \u2014 Stepper is interactive, Plan is read-only intent). Don't use it for a single proposed action (just render a confirm dialog).",
+    commonMistakes: [
+      "Treating Plan as a stateful wizard \u2014 Plan is pre-execution display; once the user approves, swap the rendered Plan for a `<Task>` whose steps update as the agent runs",
+      "Adding `state` to Plan steps \u2014 that's `TaskStep`. PlanStep has only `id`, `label`, `detail`",
+      "Omitting both `onApprove` and `onCancel` when an approval gate is intended \u2014 the footer renders only when at least one handler is set",
+      "Putting reasoning in `step.label` \u2014 keep labels short imperative phrases; put any rationale in `step.detail` or a separate `<Reasoning>` block above the Plan"
+    ],
+    relatedComponents: ["task", "stepper", "reasoning", "tool-call"],
+    accessibilityNotes: "The step list renders as a real `<ol>` with an aria-label tied to the optional plan label, so screen readers announce it as an ordered list. Step indicators are aria-hidden (decorative) \u2014 the step label is the announced content. Approve / Cancel buttons inherit Button primitive accessibility (real `<button>`, focus ring, disabled handling).",
+    tokenBudget: 240
+  },
+  tags: ["ai", "agent", "plan", "approval", "pre-execution"]
+};
+
+// src/ai/conversation/conversation.schema.ts
+var conversationSchema = {
+  name: "conversation",
+  displayName: "Conversation",
+  description: "High-level chat shell. Composes `<MessageList>` over a messages array, an optional `<Sources>` panel, an optional `<Shimmer>` placeholder during the dead-time before the first stream token, and a `<Composer>` row at the bottom.",
+  category: "ai",
+  subcategory: "chat",
+  props: [
+    {
+      name: "messages",
+      type: "object",
+      required: true,
+      description: "Array of `ConversationMessage` objects ({ id: string; role: Role; content: ReactNode }). Each renders as one `<Message>`."
+    },
+    {
+      name: "onSubmit",
+      type: "function",
+      required: true,
+      description: "Called with the trimmed text when the user submits the composer."
+    },
+    {
+      name: "placeholder",
+      type: "string",
+      required: false,
+      default: "Ask anything\u2026",
+      description: "Composer placeholder."
+    },
+    {
+      name: "value",
+      type: "string",
+      required: false,
+      description: "Controlled composer text. Pass with `onValueChange` to take control of the input \u2014 useful for suggested prompts, voice transcripts, or form-library integration."
+    },
+    {
+      name: "onValueChange",
+      type: "function",
+      required: false,
+      description: "Called whenever the composer text changes. Required when `value` is set."
+    },
+    {
+      name: "isStreaming",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "When true, renders a `<Shimmer>` placeholder above the composer (use during the dead time before the first stream token arrives)."
+    },
+    {
+      name: "sources",
+      type: "object",
+      required: false,
+      description: "Optional `SourceRef[]` rendered as a `<Sources>` panel beneath the message stream."
+    },
+    {
+      name: "disabled",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Disable the composer (e.g. while waiting on a tool call)."
+    },
+    {
+      name: "composerActions",
+      type: "ReactNode",
+      required: false,
+      description: "Trailing slot inside the composer \u2014 typically a Send button."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "composerActions",
+      description: "Trailing children passed into the underlying `<Composer>` \u2014 render Send button, attachment buttons, etc.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["clsx", "tailwind-merge", "@radix-ui/react-collapsible", "class-variance-authority"],
+    internal: [
+      "lib/utils",
+      "components/composer/composer",
+      "components/message/message",
+      "components/message-list/message-list",
+      "components/shimmer/shimmer",
+      "components/sources/sources"
+    ],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["card", "card-foreground", "border", "muted", "muted-foreground", "background", "secondary", "accent", "ring"],
+  examples: [
+    {
+      title: "Off-the-shelf chat surface",
+      description: "Pass a messages array + onSubmit handler. Internal composer state is managed for you.",
+      code: 'const [messages, setMessages] = useState<ConversationMessage[]>([]);\nfunction handle(text: string) {\n  setMessages((m) => [...m, { id: nanoid(), role: "user", content: text }]);\n  // \u2026kick off the model call\n}\n<Conversation messages={messages} onSubmit={handle} />',
+      composition: ["chat", "shell", "conversation"]
+    },
+    {
+      title: "Streaming + RAG sources",
+      description: "Show a Shimmer placeholder for the in-flight assistant turn and a Sources panel when the response cites sources.",
+      code: '<Conversation\n  messages={messages}\n  onSubmit={handle}\n  isStreaming={waitingForFirstToken}\n  sources={lastResponse?.sources}\n  placeholder="Ask the docs\u2026"\n/>',
+      composition: ["chat", "rag", "streaming"]
+    },
+    {
+      title: "Markdown-formatted assistant turns",
+      description: "Pass `<Markdown>` (or any node) as the message content for streaming-safe formatting.",
+      code: 'const messages = chunks.map((c) => ({\n  id: c.id,\n  role: c.role,\n  content: c.role === "assistant" ? <Markdown>{c.text}</Markdown> : c.text,\n}));\n<Conversation messages={messages} onSubmit={handle} />',
+      composition: ["chat", "markdown", "streaming"]
+    }
+  ],
+  ai: {
+    whenToUse: "As the off-the-shelf entry point for any chat surface \u2014 saves consumers from wiring `<MessageList>` + `<Composer>` + `<Sources>` + `<Shimmer>` manually. Use when the standard layout (history above, composer below) fits.",
+    whenNotToUse: "Don't use when you need a non-standard layout (composer-on-top, side-by-side branches, threaded sub-conversations) \u2014 drop down to the underlying primitives. Don't use for a single-shot prompt UI (just a Composer + a result panel).",
+    commonMistakes: [
+      "Passing message strings as `content` when you wanted markdown rendering \u2014 wrap with `<Markdown>{text}</Markdown>` so streaming-safe formatting kicks in",
+      "Forgetting the `id` field on each ConversationMessage \u2014 without a stable id React re-mounts every row on each update, killing input focus and animation continuity",
+      "Passing `value` without `onValueChange` (or vice-versa) \u2014 controlled mode requires both props together; without the handler, the input goes read-only because internal state can't update",
+      "Setting `isStreaming` for the entire response \u2014 only set it during the dead time BEFORE the first token; once tokens arrive, render the partial in the messages array and clear isStreaming"
+    ],
+    relatedComponents: ["message-list", "composer", "message", "sources", "shimmer", "markdown"],
+    accessibilityNotes: 'Inherits accessibility from each composed primitive: MessageList is a `role="log"` with `aria-live="polite"` so new turns announce, Composer\'s textarea is a labelled form input that submits on Enter, Sources is a labelled Collapsible, and Shimmer is `role="status"`. The composer disables cleanly via the `disabled` prop, propagating to its `<textarea>`.',
+    tokenBudget: 280
+  },
+  tags: ["ai", "chat", "shell", "conversation", "messages", "composer"]
+};
+
+// src/ai/chain-of-thought/chain-of-thought.schema.ts
+var chainOfThoughtSchema = {
+  name: "chain-of-thought",
+  displayName: "ChainOfThought",
+  description: "Structured ReAct-shape reasoning trace \u2014 each step has a thought, optional action, and optional observation. Final answer renders below the trace. Distinct from `<Reasoning>` (unstructured prose).",
+  category: "ai",
+  subcategory: "reasoning",
+  props: [
+    {
+      name: "steps",
+      type: "object",
+      required: true,
+      description: "Array of `ChainOfThoughtStep` objects ({ thought: ReactNode; action?: ReactNode; observation?: ReactNode }). Every step has a thought; action and observation are optional."
+    },
+    {
+      name: "finalAnswer",
+      type: "ReactNode",
+      required: false,
+      description: "Optional final answer rendered beneath the collapsible trace \u2014 typically a `<Markdown>` block."
+    },
+    {
+      name: "label",
+      type: "string",
+      required: false,
+      default: "Chain of thought",
+      description: "Header label on the collapsible."
+    },
+    {
+      name: "defaultOpen",
+      type: "boolean",
+      required: false,
+      default: false,
+      description: "Whether the trace is expanded by default."
+    },
+    {
+      name: "className",
+      type: "string",
+      required: false,
+      description: "Additional CSS classes on the root."
+    }
+  ],
+  variants: [],
+  slots: [
+    {
+      name: "finalAnswer",
+      description: "Final answer rendered beneath the trace. Typically a `<Markdown>` block.",
+      required: false,
+      acceptedTypes: ["ReactNode"]
+    }
+  ],
+  dependencies: {
+    npm: ["@radix-ui/react-collapsible", "clsx", "tailwind-merge"],
+    internal: ["lib/utils", "components/reasoning/reasoning"],
+    peer: ["react", "react-dom"]
+  },
+  tokensUsed: ["foreground", "muted-foreground", "muted", "ring"],
+  examples: [
+    {
+      title: "ReAct trace with a final answer",
+      description: "Two steps + a final summary rendered as Markdown.",
+      code: '<ChainOfThought\n  steps={[\n    {\n      thought: "Need to look up the auth module",\n      action: "read auth.ts",\n      observation: "200 lines, uses bcrypt + jwt",\n    },\n    { thought: "The bug is on line 42 \u2014 missing salt rounds." },\n  ]}\n  finalAnswer={<Markdown>{"Set `bcrypt.hash(pw, 12)` instead of `bcrypt.hash(pw)`."}</Markdown>}\n/>',
+      composition: ["agent", "react", "reasoning"]
+    },
+    {
+      title: "Pure thought trace (no actions)",
+      description: "When the model is reasoning without tool calls, omit action/observation.",
+      code: '<ChainOfThought\n  steps={[\n    { thought: "The user wants a 3-step migration." },\n    { thought: "Step 1 is read-only, so it can run during business hours." },\n    { thought: "Steps 2-3 need maintenance window \u2014 recommend Saturday 2am." },\n  ]}\n/>',
+      composition: ["agent", "reasoning"]
+    }
+  ],
+  ai: {
+    whenToUse: "To expose the model's structured thinking when it's doing ReAct-style tool-augmented reasoning. Each step's thought / action / observation triple matches the canonical ReAct prompting format. Pair with `<ToolCall>` for the actual tool invocations and `<Markdown>` for the final answer.",
+    whenNotToUse: "Don't use for unstructured reasoning prose (use `<Reasoning>`). Don't use for the user-facing answer itself (the `finalAnswer` slot is for the answer; the trace is the scratchpad). Don't use to render ALL agent thinking \u2014 most models also produce free-form prose that doesn't fit the ReAct shape. Don't pass a Server Component subtree as `finalAnswer` \u2014 `<ChainOfThought>` is client-only (it composes Radix Collapsible via `<Reasoning>`), so the answer must be client-renderable too.",
+    commonMistakes: [
+      "Putting the final answer inside a step's thought \u2014 it belongs in `finalAnswer` so it stays visible when the trace is collapsed",
+      "Omitting `thought` on a step (it's required) \u2014 every step represents a reasoning move, even if the action is what carries the work",
+      "Using `<ChainOfThought>` for arbitrary structured data (use a real list or table) \u2014 this primitive's labels are specifically `Thought` / `Action` / `Observation`",
+      "Setting `defaultOpen={true}` for every assistant turn \u2014 the trace can be long; default-collapsed matches user expectations and lets them peek when they want more depth"
+    ],
+    relatedComponents: ["reasoning", "tool-call", "markdown", "task"],
+    accessibilityNotes: "Wraps `<Reasoning>` (Radix Collapsible) \u2014 header is a real `<button>` with aria-expanded; content gets aria-hidden when closed. The step list renders as an `<ol>`; per-step term labels (Thought / Action / Observation) read as inline text rather than `<dt>`/`<dd>` because the visual structure is a vertical row, not a definition list. Final answer renders outside the collapsible so it stays visible regardless of trace state.",
+    tokenBudget: 260
+  },
+  tags: ["ai", "agent", "reasoning", "react", "chain-of-thought", "trace"]
+};
+
 // src/artifacts/mind-map/mind-map.schema.ts
 var mindMapSchema = {
   name: "mind-map",
@@ -8493,6 +9250,6 @@ var spacedRepetitionSchema = {
   tags: ["artifact", "study", "spaced-repetition", "srs", "anki", "rating"]
 };
 
-export { accordionSchema, alertDialogSchema, alertSchema, arcSchema, aspectRatioSchema, attachmentSchema, avatarSchema, badgeSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, checkboxSchema, chordSchema, citationSchema, clozeSchema, clusterSchema, codeBlockSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, compareTableSchema, composerSchema, containerSchema, contextMenuSchema, dataTableSchema, datePickerSchema, deckSchema, dendrogramSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, emptySchema, errorStateSchema, fileTreeSchema, flashcardSchema, flowchartSchema, formSchema, funnelSchema, ganttSchema, gridSchema, hoverCardSchema, imageOcclusionSchema, inputOTPSchema, inputSchema, labelSchema, loadingIndicatorSchema, loadingSchema, markdownSchema, matrixSchema, menubarSchema, messageActionsSchema, messageListSchema, messageSchema, mindMapSchema, multiComboboxSchema, navigationMenuSchema, orgChartSchema, paginationSchema, popoverSchema, progressSchema, pyramidSchema, quizSchema, radioGroupSchema, reasoningSchema, resizableSchema, sankeySchema, scrollAreaSchema, selectSchema, separatorSchema, sequenceSchema, sheetSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, spacedRepetitionSchema, spacerSchema, stackSchema, stepperSchema, suggestionSchema, sunburstSchema, switchSchema, tableSchema, tabsSchema, tagSchema, textareaSchema, timeAxisSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, toolCallSchema, toolbarSchema, tooltipSchema, treeMapSchema, treeSchema, vennSchema };
+export { accordionSchema, alertDialogSchema, alertSchema, arcSchema, aspectRatioSchema, attachmentSchema, avatarSchema, badgeSchema, branchSchema, breadcrumbSchema, buttonSchema, calendarSchema, cardSchema, chainOfThoughtSchema, checkboxSchema, chordSchema, citationSchema, clozeSchema, clusterSchema, codeBlockSchema, collapsibleSchema, colorPickerSchema, comboboxSchema, commandSchema, compareTableSchema, composerSchema, containerSchema, contextMenuSchema, conversationSchema, dataTableSchema, datePickerSchema, deckSchema, dendrogramSchema, dialogSchema, drawerSchema, dropdownMenuSchema, dropzoneSchema, emptySchema, errorStateSchema, fileTreeSchema, flashcardSchema, flowchartSchema, formSchema, funnelSchema, ganttSchema, gridSchema, hoverCardSchema, imageOcclusionSchema, inlineCitationSchema, inputOTPSchema, inputSchema, labelSchema, loadingIndicatorSchema, loadingSchema, markdownSchema, matrixSchema, menubarSchema, messageActionsSchema, messageListSchema, messageSchema, mindMapSchema, multiComboboxSchema, navigationMenuSchema, orgChartSchema, paginationSchema, planSchema, popoverSchema, progressSchema, pyramidSchema, quizSchema, radioGroupSchema, reasoningSchema, resizableSchema, sankeySchema, scrollAreaSchema, selectSchema, separatorSchema, sequenceSchema, sheetSchema, shimmerSchema, sidebarSchema, skeletonSchema, sliderSchema, sonnerSchema, sourcesSchema, spacedRepetitionSchema, spacerSchema, stackSchema, stepperSchema, suggestionSchema, sunburstSchema, switchSchema, tableSchema, tabsSchema, tagSchema, taskSchema, textareaSchema, timeAxisSchema, timePickerSchema, timelineSchema, toggleGroupSchema, toggleSchema, toolCallSchema, toolbarSchema, tooltipSchema, treeMapSchema, treeSchema, vennSchema };
 //# sourceMappingURL=schemas.js.map
 //# sourceMappingURL=schemas.js.map