@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/side-panel.js

@@ -0,0 +1,366 @@
+import stringWidth from 'string-width';
+import { stripVTControlCharacters } from 'node:util';
+import { FAINT, GRAY, STATUS, SUBTLE, WHITE, accentSgr } from './palette.js';
+/** The plain text of a row, for tests and width checks that care about content, not color. */
+export const panelRowText = (row) => row.segments.map(segment => segment.text).join('');
+/**
+ * Visible columns the terminal needs before the panel is worth drawing.
+ *
+ * The panel claims roughly a third of the width, so below this the chat column would drop
+ * under about 77 columns: narrow enough that the transcript's own wrapping and the command
+ * popup degrade, which is a worse trade than losing the panel.
+ */
+export const PANEL_MIN_COLUMNS = 110;
+/**
+ * Rows the panel needs before it is drawn.
+ *
+ * The floor is the tallest fixed stack the panel can reach - the Git section's four rows,
+ * the Node section's four, and the progress summary's three, plus the rules between them -
+ * so a terminal that shows the panel always has room for every section that cannot shrink.
+ */
+export const PANEL_MIN_ROWS = 14;
+/**
+ * Total columns the panel occupies at a given terminal width, divider included.
+ *
+ * A fixed share keeps the panel's measurements stable as the terminal grows while the clamps
+ * stop it from becoming a second chat column on very wide terminals or a sliver on the
+ * narrowest ones that still show it.
+ */
+export const panelWidth = (columns) => Math.min(44, Math.max(28, Math.floor(columns * 0.3)));
+/**
+ * Whether the selected graph is a custom one.
+ *
+ * The built-in Software Engineer harness is stored under `'default'` (and answers to its own
+ * id when a graph file was never written), so both spell the default; anything else is a
+ * user-authored graph, which is what the zoom section exists for.
+ */
+export const isCustomGraph = (selection, graph) => (selection ?? (graph?.id === 'software-engineer' ? 'default' : graph?.id)) !== 'default';
+const compact = Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 });
+const count = (value) => compact.format(Math.max(0, Math.round(value)));
+/**
+ * Flatten one value to a single paintable line.
+ *
+ * Panel values come from outside the render pass: a `qa.terminal` command, a graph node name,
+ * a plan item, a branch. A newline or an escape sequence in any of them would otherwise be
+ * written into the full-screen frame as itself - breaking the row arithmetic at best, driving
+ * the terminal at worst - so every value is stripped of control characters and flattened
+ * before it is measured, clipped or painted. Spacing is preserved: the panel's own alignment
+ * is made of it.
+ */
+const flat = (text) => stripVTControlCharacters(String(text))
+    .replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, ' ');
+function clip(text, width) {
+    const value = flat(text);
+    if (width <= 0)
+        return '';
+    if (stringWidth(value) <= width)
+        return value;
+    let result = '', used = 0;
+    for (const character of new Intl.Segmenter(undefined, { granularity: 'grapheme' }).segment(value)) {
+        const size = stringWidth(character.segment);
+        if (used + size > width - 1)
+            break;
+        result += character.segment;
+        used += size;
+    }
+    return result + '…';
+}
+const row = (...segments) => ({
+    segments: segments.map(segment => typeof segment === 'string' ? { text: flat(segment) } : { text: flat(segment.text), ...(segment.color === undefined ? {} : { color: segment.color }) }),
+});
+/**
+ * A row with a label on the left and a value or values right-aligned against the panel edge.
+ *
+ * The value keeps its own segments, so a row can pair a green `+120` with a red `-8`. When
+ * the two cannot both fit, the row degrades to one clipped line rather than letting the value
+ * run under the panel's edge: the panel is a fixed width, so a row that cannot fit is a row
+ * that must lose something.
+ */
+function pair(label, values, width) {
+    const valueWidth = values.reduce((total, segment) => total + stringWidth(flat(segment.text)), 0);
+    const gap = width - stringWidth(flat(label.text)) - valueWidth;
+    if (gap < 1)
+        return row({ text: clip([label.text, ...values.map(value => value.text)].join(' '), width), color: label.color });
+    return values.length ? row(label, { text: ' '.repeat(gap) }, ...values) : row(label);
+}
+/** A section heading with an optional right-aligned value, e.g. `Plan  6/14`. */
+const heading = (title, width, right = []) => pair({ text: title, color: SUBTLE }, right, width);
+/** The faint rule that separates one section from the one above it. */
+const rule = (width) => row({ text: '─'.repeat(Math.max(1, width)), color: FAINT });
+const plural = (value, word) => `${value} ${word}${value === 1 ? '' : 's'}`;
+function gitSection(data, width) {
+    const changes = data.changes;
+    const body = [];
+    const label = { text: 'Changes', color: SUBTLE };
+    if (!changes)
+        body.push(row({ text: 'Reading working tree…', color: FAINT }));
+    else if (!changes.isGit)
+        body.push(row({ text: 'Not a Git repository', color: FAINT }));
+    // A withheld reading comes first: its counts are zero because nothing was measured, and the
+    // clean-tree branch below would turn that into the one thing it is not.
+    else if (changes.skipped || changes.unavailable)
+        body.push(pair(label, [{ text: 'no counts', color: FAINT }], width));
+    else if (!changes.files && !changes.untracked && !changes.insertions && !changes.deletions)
+        body.push(pair(label, [{ text: 'clean', color: STATUS.ok }], width));
+    else
+        body.push(pair(label, [
+            { text: `+${count(changes.insertions)}`, color: STATUS.added },
+            { text: ' ' },
+            { text: `-${count(changes.deletions)}`, color: STATUS.error },
+        ], width));
+    if (changes?.isGit) {
+        // The summary's own read names the branch, so the row and the counts always describe the
+        // same repository; a read that could not name one falls back to the session's reader.
+        const branch = changes.branch ?? data.branch;
+        body.push(row({ text: '⎇ ', color: SUBTLE }, { text: clip(branch ?? 'detached', width - 2), color: GRAY }));
+        if (changes.skipped)
+            body.push(row({ text: clip(`Skipped: ${changes.skipped}`, width), color: FAINT }));
+        else if (changes.unavailable)
+            body.push(row({ text: clip(`Unavailable: ${changes.unavailable}`, width), color: FAINT }));
+        else if (changes.files || changes.untracked)
+            body.push(row({ text: clip([plural(changes.files, 'file'), ...(changes.untracked ? [`${changes.untracked} untracked`] : [])].join(' · '), width), color: FAINT }));
+    }
+    return [heading('Git tools', width), ...body];
+}
+function nodeSection(data, width) {
+    const body = [];
+    if (!data.nodes.length) {
+        body.push(row({ text: 'Idle', color: FAINT }));
+        const entry = data.graph ? data.graph.nodes[data.graph.entry]?.name ?? data.graph.entry : undefined;
+        if (entry)
+            body.push(row({ text: clip(`entry: ${entry}`, width), color: FAINT }));
+        return [heading('Node', width), ...body];
+    }
+    const [focus, ...rest] = data.nodes;
+    body.push(row({ text: '● ', color: accentSgr() }, { text: clip(focus.name, width - 2), color: WHITE }));
+    if (focus.detail)
+        body.push(row({ text: clip(`  ${focus.detail}`, width), color: GRAY }));
+    if (focus.model)
+        body.push(row({ text: clip(`  ${focus.model}`, width), color: FAINT }));
+    // A parallel run can have several nodes working at once, but the section keeps a fixed
+    // height so the packing above it can promise the panel never outgrows the terminal: the
+    // follower nodes are worth one line together, not one line each.
+    if (rest.length)
+        body.push(row({ text: clip(`  +${rest.length} more running: ${rest.map(node => node.name).join(', ')}`, width), color: FAINT }));
+    return [heading('Node', width), ...body];
+}
+function progressSection(data, width) {
+    const total = data.todos.length;
+    if (!total)
+        return [heading('Progress', width), row({ text: 'No plan published', color: FAINT })];
+    const done = data.todos.filter(todo => todo.status === 'completed').length;
+    const active = data.todos.filter(todo => todo.status === 'in_progress').length;
+    const waiting = total - done - active;
+    const share = done / total;
+    // The bar is sized from the row it shares with the percentage, so the pair always fits one
+    // row; a single filled cell still shows at least one percent of movement.
+    const label = `${Math.round(share * 100)}%`;
+    const barWidth = Math.max(3, width - stringWidth(label) - 1);
+    // A nonzero share fills at least one cell: `floor` rounds a small plan's first step (1 of 100) to
+    // nothing, which drew an empty bar beside a percentage that says otherwise.
+    const filled = share >= 1 ? barWidth : share > 0 ? Math.max(1, Math.min(barWidth, Math.floor(share * barWidth))) : 0;
+    return [
+        heading('Progress', width),
+        row({ text: '█'.repeat(filled), color: STATUS.ok }, { text: '░'.repeat(barWidth - filled), color: FAINT }, { text: ' ' }, { text: label, color: GRAY }),
+        row({ text: clip(`${done} done · ${active} active · ${waiting} waiting`, width), color: GRAY }),
+    ];
+}
+/**
+ * The current plan: its completed count, the items in progress, what comes next, and a count
+ * of whatever did not fit.
+ *
+ * The list is the elastic section - it absorbs whatever the fixed sections leave - so the
+ * rows are ordered by importance rather than by position in the plan: the item being worked
+ * on is what the reader checks, while the completed and waiting lines are context. Items fill
+ * every row the budget allows; only a plan longer than that is cut, and the cut is named on
+ * its own line. `rows` is the whole section's budget, heading included; below two rows
+ * nothing is worth drawing.
+ */
+function planSection(data, width, rows) {
+    if (rows < 2 || !data.todos.length)
+        return [];
+    const done = data.todos.filter(todo => todo.status === 'completed').length;
+    const body = [];
+    const active = data.todos.filter(todo => todo.status === 'in_progress');
+    const pending = data.todos.filter(todo => todo.status === 'pending');
+    const budget = rows - 1;
+    const doneRow = done ? 1 : 0;
+    // A plan that fits is listed whole. One that does not gives a row to the line naming the cut,
+    // unless that row is the only one there is: a single item says more than a count does.
+    const fits = active.length + doneRow + pending.length <= budget;
+    const room = fits ? budget : Math.max(1, budget - 1);
+    // The completed count shares the items' room, so it is taken out before any item is placed:
+    // appended afterwards it would land on the row the cut line needs. A cut list keeps it only
+    // beside at least one item - the heading already carries the same count.
+    const doneShown = fits || room >= 2 ? doneRow : 0;
+    const shownActive = active.slice(0, Math.max(0, room - doneShown));
+    for (const todo of shownActive)
+        body.push(row({ text: '● ', color: accentSgr() }, { text: clip(todo.text, width - 2), color: WHITE }));
+    if (doneShown)
+        body.push(row({ text: `✓ ${done} completed`, color: SUBTLE }));
+    const shownPending = pending.slice(0, Math.max(0, room - shownActive.length - doneShown));
+    for (const todo of shownPending)
+        body.push(row({ text: '○ ', color: SUBTLE }, { text: clip(todo.text, width - 2), color: GRAY }));
+    // Every item the budget left out is named, active ones included: the Progress row above counts all of
+    // them, so a list that showed two of three active items and said only "1 waiting" would hide the
+    // third entirely.
+    const omitted = [
+        active.length > shownActive.length ? `${active.length - shownActive.length} more active` : '',
+        pending.length > shownPending.length ? `${pending.length - shownPending.length} waiting` : '',
+    ].filter(Boolean);
+    // Clipped like every other row: the line can now name two omissions, and a narrow panel must not
+    // overflow on it.
+    if (omitted.length)
+        body.push(row({ text: clip(`… ${omitted.join(' · ')}`, width), color: FAINT }));
+    if (!body.length)
+        body.push(row({ text: `${done}/${data.todos.length} done`, color: GRAY }));
+    return [heading('Plan', width, [{ text: `${done}/${data.todos.length}`, color: GRAY }]), ...body.slice(0, budget)];
+}
+/** `5m 20s`, `1h 04m`, `12s` - the age a background terminal has been running. */
+export function panelDuration(milliseconds) {
+    const seconds = Math.max(0, Math.floor(milliseconds / 1000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${String(seconds % 60).padStart(2, '0')}s`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${String(minutes % 60).padStart(2, '0')}m`;
+}
+function terminalSection(data, width) {
+    if (!data.terminals.length)
+        return [];
+    // Running sessions come first: the manager keeps a naturally exited session until it is
+    // stopped explicitly, so insertion order would let three finished sessions hide the one
+    // process that is still alive - the row a reader actually needs - behind `+N more`.
+    const ordered = [...data.terminals].sort((left, right) => Number(right.running) - Number(left.running));
+    const body = ordered.slice(0, 3).map(session => {
+        const age = session.running && session.startedAt !== undefined ? ` · ${panelDuration(data.now - session.startedAt)}` : '';
+        // The age is what the row exists for, so it is reserved before the command is clipped: a
+        // long test-runner invocation must lose its own tail, not the elapsed time a reader is
+        // watching while the row keeps repainting for it.
+        const life = clip(`${session.id} · ${session.command}`, Math.max(1, width - 2 - stringWidth(age)));
+        return row({ text: session.running ? '● ' : '○ ', color: session.running ? STATUS.ok : FAINT }, { text: life, color: session.running ? GRAY : FAINT }, { text: age, color: session.running ? GRAY : FAINT });
+    });
+    if (ordered.length > body.length)
+        body.push(row({ text: `  +${ordered.length - body.length} more`, color: FAINT }));
+    return [heading('Terminals', width), ...body];
+}
+const MARK = (visited, active, id) => active.has(id) ? { glyph: '●', color: accentSgr() } : visited.has(id) ? { glyph: '✓', color: STATUS.ok } : { glyph: '○', color: FAINT };
+/**
+ * The zoomed view of the graph section the run is in: what leads into the current node and
+ * what it hands off to, with every node marked as visited, current, or not yet reached.
+ *
+ * Only a custom graph gets this: the built-in harness is a single agent node, and a zoom of
+ * it would say nothing a `Node` row does not already say. Neighbours are capped so a hub node
+ * cannot push the panel's other sections off the screen.
+ */
+function graphSection(data, width) {
+    const graph = data.graph;
+    if (!data.customGraph || !graph)
+        return [];
+    const visited = new Set(data.visited);
+    const active = new Set(data.nodes.map(node => node.id));
+    const focusOf = (id) => graph.nodes[id]?.name ?? id;
+    const focus = data.nodes[0]?.id ?? data.stoppedNode ?? [...data.visited].at(-1) ?? graph.entry;
+    const incoming = [...new Set(graph.edges.filter(edge => edge.target === focus && edge.source !== focus).map(edge => edge.source))];
+    // Self-targeting edges are hand-offs too: a bounded retry (a node with `maxNodeVisits` routing
+    // back to itself) is an outcome of this node, and dropping it would present the node as having
+    // no such route at all.
+    const outgoing = graph.edges.filter(edge => edge.source === focus);
+    const body = [];
+    // A join node can have more inputs than the cap shows; the hidden remainder is reported
+    // before the rows it was cut from, so a five-input join does not read as a two-input one.
+    if (incoming.length > 2)
+        body.push(row({ text: `  +${incoming.length - 2} more upstream`, color: FAINT }));
+    for (const id of incoming.slice(-2)) {
+        const mark = MARK(visited, active, id);
+        body.push(row({ text: '▲ ', color: FAINT }, { text: `${mark.glyph} `, color: mark.color }, { text: clip(focusOf(id), width - 4), color: GRAY }));
+    }
+    // The focus row is the marker the whole zoom is read against: `●` while a node is running,
+    // where a run ended (completed or stopped mid-node), and the same `○` an unreached node
+    // carries while the panel is idle and the focus is only the graph's entry - the row must not
+    // claim a position nothing has reached yet.
+    const stopped = data.stoppedNode === focus;
+    const focusGlyph = active.has(focus) || visited.has(focus) || stopped ? '●' : '○';
+    // A run that stopped on a node it had visited earlier is a stopped position, not a completed
+    // one: the amber marker outranks the historical visit.
+    const focusColor = active.has(focus) ? accentSgr() : stopped ? STATUS.warn : visited.has(focus) ? STATUS.ok : FAINT;
+    body.push(row({ text: `${focusGlyph} `, color: focusColor }, { text: clip(focusOf(focus), width - 2), color: active.has(focus) ? WHITE : GRAY }));
+    // Distinct routes are distinct rows even when they lead to the same node: a QA node can hand off
+    // to one End through `pass` and through `fail`, and collapsing them by target would hide one.
+    const routes = [...new Map(outgoing.map(edge => [`${edge.target}\u0000${edge.outcome ?? ''}`, edge])).values()];
+    const unique = routes.slice(0, 3);
+    unique.forEach((edge, index) => {
+        const mark = MARK(visited, active, edge.target);
+        const loop = edge.target === focus;
+        const label = edge.outcome ? `${focusOf(edge.target)} · ${edge.outcome}` : focusOf(edge.target);
+        // A loop is drawn with its own arrow so a retry back to this node is not mistaken for a
+        // hand-off to a neighbour that happens to share its name.
+        body.push(row({ text: `${index === unique.length - 1 ? '└─' : '├─'}${loop ? '↻' : '▶'} `, color: FAINT }, { text: `${mark.glyph} `, color: mark.color }, { text: clip(label, width - 6), color: GRAY }));
+    });
+    const hidden = routes.length - unique.length;
+    if (hidden > 0)
+        body.push(row({ text: `  +${hidden} more`, color: FAINT }));
+    return [heading('Graph', width, [{ text: `${visited.size}/${Object.keys(graph.nodes).length}`, color: GRAY }]), ...body];
+}
+/**
+ * The panel's rows, top to bottom, for a terminal of `columns` x `height`.
+ *
+ * Sections are anchored: Git tools, Node, Progress and the plan read from the top, while the
+ * terminal list and the graph zoom are held against the bottom - the reader asked for the graph
+ * section to be at the bottom of the panel - with whatever rows the top sections leave as blank
+ * space between them, so a tall terminal does not park the zoom in the middle of the screen.
+ * The panel never outgrows the terminal: the plan list is elastic and takes only what the fixed
+ * sections leave, and when even those overflow, whole sections are given up from the bottom
+ * upward - the zoom first, then the terminal list - because the sections above them are read on
+ * every run while those two describe states that come and go.
+ */
+export function sidePanelRows(data, columns, height) {
+    const width = Math.max(8, Math.floor(columns));
+    if (height < PANEL_MIN_ROWS || width < 8)
+        return [];
+    const git = gitSection(data, width);
+    const node = nodeSection(data, width);
+    const progress = progressSection(data, width);
+    let terminals = terminalSection(data, width);
+    let graph = graphSection(data, width);
+    let plan = [];
+    // Total rows a set of sections occupies once the rules between them are counted.
+    const total = (sections) => sections.reduce((sum, rows) => sum + rows.length, 0)
+        + Math.max(0, sections.length - 1);
+    // The plan's own rule and heading, before it can show a single item.
+    const PLAN_OVERHEAD = 2;
+    for (;;) {
+        const anchored = [git, node, progress, terminals, graph].filter(rows => rows.length);
+        const room = height - total(anchored) - (data.todos.length ? PLAN_OVERHEAD : 0);
+        if (room >= 0) {
+            plan = data.todos.length && room >= 1 ? planSection(data, width, room + 1) : [];
+            break;
+        }
+        if (graph.length) {
+            graph = [];
+            continue;
+        }
+        if (terminals.length) {
+            terminals = [];
+            continue;
+        }
+        // Nothing left to give up: the floor above guarantees this cannot happen, and a plan is
+        // not worth drawing over sections that would then be cut off mid-row.
+        plan = [];
+        break;
+    }
+    const top = [git, node, progress, plan].filter(rows => rows.length);
+    const bottom = [terminals, graph].filter(rows => rows.length);
+    const assemble = (groups) => groups.filter(rows => rows.length)
+        .flatMap((rows, index) => index === 0 ? rows : [rule(width), ...rows]);
+    const topRows = assemble(top);
+    const bottomRows = bottom.length ? [rule(width), ...assemble(bottom)] : [];
+    if (!bottomRows.length)
+        return topRows;
+    // The rows nobody claimed sit between the two groups; without them the bottom sections would
+    // simply follow the plan, which is where they already were before they were anchored.
+    const gap = Array.from({ length: Math.max(0, height - topRows.length - bottomRows.length) }, () => ({ segments: [] }));
+    return [...topRows, ...gap, ...bottomRows];
+}

package/dist/src/skill-commands.d.ts

@@ -0,0 +1 @@
+export declare function isBuiltinSlashCommand(input: string): boolean;

package/dist/src/skill-commands.js

@@ -0,0 +1,11 @@
+/** Built-in commands retain their existing meaning when a skill has the same name.
+ * Such a skill remains available through its fully qualified catalog command. */
+const BUILTIN_COMMANDS = new Set([
+    'browser', 'session', 'login', 'auth', 'model', 'providers', 'subagent', 'reasoning',
+    'graph', 'codegraph', 'dashboard', 'attach', 'usage', 'permissions', 'jev',
+    'feedback', 'yolo', 'tools', 'skills', 'plugins', 'mcp', 'logout', 'status',
+    'clear', 'compact', 'help', 'exit', 'quit',
+]);
+export function isBuiltinSlashCommand(input) {
+    return BUILTIN_COMMANDS.has(input.trim().split(/\s+/, 1)[0].slice(1));
+}

package/dist/src/skills/bundled/ai-elements/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: ai-elements
+description: Build AI chat interfaces using ai-elements components — conversations, messages, tool displays, prompt inputs, and more. Use when the user wants to build a chatbot, AI assistant UI, or any AI-powered chat interface.
+---
+
+<!--
+Derived from vercel/ai-elements (skills/ai-elements/SKILL.md).
+Copyright 2023 Vercel, Inc. Licensed under Apache-2.0.
+Modified by ZCode: local integration, formatting and adaptations.
+See THIRD-PARTY-NOTICES.md in the repository root for license and provenance.
+-->
+
+# AI Elements
+
+[AI Elements](https://www.npmjs.com/package/ai-elements) is a component library and custom registry built on top of [shadcn/ui](https://ui.shadcn.com/) to help you build AI-native applications faster. It provides pre-built components like conversations, messages and more.
+
+Installing AI Elements is straightforward and can be done in a couple of ways. You can use the dedicated CLI command for the fastest setup, or integrate via the standard shadcn/ui CLI if you've already adopted shadcn's workflow.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx ai-elements@latest`, `pnpm dlx ai-elements@latest`, or `bunx --bun ai-elements@latest` — based on the project's `packageManager`. Examples below use `npx ai-elements@latest` but substitute the correct runner for the project.
+
+## Prerequisites
+
+Before installing AI Elements, make sure your environment meets the following requirements:
+
+- [Node.js](https://nodejs.org/en/download/), version 18 or later
+- A [Next.js](https://nextjs.org/) project with the [AI SDK](https://ai-sdk.dev/) installed.
+- [shadcn/ui](https://ui.shadcn.com/) installed in your project. If you don't have it installed, running any install command will automatically install it for you.
+- We also highly recommend using the [AI Gateway](https://vercel.com/docs/ai-gateway) and adding `AI_GATEWAY_API_KEY` to your `env.local` so you don't have to use an API key from every provider. AI Gateway also gives $5 in usage per month so you can experiment with models. You can obtain an API key [here](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys&title=Get%20your%20AI%20Gateway%20key).
+
+## Installing Components
+
+You can install AI Elements components using either the AI Elements CLI or the shadcn/ui CLI. Both achieve the same result: adding the selected component’s code and any needed dependencies to your project.
+
+The CLI will download the component’s code and integrate it into your project’s directory (usually under your components folder). By default, AI Elements components are added to the `@/components/ai-elements/` directory (or whatever folder you’ve configured in your shadcn components settings).
+
+After running the command, you should see a confirmation in your terminal that the files were added. You can then proceed to use the component in your code.
+
+## Usage
+
+Once an AI Elements component is installed, you can import it and use it in your application like any other React component. The components are added as part of your codebase (not hidden in a library), so the usage feels very natural.
+
+## Example
+
+After installing AI Elements components, you can use them in your application like any other React component. For example:
+
+```tsx title="conversation.tsx"
+"use client";
+
+import { Message, MessageContent, MessageResponse } from "@/components/ai-elements/message";
+import { useChat } from "@ai-sdk/react";
+
+const Example = () => {
+  const { messages } = useChat();
+
+  return (
+    <>
+      {messages.map(({ role, parts }, index) => (
+        <Message from={role} key={index}>
+          <MessageContent>
+            {parts.map((part, i) => {
+              switch (part.type) {
+                case "text":
+                  return <MessageResponse key={`${role}-${i}`}>{part.text}</MessageResponse>;
+              }
+            })}
+          </MessageContent>
+        </Message>
+      ))}
+    </>
+  );
+};
+
+export default Example;
+```
+
+In the example above, we import the `Message` component from our AI Elements directory and include it in our JSX. Then, we compose the component with the `MessageContent` and `MessageResponse` subcomponents. You can style or configure the component just as you would if you wrote it yourself – since the code lives in your project, you can even open the component file to see how it works or make custom modifications.
+
+## Extensibility
+
+All AI Elements components take as many primitive attributes as possible. For example, the `Message` component extends `HTMLAttributes<HTMLDivElement>`, so you can pass any props that a `div` supports. This makes it easy to extend the component with your own styles or functionality.
+
+## Customization
+
+After installation, no additional setup is needed. The component’s styles (Tailwind CSS classes) and scripts are already integrated. You can start interacting with the component in your app immediately.
+
+For example, if you'd like to remove the rounding on `Message`, you can go to `components/ai-elements/message.tsx` and remove `rounded-lg` as follows:
+
+```tsx title="components/ai-elements/message.tsx" highlight="8"
+export const MessageContent = ({ children, className, ...props }: MessageContentProps) => (
+  <div
+    className={cn(
+      "flex flex-col gap-2 text-sm text-foreground",
+      "group-[.is-user]:bg-primary group-[.is-user]:text-primary-foreground group-[.is-user]:px-4 group-[.is-user]:py-3",
+      className,
+    )}
+    {...props}
+  >
+    <div className="is-user:dark">{children}</div>
+  </div>
+);
+```
+
+## Troubleshooting
+
+### Why are my components not styled?
+
+Make sure your project is configured correctly for shadcn/ui in Tailwind 4 - this means having a `globals.css` file that imports Tailwind and includes the shadcn/ui base styles.
+
+### I ran the AI Elements CLI but nothing was added to my project
+
+Double-check that:
+
+- Your current working directory is the root of your project (where `package.json` lives).
+- Your components.json file (if using shadcn-style config) is set up correctly.
+- You’re using the latest version of the AI Elements CLI:
+
+```bash title="Terminal"
+npx ai-elements@latest
+```
+
+If all else fails, feel free to open an [issue on GitHub](https://github.com/vercel/ai-elements/issues).
+
+### Theme switching doesn’t work — my app stays in light mode
+
+Ensure your app is using the same data-theme system that shadcn/ui and AI Elements expect. The default implementation toggles a data-theme attribute on the `<html>` element. Make sure your tailwind.config.js is using class or data- selectors accordingly.
+
+### The component imports fail with “module not found”
+
+Check the file exists. If it does, make sure your `tsconfig.json` has a proper paths alias for `@/` i.e.
+
+```json title="tsconfig.json"
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./*"]
+    }
+  }
+}
+```
+
+### My AI coding assistant can't access AI Elements components
+
+1. Verify your config file syntax is valid JSON.
+2. Check that the file path is correct for your AI tool.
+3. Restart your coding assistant after making changes.
+4. Ensure you have a stable internet connection.
+
+### Still stuck?
+
+If none of these answers help, open an [issue on GitHub](https://github.com/vercel/ai-elements/issues) and someone will be happy to assist.
+
+## Available Components
+
+See the `references/` folder for detailed documentation on each component. Paths beginning with `scripts/` in those references are examples relative to this skill directory, not repository-root scripts. They are component examples, not installed application features.