@usetheo/ui 0.13.0 → 0.13.2

package/dist/components/composites/agent-tool-renderer/agent-tool-renderer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `<AgentToolRenderer>` + the tool-renderer **registry** (M5-3).
+ *
+ * Dispatches a `ToolUIPart` to a rich renderer by classification kind
+ * (`diff` / `terminal` / `code` / `created-files` / `data-table`), falling back
+ * to `<ToolCallPart>` for anything unmapped. Mirrors the existing
+ * `partRenderers` / `dataRenderers` override registries on `<ChatMessage>` — the
+ * registry is prop-threaded, no React context (ADR D2).
+ *
+ * The default renderers are **defensive best-effort** (ADR D3): `code` and
+ * `terminal` are generic over any string output; `diff` / `created-files` /
+ * `data-table` render their rich primitive only when the output already matches
+ * the structured shape, else they degrade to `<ToolCallPart>` (never throw on
+ * `unknown`). Faithful sdk-tools `ToolUIPart`→props adapters are the M5-4 slice
+ * (`@theokit/ui/sdk-tools-adapters`).
+ */
+import type { JSX, ReactNode } from "react";
+import type { ToolUIPart } from "../../../types/chat.js";
+/** The rich surfaces a tool invocation can be dispatched to. */
+export type ToolRendererKind = "diff" | "terminal" | "code" | "created-files" | "data-table";
+/** A renderer for one tool invocation. Returns `ReactNode` (never throws). */
+export type ToolRenderer = (part: ToolUIPart) => ReactNode;
+/** Registry of renderers keyed by classification kind. */
+export type ToolRendererRegistry = Record<ToolRendererKind, ToolRenderer>;
+/** Maps a tool part to a kind, or `undefined` to fall back to `<ToolCallPart>`. */
+export type ClassifyTool = (part: ToolUIPart) => ToolRendererKind | undefined;
+/**
+ * Default classifier — a name-substring heuristic. Only affects the default;
+ * fully overridable per call (ADR D1/D2). Never throws; unmapped → `undefined`.
+ */
+export declare function defaultClassifyTool(part: ToolUIPart): ToolRendererKind | undefined;
+/**
+ * Resolve the renderer for a part: `classify` → registry lookup. Returns
+ * `undefined` when the tool is unmapped (the `<ToolCallPart>` fallback signal).
+ */
+export declare function resolveToolRenderer(registry: ToolRendererRegistry, classify: ClassifyTool, part: ToolUIPart): ToolRenderer | undefined;
+export declare const defaultToolRegistry: ToolRendererRegistry;
+export interface AgentToolRendererProps {
+    part: ToolUIPart;
+    /** Override the default registry (shallow-merge over `defaultToolRegistry`). */
+    toolRenderers?: ToolRendererRegistry;
+    /** Override the default classifier. */
+    classifyTool?: ClassifyTool;
+}
+/**
+ * Render one `ToolUIPart` through the registry, falling back to `<ToolCallPart>`
+ * when the tool is unmapped. Reusable outside `<ChatMessage>`.
+ *
+ * Rich renderers apply ONLY to the `output-available` state — they render
+ * `part.output`. Every other state (`input-streaming` / `input-available` /
+ * `approval-*` / `output-error` / `output-denied`) carries no output (and, for
+ * errors, only `errorText`), so it routes to `<ToolCallPart>`, which renders the
+ * state badge, the input, and the error. This prevents a classified-but-errored
+ * tool (e.g. a `shell` that failed) from rendering an empty rich surface and
+ * dropping the error message.
+ */
+export declare function AgentToolRenderer({ part, toolRenderers, classifyTool, }: AgentToolRendererProps): JSX.Element;
+export declare namespace AgentToolRenderer {
+    var displayName: string;
+}

package/dist/components/composites/agent-tool-renderer/index.d.ts

@@ -0,0 +1 @@
+export { AgentToolRenderer, type AgentToolRendererProps, type ClassifyTool, defaultClassifyTool, defaultToolRegistry, resolveToolRenderer, type ToolRenderer, type ToolRendererKind, type ToolRendererRegistry, } from "./agent-tool-renderer.js";

package/dist/components/composites/agent-tool-renderer/tool-call-part.d.ts

@@ -0,0 +1,5 @@
+import type { ToolUIPart } from "../../../types/chat.js";
+export interface ToolCallPartProps {
+    part: ToolUIPart;
+}
+export declare function ToolCallPart({ part }: ToolCallPartProps): JSX.Element;

package/dist/components/composites/approval-card/approval-card.d.ts

@@ -0,0 +1,35 @@
+import { type VariantProps } from "class-variance-authority";
+import type { HTMLAttributes, ReactNode } from "react";
+import type { IconComponent } from "../../../lib/types.js";
+/**
+ * ApprovalCard — inline pause-and-ask card for an agent stream.
+ *
+ * Used when the agent wants to perform an action that requires the user's
+ * consent (run a destructive command, use a new tool, edit outside the
+ * sandbox, etc.). Renders as a bordered card inside the conversation stream,
+ * pauses the visual flow, and exposes Deny / Approve / Always-allow actions.
+ */
+declare const cardVariants: (props?: ({
+    severity?: "warning" | "destructive" | "info" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+type ApprovalSeverity = NonNullable<VariantProps<typeof cardVariants>["severity"]>;
+interface ApprovalCardProps extends Omit<HTMLAttributes<HTMLElement>, "title">, VariantProps<typeof cardVariants> {
+    /** Short headline ("Run destructive command?"). */
+    title: ReactNode;
+    /** What is being requested (command, file path, tool name…). Renders monospace. */
+    request: ReactNode;
+    /** Optional explanation line under the request. */
+    description?: ReactNode;
+    /** Optional expandable details (e.g. full command, file diff). */
+    details?: ReactNode;
+    /** Pressing the primary "Approve" button. */
+    onApprove?: () => void;
+    /** Pressing "Deny". */
+    onDeny?: () => void;
+    /** Pressing "Always allow" — optional tertiary action. */
+    onAlways?: () => void;
+    /** Customise the icon shown in the corner. */
+    icon?: IconComponent;
+}
+declare const ApprovalCard: import("react").ForwardRefExoticComponent<ApprovalCardProps & import("react").RefAttributes<HTMLElement>>;
+export { ApprovalCard, type ApprovalSeverity };

package/dist/components/composites/approval-card/index.d.ts

@@ -0,0 +1 @@
+export { ApprovalCard, type ApprovalSeverity } from "./approval-card.js";

package/dist/components/composites/chat-composer/chat-composer.d.ts

@@ -0,0 +1,68 @@
+import type { HTMLAttributes, ReactNode, TextareaHTMLAttributes } from "react";
+export type ComposerMode = "chat" | "code" | "infra";
+interface ChatComposerProps extends Omit<HTMLAttributes<HTMLFormElement>, "onSubmit"> {
+    mode?: ComposerMode;
+    value: string;
+    onValueChange: (next: string) => void;
+    onSubmit?: (value: string) => void;
+    /**
+     * If true, the composer is in "agent running" state — Send becomes a Stop button.
+     */
+    running?: boolean;
+    onStop?: () => void;
+    /**
+     * Slot above the textarea — used for the folder selector in Infra mode.
+     */
+    contextSlot?: ReactNode;
+    /**
+     * Slot above the textarea for attachments / chips.
+     */
+    attachmentsSlot?: ReactNode;
+    /**
+     * Slot on the bottom-left of the action row (e.g. custom toggles).
+     * Overrides the default attach button entirely when provided.
+     */
+    leadingActions?: ReactNode;
+    /**
+     * Slot on the bottom-right (e.g. model selector). Send/stop is appended after this.
+     */
+    trailingActions?: ReactNode;
+    /**
+     * Optional attach-file callback. If omitted (and `leadingActions` is also
+     * omitted), no attach button is rendered. This avoids fake affordances per
+     * Quality Gate §7.
+     */
+    onAttach?: () => void;
+    /**
+     * Optional voice-input callback. If omitted, no mic button is rendered.
+     * Same rationale as `onAttach`.
+     */
+    onVoiceInput?: () => void;
+    /**
+     * Accessible label for the textarea. Falls back to a mode-aware default.
+     */
+    textareaLabel?: string;
+    /**
+     * Textarea placeholder. Defaults change by mode.
+     */
+    placeholder?: string;
+    /**
+     * Extra textarea props (rows, maxLength…).
+     */
+    textareaProps?: Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "value" | "onChange">;
+}
+/**
+ * ChatComposer — message input area, shared by Chat / Code / Infra modes.
+ *
+ * Visual:
+ *   - chat / infra → soft card with violet ring on focus, generous padding
+ *   - code          → compact dense form with mono font, slash prefix hint
+ *
+ * Stateless: caller controls `value` + handles `onSubmit`. Submit fires on Enter
+ * (without Shift). Shift+Enter inserts a newline.
+ *
+ * Optional affordances (mic, attach) are opt-in via `onVoiceInput` / `onAttach`
+ * — Quality Gate §7 forbids rendering fake controls without behavior.
+ */
+declare const ChatComposer: import("react").ForwardRefExoticComponent<ChatComposerProps & import("react").RefAttributes<HTMLFormElement>>;
+export { ChatComposer };

package/dist/components/composites/chat-composer/index.d.ts

@@ -0,0 +1 @@
+export { ChatComposer, type ComposerMode } from "./chat-composer.js";

package/dist/components/composites/chat-message/chat-message-actions.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `<ChatMessageActions>` + `<ChatMessageAction>` — footer toolbar for a chat
+ * message (copy, regenerate, thumbs up/down, share, edit, …).
+ *
+ * Forked from `vercel/ai-elements` `<MessageActions>` + `<MessageAction>`
+ * (Apache-2.0, see NOTICE). Adapted to TheoUI primitives: `<Button>` from
+ * `@theokit/ui` instead of shadcn, no Tooltip primitive yet (Vercel uses
+ * one — we render the `tooltip` prop as a `title` attribute for now; a
+ * proper Tooltip primitive lands in a follow-up RFC).
+ */
+import type { ComponentProps, HTMLAttributes, ReactNode } from "react";
+import { Button } from "../../primitives/button/index.js";
+export type ChatMessageActionsProps = HTMLAttributes<HTMLDivElement>;
+export declare function ChatMessageActions({ className, children, ...props }: ChatMessageActionsProps): JSX.Element;
+export type ChatMessageActionProps = ComponentProps<typeof Button> & {
+    /** Tooltip text — rendered as native `title` for now. */
+    tooltip?: string;
+    /** Accessible label (used by screen readers when only an icon is visible). */
+    label?: string;
+    children?: ReactNode;
+};
+export declare function ChatMessageAction({ tooltip, label, variant, size, className, children, ...props }: ChatMessageActionProps): JSX.Element;

package/dist/components/composites/chat-message/chat-message-branch.d.ts

@@ -0,0 +1,17 @@
+import { type ComponentProps, type HTMLAttributes } from "react";
+import { Button } from "../../primitives/button/index.js";
+export type ChatMessageBranchProps = HTMLAttributes<HTMLDivElement> & {
+    defaultBranch?: number;
+    onBranchChange?: (branchIndex: number) => void;
+};
+export declare function ChatMessageBranch({ defaultBranch, onBranchChange, className, ...props }: ChatMessageBranchProps): JSX.Element;
+export type ChatMessageBranchContentProps = HTMLAttributes<HTMLDivElement>;
+export declare function ChatMessageBranchContent({ children, ...props }: ChatMessageBranchContentProps): JSX.Element;
+export type ChatMessageBranchSelectorProps = HTMLAttributes<HTMLDivElement>;
+export declare function ChatMessageBranchSelector({ className, ...props }: ChatMessageBranchSelectorProps): JSX.Element | null;
+export type ChatMessageBranchPreviousProps = ComponentProps<typeof Button>;
+export declare function ChatMessageBranchPrevious({ children, ...props }: ChatMessageBranchPreviousProps): JSX.Element;
+export type ChatMessageBranchNextProps = ComponentProps<typeof Button>;
+export declare function ChatMessageBranchNext({ children, ...props }: ChatMessageBranchNextProps): JSX.Element;
+export type ChatMessageBranchPageProps = HTMLAttributes<HTMLSpanElement>;
+export declare function ChatMessageBranchPage({ className, ...props }: ChatMessageBranchPageProps): JSX.Element;

package/dist/components/composites/chat-message/chat-message-response.d.ts

@@ -0,0 +1,15 @@
+import type { ReactElement } from "react";
+export interface ChatMessageResponseProps {
+    /** Raw markdown text from the model. */
+    text: string;
+    /**
+     * True while tokens are still arriving. Enables the streaming-safe
+     * preprocess pass (auto-closes incomplete `**bold`, fences, links, math).
+     */
+    isStreaming?: boolean;
+    /** Extra className on the prose wrapper. */
+    className?: string;
+}
+declare function ChatMessageResponseImpl({ text, isStreaming, className, }: ChatMessageResponseProps): ReactElement;
+export declare const ChatMessageResponse: import("react").MemoExoticComponent<typeof ChatMessageResponseImpl>;
+export {};

package/dist/components/composites/chat-message/chat-message-toolbar.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `<ChatMessageToolbar>` — bottom-of-message bar holding actions + branch nav.
+ * Forked from `vercel/ai-elements` `<MessageToolbar>` (Apache-2.0, NOTICE).
+ */
+import type { HTMLAttributes } from "react";
+export type ChatMessageToolbarProps = HTMLAttributes<HTMLDivElement>;
+export declare function ChatMessageToolbar({ className, children, ...props }: ChatMessageToolbarProps): JSX.Element;

package/dist/components/composites/chat-message/chat-message.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `<ChatMessage>` — render a chat turn from a `UIMessage` (Vercel AI SDK
+ * `parts: UIMessagePart[]` shape).
+ *
+ * Forked structural shell from `vercel/ai-elements` `<Message>` +
+ * `<MessageContent>` (Apache-2.0, see NOTICE). The role-discriminated
+ * styling (user-aligned right with secondary bubble, assistant-aligned
+ * left with primary accent border) preserves TheoUI's Violet Forge look.
+ *
+ * Two consumption shapes:
+ *
+ *   1. **Convenience** — pass a full `UIMessage`, parts are dispatched to
+ *      their built-in renderers automatically:
+ *
+ *        <ChatMessage message={msg} />
+ *
+ *   2. **Composable** — render children explicitly when you need to
+ *      compose actions/branching/custom parts:
+ *
+ *        <ChatMessage.Root from="assistant">
+ *          <ChatMessage.Content>
+ *            <ChatMessageResponse text="Hello **world**" />
+ *          </ChatMessage.Content>
+ *          <ChatMessageToolbar>
+ *            <ChatMessageActions>
+ *              <ChatMessageAction tooltip="Copy"><CopyIcon /></ChatMessageAction>
+ *            </ChatMessageActions>
+ *          </ChatMessageToolbar>
+ *        </ChatMessage.Root>
+ */
+import type { HTMLAttributes, ReactNode } from "react";
+import { type DataUIPart, type FileUIPart, type MessageRole, type ReasoningFileUIPart, type ReasoningUIPart, type SourceDocumentUIPart, type SourceUrlUIPart, type TextUIPart, type ToolUIPart, type UIMessage, type UIMessagePart } from "../../../types/chat.js";
+import { type ClassifyTool, type ToolRendererRegistry } from "../agent-tool-renderer/agent-tool-renderer.js";
+import { type DataRendererMap } from "./parts/data-part.js";
+export type ChatMessageRootProps = HTMLAttributes<HTMLDivElement> & {
+    /** Sender role — controls layout (right-aligned bubble for `user`, left for `assistant`/`system`). */
+    from: MessageRole;
+};
+export declare const ChatMessageRoot: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** Sender role — controls layout (right-aligned bubble for `user`, left for `assistant`/`system`). */
+    from: MessageRole;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export type ChatMessageContentVariant = "contained" | "flat";
+export interface ChatMessageContentProps extends HTMLAttributes<HTMLDivElement> {
+    /**
+     * `contained` (default) — bubble surface (background + padding + radius).
+     * Applied to user role automatically. Assistant defaults to `flat`.
+     *
+     * `flat` — no bubble, content flows directly. Use for assistant or system.
+     */
+    variant?: ChatMessageContentVariant;
+}
+export declare const ChatMessageContent: import("react").ForwardRefExoticComponent<ChatMessageContentProps & import("react").RefAttributes<HTMLDivElement>>;
+export interface RenderPartOptions {
+    /** Consumer-defined renderers for `data-${name}` parts. */
+    dataRenderers?: DataRendererMap;
+    /** Override built-in renderers per part `type`. */
+    partRenderers?: PartRendererMap;
+    /** Registry of rich tool renderers keyed by classification kind (M5-3). */
+    toolRenderers?: ToolRendererRegistry;
+    /** Override the default tool classifier (M5-3). */
+    classifyTool?: ClassifyTool;
+}
+export type PartRendererMap = Partial<{
+    text: (part: TextUIPart) => ReactNode;
+    reasoning: (part: ReasoningUIPart) => ReactNode;
+    "reasoning-file": (part: ReasoningFileUIPart) => ReactNode;
+    file: (part: FileUIPart) => ReactNode;
+    "source-url": (part: SourceUrlUIPart) => ReactNode;
+    "source-document": (part: SourceDocumentUIPart) => ReactNode;
+    tool: (part: ToolUIPart) => ReactNode;
+    data: (part: DataUIPart) => ReactNode;
+    "step-start": () => ReactNode;
+}>;
+export declare function renderPart(part: UIMessagePart, opts?: RenderPartOptions): ReactNode;
+export interface ChatMessageProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** The UI message to render. Parts are dispatched automatically. */
+    message: UIMessage;
+    /** Optional avatar slot rendered before assistant/system content. */
+    avatar?: ReactNode;
+    /** Optional toolbar (copy / regenerate / branch nav) rendered below the content. */
+    actions?: ReactNode;
+    /** Variant of the content bubble. */
+    variant?: ChatMessageContentVariant;
+    /** Override built-in part renderers. */
+    partRenderers?: PartRendererMap;
+    /** Renderers for `data-${name}` parts. */
+    dataRenderers?: DataRendererMap;
+    /** Registry of rich tool renderers keyed by classification kind (M5-3). */
+    toolRenderers?: ToolRendererRegistry;
+    /** Override the default tool classifier (M5-3). */
+    classifyTool?: ClassifyTool;
+}
+export declare const ChatMessage: import("react").ForwardRefExoticComponent<ChatMessageProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/components/composites/chat-message/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<ChatMessage>` — composite-layer barrel.
+ *
+ * Public surface includes:
+ *   - Convenience: `ChatMessage` (auto-dispatches parts)
+ *   - Composable shell: `ChatMessageRoot`, `ChatMessageContent`,
+ *     `ChatMessageResponse`, `ChatMessageActions`, `ChatMessageAction`,
+ *     `ChatMessageToolbar`, branch components
+ *   - Part renderers: `TextPart`, `ReasoningPart`, `ToolCallPart`,
+ *     `FilePart`, `SourceUrlPart`, `SourceDocumentPart`, `DataPart`
+ *   - Imperative helpers: `renderPart`, types for renderer maps
+ */
+export { ChatMessage, ChatMessageRoot, ChatMessageContent, type ChatMessageProps, type ChatMessageRootProps, type ChatMessageContentProps, type ChatMessageContentVariant, type PartRendererMap, type RenderPartOptions, renderPart, } from "./chat-message.js";
+export { ChatMessageResponse, type ChatMessageResponseProps, } from "./chat-message-response.js";
+export { ChatMessageActions, ChatMessageAction, type ChatMessageActionsProps, type ChatMessageActionProps, } from "./chat-message-actions.js";
+export { ChatMessageToolbar, type ChatMessageToolbarProps, } from "./chat-message-toolbar.js";
+export { ChatMessageBranch, ChatMessageBranchContent, ChatMessageBranchSelector, ChatMessageBranchPrevious, ChatMessageBranchNext, ChatMessageBranchPage, type ChatMessageBranchProps, type ChatMessageBranchContentProps, type ChatMessageBranchSelectorProps, type ChatMessageBranchPreviousProps, type ChatMessageBranchNextProps, type ChatMessageBranchPageProps, } from "./chat-message-branch.js";
+export { TextPart, type TextPartProps } from "./parts/text-part.js";
+export { ReasoningPart, type ReasoningPartProps } from "./parts/reasoning-part.js";
+export { ToolCallPart, type ToolCallPartProps } from "../agent-tool-renderer/tool-call-part.js";
+export { FilePart, type FilePartProps } from "./parts/file-part.js";
+export { SourceUrlPart, SourceDocumentPart, type SourceUrlPartProps, type SourceDocumentPartProps, } from "./parts/source-part.js";
+export { DataPart, type DataPartProps, type DataRenderer, type DataRendererMap, } from "./parts/data-part.js";

package/dist/components/composites/chat-message/parts/data-part.d.ts

@@ -0,0 +1,9 @@
+import type { DataUIPart } from "../../../../types/chat.js";
+export type DataRenderer = (data: unknown, part: DataUIPart) => JSX.Element;
+export type DataRendererMap = Record<string, DataRenderer>;
+export interface DataPartProps {
+    part: DataUIPart;
+    /** Map of `data-${name}` → renderer. */
+    renderers?: DataRendererMap;
+}
+export declare function DataPart({ part, renderers }: DataPartProps): JSX.Element;

package/dist/components/composites/chat-message/parts/file-part.d.ts

@@ -0,0 +1,5 @@
+import type { FileUIPart } from "../../../../types/chat.js";
+export interface FilePartProps {
+    part: FileUIPart;
+}
+export declare function FilePart({ part }: FilePartProps): JSX.Element;

package/dist/components/composites/chat-message/parts/reasoning-part.d.ts

@@ -0,0 +1,7 @@
+import type { ReasoningUIPart } from "../../../../types/chat.js";
+export interface ReasoningPartProps {
+    part: ReasoningUIPart;
+    /** Open by default. Useful while the model is still streaming reasoning. */
+    defaultOpen?: boolean;
+}
+export declare function ReasoningPart({ part, defaultOpen }: ReasoningPartProps): JSX.Element;

package/dist/components/composites/chat-message/parts/source-part.d.ts

@@ -0,0 +1,9 @@
+import type { SourceDocumentUIPart, SourceUrlUIPart } from "../../../../types/chat.js";
+export interface SourceUrlPartProps {
+    part: SourceUrlUIPart;
+}
+export declare function SourceUrlPart({ part }: SourceUrlPartProps): JSX.Element;
+export interface SourceDocumentPartProps {
+    part: SourceDocumentUIPart;
+}
+export declare function SourceDocumentPart({ part }: SourceDocumentPartProps): JSX.Element;

package/dist/components/composites/chat-message/parts/text-part.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `<TextPart>` — renders a `TextUIPart`.
+ *
+ * Delegates to `<ChatMessageResponse>` which handles markdown + streaming
+ * preprocess + code-block highlight + memoization.
+ */
+import type { TextUIPart } from "../../../../types/chat.js";
+export interface TextPartProps {
+    part: TextUIPart;
+}
+export declare function TextPart({ part }: TextPartProps): JSX.Element;

package/dist/components/composites/choice-prompt/choice-prompt.d.ts

@@ -0,0 +1,65 @@
+import type { HTMLAttributes, ReactNode } from "react";
+import { type PromptOption } from "../../../lib/prompt.js";
+/**
+ * ChoicePrompt — single-select "ask the user" card for agent surfaces.
+ *
+ * Mirrors the UX of Claude Code's question card: a question with an optional
+ * header chip, a list of options each carrying a label + description, optional
+ * number-key shortcuts (terminal-style `1`..`9` selection), an injectable
+ * free-text "Other" option, and a side-by-side preview pane when options carry
+ * preview content.
+ *
+ * Renders one question at a time — sequencing across multiple questions is the
+ * consumer's responsibility (there is no built-in flow orchestrator).
+ *
+ * Controlled or uncontrolled: pass `value` + `onValueChange` to control the
+ * selection, or `defaultValue` to let the component own it. Same for the Other
+ * text via `otherText` / `onOtherTextChange`.
+ */
+/** Payload handed to `onConfirm`. */
+export interface ChoicePromptResult {
+    /** The selected option value (or the reserved Other value). */
+    value: string;
+    /** Present only when the selected value is the synthesized Other option. */
+    otherText?: string;
+}
+export interface ChoicePromptProps extends Omit<HTMLAttributes<HTMLElement>, "onSelect"> {
+    /** The question being asked. */
+    question: ReactNode;
+    /** Optional secondary line under the question. */
+    description?: ReactNode;
+    /** Optional short header chip (rendered as a Badge), e.g. "Deploy". */
+    badge?: ReactNode;
+    /** The selectable options. */
+    options: PromptOption[];
+    /** Controlled selected value. */
+    value?: string;
+    /** Initial selected value when uncontrolled. */
+    defaultValue?: string;
+    /** Fired with the option value whenever the selection changes. */
+    onValueChange?: (value: string) => void;
+    /** Inject a free-text "Other" option as the last row. */
+    allowOther?: boolean;
+    /** Label for the Other row. Defaults to "Other". */
+    otherLabel?: ReactNode;
+    /** Placeholder for the Other text field. */
+    otherPlaceholder?: string;
+    /** Controlled Other text. */
+    otherText?: string;
+    /** Fired with the Other text on every keystroke. */
+    onOtherTextChange?: (text: string) => void;
+    /** Enable `1`..`9` number-key selection. Default true. */
+    enableKeyboardShortcuts?: boolean;
+    /** Show the `1`..`9` hint chips next to options. Defaults to the shortcut flag. */
+    showNumbers?: boolean;
+    /** Confirm button label. Defaults to "Confirm". Omit `onConfirm` to hide it. */
+    confirmLabel?: ReactNode;
+    /** Cancel button label. Defaults to "Cancel". Omit `onCancel` to hide it. */
+    cancelLabel?: ReactNode;
+    /** Pressing Confirm. Receives the selection (and Other text when relevant). */
+    onConfirm?: (result: ChoicePromptResult) => void;
+    /** Pressing Cancel. */
+    onCancel?: () => void;
+}
+declare const ChoicePrompt: import("react").ForwardRefExoticComponent<ChoicePromptProps & import("react").RefAttributes<HTMLElement>>;
+export { ChoicePrompt };

package/dist/components/composites/choice-prompt/index.d.ts

@@ -0,0 +1,2 @@
+export { ChoicePrompt, type ChoicePromptProps, type ChoicePromptResult } from "./choice-prompt.js";
+export type { PromptOption } from "../../../lib/prompt.js";

package/dist/components/composites/code-block/code-block.d.ts

@@ -0,0 +1,29 @@
+import type { HTMLAttributes, ReactNode } from "react";
+/**
+ * CodeBlock — terminal command / code snippet surface.
+ *
+ * Pre-rendered code block with optional terminal "$ " prefix per line,
+ * optional caption (file name), and optional CopyButton positioned top-right.
+ * The CopyButton receives the RAW `code` (without the visual "$ " prefix),
+ * so consumers paste only the executable command.
+ *
+ * @example
+ *   <CodeBlock code="theo deploy" terminal copyable />
+ *   <CodeBlock code={dotenv} caption=".env.local" copyable />
+ *
+ * `language` is reserved for future syntax highlighting (v1: ignored).
+ */
+export interface CodeBlockProps extends Omit<HTMLAttributes<HTMLDivElement>, "children"> {
+    /** Code content. Can be multiline. */
+    code: string;
+    /** Language hint (forward-compat; v1 ignored). */
+    language?: string;
+    /** When true, prefix each line with "$ " for shell commands. */
+    terminal?: boolean;
+    /** Show inline CopyButton in top-right. */
+    copyable?: boolean;
+    /** Optional caption above block (e.g. ".env.local"). */
+    caption?: ReactNode;
+}
+declare const CodeBlock: import("react").ForwardRefExoticComponent<CodeBlockProps & import("react").RefAttributes<HTMLDivElement>>;
+export { CodeBlock };

package/dist/components/composites/code-block/index.d.ts

@@ -0,0 +1 @@
+export { CodeBlock, type CodeBlockProps } from "./code-block.js";

package/dist/components/composites/command-palette/command-palette.d.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+import type { IconComponent } from "../../../lib/types.js";
+export interface CommandItem {
+    id: string;
+    label: ReactNode;
+    /** Optional secondary line (path, hint, shortcut). */
+    hint?: ReactNode;
+    /** Optional group name. Items with the same group are visually grouped. */
+    group?: string;
+    /** Optional icon. */
+    icon?: IconComponent;
+    /** Optional searchable plain-text used by the cmdk ranker. Falls back to `label` when string. */
+    searchable?: string;
+}
+interface CommandPaletteProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    items: CommandItem[];
+    onSelect: (id: string) => void;
+    placeholder?: string;
+    emptyMessage?: ReactNode;
+    /**
+     * Optional custom filter score (0 = no match, > 0 = match). Receives the
+     * `value` (the item's searchable text) and the current `search` query.
+     * Defaults to cmdk's built-in fuzzy ranker which prioritizes substring +
+     * word-boundary + consecutive matches.
+     */
+    filter?: (value: string, search: string) => number;
+}
+/**
+ * CommandPalette — Cmd+K-style global launcher with full keyboard navigation.
+ *
+ * Built on `cmdk` (the de-facto shadcn pattern) + Theo Dialog. Provides
+ * out-of-the-box: ArrowUp/ArrowDown navigation, Enter selection, Escape close,
+ * Home/End, active-item highlight via `data-selected`, and fuzzy ranking.
+ *
+ * Stateless: caller owns `open` / `onOpenChange` / `items`. Selecting an item
+ * fires `onSelect(id)` and closes the dialog.
+ */
+declare function CommandPalette({ open, onOpenChange, items, onSelect, placeholder, emptyMessage, filter, }: CommandPaletteProps): import("react/jsx-runtime").JSX.Element;
+export { CommandPalette };

package/dist/components/composites/command-palette/index.d.ts

@@ -0,0 +1 @@
+export { CommandPalette, type CommandItem } from "./command-palette.js";

package/dist/components/composites/confirm-dialog/confirm-dialog.d.ts

@@ -0,0 +1,41 @@
+import type { ReactNode } from "react";
+/**
+ * ConfirmDialog — controlled confirmation modal built on `Dialog`.
+ *
+ * Focuses Cancel on open (deliberate — NOT the destructive button).
+ * `intent="destructive"` styles the confirm button with the destructive
+ * variant. `confirmationPhrase` enables typed-confirmation guard:
+ * the confirm button is disabled until the input value matches the
+ * phrase exactly (case-sensitive). An empty string phrase is treated
+ * as "no phrase required" (`!!confirmationPhrase`). Pressing Enter in
+ * the input triggers confirm when `canConfirm` is true.
+ *
+ * `onConfirm` can be async. While the returned promise is pending,
+ * both buttons are disabled and a `Loader2` spinner appears. On
+ * resolve, the dialog closes via `onOpenChange(false)`. On reject,
+ * the dialog stays open so the consumer can show their own error.
+ *
+ * @example
+ *   <ConfirmDialog
+ *     open={open} onOpenChange={setOpen}
+ *     title="Delete project"
+ *     description="This cannot be undone."
+ *     intent="destructive"
+ *     confirmationPhrase="my-project"
+ *     onConfirm={async () => api.deleteProject(id)}
+ *   />
+ */
+export interface ConfirmDialogProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    title: ReactNode;
+    description: ReactNode;
+    confirmLabel?: ReactNode;
+    cancelLabel?: ReactNode;
+    intent?: "default" | "destructive";
+    confirmationPhrase?: string;
+    onConfirm: () => void | Promise<void>;
+    loading?: boolean;
+}
+declare const ConfirmDialog: import("react").ForwardRefExoticComponent<ConfirmDialogProps & import("react").RefAttributes<HTMLDivElement>>;
+export { ConfirmDialog };

package/dist/components/composites/confirm-dialog/index.d.ts

@@ -0,0 +1 @@
+export { ConfirmDialog, type ConfirmDialogProps } from "./confirm-dialog.js";

package/dist/components/composites/confirm-prompt/confirm-prompt.d.ts

@@ -0,0 +1,31 @@
+import type { HTMLAttributes, ReactNode } from "react";
+/**
+ * ConfirmPrompt — binary yes/no "ask the user" card for agent surfaces.
+ *
+ * The simplest member of the prompt family: a question with an optional header
+ * chip and two actions. Use `variant="destructive"` for dangerous confirmations
+ * (delete, drop, force-push) — it tones the confirm button red and exposes the
+ * card as an `alertdialog` so assistive tech announces the stakes.
+ *
+ * Renders one question at a time — sequencing is the consumer's responsibility.
+ */
+export interface ConfirmPromptProps extends Omit<HTMLAttributes<HTMLElement>, "onSelect"> {
+    /** The question being asked. */
+    question: ReactNode;
+    /** Optional secondary line under the question. */
+    description?: ReactNode;
+    /** Optional short header chip (rendered as a Badge). */
+    badge?: ReactNode;
+    /** Tone of the confirm action. `destructive` also exposes role=alertdialog. */
+    variant?: "primary" | "destructive";
+    /** Confirm button label. Defaults to "Confirm". */
+    confirmLabel?: ReactNode;
+    /** Cancel button label. Defaults to "Cancel". Omit `onCancel` to hide it. */
+    cancelLabel?: ReactNode;
+    /** Pressing Confirm. */
+    onConfirm?: () => void;
+    /** Pressing Cancel. */
+    onCancel?: () => void;
+}
+declare const ConfirmPrompt: import("react").ForwardRefExoticComponent<ConfirmPromptProps & import("react").RefAttributes<HTMLElement>>;
+export { ConfirmPrompt };