@page-speed/agent-everywhere 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,2568 @@
+import { ClassValue } from 'clsx';
+import * as react from 'react';
+import react__default, { ComponentType, ReactNode } from 'react';
+import * as class_variance_authority_types from 'class-variance-authority/types';
+import { VariantProps } from 'class-variance-authority';
+import * as AvatarPrimitive from '@radix-ui/react-avatar';
+import * as ProgressPrimitive from '@radix-ui/react-progress';
+import * as ScrollAreaPrimitive from '@radix-ui/react-scroll-area';
+import * as CollapsiblePrimitive from '@radix-ui/react-collapsible';
+import * as TooltipPrimitive from '@radix-ui/react-tooltip';
+
+type MessageRole = 'user' | 'assistant' | 'system';
+interface AgentMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    timestamp: Date;
+    metadata?: MessageMetadata;
+    attachments?: Attachment[];
+    reasoning?: ReasoningStep[];
+    steps?: ExecutionStep[];
+    feedback?: MessageFeedback;
+    /** For chart/data messages */
+    data?: DataPayload;
+}
+interface MessageMetadata {
+    model?: string;
+    tokens?: number;
+    latencyMs?: number;
+    sentiment?: SentimentScore;
+    /** Custom metadata for extensibility */
+    custom?: Record<string, unknown>;
+}
+type AttachmentType = 'image' | 'audio' | 'video' | 'document' | 'file';
+interface Attachment {
+    id: string;
+    type: AttachmentType;
+    name: string;
+    url?: string;
+    size?: number;
+    sizeLabel?: string;
+    mimeType?: string;
+    preview?: string;
+}
+type ReasoningStatus = 'pending' | 'active' | 'complete';
+interface ReasoningStep {
+    id: string;
+    label: string;
+    content: string;
+    icon?: string;
+    duration?: number;
+    status: ReasoningStatus;
+}
+type ExecutionStepStatus = 'pending' | 'active' | 'complete' | 'error';
+interface ExecutionStep {
+    id: string;
+    title: string;
+    description: string;
+    status: ExecutionStepStatus;
+    duration?: string;
+    code?: string;
+    output?: string;
+}
+type LayoutMode = 'panel' | 'widget' | 'overlay' | 'fullscreen' | 'split' | 'mobile';
+type WidgetPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left' | 'center';
+interface LayoutConfig {
+    mode: LayoutMode;
+    position?: WidgetPosition;
+    width?: string | number;
+    height?: string | number;
+    maxWidth?: string | number;
+    maxHeight?: string | number;
+    expandable?: boolean;
+    minimizable?: boolean;
+    closable?: boolean;
+    draggable?: boolean;
+}
+interface ComponentSlot {
+    id: string;
+    component: string;
+    props?: Record<string, unknown>;
+    /** Conditional rendering */
+    visible?: boolean;
+}
+interface AgentConfig {
+    /** Unique agent instance ID */
+    id: string;
+    /** Display name */
+    name?: string;
+    /** Layout configuration */
+    layout: LayoutConfig;
+    /** Header slot */
+    header?: ComponentSlot;
+    /** Message list configuration */
+    messages?: {
+        /** Default message renderer */
+        defaultRenderer?: string;
+        /** Custom renderers by message type */
+        renderers?: Record<string, string>;
+    };
+    /** Input slot configuration */
+    input?: ComponentSlot;
+    /** Sidebar slot */
+    sidebar?: ComponentSlot;
+    /** Footer slot */
+    footer?: ComponentSlot;
+    /** Theme overrides */
+    theme?: ThemeConfig;
+    /** Feature flags */
+    features?: AgentFeatures;
+}
+interface AgentFeatures {
+    /** Enable feedback collection */
+    feedback?: boolean;
+    /** Enable chain of thought display */
+    reasoning?: boolean;
+    /** Enable file attachments */
+    attachments?: boolean;
+    /** Enable quick replies */
+    quickReplies?: boolean;
+    /** Enable prompt templates */
+    templates?: boolean;
+    /** Enable inline suggestions */
+    suggestions?: boolean;
+    /** Enable typing indicator */
+    typingIndicator?: boolean;
+    /** Enable message copy */
+    copyMessages?: boolean;
+}
+interface ThemeConfig {
+    /** Primary brand color */
+    primary?: string;
+    /** Accent color */
+    accent?: string;
+    /** Background color */
+    background?: string;
+    /** Text color */
+    foreground?: string;
+    /** Border radius */
+    radius?: string;
+    /** Custom CSS variables */
+    variables?: Record<string, string>;
+}
+type TrendDirection = 'up' | 'down' | 'stable';
+interface MetricData {
+    id: string;
+    label: string;
+    value: string | number;
+    trend?: {
+        direction: TrendDirection;
+        value: number;
+        label?: string;
+    };
+    icon?: string;
+    description?: string;
+}
+type ChartType = 'bar' | 'line' | 'pie' | 'area' | 'donut';
+interface ChartDataPoint {
+    label: string;
+    value: number;
+    [key: string]: unknown;
+}
+interface ChartData {
+    type: ChartType;
+    title: string;
+    data: ChartDataPoint[];
+    insight?: string;
+    xAxisLabel?: string;
+    yAxisLabel?: string;
+}
+interface DataPayload {
+    type: 'chart' | 'table' | 'metrics' | 'custom';
+    chart?: ChartData;
+    table?: TableData;
+    metrics?: MetricData[];
+    custom?: Record<string, unknown>;
+}
+interface TableData {
+    columns: TableColumn[];
+    rows: Record<string, unknown>[];
+    title?: string;
+}
+interface TableColumn {
+    key: string;
+    label: string;
+    type?: 'string' | 'number' | 'date' | 'boolean';
+    align?: 'left' | 'center' | 'right';
+}
+type FeedbackSentiment = 'positive' | 'negative' | 'neutral';
+interface FeedbackCategory {
+    id: string;
+    label: string;
+    sentiment: FeedbackSentiment;
+}
+interface MessageFeedback {
+    vote?: 'up' | 'down';
+    categories?: string[];
+    comment?: string;
+    timestamp: Date;
+}
+interface SentimentScore {
+    overall: number;
+    label: 'positive' | 'negative' | 'neutral' | 'mixed';
+    confidence: number;
+    emotions?: EmotionScore[];
+}
+interface EmotionScore {
+    emotion: string;
+    score: number;
+    color?: string;
+}
+interface QuickReply {
+    id: string;
+    label: string;
+    prompt: string;
+    icon?: string;
+}
+interface PromptTemplate {
+    id: string;
+    title: string;
+    description?: string;
+    prompt: string;
+    category?: string;
+    variables?: TemplateVariable[];
+    icon?: string;
+}
+interface TemplateVariable {
+    name: string;
+    label: string;
+    type: 'text' | 'select' | 'number';
+    placeholder?: string;
+    options?: string[];
+    required?: boolean;
+    defaultValue?: string;
+}
+interface InlineSuggestion {
+    id: string;
+    text: string;
+    /** Full completion text */
+    completion: string;
+}
+interface AgentPersona {
+    id: string;
+    name: string;
+    description: string;
+    avatar?: string;
+    icon?: string;
+    systemPrompt?: string;
+    capabilities?: string[];
+    tone?: string;
+}
+type AgentEventType = 'message:send' | 'message:receive' | 'feedback:submit' | 'attachment:add' | 'attachment:remove' | 'layout:change' | 'widget:open' | 'widget:close' | 'widget:minimize' | 'error';
+interface AgentEvent {
+    type: AgentEventType;
+    timestamp: Date;
+    payload?: Record<string, unknown>;
+}
+interface AgentState {
+    /** Current messages */
+    messages: AgentMessage[];
+    /** Is agent processing/typing */
+    isLoading: boolean;
+    /** Current error if any */
+    error?: string;
+    /** Input value */
+    inputValue: string;
+    /** Pending attachments */
+    attachments: Attachment[];
+    /** Current layout config */
+    layout: LayoutConfig;
+    /** Is widget open (for widget mode) */
+    isOpen: boolean;
+    /** Is widget minimized */
+    isMinimized: boolean;
+    /** Unread message count */
+    unreadCount: number;
+    /** Active persona */
+    persona?: AgentPersona;
+}
+type AgentAction = {
+    type: 'SET_MESSAGES';
+    payload: AgentMessage[];
+} | {
+    type: 'ADD_MESSAGE';
+    payload: AgentMessage;
+} | {
+    type: 'UPDATE_MESSAGE';
+    payload: {
+        id: string;
+        updates: Partial<AgentMessage>;
+    };
+} | {
+    type: 'DELETE_MESSAGE';
+    payload: string;
+} | {
+    type: 'SET_LOADING';
+    payload: boolean;
+} | {
+    type: 'SET_ERROR';
+    payload: string | undefined;
+} | {
+    type: 'SET_INPUT';
+    payload: string;
+} | {
+    type: 'ADD_ATTACHMENT';
+    payload: Attachment;
+} | {
+    type: 'REMOVE_ATTACHMENT';
+    payload: string;
+} | {
+    type: 'CLEAR_ATTACHMENTS';
+} | {
+    type: 'SET_LAYOUT';
+    payload: LayoutConfig;
+} | {
+    type: 'SET_OPEN';
+    payload: boolean;
+} | {
+    type: 'SET_MINIMIZED';
+    payload: boolean;
+} | {
+    type: 'SET_UNREAD_COUNT';
+    payload: number;
+} | {
+    type: 'SET_PERSONA';
+    payload: AgentPersona | undefined;
+} | {
+    type: 'RESET';
+};
+interface RenderInstruction {
+    /** Component to render */
+    component: string;
+    /** Props to pass */
+    props?: Record<string, unknown>;
+    /** Children instructions */
+    children?: RenderInstruction[];
+    /** Slot to render into */
+    slot?: string;
+    /** Conditional */
+    condition?: boolean;
+}
+interface OrchestrationCommand {
+    type: 'inject' | 'remove' | 'update' | 'layout_change';
+    target?: string;
+    payload: RenderInstruction | LayoutConfig | string;
+}
+
+/**
+ * Merge Tailwind classes with clsx
+ */
+declare function cn(...inputs: ClassValue[]): string;
+/**
+ * Format a date to a relative time string (e.g., "2 min ago")
+ */
+declare function formatRelativeTime(date: Date): string;
+/**
+ * Format a date to a time string (e.g., "2:30 PM")
+ */
+declare function formatTime(date: Date): string;
+/**
+ * Format bytes to human-readable size
+ */
+declare function formatBytes(bytes: number): string;
+/**
+ * Generate a unique ID
+ */
+declare function generateId(prefix?: string): string;
+/**
+ * Truncate text with ellipsis
+ */
+declare function truncate(text: string, maxLength: number): string;
+/**
+ * Debounce function
+ */
+declare function debounce<T extends (...args: unknown[]) => unknown>(fn: T, delay: number): (...args: Parameters<T>) => void;
+/**
+ * Copy text to clipboard
+ */
+declare function copyToClipboard(text: string): Promise<boolean>;
+/**
+ * Parse markdown-style bold text to segments
+ */
+declare function parseTextWithBold(text: string): Array<{
+    text: string;
+    bold: boolean;
+}>;
+/**
+ * Get initials from a name
+ */
+declare function getInitials(name: string, maxLength?: number): string;
+/**
+ * Calculate percentage
+ */
+declare function calculatePercentage(value: number, total: number): number;
+/**
+ * Format a number with commas
+ */
+declare function formatNumber(num: number): string;
+/**
+ * Format currency
+ */
+declare function formatCurrency(amount: number, currency?: string): string;
+/**
+ * Delay/sleep utility
+ */
+declare function delay(ms: number): Promise<void>;
+/**
+ * Check if we're in a browser environment
+ */
+declare function isBrowser(): boolean;
+/**
+ * Check if we're inside an iframe
+ */
+declare function isInIframe(): boolean;
+/**
+ * Get color for sentiment
+ */
+declare function getSentimentColor(sentiment: 'positive' | 'negative' | 'neutral' | 'mixed'): string;
+/**
+ * Get background color for sentiment
+ */
+declare function getSentimentBgColor(sentiment: 'positive' | 'negative' | 'neutral' | 'mixed'): string;
+
+type RegisteredComponent = react__default.ComponentType<Record<string, unknown>>;
+declare class ComponentRegistry {
+    private components;
+    register(name: string, component: RegisteredComponent): void;
+    get(name: string): RegisteredComponent | undefined;
+    has(name: string): boolean;
+    unregister(name: string): void;
+    list(): string[];
+    clear(): void;
+}
+declare const componentRegistry: ComponentRegistry;
+interface AgentContextValue {
+    config: AgentConfig;
+    state: AgentState;
+    dispatch: react__default.Dispatch<AgentAction>;
+    sendMessage: (content: string, attachments?: Attachment[]) => void;
+    addMessage: (message: Omit<AgentMessage, 'id' | 'timestamp'>) => AgentMessage;
+    updateMessage: (id: string, updates: Partial<AgentMessage>) => void;
+    deleteMessage: (id: string) => void;
+    setLoading: (loading: boolean) => void;
+    setError: (error: string | undefined) => void;
+    setInput: (value: string) => void;
+    addAttachment: (attachment: Attachment) => void;
+    removeAttachment: (id: string) => void;
+    clearAttachments: () => void;
+    setLayout: (layout: LayoutConfig) => void;
+    setOpen: (open: boolean) => void;
+    setMinimized: (minimized: boolean) => void;
+    setPersona: (persona: AgentPersona | undefined) => void;
+    reset: () => void;
+    executeCommand: (command: OrchestrationCommand) => void;
+}
+interface AgentProviderProps {
+    config: AgentConfig;
+    initialMessages?: AgentMessage[];
+    onSendMessage?: (content: string, attachments?: Attachment[]) => Promise<void>;
+    onEvent?: (event: {
+        type: string;
+        payload?: unknown;
+    }) => void;
+    children: react__default.ReactNode;
+}
+declare function AgentProvider({ config, initialMessages, onSendMessage, onEvent, children, }: AgentProviderProps): react__default.JSX.Element;
+declare function useAgent(): AgentContextValue;
+declare function useAgentMessages(): {
+    messages: AgentMessage[];
+    isLoading: boolean;
+    addMessage: (message: Omit<AgentMessage, "id" | "timestamp">) => AgentMessage;
+    updateMessage: (id: string, updates: Partial<AgentMessage>) => void;
+    deleteMessage: (id: string) => void;
+};
+declare function useAgentInput(): {
+    value: string;
+    attachments: Attachment[];
+    isLoading: boolean;
+    setValue: (value: string) => void;
+    send: (content: string, attachments?: Attachment[]) => void;
+    addAttachment: (attachment: Attachment) => void;
+    removeAttachment: (id: string) => void;
+    clearAttachments: () => void;
+};
+declare function useAgentLayout(): {
+    layout: LayoutConfig;
+    isOpen: boolean;
+    isMinimized: boolean;
+    setLayout: (layout: LayoutConfig) => void;
+    setOpen: (open: boolean) => void;
+    setMinimized: (minimized: boolean) => void;
+};
+interface DynamicRendererProps {
+    instruction: RenderInstruction;
+    fallback?: react__default.ReactNode;
+}
+declare function DynamicRenderer({ instruction, fallback }: DynamicRendererProps): react__default.JSX.Element | null;
+interface SlotRendererProps {
+    slot: ComponentSlot | undefined;
+    fallback?: react__default.ReactNode;
+}
+declare function SlotRenderer({ slot, fallback }: SlotRendererProps): react__default.JSX.Element;
+
+type ComponentCategory = 'primitive' | 'input' | 'message' | 'data-display' | 'interactive' | 'specialty' | 'container';
+/** Logical capability tags an orchestrator can match intent against. */
+type ComponentCapability = 'text' | 'streaming' | 'reasoning' | 'steps' | 'feedback' | 'attachments' | 'file-upload' | 'voice' | 'image-generation' | 'suggestions' | 'templates' | 'quick-replies' | 'persona' | 'sentiment' | 'handoff' | 'chart' | 'table' | 'metrics' | 'progress' | 'entity-card' | 'option-select' | 'settings' | 'analytics' | 'wizard' | 'quiz' | 'writing' | 'layout' | 'media-gallery' | 'listing' | 'controls' | 'allocation' | 'recommendation' | 'schedule' | 'lesson' | 'media-editing';
+interface ManifestPropSpec {
+    name: string;
+    /** TS-ish type string for orchestrator/LLM consumption. */
+    type: string;
+    required?: boolean;
+    description?: string;
+}
+interface ComponentManifestEntry {
+    /** Registry key + import name. */
+    name: string;
+    category: ComponentCategory;
+    /** One-line description of what it does. */
+    description: string;
+    capabilities: ComponentCapability[];
+    /** Guidance for an orchestrator on when to select this component. */
+    whenToUse: string;
+    /** Key props (not exhaustive — the source of truth is the TS interface). */
+    props: ManifestPropSpec[];
+    /** Render surfaces this component is appropriate for. */
+    surfaces: Array<'conversation' | 'dashboard' | 'widget'>;
+}
+declare const componentManifest: ComponentManifestEntry[];
+/** Lookup a manifest entry by component name. */
+declare function getManifestEntry(name: string): ComponentManifestEntry | undefined;
+/** Filter manifest entries by capability — the core orchestrator query. */
+declare function findComponentsByCapability(capability: ComponentCapability): ComponentManifestEntry[];
+/** Filter manifest entries appropriate for a given render surface. */
+declare function findComponentsBySurface(surface: 'conversation' | 'dashboard' | 'widget'): ComponentManifestEntry[];
+/** Filter by category. */
+declare function findComponentsByCategory(category: ComponentCategory): ComponentManifestEntry[];
+
+type AnyComponent = ComponentType<Record<string, unknown>>;
+/**
+ * Map of manifest component name → component. Keys correspond exactly to the
+ * `name` field of each entry in `componentManifest`, so a render instruction
+ * produced from the manifest resolves to the right component.
+ */
+declare const componentMap: Record<string, AnyComponent>;
+/**
+ * Register every built-in component into the shared registry. Idempotent —
+ * safe to call from multiple entry points. Call once during app startup so the
+ * orchestrator can render components by manifest name.
+ */
+declare function registerAllComponents(): void;
+
+/**
+ * A single chunk emitted while the backend produces a response. The surface
+ * layer reduces a stream of these into a live-updating assistant message.
+ */
+type AgentStreamChunk = {
+    type: 'message_start';
+    messageId: string;
+    role: 'assistant';
+} | {
+    type: 'reasoning';
+    step: ReasoningStep;
+} | {
+    type: 'step';
+    step: ExecutionStep;
+} | {
+    type: 'tool_call';
+    call: ToolCall;
+} | {
+    type: 'tool_result';
+    callId: string;
+    result: ToolResult;
+} | {
+    type: 'text_delta';
+    text: string;
+} | {
+    type: 'data';
+    data: DataPayload;
+} | {
+    type: 'message_complete';
+    message: AgentMessage;
+} | {
+    type: 'error';
+    message: string;
+};
+interface ToolCall {
+    id: string;
+    /** Tool/function name the agent decided to invoke */
+    name: string;
+    /** Arguments the agent passed, already parsed */
+    arguments: Record<string, unknown>;
+    /** Human-readable label for display */
+    label?: string;
+}
+interface ToolResult {
+    status: 'success' | 'error';
+    /** Arbitrary structured output from the tool */
+    output?: unknown;
+    /** Optional renderable payload (chart/table/metrics) */
+    data?: DataPayload;
+    error?: string;
+}
+/**
+ * Declarative description of a tool the backend can call. Mirrors the shape an
+ * orchestrator/LLM would receive, so the same definitions work for both.
+ */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+interface ReportSection {
+    id: string;
+    title: string;
+    /** Narrative text for the section */
+    summary?: string;
+    /** Structured payload rendered as chart/table/metrics */
+    data?: DataPayload;
+}
+interface AgentReport {
+    id: string;
+    title: string;
+    subtitle?: string;
+    generatedAt: Date;
+    sections: ReportSection[];
+}
+interface SendOptions {
+    /** Prior conversation, newest last */
+    history?: AgentMessage[];
+    /** Pending attachments to include with the message */
+    attachments?: Attachment[];
+    /** Tools the agent is allowed to call this turn */
+    tools?: ToolDefinition[];
+    /** Abort the in-flight request */
+    signal?: AbortSignal;
+}
+interface GenerateReportOptions {
+    /** Free-form prompt describing the desired report */
+    prompt: string;
+    /** Conversation context to ground the report in */
+    history?: AgentMessage[];
+    signal?: AbortSignal;
+}
+/**
+ * The single interface the engine depends on. Implement this against any real
+ * provider (Anthropic, OpenAI, a private on-prem model, an orchestration
+ * gateway) and the entire component system works unchanged.
+ */
+interface AgentBackend {
+    /** Stream an assistant response for a user message. */
+    send(content: string, options?: SendOptions): AsyncIterable<AgentStreamChunk>;
+    /** Produce a structured report (powers expand-to-dashboard). */
+    generateReport(options: GenerateReportOptions): Promise<AgentReport>;
+    /** Optional: tools this backend exposes to the orchestrator. */
+    listTools?(): ToolDefinition[];
+}
+
+interface MockBackendConfig {
+    /** Delay between streamed tokens, ms. */
+    tokenDelayMs?: number;
+    /** Delay before the stream starts, ms. */
+    latencyMs?: number;
+    /** Emit reasoning steps before the answer. */
+    withReasoning?: boolean;
+    /** Emit a tool call + result mid-stream. */
+    withToolCalls?: boolean;
+    /** Attach a generated data payload to responses. */
+    withData?: boolean;
+    /**
+     * Override how the reply text is produced. Receives the user content and
+     * returns the full assistant reply (still streamed token-by-token).
+     */
+    responder?: (content: string) => string;
+    /** Tool definitions advertised by `listTools()`. */
+    tools?: ToolDefinition[];
+}
+declare function createMockBackend(config?: MockBackendConfig): AgentBackend;
+
+interface UseAgentBackendOptions {
+    backend: AgentBackend;
+    initialMessages?: AgentMessage[];
+    onError?: (error: Error) => void;
+}
+interface UseAgentBackendResult {
+    messages: AgentMessage[];
+    isLoading: boolean;
+    error?: string;
+    activeToolCalls: ToolCall[];
+    send: (content: string, attachments?: Attachment[]) => Promise<void>;
+    generateReport: (prompt: string) => Promise<AgentReport>;
+    setMessages: React.Dispatch<React.SetStateAction<AgentMessage[]>>;
+    reset: () => void;
+    cancel: () => void;
+}
+declare function useAgentBackend({ backend, initialMessages, onError, }: UseAgentBackendOptions): UseAgentBackendResult;
+
+/** A prior turn replayed to the agent as grounding context. */
+interface ConversationHistoryItem {
+    role: 'user' | 'assistant';
+    content: string;
+}
+/** Kinds of attachment the agent understands. */
+type AttachmentKind = 'uploaded_media' | 'source_url' | 'scraped_media';
+/** Coarse media classification for an attachment. */
+type AttachmentMediaType = 'image' | 'video' | 'svg' | 'unknown';
+/**
+ * A single attachment sent alongside a user message. Only `kind` is required;
+ * everything else is optional and forwarded verbatim to the backend.
+ */
+interface AgentAttachment {
+    kind: AttachmentKind | (string & {});
+    mediaRecordId?: number | string | null;
+    mediaType?: AttachmentMediaType | (string & {});
+    url?: string | null;
+    token?: string | null;
+    filename?: string | null;
+    alt?: string | null;
+    sourceUrl?: string | null;
+    intentHint?: string | null;
+}
+/**
+ * Opaque generated block. The engine never interprets block internals — it
+ * forwards them to the host via `onGeneratedBlocks`. Callers supply their own
+ * block type via the generic on the client/hook.
+ */
+type AgentBlock = Record<string, unknown>;
+/** Update semantics returned with a block payload. */
+type BlockUpdateMode = 'full_page' | 'partial_update' | (string & {});
+/** The only message type the backend accepts. */
+interface UserMessageEnvelope<TBlock = AgentBlock> {
+    type: 'user_message';
+    message: string;
+    blocks: TBlock[];
+    conversationHistory: ConversationHistoryItem[];
+    contentBrief?: Record<string, unknown> | null;
+    attachments?: AgentAttachment[];
+}
+interface ConnectionReadyEnvelope {
+    type: 'connection_ready';
+    pageCategoryId?: string;
+    pageCategoryName?: string;
+    pageCategorySlug?: string;
+}
+interface AssistantMessageStartEnvelope {
+    type: 'assistant_message_start';
+    messageId: string;
+    userId?: number | string;
+}
+interface AssistantMessageDeltaEnvelope {
+    type: 'assistant_message_delta';
+    messageId: string;
+    delta: string;
+}
+interface AssistantMessageThinkingDeltaEnvelope {
+    type: 'assistant_message_thinking_delta';
+    messageId: string;
+    delta: string;
+}
+interface AssistantMessageBlocksEnvelope<TBlock = AgentBlock> {
+    type: 'assistant_message_blocks';
+    messageId: string;
+    blocks: TBlock[] | null;
+    updateMode?: BlockUpdateMode;
+}
+interface AssistantMessageCompleteEnvelope<TBlock = AgentBlock> {
+    type: 'assistant_message_complete';
+    messageId?: string;
+    message: string;
+    thinking?: string | null;
+    blocks: TBlock[] | null;
+    updateMode?: BlockUpdateMode;
+}
+interface ErrorEnvelope {
+    type: 'error';
+    error?: string;
+}
+/** Discriminated union of every envelope the backend can emit. */
+type ServerEnvelope<TBlock = AgentBlock> = ConnectionReadyEnvelope | AssistantMessageStartEnvelope | AssistantMessageDeltaEnvelope | AssistantMessageThinkingDeltaEnvelope | AssistantMessageBlocksEnvelope<TBlock> | AssistantMessageCompleteEnvelope<TBlock> | ErrorEnvelope;
+/**
+ * Resolves a fully-qualified WebSocket URL for a conversation. The host app
+ * supplies this so the package never embeds any origin or route structure.
+ *
+ * Implementations typically read an API origin from an environment variable
+ * and append whatever path their backend exposes. Return a `ws://` or `wss://`
+ * URL. The default builder below is a convenience, not a requirement.
+ */
+type SocketUrlResolver = (params: {
+    websiteId: string | number;
+    pageCategoryId: string;
+}) => string;
+/**
+ * Convenience builder that upgrades a caller-supplied HTTP(S) origin to ws/wss
+ * and appends a path. Both `baseUrl` and `path` are REQUIRED and supplied by
+ * the host — this package ships no default origin and no default route, so
+ * nothing about any specific backend is baked in.
+ *
+ * @param baseUrl  Absolute http(s) origin (e.g. read from an env var).
+ * @param path     Path on that origin, with `{websiteId}` and
+ *                 `{pageCategoryId}` placeholders substituted.
+ * @param params   The identifiers to substitute into `path`.
+ */
+declare function buildSocketUrl(baseUrl: string, path: string, params: {
+    websiteId: string | number;
+    pageCategoryId: string;
+}): string;
+/** Coerce/normalize an arbitrary website id into numeric form, or null. */
+declare function normalizeWebsiteId(value: string | number): number | null;
+
+type ConnectionState = 'idle' | 'connecting' | 'ready' | 'streaming' | 'error' | 'requires_shared_domain';
+interface SocketClientOptions<TBlock = AgentBlock> {
+    /** Numeric (or numeric-string) website id. */
+    websiteId: string | number;
+    /** Page-category token the conversation is scoped to. */
+    pageCategoryId: string;
+    /**
+     * A fully-qualified `ws://`/`wss://` URL, OR an http(s) origin that will be
+     * upgraded by `resolveSocketUrl`. Provide exactly one of `socketUrl` or
+     * `resolveSocketUrl`.
+     */
+    socketUrl?: string;
+    /**
+     * Resolver that returns the WebSocket URL for this conversation. Supplied by
+     * the host so the package embeds no origin/route. Takes precedence over
+     * `socketUrl` when both are present.
+     */
+    resolveSocketUrl?: SocketUrlResolver;
+    /** Called whenever the high-level connection state changes. */
+    onStateChange?: (state: ConnectionState) => void;
+    /** Called for every decoded server envelope. */
+    onEnvelope?: (envelope: ServerEnvelope<TBlock>) => void;
+    /** Called on a transport or protocol error with a human-readable message. */
+    onError?: (message: string) => void;
+    /**
+     * Optional WebSocket implementation (for non-browser/SSR/test environments).
+     * Defaults to the global `WebSocket`.
+     */
+    webSocketImpl?: typeof WebSocket;
+    /** Cap on the reconnect backoff, ms. Defaults to 30_000. */
+    maxReconnectDelayMs?: number;
+}
+interface SocketSendPayload<TBlock = AgentBlock> {
+    message: string;
+    blocks: TBlock[];
+    conversationHistory: ConversationHistoryItem[];
+    contentBrief?: Record<string, unknown> | null;
+    attachments?: AgentAttachment[];
+}
+/**
+ * Manages a single semantic-builder WebSocket connection. Pure TS (not React)
+ * so it can be reused by hooks, the AgentBackend adapter, tests, or a
+ * non-React host. Call `connect()` to open and `close()` to tear down.
+ */
+declare class SemanticBuilderSocketClient<TBlock = AgentBlock> {
+    private readonly options;
+    private socket;
+    private reconnectTimer;
+    private shouldReconnect;
+    private reconnectAttempts;
+    private connectedOnce;
+    private state;
+    private readonly WebSocketImpl;
+    private readonly maxReconnectDelayMs;
+    constructor(options: SocketClientOptions<TBlock>);
+    /** Current high-level connection state. */
+    getState(): ConnectionState;
+    /** True when the socket is open and the backend is ready for messages. */
+    isReady(): boolean;
+    private setState;
+    private resolveUrl;
+    /** Open (or re-open) the connection. Idempotent for an already-open socket. */
+    connect(): void;
+    /**
+     * Send a user message. Returns false (without throwing) when the socket is
+     * not ready, so callers can surface a friendly "not connected yet" message.
+     */
+    send(payload: SocketSendPayload<TBlock>): boolean;
+    /** Force a fresh connection attempt, resetting backoff. */
+    retry(): void;
+    /** Permanently close the connection and stop reconnecting. */
+    close(): void;
+    private isSocketOpen;
+    private closeSocket;
+}
+
+type ChatMessageRole = 'system' | 'user' | 'assistant';
+interface SemanticBuilderChatMessage {
+    id: string;
+    role: ChatMessageRole;
+    content: string;
+    thinking?: string;
+    streaming?: boolean;
+    createdAt: number;
+}
+interface UseSemanticBuilderOptions<TBlock = AgentBlock> {
+    /**
+     * A fully-qualified `ws`/`wss` URL. Provide this OR `resolveSocketUrl`. The
+     * host owns the origin/route; this package embeds neither.
+     */
+    socketUrl?: string;
+    /** Resolver that returns the socket URL for this conversation. */
+    resolveSocketUrl?: SocketUrlResolver;
+    websiteId: string | number;
+    pageCategoryId: string;
+    pageName: string;
+    pageSlug?: string;
+    /** Current page blocks, forwarded to the agent for grounding. */
+    blocks: TBlock[];
+    /** Optional content brief grounding context. */
+    contentBrief?: Record<string, unknown> | null;
+    /** Connect only when enabled (e.g. once the page has finished loading). */
+    enabled: boolean;
+    /** Invoked when the agent returns generated blocks. */
+    onGeneratedBlocks?: (blocks: TBlock[], updateMode?: BlockUpdateMode) => void;
+    /**
+     * Optional hook to intercept undo-like messages and restore a prior local
+     * snapshot before hitting the network. Return the restored blocks to short
+     * circuit, or null/undefined to fall through to the agent.
+     */
+    onUndoRequest?: (message: string) => Promise<TBlock[] | null> | TBlock[] | null;
+    /** Optional override for the welcome system message. */
+    buildWelcomeMessage?: (args: {
+        pageName: string;
+        hasContentBrief: boolean;
+    }) => string;
+    /** Optional WebSocket implementation (SSR/tests). */
+    webSocketImpl?: typeof WebSocket;
+}
+interface SendMessageOptions {
+    /** Don't render a user/assistant bubble; used for background auto-draft. */
+    hidden?: boolean;
+    attachments?: AgentAttachment[];
+}
+interface UseSemanticBuilderResult {
+    messages: SemanticBuilderChatMessage[];
+    connectionState: ConnectionState;
+    connectionError: string | null;
+    statusLabel: string;
+    isConnected: boolean;
+    isStreaming: boolean;
+    sendMessage: (content: string, options?: SendMessageOptions) => Promise<boolean>;
+    retry: () => void;
+}
+declare function useSemanticBuilder<TBlock = AgentBlock>({ socketUrl, resolveSocketUrl, websiteId, pageCategoryId, pageName, pageSlug, blocks, contentBrief, enabled, onGeneratedBlocks, onUndoRequest, buildWelcomeMessage, webSocketImpl, }: UseSemanticBuilderOptions<TBlock>): UseSemanticBuilderResult;
+
+declare const buttonVariants: (props?: ({
+    variant?: "link" | "outline" | "default" | "destructive" | "secondary" | "ghost" | null | undefined;
+    size?: "sm" | "default" | "lg" | "icon" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface ButtonProps extends react.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
+
+declare const Input: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref"> & react.RefAttributes<HTMLInputElement>>;
+
+declare const Textarea: react.ForwardRefExoticComponent<Omit<react.DetailedHTMLProps<react.TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, "ref"> & react.RefAttributes<HTMLTextAreaElement>>;
+
+declare const badgeVariants: (props?: ({
+    variant?: "error" | "outline" | "default" | "destructive" | "secondary" | "success" | "warning" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+interface BadgeProps extends react.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
+}
+declare function Badge({ className, variant, ...props }: BadgeProps): react.JSX.Element;
+
+declare const Avatar: react.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarProps & react.RefAttributes<HTMLSpanElement>, "ref"> & react.RefAttributes<HTMLSpanElement>>;
+declare const AvatarImage: react.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarImageProps & react.RefAttributes<HTMLImageElement>, "ref"> & react.RefAttributes<HTMLImageElement>>;
+declare const AvatarFallback: react.ForwardRefExoticComponent<Omit<AvatarPrimitive.AvatarFallbackProps & react.RefAttributes<HTMLSpanElement>, "ref"> & react.RefAttributes<HTMLSpanElement>>;
+
+declare const Progress: react.ForwardRefExoticComponent<Omit<ProgressPrimitive.ProgressProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const ScrollArea: react.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+declare const ScrollBar: react.ForwardRefExoticComponent<Omit<ScrollAreaPrimitive.ScrollAreaScrollbarProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+declare const Collapsible: react.ForwardRefExoticComponent<CollapsiblePrimitive.CollapsibleProps & react.RefAttributes<HTMLDivElement>>;
+declare const CollapsibleTrigger: react.ForwardRefExoticComponent<CollapsiblePrimitive.CollapsibleTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const CollapsibleContent: react.ForwardRefExoticComponent<CollapsiblePrimitive.CollapsibleContentProps & react.RefAttributes<HTMLDivElement>>;
+
+declare const TooltipProvider: react.FC<TooltipPrimitive.TooltipProviderProps>;
+declare const Tooltip: react.FC<TooltipPrimitive.TooltipProps>;
+declare const TooltipTrigger: react.ForwardRefExoticComponent<TooltipPrimitive.TooltipTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+declare const TooltipContent: react.ForwardRefExoticComponent<Omit<TooltipPrimitive.TooltipContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+
+interface MessageBubbleProps {
+    role: MessageRole;
+    children: React.ReactNode;
+    className?: string;
+    /** Remove default styling, just provide structure */
+    unstyled?: boolean;
+}
+declare function MessageBubble({ role, children, className, unstyled }: MessageBubbleProps): react.JSX.Element;
+
+interface AgentAvatarProps {
+    role: MessageRole;
+    /** For assistant, optionally pass persona */
+    persona?: AgentPersona;
+    /** For user, optionally pass name */
+    name?: string;
+    /** Custom image URL */
+    src?: string;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    className?: string;
+}
+declare function AgentAvatar({ role, persona, name, src, size, className, }: AgentAvatarProps): react.JSX.Element;
+
+interface TypingIndicatorProps {
+    className?: string;
+    /** Dot size */
+    size?: 'sm' | 'md';
+    /** Label to show */
+    label?: string;
+}
+declare function TypingIndicator({ className, size, label }: TypingIndicatorProps): react.JSX.Element;
+
+interface TimestampProps {
+    date: Date;
+    /** Format style */
+    format?: 'time' | 'relative';
+    className?: string;
+}
+declare function Timestamp({ date, format, className }: TimestampProps): react.JSX.Element;
+
+type StatusType = 'online' | 'offline' | 'busy' | 'away';
+interface StatusBadgeProps {
+    status: StatusType;
+    label?: string;
+    showDot?: boolean;
+    className?: string;
+}
+declare function StatusBadge({ status, label, showDot, className, }: StatusBadgeProps): react.JSX.Element;
+
+type SystemMessageType = 'info' | 'warning' | 'error' | 'success';
+interface SystemMessageProps {
+    type?: SystemMessageType;
+    children: React.ReactNode;
+    className?: string;
+    /** Show icon */
+    showIcon?: boolean;
+}
+declare function SystemMessage({ type, children, className, showIcon, }: SystemMessageProps): react.JSX.Element;
+
+interface MessageActionsProps {
+    /** Content to copy */
+    content?: string;
+    /** Show copy button */
+    showCopy?: boolean;
+    /** Show vote buttons */
+    showVote?: boolean;
+    /** Show more button */
+    showMore?: boolean;
+    /** Current vote state */
+    vote?: 'up' | 'down' | null;
+    /** Vote callback */
+    onVote?: (vote: 'up' | 'down' | null) => void;
+    /** More options callback */
+    onMore?: () => void;
+    /** Custom actions */
+    children?: React.ReactNode;
+    className?: string;
+    /** Size variant */
+    size?: 'sm' | 'md';
+}
+declare function MessageActions({ content, showCopy, showVote, showMore, vote, onVote, onMore, children, className, size, }: MessageActionsProps): react.JSX.Element;
+
+interface PromptInputProps {
+    /** Current input value */
+    value: string;
+    /** Value change handler */
+    onChange: (value: string) => void;
+    /** Submit handler */
+    onSubmit: () => void;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disable input */
+    disabled?: boolean;
+    /** Loading state */
+    loading?: boolean;
+    /** Auto focus */
+    autoFocus?: boolean;
+    /** Show send button */
+    showSendButton?: boolean;
+    /** Custom send button content */
+    sendButtonContent?: React.ReactNode;
+    /** Additional actions (left side) */
+    leftActions?: React.ReactNode;
+    /** Additional actions (right side, before send) */
+    rightActions?: React.ReactNode;
+    /** Container class */
+    className?: string;
+    /** Input class */
+    inputClassName?: string;
+    /** Variant styling */
+    variant?: 'default' | 'minimal' | 'bordered';
+}
+declare const PromptInput: react.ForwardRefExoticComponent<PromptInputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface MultimodalInputProps {
+    /** Current input value */
+    value: string;
+    /** Value change handler */
+    onChange: (value: string) => void;
+    /** Submit handler */
+    onSubmit: () => void;
+    /** Current attachments */
+    attachments?: Attachment[];
+    /** Add attachment handler */
+    onAddAttachment?: (file: File) => void;
+    /** Remove attachment handler */
+    onRemoveAttachment?: (id: string) => void;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disable input */
+    disabled?: boolean;
+    /** Loading state */
+    loading?: boolean;
+    /** Show file button */
+    showFileButton?: boolean;
+    /** Show image button */
+    showImageButton?: boolean;
+    /** Show mic button */
+    showMicButton?: boolean;
+    /** Accepted file types */
+    acceptedFileTypes?: string;
+    /** Accepted image types */
+    acceptedImageTypes?: string;
+    /** Max file size in bytes */
+    maxFileSize?: number;
+    /** Container class */
+    className?: string;
+}
+declare const MultimodalInput: react.ForwardRefExoticComponent<MultimodalInputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface QuickRepliesProps {
+    /** Available quick replies */
+    replies: QuickReply[];
+    /** Click handler */
+    onSelect: (reply: QuickReply) => void;
+    /** Disable interactions */
+    disabled?: boolean;
+    /** Container class */
+    className?: string;
+    /** Pill variant */
+    variant?: 'default' | 'outline' | 'filled';
+    /** Size */
+    size?: 'sm' | 'md';
+}
+declare function QuickReplies({ replies, onSelect, disabled, className, variant, size, }: QuickRepliesProps): react.JSX.Element | null;
+
+interface TemplateSelectorProps {
+    /** Available templates */
+    templates: PromptTemplate[];
+    /** Template selection handler */
+    onSelect: (template: PromptTemplate, variables?: Record<string, string>) => void;
+    /** Optional category filter */
+    categories?: string[];
+    /** Show search */
+    showSearch?: boolean;
+    /** Container class */
+    className?: string;
+    /** Variant */
+    variant?: 'grid' | 'list';
+}
+declare function TemplateSelector({ templates, onSelect, categories, showSearch, className, variant, }: TemplateSelectorProps): react.JSX.Element;
+
+interface InlineSuggestionsInputProps {
+    /** Current input value */
+    value: string;
+    /** Value change handler */
+    onChange: (value: string) => void;
+    /** Get suggestions based on current input */
+    getSuggestions?: (input: string) => InlineSuggestion[];
+    /** Placeholder text */
+    placeholder?: string;
+    /** Disable input */
+    disabled?: boolean;
+    /** Container class */
+    className?: string;
+    /** Input class */
+    inputClassName?: string;
+    /** Debounce delay for suggestions */
+    debounceMs?: number;
+}
+declare const InlineSuggestionsInput: react.ForwardRefExoticComponent<InlineSuggestionsInputProps & react.RefAttributes<HTMLInputElement>>;
+
+interface FileDropZoneProps {
+    /** Current files */
+    files?: Attachment[];
+    /** Add files handler */
+    onAddFiles?: (files: Attachment[]) => void;
+    /** Remove file handler */
+    onRemoveFile?: (id: string) => void;
+    /** Accepted file types (e.g., "image/*,.pdf") */
+    accept?: string;
+    /** Max file size in bytes */
+    maxFileSize?: number;
+    /** Max number of files */
+    maxFiles?: number;
+    /** Disable interactions */
+    disabled?: boolean;
+    /** Container class */
+    className?: string;
+    /** Variant */
+    variant?: 'compact' | 'full';
+}
+declare function FileDropZone({ files, onAddFiles, onRemoveFile, accept, maxFileSize, // 10MB
+maxFiles, disabled, className, variant, }: FileDropZoneProps): react.JSX.Element;
+
+interface LibraryPrompt {
+    id: string;
+    title: string;
+    prompt: string;
+    description?: string;
+    category?: string;
+    tags?: string[];
+}
+interface PromptLibraryProps {
+    prompts: LibraryPrompt[];
+    /** Fired when a prompt is chosen. */
+    onSelect?: (prompt: LibraryPrompt) => void;
+    /** Enable the search box. */
+    searchable?: boolean;
+    /** Enable category filter chips. */
+    filterByCategory?: boolean;
+    className?: string;
+}
+declare function PromptLibrary({ prompts, onSelect, searchable, filterByCategory, className, }: PromptLibraryProps): react.JSX.Element;
+
+interface MessageWithStepsProps {
+    /** Steps to display */
+    steps: ExecutionStep[];
+    /** Title for the step list */
+    title?: string;
+    /** Show progress bar */
+    showProgress?: boolean;
+    /** Initially expanded step index */
+    defaultExpanded?: number;
+    /** Container class */
+    className?: string;
+    /** Footer content */
+    footer?: React.ReactNode;
+}
+declare function MessageWithSteps({ steps, title, showProgress, defaultExpanded, className, footer, }: MessageWithStepsProps): react.JSX.Element;
+
+interface MessageWithReasoningProps {
+    /** Reasoning steps */
+    steps: ReasoningStep[];
+    /** Final answer content */
+    children?: React.ReactNode;
+    /** Title for the reasoning section */
+    title?: string;
+    /** Show timing bar */
+    showTimingBar?: boolean;
+    /** Container class */
+    className?: string;
+    /** Actions to display after the answer */
+    actions?: React.ReactNode;
+}
+declare function MessageWithReasoning({ steps, children, title, showTimingBar, className, actions, }: MessageWithReasoningProps): react.JSX.Element;
+
+interface MessageWithFeedbackProps {
+    /** Message content */
+    children: React.ReactNode;
+    /** Current feedback state */
+    feedback?: MessageFeedback;
+    /** Feedback submission handler */
+    onFeedback?: (feedback: MessageFeedback) => void;
+    /** Available feedback categories */
+    categories?: FeedbackCategory[];
+    /** Show comment input */
+    showComment?: boolean;
+    /** Label for the feedback prompt */
+    promptLabel?: string;
+    /** Container class */
+    className?: string;
+}
+declare function MessageWithFeedback({ children, feedback: initialFeedback, onFeedback, categories, showComment, promptLabel, className, }: MessageWithFeedbackProps): react.JSX.Element;
+
+interface MessageWithAttachmentsProps {
+    /** Message content */
+    children?: React.ReactNode;
+    /** Attachments */
+    attachments: Attachment[];
+    /** Click handler for attachment */
+    onAttachmentClick?: (attachment: Attachment) => void;
+    /** Container class */
+    className?: string;
+    /** Attachment display variant */
+    variant?: 'compact' | 'card';
+}
+declare function MessageWithAttachments({ children, attachments, onAttachmentClick, className, variant, }: MessageWithAttachmentsProps): react.JSX.Element | null;
+
+interface MessageListProps {
+    messages: AgentMessage[];
+    /** Show avatars next to messages. */
+    showAvatars?: boolean;
+    /** Optional custom renderer; falls back to the built-in renderer. */
+    renderMessage?: (message: AgentMessage) => React.ReactNode;
+    /** Feedback handler passed to feedback-capable messages. */
+    onFeedback?: (messageId: string, vote: 'up' | 'down') => void;
+    className?: string;
+}
+/**
+ * Renders a list of AgentMessages. For each message it composes the optional
+ * rich sections (reasoning, steps) above the message bubble, then the bubble
+ * content, attachments, and any structured data payload. This is the default
+ * conversation body shared by every surface.
+ */
+declare function MessageList({ messages, showAvatars, renderMessage, className, }: MessageListProps): react.JSX.Element;
+
+interface PersonaSelectorProps {
+    /** Available personas to choose from. */
+    personas: AgentPersona[];
+    /** Currently selected persona id (controlled). */
+    selectedId?: string;
+    /** Selection handler. */
+    onSelect?: (persona: AgentPersona) => void;
+    /** Show the selected persona's system prompt preview. */
+    showSystemPrompt?: boolean;
+    /** Render personas as a horizontal row instead of a list. */
+    orientation?: 'vertical' | 'horizontal';
+    /** Optional icon resolver for a persona (defaults to a user icon). */
+    renderIcon?: (persona: AgentPersona) => React.ReactNode;
+    className?: string;
+}
+declare function PersonaSelector({ personas, selectedId, onSelect, showSystemPrompt, orientation, renderIcon, className, }: PersonaSelectorProps): react.JSX.Element;
+
+interface EntityField {
+    label: string;
+    value: string;
+    icon?: React.ReactNode;
+}
+interface EntityAction {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    variant?: 'default' | 'outline' | 'secondary' | 'ghost';
+    onClick?: () => void;
+}
+interface EntityCardData {
+    id: string;
+    /** Primary title (name of the person/place/item). */
+    title: string;
+    /** Secondary line under the title. */
+    subtitle?: string;
+    /** Avatar/image URL. */
+    imageUrl?: string;
+    /** Short descriptive text. */
+    description?: string;
+    /** Tags/labels. */
+    tags?: string[];
+    /** Structured key/value fields. */
+    fields?: EntityField[];
+    /** Optional status badge. */
+    status?: {
+        label: string;
+        tone?: 'neutral' | 'positive' | 'warning' | 'negative';
+    };
+}
+interface EntityCardProps {
+    entity: EntityCardData;
+    /** Actions rendered in the card footer. */
+    actions?: EntityAction[];
+    /** Card click handler. */
+    onClick?: (entity: EntityCardData) => void;
+    /** Compact layout. */
+    compact?: boolean;
+    className?: string;
+}
+declare function EntityCard({ entity, actions, onClick, compact, className }: EntityCardProps): react.JSX.Element;
+
+interface OptionCardItem {
+    id: string;
+    title: string;
+    description?: string;
+    imageUrl?: string;
+    /** Optional headline value (price, score, rating, etc.). */
+    value?: string;
+    /** Highlight chips. */
+    highlights?: string[];
+    /** Mark as recommended/featured. */
+    recommended?: boolean;
+    /** Disable selection. */
+    disabled?: boolean;
+}
+interface OptionCardsProps {
+    options: OptionCardItem[];
+    /** Selected option id(s). */
+    selectedIds?: string[];
+    /** Allow selecting more than one. */
+    multiple?: boolean;
+    /** Selection handler. */
+    onSelect?: (id: string, selectedIds: string[]) => void;
+    /** Label for the per-card action button. */
+    actionLabel?: string;
+    /** Per-card action handler (renders a button when provided). */
+    onAction?: (option: OptionCardItem) => void;
+    /** Layout columns. */
+    columns?: 1 | 2 | 3;
+    className?: string;
+}
+declare function OptionCards({ options, selectedIds, multiple, onSelect, actionLabel, onAction, columns, className, }: OptionCardsProps): react.JSX.Element;
+
+interface ListingField {
+    /** Optional leading icon. */
+    icon?: React.ReactNode;
+    /** Field value (e.g. "Remote", "$120/hr", "2 days ago"). */
+    value: string;
+}
+interface ListingAction {
+    id: string;
+    label: string;
+    variant?: 'default' | 'outline' | 'secondary' | 'ghost';
+    /** Stretch to fill available width. */
+    fill?: boolean;
+    onClick?: () => void;
+}
+interface Listing {
+    id: string;
+    /** Primary heading. */
+    title: string;
+    /** Secondary heading (source/organization/author). */
+    subtitle?: string;
+    /** Body description. */
+    description?: string;
+    /** Inline meta fields (location, value, date, etc.). */
+    fields?: ListingField[];
+    /** Tag chips. */
+    tags?: string[];
+    /** Per-card actions. */
+    actions?: ListingAction[];
+}
+interface ListingFeedProps {
+    listings: Listing[];
+    /** Set of bookmarked/saved ids (controlled). */
+    savedIds?: string[];
+    /** Toggle handler for the bookmark affordance. Hides the icon when omitted. */
+    onToggleSaved?: (id: string) => void;
+    /** Click handler for the whole card. */
+    onSelect?: (listing: Listing) => void;
+    className?: string;
+}
+declare function ListingFeed({ listings, savedIds, onToggleSaved, onSelect, className, }: ListingFeedProps): react.JSX.Element;
+
+type ControlTileType = 'toggle' | 'slider' | 'status' | 'action';
+interface ControlTile {
+    id: string;
+    label: string;
+    type: ControlTileType;
+    /** Optional leading icon. */
+    icon?: React.ReactNode;
+    /** Grouping key (rendered as a section header). */
+    group?: string;
+    /** toggle: on/off state. */
+    on?: boolean;
+    /** slider: current numeric value. */
+    value?: number;
+    /** slider: bounds + step. */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** slider: unit suffix shown next to the value (e.g. "%", "°"). */
+    unit?: string;
+    /** status: free-form descriptor shown under the label. */
+    statusLabel?: string;
+    /** status tone -> color. */
+    statusTone?: 'neutral' | 'positive' | 'warning' | 'negative';
+    /** action: button label. */
+    actionLabel?: string;
+    /** Disable the tile. */
+    disabled?: boolean;
+}
+interface ControlGridProps {
+    tiles: ControlTile[];
+    /** Number of columns. */
+    columns?: 1 | 2 | 3;
+    /** Toggle handler (type: toggle). */
+    onToggle?: (id: string, next: boolean) => void;
+    /** Slider change handler (type: slider). */
+    onValueChange?: (id: string, value: number) => void;
+    /** Action handler (type: action). */
+    onAction?: (id: string) => void;
+    className?: string;
+}
+declare function ControlGrid({ tiles, columns, onToggle, onValueChange, onAction, className, }: ControlGridProps): react.JSX.Element;
+
+type RecommendationTone = 'suggestion' | 'caution' | 'positive' | 'info';
+interface RecommendationAction {
+    id: string;
+    label: string;
+    variant?: 'default' | 'outline' | 'secondary' | 'ghost';
+    onClick?: () => void;
+}
+interface Recommendation {
+    id: string;
+    /** Headline recommendation. */
+    title: string;
+    /** Supporting explanation of *why* this is recommended. */
+    rationale: string;
+    /** Tone drives icon + accent color. */
+    tone?: RecommendationTone;
+    /** Optional confidence/priority chip text (e.g. "High priority"). */
+    badge?: string;
+    /** Optional structured impact line (e.g. "Expected change: +5%"). */
+    impact?: string;
+    /** Actions the user can take on this recommendation. */
+    actions?: RecommendationAction[];
+}
+interface RecommendationCardsProps {
+    recommendations: Recommendation[];
+    className?: string;
+}
+declare function RecommendationCards({ recommendations, className }: RecommendationCardsProps): react.JSX.Element;
+
+type AgendaItemState = 'upcoming' | 'active' | 'done';
+interface AgendaSlotOption {
+    id: string;
+    label: string;
+}
+interface AgendaItemAction {
+    id: string;
+    label: string;
+    variant?: 'default' | 'outline' | 'secondary' | 'ghost';
+    onClick?: () => void;
+}
+interface AgendaItem {
+    id: string;
+    /** Time label (e.g. "10:00 AM", "Day 1 · 14:00"). */
+    time: string;
+    /** Optional end/duration label. */
+    duration?: string;
+    /** Title of the slot/session. */
+    title: string;
+    /** Secondary line (location, host, track). */
+    subtitle?: string;
+    /** Body description. */
+    description?: string;
+    /** Tag chips. */
+    tags?: string[];
+    /** Lifecycle state -> visual emphasis. */
+    state?: AgendaItemState;
+    /** Selectable proposed time options (rendered as buttons). */
+    options?: AgendaSlotOption[];
+    /** Per-item actions. */
+    actions?: AgendaItemAction[];
+}
+interface ScheduleTimelineProps {
+    items: AgendaItem[];
+    /** Selected option id (controlled). */
+    selectedOptionId?: string;
+    /** Option selection handler. */
+    onSelectOption?: (itemId: string, optionId: string) => void;
+    className?: string;
+}
+declare function ScheduleTimeline({ items, selectedOptionId, onSelectOption, className, }: ScheduleTimelineProps): react.JSX.Element;
+
+type SettingControlType = 'toggle' | 'select' | 'radio';
+interface SettingControl {
+    id: string;
+    label: string;
+    description?: string;
+    type: SettingControlType;
+    /** Current value: boolean for toggle, string for select/radio. */
+    value: boolean | string;
+    /** Options for select/radio. */
+    options?: Array<{
+        label: string;
+        value: string;
+    }>;
+    disabled?: boolean;
+}
+interface SettingsGroup {
+    id: string;
+    title?: string;
+    description?: string;
+    controls: SettingControl[];
+}
+interface SettingsPanelProps {
+    groups: SettingsGroup[];
+    /** Change handler: emits the control id and its new value. */
+    onChange?: (controlId: string, value: boolean | string) => void;
+    className?: string;
+}
+declare function SettingsPanel({ groups, onChange, className }: SettingsPanelProps): react.JSX.Element;
+
+/**
+ * Lifecycle of an agent-to-agent handoff.
+ *  - 'connecting' → the target agent is being brought online / routed to.
+ *  - 'handed-off' → control has transferred to the target agent.
+ *  - 'active'     → the target agent is now actively handling the request.
+ */
+type HandoffStatus = 'connecting' | 'handed-off' | 'active';
+/** Visual presentation of a handoff. */
+type HandoffVariant = 
+/** Simple A → B transition. */
+'direct'
+/** A → specialist B, foregrounding the routing reason. */
+ | 'routing'
+/** Triage: route a request to one of several candidate agents. */
+ | 'triage';
+/** A single agent participating in a handoff. Fully data-driven. */
+interface HandoffAgent {
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Role / specialty line (e.g. "Project Management"). */
+    specialty?: string;
+    /** Avatar/thumbnail image URL. */
+    avatarUrl?: string;
+}
+/** A candidate target in a triage handoff, with a match signal. */
+interface HandoffCandidate extends HandoffAgent {
+    /** Why this candidate matches the request. */
+    reason?: string;
+    /** Optional 0–100 match/confidence used to mark + sort the selected one. */
+    match?: number;
+    /** Marks the candidate the request is being routed to. */
+    selected?: boolean;
+}
+interface HandoffAction {
+    id: string;
+    label: string;
+    variant?: 'primary' | 'secondary';
+    onClick?: () => void;
+}
+interface AgentHandoffProps {
+    /** Layout/semantics of the handoff. Defaults to 'direct'. */
+    variant?: HandoffVariant;
+    /** The agent handing the request off. */
+    from: HandoffAgent;
+    /**
+     * The agent receiving the request. Required for 'direct'/'routing'. For
+     * 'triage', omit and supply `candidates` instead (the selected candidate is
+     * treated as the target).
+     */
+    to?: HandoffAgent;
+    /** Candidate agents for a 'triage' handoff. */
+    candidates?: HandoffCandidate[];
+    /** Short reason/context line for the handoff. */
+    reason?: string;
+    /** Current handoff status. Defaults to 'connecting'. */
+    status?: HandoffStatus;
+    /** Optional action buttons (e.g. accept/continue). */
+    actions?: HandoffAction[];
+    className?: string;
+}
+/**
+ * AgentHandoff visualizes a handoff between specialized AI agents based on
+ * request type (onboarding / routing). It supports several variants — a direct
+ * A→B transition, a "routing to specialist" with a reason, and a multi-agent
+ * triage that routes a request to one of several candidates. Everything is
+ * driven by typed props: the component hardcodes no names, specialties, or
+ * images.
+ */
+declare function AgentHandoff({ variant, from, to, candidates, reason, status, actions, className, }: AgentHandoffProps): react.JSX.Element;
+
+interface ChartContainerProps {
+    /** Chart configuration */
+    data: ChartData;
+    /** Height of chart */
+    height?: number;
+    /** Show download button */
+    showDownload?: boolean;
+    /** Show insight */
+    showInsight?: boolean;
+    /** Download handler */
+    onDownload?: () => void;
+    /** Container class */
+    className?: string;
+    /** Color palette */
+    colors?: string[];
+}
+declare function ChartContainer({ data, height, showDownload, showInsight, onDownload, className, colors, }: ChartContainerProps): react.JSX.Element;
+
+interface MetricsGridProps {
+    /** Metrics to display */
+    metrics: MetricData[];
+    /** Number of columns */
+    columns?: 2 | 3 | 4;
+    /** Container class */
+    className?: string;
+    /** Variant */
+    variant?: 'card' | 'compact';
+}
+declare function MetricsGrid({ metrics, columns, className, variant, }: MetricsGridProps): react.JSX.Element;
+
+interface DataTableProps {
+    /** Table data */
+    data: TableData;
+    /** Sort column */
+    sortColumn?: string;
+    /** Sort direction */
+    sortDirection?: 'asc' | 'desc';
+    /** Sort change handler */
+    onSort?: (column: string) => void;
+    /** Row click handler */
+    onRowClick?: (row: Record<string, unknown>) => void;
+    /** Container class */
+    className?: string;
+    /** Compact mode */
+    compact?: boolean;
+    /** Max height with scroll */
+    maxHeight?: number;
+}
+declare function DataTable({ data, sortColumn, sortDirection, onSort, onRowClick, className, compact, maxHeight, }: DataTableProps): react.JSX.Element;
+
+type ProgressStepStatus = 'complete' | 'active' | 'pending' | 'error';
+interface ProgressStep {
+    id: string;
+    label: string;
+    description?: string;
+    status: ProgressStepStatus;
+}
+interface ProgressTrackerProps {
+    /** Steps to display */
+    steps: ProgressStep[];
+    /** Orientation */
+    orientation?: 'horizontal' | 'vertical';
+    /** Container class */
+    className?: string;
+    /** Show progress percentage */
+    showPercentage?: boolean;
+    /** Compact mode */
+    compact?: boolean;
+}
+declare function ProgressTracker({ steps, orientation, className, showPercentage, compact, }: ProgressTrackerProps): react.JSX.Element;
+
+interface SentimentDisplayProps {
+    sentiment: SentimentScore;
+    /** Show the per-emotion breakdown bars. */
+    showEmotions?: boolean;
+    /** Show the numeric confidence. */
+    showConfidence?: boolean;
+    className?: string;
+}
+declare function SentimentDisplay({ sentiment, showEmotions, showConfidence, className, }: SentimentDisplayProps): react.JSX.Element;
+
+interface DataPayloadViewProps {
+    payload: DataPayload;
+    className?: string;
+}
+/** Renders any DataPayload via the appropriate data-display component. */
+declare function DataPayloadView({ payload, className }: DataPayloadViewProps): react.JSX.Element | null;
+interface ReportViewProps {
+    report: AgentReport;
+    className?: string;
+}
+/**
+ * Renders a structured AgentReport as a sequence of titled sections. Used as
+ * the default content for the expand-to-dashboard surface.
+ */
+declare function ReportView({ report, className }: ReportViewProps): react.JSX.Element;
+
+type MediaKind = 'image' | 'video' | 'file' | 'link';
+interface MediaItem {
+    id: string;
+    kind: MediaKind;
+    /** Title/filename shown under or over the item. */
+    label: string;
+    /** Thumbnail/preview image URL (images & video). */
+    thumbnailUrl?: string;
+    /** Full-size/source URL for preview, download, or open. */
+    url?: string;
+    /** Secondary line (size, domain, author, date, etc.). */
+    meta?: string;
+    /** Free-form group key used by the grouping tabs. */
+    group?: string;
+    /** Solid background swatch for thumbnail-less items. */
+    swatchClassName?: string;
+}
+interface MediaGalleryProps {
+    items: MediaItem[];
+    /** Group items into filter tabs by `group` (falls back to kind). */
+    groupBy?: 'group' | 'kind' | 'none';
+    /** Number of columns in the image/video grid. */
+    columns?: 2 | 3 | 4;
+    /** Open a lightbox/preview when an item is activated. */
+    enablePreview?: boolean;
+    /** Per-item primary action (download/open). Renders a button when provided. */
+    onItemAction?: (item: MediaItem) => void;
+    /** Item click handler (fires alongside preview). */
+    onItemClick?: (item: MediaItem) => void;
+    /** Footer "view all" action. */
+    onViewAll?: () => void;
+    className?: string;
+}
+declare function MediaGallery({ items, groupBy, columns, enablePreview, onItemAction, onItemClick, onViewAll, className, }: MediaGalleryProps): react.JSX.Element;
+
+interface AllocationSegment {
+    id: string;
+    /** Segment label. */
+    label: string;
+    /** Optional secondary descriptor. */
+    description?: string;
+    /** Weight (0-100). Rows are sorted as provided. */
+    weight: number;
+    /** Optional formatted magnitude (e.g. "$50K", "1.2k units"). */
+    amount?: string;
+    /** Optional signed delta shown with tone (e.g. "+12.3%"). */
+    delta?: number;
+    /** Categorical tag rendered as a badge. */
+    tag?: string;
+    /** Tag tone. */
+    tone?: 'neutral' | 'positive' | 'warning' | 'negative';
+    /** Bar fill color class (defaults to a palette by index). */
+    colorClassName?: string;
+}
+interface AllocationSummaryStat {
+    label: string;
+    value: string;
+}
+interface AllocationBreakdownProps {
+    segments: AllocationSegment[];
+    /** Optional headline stats grid shown above the rows. */
+    summary?: AllocationSummaryStat[];
+    /** Show the proportional stacked bar at the top. */
+    showStackedBar?: boolean;
+    className?: string;
+}
+declare function AllocationBreakdown({ segments, summary, showStackedBar, className, }: AllocationBreakdownProps): react.JSX.Element;
+
+type TrendTone = 'positive' | 'negative' | 'neutral';
+interface AnalyticsTrend {
+    /** Magnitude shown next to the arrow (e.g. 12.4 → "12.4%"). */
+    value: number;
+    /** Visual direction of the arrow. Defaults to value sign. */
+    direction?: 'up' | 'down';
+    /** Color treatment; lets "down is good" cases stay green. */
+    tone?: TrendTone;
+}
+interface AnalyticsMetric {
+    id: string;
+    label: string;
+    value: string | number;
+    /** Optional suffix rendered after the value (e.g. "/5"). */
+    unit?: string;
+    icon?: React.ReactNode;
+    trend?: AnalyticsTrend;
+}
+interface AnalyticsDistributionSegment {
+    id: string;
+    label: string;
+    /** Percentage of the whole (0–100). */
+    value: number;
+    /** Tailwind background class for bar + legend dot. */
+    colorClassName?: string;
+}
+interface AnalyticsHighlight {
+    label: string;
+    /** Big formatted value, e.g. "87%". */
+    value: string;
+    /** Progress fill 0–100. Defaults to a numeric parse of value. */
+    progress?: number;
+    icon?: React.ReactNode;
+    trend?: AnalyticsTrend;
+    colorClassName?: string;
+}
+interface AnalyticsBreakdownRow {
+    id: string;
+    label: string;
+    /** Bar fill 0–100. */
+    percentage: number;
+    /** Secondary count/measure rendered on the right. */
+    count?: string | number;
+    trend?: AnalyticsTrend;
+}
+interface AnalyticsRankedRow {
+    id: string;
+    label: string;
+    /** Bar fill 0–100. */
+    percentage: number;
+    /** Right-aligned value label (e.g. "0.8s"). */
+    value: string;
+    colorClassName?: string;
+}
+interface AnalyticsRecentItem {
+    id: string;
+    label: string;
+    /** Category/secondary label. */
+    category?: string;
+    /** Status dot tone. */
+    tone?: TrendTone;
+    /** Right-aligned meta fields (e.g. ["12 msgs", "4m 22s"]). */
+    meta?: string[];
+    /** Optional 0–5 rating rendered as filled/empty dots. */
+    rating?: number;
+    /** Relative time label (e.g. "5 min ago"). */
+    time?: string;
+}
+interface AnalyticsDashboardProps {
+    /** Header title. */
+    title?: string;
+    /** Range pill text (e.g. "Last 30 days"). */
+    range?: string;
+    /** Right-aligned summary count text (e.g. "2,847 records"). */
+    summary?: string;
+    /** Top KPI cards (typically 3). */
+    metrics?: AnalyticsMetric[];
+    /** Distribution segmented bar. */
+    distribution?: AnalyticsDistributionSegment[];
+    /** Label for the distribution block. */
+    distributionLabel?: string;
+    /** Highlighted single % metric beside the distribution. */
+    highlight?: AnalyticsHighlight;
+    /** Left "breakdown" list. */
+    breakdown?: AnalyticsBreakdownRow[];
+    breakdownLabel?: string;
+    /** Right "ranked / percentile" list. */
+    ranked?: AnalyticsRankedRow[];
+    rankedLabel?: string;
+    /** Bottom recent-items list. */
+    recentItems?: AnalyticsRecentItem[];
+    recentLabel?: string;
+    className?: string;
+}
+/**
+ * AnalyticsDashboard renders a polished, fully responsive analytics report:
+ * a header with range pill + summary, KPI cards, a distribution bar + a
+ * highlighted metric, a two-column breakdown/ranked pair, and a recent-items
+ * list. Every multi-column row collapses to a single column on narrow surfaces
+ * (panel/widget/split). All content is prop-driven and industry-agnostic.
+ */
+declare function AnalyticsDashboard({ title, range, summary, metrics, distribution, distributionLabel, highlight, breakdown, breakdownLabel, ranked, rankedLabel, recentItems, recentLabel, className, }: AnalyticsDashboardProps): react.JSX.Element;
+
+interface ConversationArtifactProps {
+    /** Rich content (a data-display component) rendered inside the assistant turn. */
+    children: ReactNode;
+    /** Optional intro text shown as a bubble above the artifact. */
+    intro?: string;
+    /** Optional caption shown below the artifact. */
+    caption?: string;
+    /** Show the assistant avatar. */
+    showAvatar?: boolean;
+    className?: string;
+}
+/**
+ * ConversationArtifact wraps an arbitrary rich-content node (chart, gallery,
+ * report, etc.) as an assistant conversation turn so an orchestrator can drop
+ * any data-display component directly into a message thread. It reuses the
+ * shared message primitives (container + avatar + bubble) so it lines up with
+ * the rest of the conversation across every surface. Purely presentational and
+ * industry-agnostic — the artifact is supplied via `children`.
+ */
+declare function ConversationArtifact({ children, intro, caption, showAvatar, className, }: ConversationArtifactProps): react.JSX.Element;
+
+interface StylePreset {
+    id: string;
+    label: string;
+    description?: string;
+}
+interface AspectRatio {
+    id: string;
+    label: string;
+    value: string;
+    dimensions: string;
+}
+interface GeneratedImage {
+    id: string;
+    url?: string;
+    prompt: string;
+    style?: string;
+    aspectRatio?: string;
+    seed?: string;
+    model?: string;
+    steps?: number;
+    timestamp: Date;
+    isFavorite?: boolean;
+}
+interface ImageGeneratorProps {
+    /** Available style presets */
+    stylePresets?: StylePreset[];
+    /** Available aspect ratios */
+    aspectRatios?: AspectRatio[];
+    /** Initial prompt value */
+    initialPrompt?: string;
+    /** Quality options */
+    qualityOptions?: Array<{
+        id: string;
+        label: string;
+    }>;
+    /** Generated images */
+    images?: GeneratedImage[];
+    /** Callback when generation is requested */
+    onGenerate?: (params: {
+        prompt: string;
+        style: string;
+        aspectRatio: string;
+        quality: string;
+    }) => void;
+    /** Callback when image is selected */
+    onSelectImage?: (image: GeneratedImage) => void;
+    /** Callback when image is downloaded */
+    onDownload?: (image: GeneratedImage) => void;
+    /** Callback when seed is copied */
+    onCopySeed?: (seed: string) => void;
+    /** Callback when shuffle/regenerate is requested */
+    onShuffle?: (image: GeneratedImage) => void;
+    /** Loading state */
+    isGenerating?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+declare function ImageGenerator({ stylePresets, aspectRatios, qualityOptions, initialPrompt, images, onGenerate, onSelectImage, onDownload, onCopySeed, onShuffle, isGenerating, className, }: ImageGeneratorProps): react.JSX.Element;
+
+interface WritingTone {
+    id: string;
+    label: string;
+    description?: string;
+}
+interface WritingFormat {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+}
+interface WritingAction {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    description?: string;
+}
+interface WritingAssistantProps {
+    /** Initial content */
+    initialContent?: string;
+    /** Available tones */
+    tones?: WritingTone[];
+    /** Available formats */
+    formats?: WritingFormat[];
+    /** Available actions */
+    actions?: WritingAction[];
+    /** Callback when content changes */
+    onChange?: (content: string) => void;
+    /** Callback when action is triggered */
+    onAction?: (actionId: string, content: string, options: {
+        tone: string;
+        format: string;
+    }) => void;
+    /** Loading state */
+    isProcessing?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+declare function WritingAssistant({ initialContent, tones, formats, actions, onChange, onAction, isProcessing, className, }: WritingAssistantProps): react.JSX.Element;
+
+interface QuizOption {
+    id: string;
+    text: string;
+}
+interface QuizQuestion {
+    id: string;
+    question: string;
+    options: QuizOption[];
+    correctOptionId: string;
+    explanation?: string;
+    hint?: string;
+    category?: string;
+    difficulty?: 'easy' | 'medium' | 'hard';
+}
+interface QuizResult {
+    questionId: string;
+    selectedOptionId: string | null;
+    isCorrect: boolean;
+    timeSpent?: number;
+}
+interface QuizCardProps {
+    /** Questions to display */
+    questions: QuizQuestion[];
+    /** Current question index (controlled) */
+    currentIndex?: number;
+    /** Callback when answer is selected */
+    onAnswer?: (questionId: string, optionId: string, isCorrect: boolean) => void;
+    /** Callback when quiz is completed */
+    onComplete?: (results: QuizResult[]) => void;
+    /** Callback when next question is requested */
+    onNext?: () => void;
+    /** Show hints */
+    showHints?: boolean;
+    /** Show explanations after answering */
+    showExplanations?: boolean;
+    /** Allow retrying wrong answers */
+    allowRetry?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+declare function QuizCard({ questions, currentIndex: controlledIndex, onAnswer, onComplete, onNext, showHints, showExplanations, allowRetry, className, }: QuizCardProps): react.JSX.Element;
+
+interface OnboardingStep {
+    id: string;
+    title: string;
+    description: string;
+    content?: React.ReactNode;
+    image?: string;
+    isComplete?: boolean;
+    isSkippable?: boolean;
+    action?: {
+        label: string;
+        onClick: () => void | Promise<void>;
+    };
+}
+interface OnboardingWizardProps {
+    /** Steps to display */
+    steps: OnboardingStep[];
+    /** Current step index (controlled) */
+    currentStep?: number;
+    /** Callback when step changes */
+    onStepChange?: (index: number) => void;
+    /** Callback when onboarding is completed */
+    onComplete?: () => void;
+    /** Callback when onboarding is skipped */
+    onSkip?: () => void;
+    /** Allow skipping */
+    allowSkip?: boolean;
+    /** Show progress indicator */
+    showProgress?: boolean;
+    /** Custom class name */
+    className?: string;
+}
+declare function OnboardingWizard({ steps, currentStep: controlledStep, onStepChange, onComplete, onSkip, allowSkip, showProgress, className, }: OnboardingWizardProps): react.JSX.Element | null;
+
+interface LessonStep {
+    id: string;
+    /** Step title. */
+    title: string;
+    /** Body content. Supports **bold** segments and blank-line paragraphs. */
+    content: string;
+    /** Optional short label for the step rail/tooltip. */
+    shortLabel?: string;
+    /** Optional knowledge check shown after the content. */
+    quiz?: QuizQuestion[];
+    /** Require a correct quiz answer before advancing. */
+    requireQuizPass?: boolean;
+}
+interface GuidedLessonFlowProps {
+    steps: LessonStep[];
+    /** Controlled current step index. */
+    currentIndex?: number;
+    /** Title shown in the header. */
+    title?: string;
+    /** Optional level/track chip. */
+    badge?: string;
+    /** Step change handler. */
+    onStepChange?: (index: number) => void;
+    /** Quiz answer handler (bubbled from the embedded QuizCard). */
+    onAnswer?: (stepId: string, questionId: string, optionId: string, isCorrect: boolean) => void;
+    /** Completion handler. */
+    onComplete?: () => void;
+    className?: string;
+}
+declare function GuidedLessonFlow({ steps, currentIndex: controlledIndex, title, badge, onStepChange, onAnswer, onComplete, className, }: GuidedLessonFlowProps): react.JSX.Element;
+
+interface EditorTool {
+    id: string;
+    label: string;
+    icon?: React.ReactNode;
+    /** Swatch/preview color for tool tiles without an icon. */
+    swatch?: string;
+}
+interface EditorAdjustment {
+    id: string;
+    label: string;
+    value: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface MediaEditorCanvasProps {
+    /** Source image URL for the canvas. Falls back to a placeholder tile. */
+    sourceUrl?: string;
+    /** Result/preview image URL (used for the "after" comparison view). */
+    previewUrl?: string;
+    /** Selectable tools (filters/presets/crop/etc.). */
+    tools?: EditorTool[];
+    /** Active tool id (controlled). */
+    activeToolId?: string;
+    /** Continuous adjustment controls. */
+    adjustments?: EditorAdjustment[];
+    /** Enable the before/after comparison toggle. */
+    enableCompare?: boolean;
+    /** Labels for the compare toggle. */
+    beforeLabel?: string;
+    afterLabel?: string;
+    onSelectTool?: (id: string) => void;
+    onAdjust?: (id: string, value: number) => void;
+    onReset?: () => void;
+    onSave?: () => void;
+    className?: string;
+}
+declare function MediaEditorCanvas({ sourceUrl, previewUrl, tools, activeToolId, adjustments, enableCompare, beforeLabel, afterLabel, onSelectTool, onAdjust, onReset, onSave, className, }: MediaEditorCanvasProps): react.JSX.Element;
+
+interface ConversationMetric {
+    id: string;
+    label: string;
+    value: number | string;
+    change?: number;
+    changeLabel?: string;
+    icon?: React.ReactNode;
+}
+interface TopicData {
+    topic: string;
+    count: number;
+    percentage: number;
+}
+interface SentimentData {
+    sentiment: 'positive' | 'negative' | 'neutral';
+    value: number;
+}
+interface TimelineData {
+    date: string;
+    messages: number;
+    responses: number;
+}
+interface ConversationAnalyticsProps {
+    /** Key metrics to display */
+    metrics?: ConversationMetric[];
+    /** Topics discussed */
+    topics?: TopicData[];
+    /** Sentiment breakdown */
+    sentiment?: SentimentData[];
+    /** Messages over time */
+    timeline?: TimelineData[];
+    /** Time period label */
+    period?: string;
+    /** Custom class name */
+    className?: string;
+}
+declare function ConversationAnalytics({ metrics, topics, sentiment, timeline, period, className, }: ConversationAnalyticsProps): react.JSX.Element;
+
+interface PerformanceMetric {
+    id: string;
+    label: string;
+    value: number | string;
+    unit?: string;
+    change?: number;
+    status?: 'good' | 'warning' | 'error';
+    icon?: React.ReactNode;
+}
+interface LatencyData {
+    time: string;
+    p50: number;
+    p95: number;
+    p99: number;
+}
+interface TokenUsageData {
+    date: string;
+    input: number;
+    output: number;
+}
+interface ErrorData {
+    type: string;
+    count: number;
+    percentage: number;
+}
+interface PerformanceMetricsProps {
+    /** Key metrics */
+    metrics?: PerformanceMetric[];
+    /** Latency over time */
+    latency?: LatencyData[];
+    /** Token usage */
+    tokenUsage?: TokenUsageData[];
+    /** Error breakdown */
+    errors?: ErrorData[];
+    /** Time period */
+    period?: string;
+    /** Custom class name */
+    className?: string;
+}
+declare function PerformanceMetrics({ metrics, latency, tokenUsage, errors, period, className, }: PerformanceMetricsProps): react.JSX.Element;
+
+interface ChatPanelProps {
+    /** Panel title */
+    title?: string;
+    /** Panel subtitle or status */
+    subtitle?: string;
+    /** Header icon */
+    icon?: React.ReactNode;
+    /** Header actions (right side) */
+    headerActions?: React.ReactNode;
+    /** Messages content */
+    children: React.ReactNode;
+    /** Input component */
+    input?: React.ReactNode;
+    /** Quick replies or suggestions (above input) */
+    suggestions?: React.ReactNode;
+    /** Footer content (below input) */
+    footer?: React.ReactNode;
+    /** Is loading/typing */
+    isLoading?: boolean;
+    /** Auto-scroll to bottom */
+    autoScroll?: boolean;
+    /** Container class */
+    className?: string;
+    /** Content class */
+    contentClassName?: string;
+    /** Fixed height or flexible */
+    height?: number | string;
+    /** Model selector (in header) */
+    modelSelector?: React.ReactNode;
+}
+declare function ChatPanel({ title, subtitle, icon, headerActions, children, input, suggestions, footer, isLoading, autoScroll, className, contentClassName, height, modelSelector, }: ChatPanelProps): react.JSX.Element;
+
+interface FloatingWidgetProps {
+    /** Is widget open */
+    isOpen: boolean;
+    /** Is widget minimized */
+    isMinimized?: boolean;
+    /** Toggle open state */
+    onToggle: () => void;
+    /** Toggle minimized state */
+    onMinimize?: () => void;
+    /** Close widget */
+    onClose?: () => void;
+    /** Widget title */
+    title?: string;
+    /** Widget icon */
+    icon?: React.ReactNode;
+    /** Online status */
+    status?: 'online' | 'offline' | 'busy' | 'away';
+    /** Unread message count */
+    unreadCount?: number;
+    /** Messages content */
+    children: React.ReactNode;
+    /** Input component */
+    input?: React.ReactNode;
+    /** Quick replies */
+    quickReplies?: React.ReactNode;
+    /** Footer (e.g., "Powered by...") */
+    footer?: React.ReactNode;
+    /** Is loading/typing */
+    isLoading?: boolean;
+    /** Position on screen */
+    position?: WidgetPosition;
+    /** Widget width */
+    width?: number;
+    /** Widget height */
+    height?: number;
+    /** Container class */
+    className?: string;
+    /** Show minimizable button */
+    showMinimize?: boolean;
+    /** Show close button */
+    showClose?: boolean;
+}
+declare function FloatingWidget({ isOpen, isMinimized, onToggle, onMinimize, onClose, title, icon, status, unreadCount, children, input, quickReplies, footer, isLoading, position, width, height, className, showMinimize, showClose, }: FloatingWidgetProps): react.JSX.Element;
+
+interface OverlayModalProps {
+    /** Is modal open */
+    isOpen: boolean;
+    /** Close handler */
+    onClose: () => void;
+    /** Modal title */
+    title?: string;
+    /** Avatar/agent info */
+    agent?: {
+        name: string;
+        avatar?: string;
+        initials?: string;
+        status?: string;
+    };
+    /** Messages content */
+    children: React.ReactNode;
+    /** Input component */
+    input?: React.ReactNode;
+    /** Is loading/typing */
+    isLoading?: boolean;
+    /** Modal width */
+    width?: number | string;
+    /** Modal height */
+    height?: number | string;
+    /** Container class */
+    className?: string;
+    /** Backdrop class */
+    backdropClassName?: string;
+    /** Close on backdrop click */
+    closeOnBackdrop?: boolean;
+}
+declare function OverlayModal({ isOpen, onClose, title, agent, children, input, isLoading, width, height, className, backdropClassName, closeOnBackdrop, }: OverlayModalProps): react.JSX.Element;
+
+interface FullscreenDashboardProps {
+    /** Is fullscreen active */
+    isFullscreen?: boolean;
+    /** Exit fullscreen handler */
+    onExitFullscreen?: () => void;
+    /** Title */
+    title?: string;
+    /** Header actions */
+    headerActions?: React.ReactNode;
+    /** Main content (chat area) */
+    children: React.ReactNode;
+    /** Sidebar content (optional) */
+    sidebar?: React.ReactNode;
+    /** Input component */
+    input?: React.ReactNode;
+    /** Is loading */
+    isLoading?: boolean;
+    /** Sidebar position */
+    sidebarPosition?: 'left' | 'right';
+    /** Sidebar width */
+    sidebarWidth?: number;
+    /** Show sidebar toggle */
+    showSidebarToggle?: boolean;
+    /** Sidebar is collapsed */
+    isSidebarCollapsed?: boolean;
+    /** Toggle sidebar */
+    onToggleSidebar?: () => void;
+    /** Container class */
+    className?: string;
+}
+declare function FullscreenDashboard({ isFullscreen, onExitFullscreen, title, headerActions, children, sidebar, input, isLoading, sidebarPosition, sidebarWidth, showSidebarToggle, isSidebarCollapsed, onToggleSidebar, className, }: FullscreenDashboardProps): react.JSX.Element;
+
+interface SplitViewProps {
+    /** Chat/main content (left side) */
+    children: React.ReactNode;
+    /** Data panel content (right side) */
+    dataPanel: React.ReactNode;
+    /** Chat input */
+    input?: React.ReactNode;
+    /** Is loading */
+    isLoading?: boolean;
+    /** Initial split ratio (0-1) */
+    initialSplit?: number;
+    /** Minimum panel width in pixels */
+    minPanelWidth?: number;
+    /** Is data panel collapsed */
+    isCollapsed?: boolean;
+    /** Toggle collapse */
+    onToggleCollapse?: () => void;
+    /** Resizable */
+    resizable?: boolean;
+    /** Container class */
+    className?: string;
+    /** Chat panel title */
+    chatTitle?: string;
+    /** Data panel title */
+    dataPanelTitle?: string;
+}
+declare function SplitView({ children, dataPanel, input, isLoading, initialSplit, minPanelWidth, isCollapsed, onToggleCollapse, resizable, className, chatTitle, dataPanelTitle, }: SplitViewProps): react.JSX.Element;
+
+interface MobileShellProps {
+    /** Title */
+    title?: string;
+    /** Subtitle */
+    subtitle?: string;
+    /** Back button handler */
+    onBack?: () => void;
+    /** More options handler */
+    onMore?: () => void;
+    /** Status */
+    status?: 'online' | 'offline' | 'busy' | 'away';
+    /** Messages content */
+    children: React.ReactNode;
+    /** Input component */
+    input?: React.ReactNode;
+    /** Quick replies */
+    quickReplies?: React.ReactNode;
+    /** Is loading */
+    isLoading?: boolean;
+    /** Container class */
+    className?: string;
+    /** Safe area insets */
+    safeArea?: boolean;
+}
+declare function MobileShell({ title, subtitle, onBack, onMore, status, children, input, quickReplies, isLoading, className, safeArea, }: MobileShellProps): react.JSX.Element;
+
+interface FullBleedSurfaceProps {
+    /** The artifact (chart, gallery, editor, generator, etc.) rendered edge-to-edge. */
+    children: ReactNode;
+    /** Surface title shown in the header. */
+    title?: string;
+    /** Optional icon shown before the title. */
+    icon?: ReactNode;
+    /** Optional header actions (right side, before the exit control). */
+    headerActions?: ReactNode;
+    /**
+     * Exit handler. When provided, an X control is shown and Esc returns to the
+     * previous surface. The host decides where "exit" goes (typically panel).
+     */
+    onExit?: () => void;
+    /** Accessible label / tooltip for the exit control. */
+    exitLabel?: string;
+    /** Treat as an overlay (fixed inset). When false, fills its parent (h-full). */
+    overlay?: boolean;
+    className?: string;
+}
+/**
+ * FullBleedSurface presents a single large artifact using the entire available
+ * surface — no conversation column, no composer, no max-width cap. It exists so
+ * an orchestrator can promote a big visualization (analytics dashboard, media
+ * gallery, generator, editor, …) to a maximum-real-estate layout for the
+ * fullscreen and split surfaces, where the goal is visibility rather than chat.
+ *
+ * Purely presentational and industry-agnostic — the artifact is supplied via
+ * `children` and is responsible for its own internal scrolling/layout.
+ */
+declare function FullBleedSurface({ children, title, icon, headerActions, onExit, exitLabel, overlay, className, }: FullBleedSurfaceProps): react.JSX.Element;
+
+interface AgentSurfaceProps {
+    /** Which rendering surface to present. */
+    mode: LayoutMode;
+    /** Conversation messages rendered by the shared MessageList. */
+    messages: AgentMessage[];
+    /** Loading/typing indicator state. */
+    isLoading?: boolean;
+    /** Current draft value. If provided, a default PromptInput is rendered. */
+    inputValue?: string;
+    /** Draft change handler. */
+    onInputChange?: (value: string) => void;
+    /** Submit handler. */
+    onSubmit?: () => void;
+    /** Placeholder for the default input. */
+    inputPlaceholder?: string;
+    /** Fully custom input node; overrides the default PromptInput. */
+    input?: ReactNode;
+    /** Surface title (header). */
+    title?: string;
+    /** Surface subtitle/status text. */
+    subtitle?: string;
+    /** Header icon. */
+    icon?: ReactNode;
+    /** Header actions (right side). */
+    headerActions?: ReactNode;
+    /** Suggestions/quick-replies node shown above the input. */
+    suggestions?: ReactNode;
+    /** Show avatars in the conversation. */
+    showAvatars?: boolean;
+    /** Custom message renderer passed through to MessageList. */
+    renderMessage?: (message: AgentMessage) => ReactNode;
+    /** Feedback handler passed to MessageList. */
+    onFeedback?: (messageId: string, vote: 'up' | 'down') => void;
+    /**
+     * Structured report rendered in the data region. Used by the
+     * dashboard/split surfaces (sidebar or data panel). If omitted, a custom
+     * `dataPanel` node may be supplied instead.
+     */
+    report?: AgentReport;
+    /** Custom data-region node; overrides `report`. */
+    dataPanel?: ReactNode;
+    /** Open state for widget/overlay surfaces. */
+    isOpen?: boolean;
+    /** Toggle handler for the widget launcher. */
+    onToggle?: () => void;
+    /** Close handler for widget/overlay surfaces. */
+    onClose?: () => void;
+    /**
+     * Exit handler for the fullscreen surface. When provided, the fullscreen
+     * container shows a close (X) control and binds Esc to return to the
+     * previous surface. The host decides where "exit" goes (typically panel).
+     */
+    onExitFullscreen?: () => void;
+    /** Widget anchor position. */
+    position?: WidgetPosition;
+    /** Online status for widget/mobile headers. */
+    status?: 'online' | 'offline' | 'busy' | 'away';
+    className?: string;
+}
+/**
+ * AgentSurface is the single entry point that renders the agent UI into any
+ * supported layout from one set of primitives. The orchestrator selects a
+ * `mode` and the same messages, input, and report flow into the matching
+ * container — there are no per-surface forks of the conversation logic.
+ *
+ *   - 'panel'      → inline ChatPanel (standard conversation)
+ *   - 'fullscreen' → FullscreenDashboard (chat + report sidebar)
+ *   - 'split'      → SplitView (chat beside a live data panel)
+ *   - 'widget'     → FloatingWidget (embeddable launcher + conversation)
+ *   - 'overlay'    → OverlayModal (centered modal conversation)
+ *   - 'mobile'     → MobileShell (full-height mobile layout)
+ */
+declare function AgentSurface({ mode, messages, isLoading, inputValue, onInputChange, onSubmit, inputPlaceholder, input, title, subtitle, icon, headerActions, suggestions, showAvatars, renderMessage, onFeedback, report, dataPanel, isOpen, onToggle, onClose, onExitFullscreen, position, status, className, }: AgentSurfaceProps): react.JSX.Element;
+
+export { type AgendaItem, type AgendaItemAction, type AgendaItemState, type AgendaSlotOption, type AgentAction, type AgentAttachment, AgentAvatar, type AgentBackend, type AgentBlock, type AgentConfig, type AgentContextValue, type AgentEvent, type AgentEventType, type AgentFeatures, AgentHandoff, type AgentHandoffProps, type AgentMessage, type AgentPersona, AgentProvider, type AgentProviderProps, type AgentReport, type AgentState, type AgentStreamChunk, AgentSurface, type AgentSurfaceProps, AllocationBreakdown, type AllocationSegment, type AllocationSummaryStat, type AnalyticsBreakdownRow, AnalyticsDashboard, type AnalyticsDashboardProps, type AnalyticsDistributionSegment, type AnalyticsHighlight, type AnalyticsMetric, type AnalyticsRankedRow, type AnalyticsRecentItem, type AnalyticsTrend, type AssistantMessageBlocksEnvelope, type AssistantMessageCompleteEnvelope, type AssistantMessageDeltaEnvelope, type AssistantMessageStartEnvelope, type AssistantMessageThinkingDeltaEnvelope, type Attachment, type AttachmentKind, type AttachmentMediaType, type AttachmentType, Avatar, AvatarFallback, AvatarImage, Badge, type BlockUpdateMode, Button, ChartContainer, type ChartData, type ChartDataPoint, type ChartType, type ChatMessageRole, ChatPanel, Collapsible, CollapsibleContent, CollapsibleTrigger, type ComponentCapability, type ComponentCategory, type ComponentManifestEntry, type ComponentSlot, type ConnectionReadyEnvelope, type ConnectionState, ControlGrid, type ControlTile, type ControlTileType, ConversationAnalytics, ConversationArtifact, type ConversationArtifactProps, type ConversationHistoryItem, type DataPayload, DataPayloadView, DataTable, DynamicRenderer, type EditorAdjustment, type EditorTool, type EmotionScore, type EntityAction, EntityCard, type EntityCardData, type EntityField, type ErrorEnvelope, type ExecutionStep, type ExecutionStepStatus, type FeedbackCategory, type FeedbackSentiment, FileDropZone, FloatingWidget, FullBleedSurface, type FullBleedSurfaceProps, FullscreenDashboard, type GenerateReportOptions, GuidedLessonFlow, type HandoffAction, type HandoffAgent, type HandoffCandidate, type HandoffStatus, type HandoffVariant, ImageGenerator, type InlineSuggestion, InlineSuggestionsInput, Input, type LayoutConfig, type LayoutMode, type LessonStep, type LibraryPrompt, type Listing, type ListingAction, ListingFeed, type ListingField, type ManifestPropSpec, MediaEditorCanvas, MediaGallery, type MediaItem, type MediaKind, MessageActions, MessageBubble, type MessageFeedback, MessageList, type MessageListProps, type MessageMetadata, type MessageRole, MessageWithAttachments, MessageWithFeedback, MessageWithReasoning, MessageWithSteps, type MetricData, MetricsGrid, MobileShell, type MockBackendConfig, MultimodalInput, OnboardingWizard, type OptionCardItem, OptionCards, type OrchestrationCommand, OverlayModal, PerformanceMetrics, PersonaSelector, Progress, ProgressTracker, PromptInput, PromptLibrary, type PromptTemplate, QuickReplies, type QuickReply, QuizCard, type QuizOption, type QuizQuestion, type QuizResult, type ReasoningStatus, type ReasoningStep, type Recommendation, type RecommendationAction, RecommendationCards, type RecommendationTone, type RenderInstruction, type ReportSection, ReportView, ScheduleTimeline, ScrollArea, ScrollBar, type SemanticBuilderChatMessage, SemanticBuilderSocketClient, type SendMessageOptions, type SendOptions, SentimentDisplay, type SentimentScore, type ServerEnvelope, type SettingControl, type SettingsGroup, SettingsPanel, SlotRenderer, type SocketClientOptions, type SocketSendPayload, type SocketUrlResolver, SplitView, StatusBadge, SystemMessage, type TableColumn, type TableData, TemplateSelector, type TemplateVariable, Textarea, type ThemeConfig, Timestamp, type ToolCall, type ToolDefinition, type ToolResult, Tooltip, TooltipContent, TooltipProvider, TooltipTrigger, type TrendDirection, type TrendTone, TypingIndicator, type UseSemanticBuilderOptions, type UseSemanticBuilderResult, type UserMessageEnvelope, type WidgetPosition, WritingAssistant, badgeVariants, buildSocketUrl, buttonVariants, calculatePercentage, cn, componentManifest, componentMap, componentRegistry, copyToClipboard, createMockBackend, debounce, delay, findComponentsByCapability, findComponentsByCategory, findComponentsBySurface, formatBytes, formatCurrency, formatNumber, formatRelativeTime, formatTime, generateId, getInitials, getManifestEntry, getSentimentBgColor, getSentimentColor, isBrowser, isInIframe, normalizeWebsiteId, parseTextWithBold, registerAllComponents, truncate, useAgent, useAgentBackend, useAgentInput, useAgentLayout, useAgentMessages, useSemanticBuilder };