┌────────────────────────────────────────────────┐
│  PRIMITIVES LAYER (React Components)           │
│  ThreadPrimitive, MessagePrimitive,            │
│  ComposerPrimitive, BranchPickerPrimitive,     │
│  ActionBarPrimitive, ContentPartPrimitive,     │
│  AttachmentPrimitive                           │
├────────────────────────────────────────────────┤
│  REACT BINDINGS LAYER (Hooks + Context)        │
│  useThread, useMessage, useComposer,           │
│  useContentPart, useAui, useAuiState,          │
│  useAuiEvent, ThreadContext, MessageContext     │
├────────────────────────────────────────────────┤
│  CORE RUNTIME LAYER (Provider-agnostic)        │
│  ThreadRuntime, MessageRuntime,                │
│  ComposerRuntime, ContentPartRuntime,          │
│  AttachmentRuntime, AssistantRuntime           │
└────────────────────────────────────────────────┘

interface AssistantRuntime {
  // Thread management
  readonly thread: ThreadRuntime;
  switchToNewThread(): void;
  switchToThread(threadId: string): void;

  // Registration
  registerModelConfigProvider(provider: ModelConfigProvider): Unsubscribe;

  // Reactive subscriptions
  subscribe(callback: () => void): Unsubscribe;
}

interface ModelConfigProvider {
  getModelConfig(): ModelConfig;
}

interface ModelConfig {
  system?: string;
  tools?: Record<string, Tool>;
  callSettings?: {
    maxTokens?: number;
    temperature?: number;
    topP?: number;
  };
  config?: Record<string, unknown>;  // arbitrary provider config
}

function useVercelUseChatRuntime(chatHelpers: UseChatHelpers): AssistantRuntime;
function useVercelRSCRuntime(rscHelpers: RSCHelpers): AssistantRuntime;

interface ThreadRuntime {
  // State
  readonly path: ThreadRuntimePath;           // { ref: string; threadSelector: { type: "main" | "byId"; threadId?: string } }
  readonly composer: ThreadComposerRuntime;
  readonly messages: readonly ThreadMessage[];
  readonly isDisabled: boolean;
  readonly isRunning: boolean;
  readonly extras: Record<string, unknown>;    // provider-specific metadata
  readonly capabilities: ThreadCapabilities;
  readonly speech: SpeechState | undefined;

  // Message access
  getMessageById(messageId: string): {
    parentId: string | null;
    message: ThreadMessage;
  } | undefined;

  // Actions
  append(message: AppendMessage): void;
  startRun(config?: StartRunConfig): void;
  cancelRun(): void;
  addToolResult(options: AddToolResultOptions): void;
  speak(messageId: string): void;
  stopSpeaking(): void;

  // Import/Export
  import(repository: ExportedMessageRepository): void;
  export(): ExportedMessageRepository;

  // Child runtimes
  getMessagesRuntime(): ThreadMessagesRuntime;

  // Subscriptions
  subscribe(callback: () => void): Unsubscribe;
  unstable_on(event: ThreadRuntimeEventType, callback: () => void): Unsubscribe;
}

interface ThreadCapabilities {
  switchToBranch: boolean;
  edit: boolean;
  reload: boolean;
  cancel: boolean;
  unstable_copy: boolean;
  speak: boolean;
  attachments: boolean;
  feedback: boolean;
}

// Internal message repository
class MessageRepository {
  private messages: Map<string, MessageNode> = new Map();
  private head: MessageNode | null = null;
  private root: MessageNode = { /* sentinel */ };

  // Each node tracks parent + children for tree navigation
  interface MessageNode {
    id: string;
    message: ThreadMessage;
    parent: MessageNode | null;
    children: MessageNode[];       // all branches from this point
    activeChildIndex: number;      // which branch is currently selected
  }

  // Get the linear path from root to current head
  getMessages(): ThreadMessage[] {
    // Walk from root following activeChildIndex at each level
    const result: ThreadMessage[] = [];
    let current = this.root;
    while (current.children.length > 0) {
      const child = current.children[current.activeChildIndex];
      result.push(child.message);
      current = child;
    }
    return result;
  }

  // Branch operations
  switchToBranch(messageId: string): void {
    const node = this.messages.get(messageId);
    // Walk up to find the branching parent
    // Set parent.activeChildIndex to the index of this child
    // Reset head to walk down this new branch
  }

  getBranchInfo(messageId: string): { branchIndex: number; branchCount: number } {
    const node = this.messages.get(messageId);
    const parent = node.parent;
    return {
      branchIndex: parent.children.indexOf(node),
      branchCount: parent.children.length,
    };
  }

  // Adding messages
  addOrUpdateMessage(parentId: string | null, message: ThreadMessage): void {
    // If message.id exists, update in place
    // Otherwise create new node as child of parent
    // Auto-set as active child of parent
  }
}

type ThreadMessage = ThreadUserMessage | ThreadAssistantMessage | ThreadSystemMessage;

interface ThreadMessageBase {
  id: string;
  createdAt: Date;
  metadata?: {
    unstable_annotations?: unknown[];
    unstable_data?: unknown[];
    custom?: Record<string, unknown>;
    steps?: StepMetadata[];          // multi-step reasoning
    feedback?: MessageFeedback;       // thumbs up/down
  };
}

interface ThreadUserMessage extends ThreadMessageBase {
  role: "user";
  content: Array<TextContentPart | ImageContentPart | FileContentPart | AudioContentPart>;
  attachments: readonly CompleteAttachment[];
}

interface ThreadAssistantMessage extends ThreadMessageBase {
  role: "assistant";
  content: Array<TextContentPart | ReasoningContentPart | ToolCallContentPart | UIContentPart | FileContentPart | ImageContentPart | AudioContentPart | SourceContentPart | DataContentPart>;
  status: MessageStatus;
  roundtrips?: unknown[];            // deprecated, use metadata.steps
}

interface ThreadSystemMessage extends ThreadMessageBase {
  role: "system";
  content: [TextContentPart];
}

interface TextContentPart {
  type: "text";
  text: string;
}

interface ReasoningContentPart {
  type: "reasoning";
  text: string;
  signature?: string;        // cryptographic signature for verification
}

interface ToolCallContentPart {
  type: "tool-call";
  toolCallId: string;
  toolName: string;
  args: Record<string, unknown>;
  result?: unknown;
  isError?: boolean;
  argsText: string;          // raw JSON string for streaming display
}

interface ImageContentPart {
  type: "image";
  image: string;             // URL or data URI
}

interface FileContentPart {
  type: "file";
  data: string;              // base64 encoded
  mimeType: string;
  name?: string;
}

interface AudioContentPart {
  type: "audio";
  audio: { data: string; format: "mp3" | "wav" | "pcm16" };
}

interface UIContentPart {
  type: "ui";
  display: ReactNode;        // arbitrary React component
}

interface SourceContentPart {
  type: "source";
  sourceType: "url";
  id: string;
  url: string;
  title?: string;
}

interface DataContentPart {
  type: "data";
  data: unknown;             // arbitrary structured data
}

type MessageStatus =
  | { type: "running" }                                         // actively streaming
  | { type: "requires-action"; reason: "tool-calls" }          // waiting for tool results
  | { type: "complete"; reason: "stop" | "unknown" }           // finished normally
  | { type: "incomplete"; reason: "cancelled" | "length" | "content-filter" | "other" | "error"; error?: unknown };

interface AssistantStreamChunk {
  // Path identifies WHERE in the message tree to apply the update.
  // Paths use numeric indices separated by dots to address nested content.
  path: string;               // e.g., "parts.0", "parts.1.result", "status"
  type: string;               // operation type
  value: unknown;             // the data payload
}

class StreamProcessor {
  private draft: Mutable<ThreadAssistantMessage>;
  private partIndex: number = 0;

  processChunk(chunk: AssistantStreamChunk): void {
    switch (chunk.type) {
      case "text-delta": {
        const idx = this.resolvePartIndex(chunk.path);
        if (!this.draft.content[idx]) {
          this.draft.content[idx] = { type: "text", text: "" };
        }
        (this.draft.content[idx] as TextContentPart).text += chunk.value;
        break;
      }
      case "tool-call-begin": {
        const idx = this.resolvePartIndex(chunk.path);
        this.draft.content[idx] = {
          type: "tool-call",
          toolCallId: chunk.value.toolCallId,
          toolName: chunk.value.toolName,
          args: {},
          argsText: "",
        };
        break;
      }
      case "tool-call-delta": {
        const idx = this.resolvePartIndex(chunk.path);
        const part = this.draft.content[idx] as ToolCallContentPart;
        part.argsText += chunk.value;
        // Attempt incremental JSON parse of argsText into args
        try { part.args = JSON.parse(part.argsText); } catch {}
        break;
      }
      case "status": {
        this.draft.status = chunk.value as MessageStatus;
        break;
      }
      // ... etc for each type
    }
    this.notifySubscribers();
  }
}

// Core reactive primitive — a subscribable store
class ReactiveStore<T> {
  private value: T;
  private listeners: Set<() => void> = new Set();

  get(): T { return this.value; }

  set(newValue: T): void {
    if (Object.is(this.value, newValue)) return;
    this.value = newValue;
    this.listeners.forEach(fn => fn());
  }

  subscribe(listener: () => void): Unsubscribe {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }
}

// Subscribe to a computed value from a runtime — re-renders ONLY when the selector's output changes
function useAuiState<TRuntime, TSelected>(
  runtimeHook: () => TRuntime,
  selector: (runtime: TRuntime) => TSelected,
  equalityFn?: (a: TSelected, b: TSelected) => boolean,
): TSelected {
  const runtime = runtimeHook();
  // useSyncExternalStore under the hood
  return useSyncExternalStore(
    (callback) => runtime.subscribe(callback),
    () => selector(runtime.getState()),
  );
}

// Subscribe to events without re-rendering
function useAuiEvent<TRuntime>(
  runtimeHook: () => TRuntime,
  event: string,
  callback: (data: unknown) => void,
): void {
  const runtime = runtimeHook();
  useEffect(() => {
    return runtime.unstable_on(event, callback);
  }, [runtime, event, callback]);
}

// Get the raw runtime reference (no subscription)
function useAui<TRuntime>(
  runtimeHook: () => TRuntime,
): TRuntime {
  return runtimeHook();
}

const ThreadPrimitive = {
  Root: ThreadRoot,           // Container div, provides ThreadContext
  Viewport: ThreadViewport,   // Scrollable container with auto-scroll behavior
  Messages: ThreadMessages,   // Renders message list with branching support
  ScrollToBottom: ThreadScrollToBottom,  // Button shown when scrolled up
  Suggestion: ThreadSuggestion,          // Clickable suggestion chip
  If: ThreadIf,               // Conditional rendering based on thread state
  Empty: ThreadEmpty,         // Shown when thread has no messages
};

interface ThreadViewportProps {
  autoScroll?: boolean;        // default true — scroll to bottom on new content
  children: ReactNode;
}

// Implementation detail: uses IntersectionObserver on a sentinel element
// at the bottom of the scroll container. When the sentinel is visible,
// auto-scroll is "engaged". When user scrolls up (sentinel leaves viewport),
// auto-scroll disengages. New messages re-engage auto-scroll.

interface ThreadMessagesProps {
  components: {
    UserMessage: ComponentType;            // rendered for role="user"
    AssistantMessage: ComponentType;       // rendered for role="assistant"
    SystemMessage?: ComponentType;         // rendered for role="system"
    EditComposer?: ComponentType;          // rendered when editing a user message
    AssistantEditComposer?: ComponentType; // rendered when editing an assistant message (rare)
  };
}

// Each rendered message is automatically wrapped in a MessageContext provider
// that gives the message's sub-components access to the specific MessageRuntime.

const MessagePrimitive = {
  Root: MessageRoot,           // Container, provides MessageContext
  Content: MessageContent,     // Renders content parts with component mapping
  InProgress: MessageInProgress, // Shown while message is streaming
  If: MessageIf,               // Conditional rendering based on message state
  Attachments: MessageAttachments, // Renders user message attachments
};

interface MessageContentProps {
  components?: {
    Text?: ComponentType<TextContentPartProps>;
    Reasoning?: ComponentType<ReasoningContentPartProps>;
    Image?: ComponentType<ImageContentPartProps>;
    File?: ComponentType<FileContentPartProps>;
    Audio?: ComponentType<AudioContentPartProps>;
    UI?: ComponentType<UIContentPartProps>;
    tools?: {
      by_name?: Record<string, ComponentType<ToolCallContentPartProps>>;
      Fallback?: ComponentType<ToolCallContentPartProps>;
    };
    Source?: ComponentType<SourceContentPartProps>;
    Data?: ComponentType<DataContentPartProps>;
  };
}

// Rendering logic:
// For each content part in the message:
//   1. Look up the component by part.type in the components map
//   2. For tool-calls, look up by_name[toolName] first, fall back to Fallback
//   3. If no component found, use built-in defaults (Text renders <p>, etc.)
//   4. Wrap each part in a ContentPartContext provider with its own runtime

const ComposerPrimitive = {
  Root: ComposerRoot,          // <form> element wrapping the composer
  Input: ComposerInput,        // <textarea> with auto-resize
  Send: ComposerSend,          // Submit button, disabled when empty or running
  Cancel: ComposerCancel,      // Cancel ongoing generation
  Attachments: ComposerAttachments, // Render attached files
  AddAttachment: ComposerAddAttachment, // File picker trigger button
  If: ComposerIf,              // Conditional rendering
};

interface ComposerInputProps {
  autoFocus?: boolean;
  placeholder?: string;
  submitOnEnter?: boolean;     // default true — Enter sends, Shift+Enter newline
  rows?: number;               // minimum rows
}

// Implementation:
// 1. Uses a hidden <div> mirror with identical styling to measure content height
// 2. On each input event, copies text to mirror, reads scrollHeight, sets textarea height
// 3. Caps at a configurable max-height (e.g., 200px), then switches to scroll
// 4. On Enter (without Shift), calls composerRuntime.send()
// 5. After send, resets height to initial rows

// Enabled when ALL of:
// 1. composer.text.trim().length > 0 OR composer.attachments.length > 0
// 2. thread.isRunning === false
// 3. thread.isDisabled === false
// Renders as <button type="submit">

const BranchPickerPrimitive = {
  Root: BranchPickerRoot,      // Container div
  Previous: BranchPickerPrevious,  // Button to switch to previous branch
  Next: BranchPickerNext,         // Button to switch to next branch
  Count: BranchPickerCount,       // Text showing "2 / 5" style branch indicator
  Number: BranchPickerNumber,     // Current branch number
  If: BranchPickerIf,             // Conditional: only render if branches > 1
};

const ActionBarPrimitive = {
  Root: ActionBarRoot,
  Copy: ActionBarCopy,         // Copy message text to clipboard
  Edit: ActionBarEdit,         // Enter edit mode for user messages
  Reload: ActionBarReload,     // Re-generate assistant response
  Speak: ActionBarSpeak,       // Text-to-speech
  StopSpeaking: ActionBarStopSpeaking,
  FeedbackPositive: ActionBarFeedbackPositive,   // Thumbs up
  FeedbackNegative: ActionBarFeedbackNegative,   // Thumbs down
  If: ActionBarIf,             // Conditional by message role, state
};

interface ActionBarRootProps {
  hideWhenRunning?: boolean;   // default true — hide during streaming
  autohide?: "always" | "not-last" | "never";
  // "always": only show on hover
  // "not-last": show for last message, hover for others
  // "never": always visible
  autohideFloat?: "always" | "never" | "single-branch";
  // Controls whether the action bar floats above the message
}

const AttachmentPrimitive = {
  Root: AttachmentRoot,        // Container
  Name: AttachmentName,        // File name display
  Remove: AttachmentRemove,    // Remove from composer (only in composer context)
  unstable_Thumb: AttachmentThumb,  // Thumbnail preview (images)
};

// ThreadPrimitive.If
interface ThreadIfProps {
  empty?: boolean;             // render if thread has no messages
  running?: boolean;           // render if model is generating
  disabled?: boolean;          // render if thread is disabled
  children: ReactNode;
}

// MessagePrimitive.If
interface MessageIfProps {
  user?: boolean;              // render if user message
  assistant?: boolean;         // render if assistant message
  system?: boolean;            // render if system message
  hasBranches?: boolean;       // render if message has alternate branches
  copied?: boolean;            // render if message was recently copied
  speaking?: boolean;          // render if TTS is active
  hasAttachments?: boolean;
  submittedFeedback?: "positive" | "negative";
  children: ReactNode;
}

AssistantContext (AssistantRuntime)
  └── ThreadContext (ThreadRuntime)
        └── MessageContext (MessageRuntime)
              └── ContentPartContext (ContentPartRuntime)
              └── AttachmentContext (AttachmentRuntime)
        └── ComposerContext (ComposerRuntime)

// Get runtime instances from context
function useAssistantRuntime(): AssistantRuntime;
function useThreadRuntime(): ThreadRuntime;
function useMessageRuntime(): MessageRuntime;
function useContentPartRuntime(): ContentPartRuntime;
function useComposerRuntime(): ComposerRuntime;
function useAttachmentRuntime(): AttachmentRuntime;

// Convenience hooks that combine context + selector
function useThread(): ThreadState;           // shorthand for useAuiState(useThreadRuntime, ...)
function useMessage(): MessageState;
function useContentPart(): ContentPartState;
function useComposer(): ComposerState;

interface AssistantRuntimeProviderProps {
  runtime: AssistantRuntime;
  children: ReactNode;
}

function AssistantRuntimeProvider({ runtime, children }: AssistantRuntimeProviderProps): JSX.Element {
  return (
    <AssistantContext.Provider value={runtime}>
      <ThreadContext.Provider value={runtime.thread}>
        {children}
      </ThreadContext.Provider>
    </AssistantContext.Provider>
  );
}

function useChatRuntime({
  api,
  adapters,
  ...chatOptions
}: UseChatRuntimeOptions): AssistantRuntime {
  // 1. Calls useChat() from @ai-sdk/react internally
  // 2. Creates a VercelUseChatRuntime that wraps the chat helpers
  // 3. Syncs messages bidirectionally:
  //    - Vercel's Message[] ↔ internal ThreadMessage[]
  //    - Vercel's streaming chunks → internal AssistantStreamChunks
  // 4. Maps Vercel tool invocations → ToolCallContentParts
  // 5. Handles tool result submission via addToolResult

  // Returns an AssistantRuntime ready for AssistantRuntimeProvider
}

// Vercel AI SDK message format → Internal format
function vercelToThreadMessage(message: VercelMessage): ThreadMessage {
  if (message.role === "user") {
    return {
      id: message.id,
      role: "user",
      createdAt: message.createdAt ?? new Date(),
      content: message.content
        ? [{ type: "text", text: message.content }]
        : [],
      attachments: (message.experimental_attachments ?? []).map(a => ({
        type: a.contentType?.startsWith("image/") ? "image" : "file",
        name: a.name ?? "file",
        contentType: a.contentType,
        content: [/* ... */],
      })),
    };
  }

  if (message.role === "assistant") {
    const content: ContentPart[] = [];

    // Text content
    if (message.content) {
      content.push({ type: "text", text: message.content });
    }

    // Reasoning
    if (message.reasoning) {
      content.push({ type: "reasoning", text: message.reasoning });
    }

    // Tool invocations
    for (const invocation of message.toolInvocations ?? []) {
      content.push({
        type: "tool-call",
        toolCallId: invocation.toolCallId,
        toolName: invocation.toolName,
        args: invocation.args,
        argsText: JSON.stringify(invocation.args),
        result: invocation.state === "result" ? invocation.result : undefined,
        isError: false,
      });
    }

    // Sources (annotations)
    for (const annotation of message.annotations ?? []) {
      if (annotation?.type === "source") {
        content.push({ type: "source", ...annotation });
      }
    }

    return {
      id: message.id,
      role: "assistant",
      createdAt: message.createdAt ?? new Date(),
      content,
      status: deriveStatus(message),
    };
  }
}

interface Tool<TArgs = unknown, TResult = unknown> {
  description: string;
  parameters: JSONSchema7;           // JSON Schema for argument validation
  execute?: (args: TArgs, context: ToolExecutionContext) => Promise<TResult>;
  render?: ComponentType<ToolCallContentPartProps<TArgs, TResult>>;
}

interface ToolExecutionContext {
  messageId: string;
  toolCallId: string;
  abortSignal: AbortSignal;
}

1. **Model generates tool call** → message status becomes `{ type: "requires-action", reason: "tool-calls" }`

// Example approval component
function ToolApproval({ toolCall }: { toolCall: ToolCallContentPart }) {
  const threadRuntime = useThreadRuntime();

  const approve = async () => {
    // Execute the tool client-side
    const result = await executeToolLocally(toolCall.toolName, toolCall.args);
    threadRuntime.addToolResult({
      toolCallId: toolCall.toolCallId,
      result,
    });
  };

  const reject = () => {
    threadRuntime.addToolResult({
      toolCallId: toolCall.toolCallId,
      result: "User rejected this tool call",
      isError: true,
    });
  };

  return (
    <div>
      <p>Tool: {toolCall.toolName}</p>
      <pre>{JSON.stringify(toolCall.args, null, 2)}</pre>
      <button onClick={approve}>Approve</button>
      <button onClick={reject}>Reject</button>
    </div>
  );
}

interface AttachmentAdapter {
  // Called when user selects files
  add(state: { file: File }): Promise<PendingAttachment>;

  // Called when user removes an attachment before sending
  remove(attachment: PendingAttachment): Promise<void>;

  // Called when message is sent — converts pending → complete
  send(attachment: PendingAttachment): Promise<CompleteAttachment>;

  // File type accept filter (e.g., "image/*,.pdf")
  accept: string;
}

interface PendingAttachment {
  id: string;
  type: "image" | "document" | "file";
  name: string;
  file: File;
  contentType: string;
  content?: unknown;        // populated after processing
  status: "pending" | "uploading" | "ready" | "error";
}

interface CompleteAttachment {
  id: string;
  type: "image" | "document" | "file";
  name: string;
  contentType: string;
  content: Array<TextContentPart | ImageContentPart | FileContentPart>;
}

// SimpleImageAttachmentAdapter — reads images as data URIs
class SimpleImageAttachmentAdapter implements AttachmentAdapter {
  accept = "image/*";

  async add({ file }) {
    return {
      id: generateId(),
      type: "image",
      name: file.name,
      file,
      contentType: file.type,
      status: "ready",
    };
  }

  async send(attachment) {
    const dataUri = await readAsDataURL(attachment.file);
    return {
      ...attachment,
      content: [{ type: "image", image: dataUri }],
    };
  }
}

// SimpleTextAttachmentAdapter — reads text/json/code files as text
class SimpleTextAttachmentAdapter implements AttachmentAdapter {
  accept = "text/*,application/json,.md,.csv,.xml,.yaml,.yml";

  async send(attachment) {
    const text = await attachment.file.text();
    return {
      ...attachment,
      content: [{ type: "text", text: `File: ${attachment.name}\n\n${text}` }],
    };
  }
}

// CompositeAttachmentAdapter — combines multiple adapters
class CompositeAttachmentAdapter implements AttachmentAdapter {
  constructor(private adapters: AttachmentAdapter[]) {}
  accept = this.adapters.map(a => a.accept).join(",");

  async add(state) {
    // Find first adapter whose accept matches the file type
    const adapter = this.adapters.find(a => matchesAccept(a.accept, state.file));
    return adapter.add(state);
  }
}

interface MarkdownTextProps {
  smooth?: boolean;            // enable character-by-character smooth streaming animation
  components?: MarkdownComponents;  // override specific element renderers
}

// Built-in rendering pipeline:
// 1. Parse markdown with remark (remark-gfm for tables/strikethrough)
// 2. Convert to React via rehype-react
// 3. Apply syntax highlighting to code blocks via rehype-highlight or Shiki
// 4. Render LaTeX via rehype-katex (inline $ and display $$)
// 5. Apply custom component overrides

// Default component map:
const defaultComponents: MarkdownComponents = {
  p: ({ children }) => <p>{children}</p>,
  h1: ({ children }) => <h1>{children}</h1>,
  // ... h2-h6
  code: ({ className, children }) => {
    const language = className?.replace("language-", "");
    if (language) {
      return <SyntaxHighlighter language={language}>{children}</SyntaxHighlighter>;
    }
    return <code>{children}</code>;
  },
  pre: ({ children }) => (
    <div className="relative">
      <CopyButton />
      <pre>{children}</pre>
    </div>
  ),
  a: ({ href, children }) => <a href={href} target="_blank" rel="noopener">{children}</a>,
  table: ({ children }) => <div className="overflow-x-auto"><table>{children}</table></div>,
  // ... th, td, tr, ul, ol, li, blockquote, hr, img
};

function useSmoothText(text: string): { displayText: string; isAnimating: boolean } {
  const [displayText, setDisplayText] = useState("");
  const animationRef = useRef<number>();
  const targetRef = useRef(text);

  useEffect(() => {
    targetRef.current = text;

    function animate() {
      setDisplayText(prev => {
        if (prev.length >= targetRef.current.length) return targetRef.current;
        // Reveal 1-3 characters per frame depending on backlog
        const backlog = targetRef.current.length - prev.length;
        const charsToAdd = Math.min(Math.ceil(backlog / 10) + 1, 3);
        return targetRef.current.slice(0, prev.length + charsToAdd);
      });
      animationRef.current = requestAnimationFrame(animate);
    }

    animationRef.current = requestAnimationFrame(animate);
    return () => cancelAnimationFrame(animationRef.current!);
  }, [text]);

  return {
    displayText,
    isAnimating: displayText !== text,
  };
}

// tailwind.config.js
module.exports = {
  plugins: [require("@assistant-ui/tailwindcss")],
};

<MessagePrimitive.Root className="aui-user:bg-blue-50 aui-assistant:bg-gray-50 aui-error:border-red-500">
  <MessagePrimitive.Content />
</MessagePrimitive.Root>

interface SpeechSynthesisAdapter {
  speak(text: string): SpeechSubscription;
}

interface SpeechSubscription {
  cancel(): void;
  subscribe(callback: (state: SpeechState) => void): Unsubscribe;
}

interface SpeechState {
  status: "speaking" | "paused" | "ended" | "error";
}

// Web Speech API adapter (built-in)
class WebSpeechSynthesisAdapter implements SpeechSynthesisAdapter {
  speak(text: string): SpeechSubscription {
    const utterance = new SpeechSynthesisUtterance(text);
    speechSynthesis.speak(utterance);

    return {
      cancel: () => speechSynthesis.cancel(),
      subscribe: (callback) => {
        utterance.onstart = () => callback({ status: "speaking" });
        utterance.onend = () => callback({ status: "ended" });
        utterance.onerror = () => callback({ status: "error" });
        return () => {
          utterance.onstart = null;
          utterance.onend = null;
          utterance.onerror = null;
        };
      },
    };
  }
}

interface ThreadListRuntime {
  // Currently active thread
  readonly mainThread: ThreadRuntime;

  // Archived/historical threads
  readonly threads: readonly ThreadListItem[];
  readonly archivedThreads: readonly ThreadListItem[];

  // Thread switching
  switchToThread(threadId: string): void;
  switchToNewThread(): void;

  // Thread lifecycle
  rename(threadId: string, newTitle: string): Promise<void>;
  archive(threadId: string): Promise<void>;
  unarchive(threadId: string): Promise<void>;
  delete(threadId: string): Promise<void>;

  subscribe(callback: () => void): Unsubscribe;
}

interface ThreadListItem {
  id: string;
  title?: string;
  status: "regular" | "archived";
  remoteId?: string;          // server-side ID for persistence
}

interface ExternalStoreAdapter {
  // Thread list operations
  threads?: {
    list(): Promise<ThreadListItem[]>;
    rename(threadId: string, title: string): Promise<void>;
    archive(threadId: string): Promise<void>;
    delete(threadId: string): Promise<void>;
    create?(): Promise<{ threadId: string; remoteId: string }>;
  };

  // Message persistence
  messages?: {
    list(threadId: string): Promise<ThreadMessage[]>;
  };

  // Streaming
  onNew(message: AppendMessage): Promise<void>;

  // Converts external messages to internal format
  convertMessage?: (message: unknown) => ThreadMessage;
}

// Usage
function useExternalStoreRuntime(adapter: ExternalStoreAdapter): AssistantRuntime;

import {
  AssistantRuntimeProvider,
  ThreadPrimitive,
  MessagePrimitive,
  ComposerPrimitive,
  BranchPickerPrimitive,
  ActionBarPrimitive,
} from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";
import { MarkdownText } from "@assistant-ui/react-markdown";

function MyChat() {
  const runtime = useChatRuntime({ api: "/api/chat" });

  return (
    <AssistantRuntimeProvider runtime={runtime}>
      <ThreadPrimitive.Root className="flex flex-col h-full">
        <ThreadPrimitive.Viewport className="flex-1 overflow-y-auto p-4">
          <ThreadPrimitive.Empty>
            <p className="text-gray-400">How can I help you?</p>
          </ThreadPrimitive.Empty>

          <ThreadPrimitive.Messages
            components={{
              UserMessage: () => (
                <MessagePrimitive.Root className="flex justify-end mb-4">
                  <div className="bg-blue-500 text-white rounded-lg p-3 max-w-[80%]">
                    <MessagePrimitive.Content />
                  </div>
                  <BranchPickerPrimitive.Root>
                    <BranchPickerPrimitive.Previous />
                    <BranchPickerPrimitive.Number /> / <BranchPickerPrimitive.Count />
                    <BranchPickerPrimitive.Next />
                  </BranchPickerPrimitive.Root>
                </MessagePrimitive.Root>
              ),
              AssistantMessage: () => (
                <MessagePrimitive.Root className="flex mb-4">
                  <div className="bg-gray-100 rounded-lg p-3 max-w-[80%]">
                    <MessagePrimitive.Content
                      components={{
                        Text: ({ text }) => <MarkdownText smooth>{text}</MarkdownText>,
                        tools: {
                          Fallback: ({ toolName, args, result }) => (
                            <details>
                              <summary>Tool: {toolName}</summary>
                              <pre>{JSON.stringify(args, null, 2)}</pre>
                              {result && <pre>Result: {JSON.stringify(result)}</pre>}
                            </details>
                          ),
                        },
                      }}
                    />
                  </div>
                  <ActionBarPrimitive.Root autohide="not-last">
                    <ActionBarPrimitive.Copy />
                    <ActionBarPrimitive.Reload />
                    <ActionBarPrimitive.FeedbackPositive />
                    <ActionBarPrimitive.FeedbackNegative />
                  </ActionBarPrimitive.Root>
                </MessagePrimitive.Root>
              ),
            }}
          />
        </ThreadPrimitive.Viewport>

        <div className="border-t p-4">
          <ComposerPrimitive.Root className="flex gap-2">
            <ComposerPrimitive.AddAttachment />
            <ComposerPrimitive.Attachments />
            <ComposerPrimitive.Input
              placeholder="Type a message..."
              className="flex-1 resize-none border rounded-lg p-2"
            />
            <ThreadPrimitive.If running={false}>
              <ComposerPrimitive.Send className="bg-blue-500 text-white rounded-lg px-4" />
            </ThreadPrimitive.If>
            <ThreadPrimitive.If running>
              <ComposerPrimitive.Cancel className="bg-red-500 text-white rounded-lg px-4" />
            </ThreadPrimitive.If>
          </ComposerPrimitive.Root>
        </div>
      </ThreadPrimitive.Root>
    </AssistantRuntimeProvider>
  );
}