shmakk 1.1.0 → 1.2.0

package/skills/frontend-ai-elements.md

@@ -0,0 +1,483 @@
+---
+name: ai-elements
+description: AI Elements component library guidance — pre-built React components for AI interfaces built on shadcn/ui. Use when building chat UIs, message displays, tool call rendering, streaming responses, reasoning panels, or any AI-native interface with the AI SDK.
+metadata:
+  priority: 5
+  docs:
+    - "https://sdk.vercel.ai/docs/ai-sdk-ui/chatbot-with-tool-calling"
+  sitemap: "https://sdk.vercel.ai/sitemap.xml"
+  pathPatterns:
+    - 'components/ai-elements/**'
+    - 'src/components/ai-elements/**'
+    - 'components/**/chat*'
+    - 'components/**/*chat*'
+    - 'components/**/message*'
+    - 'components/**/*message*'
+    - 'src/components/**/chat*'
+    - 'src/components/**/*chat*'
+    - 'src/components/**/message*'
+    - 'src/components/**/*message*'
+  importPatterns:
+    - 'ai'
+    - '@ai-sdk/*'
+    - '@ai-sdk/react'
+    - '@/components/ai-elements/*'
+  bashPatterns:
+    - '\bnpx\s+ai-elements\b'
+    - '\bnpm\s+(install|i|add)\s+[^\n]*\bai-elements\b'
+    - '\bpnpm\s+(install|i|add)\s+[^\n]*\bai-elements\b'
+    - '\bbun\s+(install|i|add)\s+[^\n]*\bai-elements\b'
+    - '\byarn\s+add\s+[^\n]*\bai-elements\b'
+    - '\bnpx\s+shadcn@latest\s+add\s+[^\n]*elements\.ai-sdk\.dev\b'
+    - '\bnpm\s+(install|i|add)\s+[^\n]*\b@ai-sdk/react\b'
+    - '\bpnpm\s+(install|i|add)\s+[^\n]*\b@ai-sdk/react\b'
+    - '\bbun\s+(install|i|add)\s+[^\n]*\b@ai-sdk/react\b'
+    - '\byarn\s+add\s+[^\n]*\b@ai-sdk/react\b'
+  promptSignals:
+    phrases:
+      - "ai elements"
+      - "ai components"
+      - "chat components"
+      - "chat ui"
+      - "chat interface"
+      - "voice elements"
+      - "code elements"
+      - "voice agent"
+      - "speech input"
+      - "transcription component"
+      - "code editor component"
+      - "streaming markdown"
+      - "streaming ui"
+      - "streaming response"
+      - "markdown formatting"
+    allOf:
+      - [message, component]
+      - [conversation, component]
+      - [markdown, stream]
+      - [markdown, render]
+      - [chat, ui]
+      - [chat, interface]
+      - [stream, response]
+      - [ai, component]
+    anyOf:
+      - "message component"
+      - "conversation component"
+      - "tool call display"
+      - "reasoning display"
+      - "voice conversation"
+      - "speech to text"
+      - "text to speech"
+      - "mic selector"
+      - "voice selector"
+      - "ai code editor"
+      - "file tree component"
+      - "terminal component"
+      - "stack trace component"
+      - "test results component"
+      - "react-markdown"
+      - "chat ui"
+      - "terminal"
+      - "useChat"
+      - "streamText"
+    noneOf:
+      - "vue"
+      - "svelte"
+      - "readme"
+      - "markdown file"
+      - "changelog"
+    minScore: 6
+category: frontend
+---
+
+# AI Elements
+
+> **CRITICAL — Your training data is outdated for this library.** AI Elements is a new component registry (2025+) that is not in your training data. Before using AI Elements, **fetch the docs** at https://ai-sdk.dev/elements and the component reference at https://ai-sdk.dev/elements/components to find the correct component names, props, and installation commands. Install components via `npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/<component>.json` — do not create these components from scratch.
+
+You are an expert in AI Elements — a component library and custom shadcn/ui registry built on top of shadcn/ui to help you build AI-native applications faster. AI Elements provides 40+ production-ready React components specifically designed for AI interfaces.
+
+## Overview
+
+**AI Elements is mandatory for any project that displays AI-generated text.** Install it immediately after scaffolding — do not build chat UIs or AI text displays from scratch. Without AI Elements, AI-generated markdown renders as ugly raw text with visible `**`, `##`, `---` characters.
+
+Unlike regular UI libraries, AI Elements understands AI-specific patterns — message parts, streaming states, tool calls, reasoning displays, and markdown rendering. Components are tightly integrated with AI SDK hooks like `useChat` and handle the unique challenges of streaming AI responses.
+
+The CLI adds components directly to your codebase with full source code access — no hidden dependencies, fully customizable.
+
+## Type Errors in AI Elements
+
+**NEVER add `@ts-nocheck` to AI Elements files.** If `next build` reports a type error in an AI Elements component (e.g. `plan.tsx`, `toolbar.tsx`), the cause is a version mismatch between the component and its dependencies (`@base-ui/react`, shadcn/ui `Button`, etc.).
+
+**Fix**:
+1. Reinstall the broken component: `npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/<component>.json --overwrite`
+2. If that fails, update the conflicting dep: `npm install @base-ui/react@latest`
+3. Only if the component is truly unused, delete it — don't suppress its types
+
+Adding `@ts-nocheck` hides real bugs and breaks IDE support for the entire file.
+
+**Install only the components you need** — do NOT install the full suite:
+```bash
+npx ai-elements@latest add message          # MessageResponse for markdown rendering
+npx ai-elements@latest add conversation     # Full chat UI (if building a chat app)
+```
+
+## Rendering Any AI-Generated Markdown
+
+**`<MessageResponse>` is the universal markdown renderer.** Use it for ANY AI-generated text — not just chat messages. It's exported from `@/components/ai-elements/message` and wraps Streamdown with code highlighting, math, mermaid, and CJK plugins.
+
+```tsx
+import { MessageResponse } from "@/components/ai-elements/message";
+
+// Workflow event with markdown content
+<MessageResponse>{event.briefing}</MessageResponse>
+
+// Any AI-generated string
+<MessageResponse>{generatedReport}</MessageResponse>
+
+// Streaming text from getWritable events
+<MessageResponse>{narrativeText}</MessageResponse>
+```
+
+**Never render AI text as raw JSX** like `{event.content}` or `<p>{text}</p>` — this displays ugly unformatted markdown with visible `**`, `##`, `---`. Always wrap in `<MessageResponse>`.
+
+This applies everywhere AI text appears: workflow event displays, briefing panels, reports, narrative streams, notifications, email previews.
+
+## Design Direction for AI Interfaces
+
+AI Elements solves message rendering, not the whole product aesthetic. Surround it with shadcn + Geist discipline. Use Conversation/Message for the stream area, compose the rest with shadcn primitives. Use Geist Sans for conversational UI, Geist Mono for tool args/JSON/code/timestamps. Default to dark mode for AI products. Avoid generic AI styling: purple gradients, glassmorphism everywhere, over-animated status indicators.
+
+## Installation
+
+**Install only the components you actually use.** Do NOT run `npx ai-elements@latest` without arguments or install `all.json` — this installs 48 components, most of which you won't need, and may introduce type conflicts between unused components and your dependency versions.
+
+```bash
+# Install specific components (RECOMMENDED)
+npx ai-elements@latest add message          # MessageResponse — required for any AI text
+npx ai-elements@latest add conversation     # Full chat UI container
+npx ai-elements@latest add code-block       # Syntax-highlighted code
+npx ai-elements@latest add tool             # Tool call display
+
+# Or use shadcn CLI directly with the registry URL
+npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/message.json
+npx shadcn@latest add https://elements.ai-sdk.dev/api/registry/conversation.json
+```
+
+**Never install all.json** — it pulls in 48 components including ones with `@base-ui/react` dependencies that may conflict with your shadcn version.
+
+Components are installed into `src/components/ai-elements/` by default.
+
+## Key Components
+
+### Conversation + Message (Core)
+
+The most commonly used components for building chat interfaces:
+
+```tsx
+'use client'
+import { useChat } from '@ai-sdk/react'
+import { DefaultChatTransport } from 'ai'
+import { Conversation } from '@/components/ai-elements/conversation'
+import { Message } from '@/components/ai-elements/message'
+
+export function Chat() {
+  const { messages, sendMessage, status } = useChat({
+    transport: new DefaultChatTransport({ api: '/api/chat' }),
+  })
+
+  return (
+    <Conversation>
+      {messages.map((message) => (
+        <Message key={message.id} message={message} />
+      ))}
+    </Conversation>
+  )
+}
+```
+
+The `Conversation` component wraps messages with auto-scrolling and a scroll-to-bottom button.
+
+The `Message` component renders message parts automatically — text, tool calls, reasoning, images — without manual part-type checking.
+
+### Message Markdown
+
+The `MessageMarkdown` sub-component is optimized for streaming — it efficiently handles incremental markdown updates without re-parsing the entire content on each stream chunk:
+
+```tsx
+import { MessageMarkdown } from '@/components/ai-elements/message'
+
+// Inside a custom message renderer
+<MessageMarkdown content={part.text} />
+```
+
+### Tool Call Display
+
+Renders tool invocations with inputs, outputs, and status indicators:
+
+```tsx
+import { Tool } from '@/components/ai-elements/tool'
+
+// Renders tool name, input parameters, output, and loading state
+<Tool toolInvocation={toolPart} />
+```
+
+### Reasoning / Chain of Thought
+
+Collapsible reasoning display for models that expose thinking:
+
+```tsx
+import { Reasoning } from '@/components/ai-elements/reasoning'
+
+<Reasoning content={reasoningText} />
+```
+
+### Code Block
+
+Syntax-highlighted code with copy button:
+
+```tsx
+import { CodeBlock } from '@/components/ai-elements/code-block'
+
+<CodeBlock language="typescript" code={codeString} />
+```
+
+### Prompt Input
+
+Rich input with attachment support, submit button, and keyboard shortcuts:
+
+```tsx
+import { PromptInput } from '@/components/ai-elements/prompt-input'
+
+<PromptInput
+  onSubmit={(text) => sendMessage({ text })}
+  isLoading={status === 'streaming'}
+  placeholder="Ask anything..."
+/>
+```
+
+## Full Component List
+
+| Component | Purpose |
+|-----------|---------|
+| `conversation` | Message container with auto-scroll |
+| `message` | Renders all message part types |
+| `code-block` | Syntax-highlighted code with copy |
+| `reasoning` | Collapsible thinking/reasoning display |
+| `tool` | Tool call display with status |
+| `actions` | Response action buttons (copy, regenerate) |
+| `agent` | Agent status and step display |
+| `artifact` | Rendered artifact preview |
+| `attachments` | File attachment display |
+| `audio-player` | Audio playback controls |
+| `branch` | Message branching UI |
+| `canvas` | Drawing/annotation canvas |
+| `chain-of-thought` | Step-by-step reasoning |
+| `checkpoint` | Workflow checkpoint display |
+| `confirmation` | Tool execution approval UI |
+| `file-tree` | File structure display |
+| `image` | AI-generated image display |
+| `inline-citation` | Source citation links |
+| `loader` | Streaming/loading indicators |
+| `model-selector` | Model picker dropdown |
+| `prompt-input` | Rich text input |
+| `sandbox` | Code sandbox preview |
+| `schema-display` | JSON schema visualization |
+| `shimmer` | Loading placeholder animation |
+| `sources` | Source/reference list |
+| `suggestion` | Suggested follow-up prompts |
+| `terminal` | Terminal output display |
+| `web-preview` | Web page preview iframe |
+| `persona` | Animated AI visual (Rive WebGL2) — idle, listening, thinking, speaking, asleep states |
+| `speech-input` | Voice input capture via Web Speech API (Chrome/Edge) with MediaRecorder fallback |
+| `transcription` | Audio transcript display with playback sync, segment highlighting, click-to-seek |
+| `mic-selector` | Microphone device picker with auto-detection and permission handling |
+| `voice-selector` | AI voice picker with searchable list, metadata (gender, accent, age), context provider |
+| `agent` | AI SDK ToolLoopAgent config display — model, instructions, tools, schema |
+| `commit` | Git commit metadata display — hash, message, author, timestamp, files |
+| `environment-variables` | Env var display with masking, visibility toggle, copy |
+| `package-info` | Package dependency display with version changes and badges |
+| `snippet` | Lightweight terminal command / code snippet with copy |
+| `stack-trace` | JS/Node.js error formatting with clickable paths, collapsible frames |
+| `test-results` | Test suite results with statistics and error details |
+
+## AI Voice Elements (January 2026)
+
+Six components for building voice agents, transcription apps, and speech-powered interfaces. Integrates with AI SDK's Transcription and Speech functions.
+
+```bash
+# Install all voice components
+npx ai-elements@latest add persona speech-input transcription audio-player mic-selector voice-selector
+```
+
+### Persona — Animated AI Visual
+
+Rive WebGL2 animation that responds to conversation states (idle, listening, thinking, speaking, asleep). Multiple visual variants available.
+
+```tsx
+import { Persona } from '@/components/ai-elements/persona'
+
+<Persona state="listening" variant="orb" />
+```
+
+### SpeechInput — Voice Capture
+
+Uses Web Speech API on Chrome/Edge, falls back to MediaRecorder on Firefox/Safari.
+
+```tsx
+import { SpeechInput } from '@/components/ai-elements/speech-input'
+
+<SpeechInput onTranscript={(text) => sendMessage({ text })} />
+```
+
+### Transcription — Synchronized Transcript Display
+
+Highlights the current segment based on playback time with click-to-seek navigation.
+
+```tsx
+import { Transcription } from '@/components/ai-elements/transcription'
+
+<Transcription segments={segments} currentTime={playbackTime} onSeek={setTime} />
+```
+
+### AudioPlayer, MicSelector, VoiceSelector
+
+```tsx
+import { AudioPlayer } from '@/components/ai-elements/audio-player'   // media-chrome based, composable controls
+import { MicSelector } from '@/components/ai-elements/mic-selector'     // device picker with auto-detection
+import { VoiceSelector } from '@/components/ai-elements/voice-selector' // searchable voice list with metadata
+```
+
+## AI Code Elements (January 2026)
+
+Thirteen components for building IDEs, coding apps, and background agents. Designed for developer tooling with streaming indicators, status tracking, and syntax highlighting.
+
+```bash
+# Install code element components
+npx ai-elements@latest add agent code-block commit environment-variables file-tree package-info sandbox schema-display snippet stack-trace terminal test-results attachments
+```
+
+### Key Code Components
+
+```tsx
+import { Terminal } from '@/components/ai-elements/terminal'          // ANSI color support, auto-scroll
+import { FileTree } from '@/components/ai-elements/file-tree'         // expandable folder hierarchy
+import { StackTrace } from '@/components/ai-elements/stack-trace'     // clickable paths, collapsible frames
+import { TestResults } from '@/components/ai-elements/test-results'   // suite stats + error details
+import { Sandbox } from '@/components/ai-elements/sandbox'            // code + execution output, tabbed view
+import { Snippet } from '@/components/ai-elements/snippet'            // lightweight terminal commands with copy
+import { Commit } from '@/components/ai-elements/commit'              // git commit metadata display
+import { EnvironmentVariables } from '@/components/ai-elements/environment-variables' // masked env vars
+import { PackageInfo } from '@/components/ai-elements/package-info'   // dependency versions + badges
+import { SchemaDisplay } from '@/components/ai-elements/schema-display' // REST API visualization
+```
+
+## Integration with AI SDK v6
+
+AI Elements components understand the AI SDK v6 `UIMessage` format and render `message.parts` automatically:
+
+```tsx
+// The Message component handles all part types:
+// - type: "text" → renders as markdown
+// - type: "tool-*" → renders tool call UI with status
+// - type: "reasoning" → renders collapsible reasoning
+// - type: "image" → renders image
+// No manual part.type checking needed!
+
+{messages.map((message) => (
+  <Message key={message.id} message={message} />
+))}
+```
+
+### Server-side Pattern
+
+```ts
+// app/api/chat/route.ts
+import { streamText, convertToModelMessages, gateway } from 'ai'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const modelMessages = await convertToModelMessages(messages)
+
+  const result = streamText({
+    model: gateway('anthropic/claude-sonnet-4.6'),
+    messages: modelMessages,
+  })
+
+  return result.toUIMessageStreamResponse()
+}
+```
+
+**Key v6 patterns:**
+- Use `convertToModelMessages()` (async) to convert UI messages to model messages
+- Use `toUIMessageStreamResponse()` (not `toDataStreamResponse()`) for chat UIs
+- Use `DefaultChatTransport` in the client `useChat` hook
+
+## Custom Rendering
+
+You can customize any component after installation since you own the source code:
+
+```tsx
+// Customize the Message component for your app
+import { Message as BaseMessage } from '@/components/ai-elements/message'
+
+function CustomMessage({ message }) {
+  // Add custom tool result rendering
+  return (
+    <BaseMessage
+      message={message}
+      renderTool={(toolPart) => <MyCustomToolCard tool={toolPart} />}
+    />
+  )
+}
+```
+
+## When to Use AI Elements
+
+| Scenario | Use AI Elements? |
+|----------|-----------------|
+| Building a chat interface with AI SDK | Yes — handles streaming, parts, markdown |
+| Displaying tool call results | Yes — built-in tool status UI |
+| Rendering AI reasoning/thinking | Yes — collapsible reasoning component |
+| Streaming text panels (perspectives, summaries, reports) | Yes — use `<MessageResponse>` for each panel |
+| Simple text completion display | Yes — models always produce markdown, use `<MessageResponse>` |
+| Non-React framework (Vue, Svelte) | No — React only (use AI SDK hooks directly) |
+| Custom design system, no shadcn | Maybe — install and customize the source |
+
+### When to default to AI Elements
+
+AI Elements should be the **first choice** for rendering streaming AI responses in any React project using the AI SDK. Default to AI Elements when:
+
+- **Any `useChat` UI** — `<Message message={message} />` handles all UIMessage part types (text, tool calls, reasoning, images) without manual `part.type` switching. This is the recommended rendering path for streaming chat.
+- **Streaming markdown** — `MessageMarkdown` is optimized for incremental streaming updates. Rolling your own markdown renderer leads to flicker, re-parse overhead, and broken partial syntax.
+- **Tool call results** — The `<Tool>` component renders input args, output, loading spinners, and error states. Building this from scratch is error-prone.
+- **Multi-modal messages** — Messages with mixed text + images + tool calls + reasoning are handled automatically. Manual part iteration is tedious and fragile.
+- **Rapid prototyping** — `npx ai-elements` + `<Conversation>` + `<Message>` gives you a production-quality chat UI in under 5 minutes.
+
+Do **not** default to AI Elements when:
+- The project uses Vue, Svelte, or another non-React framework
+- You need a completely custom rendering pipeline with no shadcn dependency
+- The output is server-only (no UI rendering needed)
+
+### Common breakages
+
+Known issues and how to fix them:
+
+1. **Missing shadcn primitives** — AI Elements components depend on shadcn/ui base components (Button, Card, ScrollArea, etc.). If you see `Module not found: @/components/ui/...`, run `npx shadcn@latest add <component>` for the missing primitive.
+2. **Wrong stream format** — Using `toDataStreamResponse()` or `toTextStreamResponse()` on the server instead of `toUIMessageStreamResponse()` causes `<Message>` to receive malformed data. Always use `toUIMessageStreamResponse()` when rendering with AI Elements.
+3. **Stale `@ai-sdk/react` version** — AI Elements v1.8+ requires `@ai-sdk/react@^3.0.x`. If `useChat` returns unexpected shapes, check that you're not on `@ai-sdk/react@^1.x` or `^2.x`.
+4. **Missing `'use client'` directive** — All AI Elements components are client components. If you import them in a Server Component without a `'use client'` boundary, Next.js will throw a build error.
+5. **Tailwind content path** — Components are installed into `src/components/ai-elements/`. Ensure your `tailwind.config` content array includes `./src/components/ai-elements/**/*.{ts,tsx}` or styles will be purged.
+6. **`DefaultChatTransport` not imported** — If you pass a custom `api` endpoint, you need `new DefaultChatTransport({ api: '/custom/path' })`. Passing `{ api }` directly to `useChat` is v5 syntax and silently fails.
+
+## Common Gotchas
+
+1. **AI Elements requires shadcn/ui** — run `npx shadcn@latest init` first if not already set up
+2. **Some components have peer dependencies** — the CLI installs them automatically, but check for missing UI primitives if you see import errors
+3. **Components are installed as source** — you can and should customize them for your app's design
+4. **Use `toUIMessageStreamResponse()`** on the server, not `toDataStreamResponse()` — AI Elements expects the UI message stream format
+5. **shadcn must use Radix base** — AI Elements uses Radix-specific APIs (`asChild`, `openDelay` on Root). If shadcn was initialized with `--base base-ui`, reinstall components after switching: `npx shadcn@latest init -d --base radix -f`
+
+## Official Documentation
+
+- [AI Elements](https://ai-sdk.dev/elements)
+- [Component Reference](https://ai-sdk.dev/elements/components)
+- [GitHub: AI Elements](https://github.com/vercel/ai-elements)
+- [shadcn/ui Registry](https://ui.shadcn.com/docs/directory)