@interopio/io-assist-react 1.0.0

package/README.internal.md

@@ -0,0 +1,467 @@
+# io.Assist (React) — Internal Developer Documentation
+
+**Audience:** Developers working on or extending `@interopio/io-assist-react`.
+
+This is the React counterpart of [`@interopio/io-assist-ng`](../io-assist-ng/README.internal.md). It implements the same product behavior with React idioms: a single combined **Zustand** store instead of NgRx, plain **action modules** instead of effects/services, and **React hooks + Context** instead of Angular DI. Where behavior is identical, this doc points to the Angular equivalent rather than restating it.
+
+---
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Project Structure](#project-structure)
+- [Public API Surface](#public-api-surface)
+- [Configuration](#configuration)
+- [Root Component — IoAssist](#root-component--ioassist)
+- [Context & Store Access](#context--store-access)
+- [State Management (Zustand)](#state-management-zustand)
+  - [Store Composition](#store-composition)
+  - [Slices](#slices)
+- [Bootstrap Hooks](#bootstrap-hooks)
+- [Actions Layer](#actions-layer)
+- [AG-UI Streaming Pipeline](#ag-ui-streaming-pipeline)
+- [Response Stream Store & Background Threads](#response-stream-store--background-threads)
+- [Sampling & Elicitation Flow](#sampling--elicitation-flow)
+- [MCP Apps Integration](#mcp-apps-integration)
+- [Components](#components)
+- [Utilities](#utilities)
+- [Styling](#styling)
+- [Build & Tooling](#build--tooling)
+- [Known Caveats](#known-caveats)
+
+---
+
+## Architecture Overview
+
+`@interopio/io-assist-react` is a single React component (`<IoAssist />`) plus a module-singleton Zustand store. The consumer passes two props — `staticConfig` and `dynamicConfig` — and everything else (io.Connect bootstrap, ai-web init, streaming, UI) runs internally.
+
+```
+Consumer App
+ └── <IoAssist staticConfig={...} dynamicConfig={...} />
+      └── IoAssistProvider                       ← puts both configs on React Context
+           └── IoAssistInner
+                ├── useIoConnectBootstrap()       ← initIoConnect(): platform + theme + favorites
+                ├── useIoAiWebBootstrap()          ← initIoAiWeb(): ai-web API + agents/threads/tools/ctx
+                └── appLoadingState gate
+                     ├── LOADING / NOT_STARTED → <LoadingScreen/>
+                     ├── ERROR                 → <ErrorScreen/>  (reload on retry)
+                     └── SUCCESS               → <Chat/>          ← full UI tree
+
+ioAssistStore (module singleton, Zustand + subscribeWithSelector)
+ └── 10 slices: appLifecycle, agent, thread, message, responseStream,
+                prompt, tool, workingContext, mcpApps, confirmModal
+```
+
+**Key layers:**
+
+| Layer | Responsibility | Where |
+|-------|---------------|-------|
+| **Config / Context** | Holds `staticConfig` + `dynamicConfig`, exposes them to the tree | `context/IoAssistContext.tsx` |
+| **Zustand store** | Single combined store of 10 slices; module singleton | `stores/` |
+| **Bootstrap hooks** | Run io.Connect + ai-web init once, in order | `hooks/useIoConnectBootstrap.ts`, `hooks/useIoAiWebBootstrap.ts` |
+| **Actions** | Imperative business logic; mutate the store via `store.getState().setX()` | `actions/` |
+| **Components** | Functional components subscribing via `useIoAssistStore(selector)` | `components/` |
+
+**State-mutation convention:** Action modules read and write the store imperatively through `store.getState()` / `store.getState().setX(...)`. React selectors (`useIoAssistStore(selector)`) are reserved for render-coupled reads inside components. This keeps streaming and async flows out of the render path.
+
+---
+
+## Project Structure
+
+```
+src/
+├── index.ts                      # Package exports (IoAssist + 2 config types)
+├── IoAssist.tsx                  # Root component + loading/error gates
+├── styles/
+│   ├── index.css                 # Tailwind entry + @font-face + @theme
+│   └── defaults.css              # CSS variables (light/dark)
+├── context/
+│   └── IoAssistContext.tsx       # IoAssistProvider + config/store hooks
+├── stores/                       # Zustand slices (one file per slice) + index.ts
+├── hooks/                        # Bootstrap + UI hooks
+├── actions/                      # Imperative store-mutating logic ("services")
+├── components/                   # UI tree (chat, header, messages, threads, …)
+├── constants/                    # uiStrings, modalActions
+├── types/                        # Domain + config types (index.ts barrel)
+└── utils/                        # logger, confirmModal, message/stream/thread helpers
+```
+
+---
+
+## Public API Surface
+
+File: `src/index.ts`. Only three things are exported — everything else is internal:
+
+```typescript
+export { IoAssist } from './IoAssist';
+export type { IoAssistStaticConfig, IoAssistDynamicConfig } from './types';
+```
+
+The stylesheet is published separately via the package `exports` map (`./styles` → `dist/styles.css`).
+
+> Unlike the Angular package, prompt/icon types (`IoAssistPromptCategory`, `IconResource`, …) are **not** re-exported. They are reachable structurally through `IoAssistStaticConfig`, so consumers author `defaultPrompts` as inline literals.
+
+---
+
+## Configuration
+
+File: `src/types/config.ts`.
+
+```typescript
+type IoAssistUserConfig = { id: string; name?: string };
+
+type IoAssistStaticConfig = {
+    connectConfig: {
+        browser?: { factory: IOConnectBrowserFactoryFunction; config?: IOConnectBrowser.Config };
+        desktop?: { factory: (config?: IOConnectDesktop.Config) => Promise<IOConnectDesktop.API>; config?: IOConnectDesktop.Config };
+    };
+    aiWebConfig: {
+        agentServer: IoAiWeb.AgentServerConfig;
+        mcp?: IoAiWeb.MCPConfig;
+    };
+    defaultAgentName?: string;
+    workingContext?: IoAiWeb.WorkingContextConfig;
+    defaultPrompts?: IoAssistPromptCategory[];
+};
+
+type IoAssistDynamicConfig = {
+    user: IoAssistUserConfig;
+    agentServer?: { headers?: Record<string, string> };
+};
+```
+
+**No runtime validation.** The Angular package validates both configs with Zod (`provideIoAssist()` / `ngOnInit`). The React package does **not** — configs flow straight into Context. If validation is added later, do it in `IoAssist`/`IoAssistProvider` before the bootstrap hooks run.
+
+**Config consumption:** `actions/initIoAiWeb.ts::buildWebConfig()` builds the `IoAiWeb.WebConfig`:
+- `agentServer` = `staticConfig.aiWebConfig.agentServer` spread, with `headers` taken **only** from `dynamicConfig.agentServer?.headers` (the sole source of request headers).
+- `mcp` (if present) → `buildMcpConfig()` injects sampling/elicitation handlers (see below).
+- `workingContext` (if present) → set as `config.context`.
+
+---
+
+## Root Component — IoAssist
+
+File: `src/IoAssist.tsx`.
+
+```typescript
+type Props = { staticConfig: IoAssistStaticConfig; dynamicConfig: IoAssistDynamicConfig };
+```
+
+- Wraps the tree in `IoAssistProvider` (puts both configs on Context).
+- `IoAssistInner` calls `useIoConnectBootstrap()` then `useIoAiWebBootstrap()`, and reads `appLoadingState` to render one of three states:
+
+| `appLoadingState.type` | Render |
+|------------------------|--------|
+| `LOADING` / `NOT_STARTED` | `<LoadingScreen/>` (spinner) |
+| `ERROR` | `<ErrorScreen/>` — retry button calls `window.location.reload()` |
+| `SUCCESS` | `<Chat/>` (full UI tree) |
+
+---
+
+## Context & Store Access
+
+File: `src/context/IoAssistContext.tsx`.
+
+| Export | Purpose |
+|--------|---------|
+| `IoAssistProvider` | Provides `staticConfig` and `dynamicConfig` via two React Contexts. |
+| `useIoAssistStore(selector)` | Subscribe to the Zustand store with a selector (`useStore(ioAssistStore, selector)`). |
+| `useIoAssistConfig()` | Read the static config. Throws if used outside the provider. |
+| `useIoAssistDynamicConfig()` | Read the dynamic config. Throws if used outside the provider. |
+
+The store itself (`ioAssistStore`) is a **module singleton** created in `stores/index.ts`, so action modules can import and mutate it directly without going through Context.
+
+---
+
+## State Management (Zustand)
+
+### Store Composition
+
+File: `src/stores/index.ts`. A single store type `IoAssistStore` is the intersection of ten slices, created with the `subscribeWithSelector` middleware:
+
+```typescript
+export type IoAssistStore = AppLifecycleSlice & AgentSlice & ThreadSlice & MessageSlice &
+    ResponseStreamSlice & PromptSlice & ToolSlice & WorkingContextSlice & McpAppsSlice & ConfirmModalSlice;
+
+export const ioAssistStore = createIoAssistStore(); // module singleton
+```
+
+Each slice is a `StateCreator` in its own file. Slices freely read sibling slices (e.g. `mergeAccumulatedStreamContent` in the message slice reads `streamsByThreadId` from the response-stream slice).
+
+### Slices
+
+#### `app-lifecycle.ts` — `AppLifecycleSlice`
+State: `appLoadingState`, `isIoConnectReady`, `isDarkMode`, `ioConnectApi`, `ioAiWebApi`.
+Actions: `setAppLoadingState`, `setIsIoConnectReady`, `setIsDarkMode`, `setIoConnectApi`, `setIoAiWebApi`.
+
+#### `agent.ts` — `AgentSlice`
+State: `agents: UIAgent[]`, `selectedAgent`, `agentsLoadingState`.
+Actions: `setAgents`, `setSelectedAgent`, `setAgentsLoadingState`.
+`UIAgent` wraps the raw ai-web agent in `rawAgent` (used for `generate()` / `stream()` / `abortOperation()`).
+
+#### `thread.ts` — `ThreadSlice`
+State: `threads: UIThread[]`, `activeThreadId`, `threadLoadingState`.
+Actions: `setThreads`, `updateThread`, `removeThread`, `setActiveThreadId`, `setThreadLoadingState`.
+`UIThread` carries `update`/`delete`/`getMessages` closures bound to the raw thread.
+
+#### `message.ts` — `MessageSlice`
+State: `messages: UIMessage[]`, `isGeneratingResponse`, `messageLoadingState`, `isLastResponseSuccess`, `toolTraceState: ToolTraceState[]`, `scrollAnchorRequestId`.
+Actions: `setMessages`, `addMessage`, `updateMessage`, `clearMessages`, `setIsGeneratingResponse`, `setMessageLoadingState`, `setIsLastResponseSuccess`, `setToolTraceState`, `toggleToolTrace`, `toggleToolMessage`, `mergeAccumulatedStreamContent`, `requestScrollAnchor`.
+- Tool traces are stored **separately** from messages, keyed by the assistant message id (`stateForMessageId`), each holding `executedTools` + a `uiMessage` label + `isExpanded`.
+- `scrollAnchorRequestId` is a monotonic counter; `ScrollArea` reacts to each tick to snap to the latest content.
+- `mergeAccumulatedStreamContent(threadId)` flushes a background thread's buffered `StreamState` (user message, tool messages, assistant content, and a synthesised trace) into the visible `messages` when the user switches to that thread.
+
+#### `response-stream.ts` — `ResponseStreamSlice`
+Per-thread streaming state, keyed by thread id:
+```typescript
+type StreamState = {
+    status: ResponseStreamStatus;   // IDLE | STREAMING | COMPLETED | ERROR | ABORTED
+    content: string;
+    messageId: string | null;
+    errorMessage?: string;
+    userMessage: UIUserMessage | null;
+    toolMessages: UIToolMessage[];
+};
+```
+State: `streamsByThreadId: Record<string, StreamState>`, `completionNotifications: string[]`.
+Actions: `startStream`, `updateStreamContent`, `addStreamToolMessage`, `completeStream(threadId, shouldNotify)`, `failStream`, `abortStream`, `untrackStream` (only removes a **terminal** entry), `setStreamState` (partial patch; seeds an `IDLE` entry if missing), `clearStreamState`, `addCompletionNotification`, `clearCompletionNotification`, `clearAllCompletionNotifications`.
+- `updateStreamContent` / `addStreamToolMessage` are no-ops unless status is `STREAMING`.
+- `completeStream` adds the thread to `completionNotifications` only when `shouldNotify` is true (background completion → notification dot).
+
+#### `prompt.ts` — `PromptSlice`
+State: `allPrompts: Prompt[]`, `favoritePromptNames: string[]`, `selectedPrompt`.
+Actions: `setAllPrompts`, `setFavoritePromptNames`, `toggleFavoritePrompt`, `setSelectedPrompt`.
+
+#### `tool.ts` — `ToolSlice`
+State: `tools: UITool[]`, `toolLoadingState`.
+Actions: `setTools`, `updateToolEnabled`, `updateToolState`, `setToolLoadingState`.
+
+#### `working-context.ts` — `WorkingContextSlice`
+State: `isWorkingContextEnabled`, `workingContext`, `workingContextLoadingState`.
+Actions: `setIsWorkingContextEnabled`, `setWorkingContext`, `setWorkingContextLoadingState`.
+
+#### `mcp-apps.ts` — `McpAppsSlice`
+State: `mcpAppInstances: IoAiWeb.McpApps.AppInstance[]`.
+Actions: `addMcpApp` (dedup by id), `removeMcpApp`, `resetMcpApps`.
+
+#### `confirm-modal.ts` — `ConfirmModalSlice`
+State: `isThreadHistoryVisible`, `activePanelContent: PanelContent` (`null | 'prompts' | 'tools' | 'working-context'`), `currentConfirmModal: ConfirmModalConfig | null`.
+Actions: `setIsThreadHistoryVisible`, `setActivePanelContent`, `showConfirmModal`, `closeConfirmModal`.
+This slice only holds modal/panel **presence**. The promise-based request/response bridge lives in `utils/confirmModal.ts` (see [Utilities](#utilities)).
+
+---
+
+## Bootstrap Hooks
+
+Both hooks guard with a `useRef` so initialization runs exactly once, and run in order.
+
+#### `useIoConnectBootstrap.ts`
+On mount, calls `initIoConnect()` (`actions/initIoConnect.ts`). It wires callbacks that set `ioConnectApi`, `isIoConnectReady`, restore `favoritePromptNames` from io.Connect preferences, and apply the saved theme via `isDarkMode`. Also registers the logger with io.Connect's logger when available.
+
+#### `useIoAiWebBootstrap.ts`
+Watches `isIoConnectReady` and `appLoadingState.type`. Once io.Connect is ready and the app is still `NOT_STARTED`, calls `initIoAiWeb(staticConfig, dynamicConfig, ioAssistStore)`.
+
+#### UI hooks
+- `useIsMobileViewport.ts` — `(min-width: 768px)` media-query boolean, SSR-safe, updates on resize.
+- `useHoverMouseFollow.ts` — returns `{ ref, handlers }` for a cursor-following glow effect (layered conic-gradient divs).
+- `useIoConnectApi.ts` / `useIoAiWebApi.ts` — thin wrappers exposing the bootstrapped APIs / message helpers to components. **Internal** (not exported from the package root).
+
+---
+
+## Actions Layer
+
+The `actions/` modules are the React equivalent of the Angular services/effects. They are plain async functions that take the store (and often the configs) and mutate state imperatively.
+
+| Module | Responsibility |
+|--------|---------------|
+| `initIoConnect.ts` | Bootstraps the io.Connect platform from `connectConfig`, sets theme + favorites, registers the logger. |
+| `initIoAiWeb.ts` | Imports `IoAiWebFactory`, builds `WebConfig`, initializes ai-web, wires MCP app events, then runs post-init loaders: `listAgents` (selects `defaultAgentName` or first; then `fetchThreads`), `loadPrompts`, `loadTools`, `checkWorkingContext`. Subscribes to `tools.onChanged` to refetch. |
+| `sendUserMessage.ts` | Creates/reuses the active thread, appends the user message, requests a scroll anchor, calls `agent.stream(...)` with `thread`/`resource` memory params, then hands the run to `processResponseStream`. Refreshes threads on completion. |
+| `processResponseStream.ts` | The AG-UI event loop (see next section). |
+| `abortActiveStream.ts` | Calls `selectedAgent.rawAgent.abortOperation(threadId)`, marks the stream aborted, clears `isGeneratingResponse`. |
+| `newConversation.ts` | Resets to a fresh empty conversation. |
+| `selectThread.ts` | Switches `activeThreadId` and loads that thread's message history. |
+| `deleteThread.ts` | Deletes via `thread.delete()`, removes it from state, clears its stream state, starts a new conversation if it was active. |
+| `renameThread.ts` | Optimistically updates the title, persists via `thread.update({ title })`, reverts on failure. |
+| `toggleTool.ts` | Enables/disables a tool (updates `enabled` + reflects to the MCP layer). |
+| `toggleFavoritePrompt.ts` | Toggles a favorite and persists the set to io.Connect preferences. |
+| `sampling.ts` / `elicitation.ts` | Built-in MCP request handlers + custom-handler selection (see [Sampling & Elicitation](#sampling--elicitation-flow)). |
+| `mcpAppEvents.ts` | Wires `onAppCreated` / `onRecreateRequested` / `onAppRecreated` (see [MCP Apps](#mcp-apps-integration)). |
+
+---
+
+## AG-UI Streaming Pipeline
+
+File: `src/actions/processResponseStream.ts`.
+
+```typescript
+processResponseStream(
+    runHandle: IoAiWeb.Agents.StreamResponse,
+    threadId: string,
+    store: IoAssistStoreInstance,
+    isActiveThread: () => boolean,
+): Promise<void>
+```
+
+It subscribes to the AG-UI `StreamResponse` and maps each event to store mutations. Loop-local state held across the subscription lifetime: `toolCallArgsMap` (per-tool accumulated args), `streamedContent`, `currentMessageId`, and `hasSyntheticPlaceholder`.
+
+| AG-UI Event | Active-thread handling | Background-thread handling |
+|-------------|------------------------|----------------------------|
+| `TEXT_MESSAGE_START` | Reuse the synthetic placeholder if same-turn (matching/empty `messageId`); otherwise set a fresh `currentMessageId` and `addMessage` an empty assistant message. | Same id bookkeeping; no `addMessage`. |
+| `TEXT_MESSAGE_CONTENT` | Append `delta` to `streamedContent`; `ensureAssistantMessage` if none exists; `updateMessage(content)`. | `setStreamState(threadId, { content, messageId })`. |
+| `TEXT_MESSAGE_END` | Reset `hasSyntheticPlaceholder` (turn boundary). | — |
+| `TEXT_MESSAGE_CHUNK` | Combined start+content+end shorthand; create message if `messageId` changed, append text. | Buffer into `setStreamState`. |
+| `MESSAGES_SNAPSHOT` | Reconciliation: add/extend any assistant messages from the snapshot not already shown. | Skipped. |
+| `TOOL_CALL_START` | Create a synthetic placeholder assistant message if none yet; `addMessage(toolMessage)`; `withToolAppendedToTrace`. | Append the tool message to `StreamState.toolMessages`. |
+| `TOOL_CALL_ARGS` | Accumulate `delta` into `toolCallArgsMap[toolCallId].args`. | Same. |
+| `TOOL_CALL_END` | `JSON.parse` accumulated args; `updateMessage(toolCallId, { args })`; `withExecutedToolUpdated` + `withTraceLabel`. | Patch the buffered tool message's `args`. |
+| `TOOL_CALL_RESULT` | Read result off `event.content` (string → `JSON.parse`, falling back to `{ type: TEXT, text }`); `updateMessage(toolCallId, { result })`; update trace. | Patch the buffered tool message's `result`. |
+
+**Terminal handling:**
+- `error` → `failStream`, clear `isGeneratingResponse`, set `isLastResponseSuccess=false`, set `messageLoadingState=ERROR`, unsubscribe, `reject`.
+- `complete` → finalize all trace labels (active thread only) via `withAllTraceLabelsFinalized`, `completeStream(threadId, shouldNotify=!isActiveThread())`, clear `isGeneratingResponse`, set success state, unsubscribe, `resolve`.
+
+A `log.debug('AG-UI event …')` line at the top of `next()` enumerates every received event — the first thing to check when diagnosing missing output after sampling/tool continuations.
+
+---
+
+## Response Stream Store & Background Threads
+
+A single `agent.stream()` call can run multiple turns (text → tool → tool result → text) under one subscription, and the user may switch threads mid-stream. The pipeline routes accordingly:
+
+- **Active thread** → writes straight to `messages` + `toolTraceState` (visible UI).
+- **Background thread** → buffers into `streamsByThreadId[threadId]` (`StreamState`). On completion with `shouldNotify`, the thread id is added to `completionNotifications`, surfacing a notification dot on the thread-history control.
+- **Switching back** → `mergeAccumulatedStreamContent(threadId)` reconciles the buffered user message, tool messages, assistant content, and a synthesised trace into the visible `messages`.
+
+`isActiveThread` is passed as a **callback** (not a boolean) so it re-evaluates on every event — the active thread can change between events.
+
+---
+
+## Sampling & Elicitation Flow
+
+Files: `src/actions/sampling.ts`, `src/actions/elicitation.ts`. Both are injected into the ai-web MCP config by `initIoAiWeb.ts::buildMcpConfig()`:
+
+```typescript
+capabilities: {
+    ...mcp.clientsConfig?.capabilities,
+    sampling:    { handler: selectSampling(mcp) },
+    elicitation: { handler: selectElicitation(mcp) },
+}
+```
+
+`selectSampling` / `selectElicitation` return the consumer's `mcp.clientsConfig.capabilities.{sampling|elicitation}.handler` if it's a function, otherwise the built-in handler.
+
+### Sampling (built-in)
+
+```
+handleSamplingRequest(serverName, request)
+  ├── background thread? (request._meta.threadId !== activeThreadId) → { code: -1, … }   (rejected)
+  ├── isModalsAvailable()? → io.Connect 'noInputsConfirmationDialog' (Continue/Cancel)
+  │                          else → showConfirmModal() built-in overlay (Continue/Cancel)
+  ├── accepted → getSamplingResponse(request):
+  │       formats messages (extractTextContent) + systemPrompt → selectedAgent.rawAgent.generate(params)
+  │       → SamplingSuccessResponse { role:'assistant', content:{type:'text',text}, model, stopReason:'endTurn' }
+  └── declined / preempted / error → { code: -1, message }
+```
+
+`getSamplingResponse` calls `generate()` with `tools.autoIncludeEnabled: false` and passes through `maxTokens`, `temperature`, `modelPreferences`, and `_meta.structuredOutput`.
+
+### Elicitation (built-in)
+
+Validates `_meta.toolName` starts with `io_connect`, rejects background-thread requests, shows an accept/decline/cancel dialog (io.Connect modal or built-in overlay), and returns the corresponding `{ action, content }`.
+
+---
+
+## MCP Apps Integration
+
+Files: `src/actions/mcpAppEvents.ts`, `src/stores/mcp-apps.ts`, `src/components/messages/McpAppResource.tsx`, `src/utils/mcpAppModal.ts`.
+
+`wireMcpAppEvents(ioIntelWeb, store, dynamicConfig)` is called synchronously right after `IoAiWebFactory` resolves (before the post-init `Promise.all`) so no early events are missed:
+
+1. **`onAppCreated(app)`** — `addMcpApp(app)`; subscribe `app.onMessage` and forward app-originated chat messages through `sendUserMessage`. Unsubscribe closures are tracked in a `Map<appId, () => void>`.
+2. **`onRecreateRequested(event)`** — show a "recreate vs new instance" modal (`mcpAppModal.ts` → io.Connect modal or built-in `ConfirmModal`). While the modal is open, duplicate recreate events auto-resolve to avoid stacking.
+3. **`onAppRecreated(event)`** — `removeMcpApp(oldId)` and clean up its message listener.
+
+`McpAppResource.tsx` mounts the SDK-provided `AppInstance.element` (the sandbox-proxy iframe) into a container `div` for **inline** display; **workspace** mode opens an io.Connect workspace window. The component only attaches/detaches the element — ownership stays with the SDK.
+
+Display mode + the `io.modelcontextprotocol/ui` capability extension come from the consumer's `aiWebConfig.mcp` (see the public README's MCP Apps section).
+
+---
+
+## Components
+
+```
+components/
+├── chat/
+│   ├── Chat.tsx              # Main layout: header, message area, input, welcome/favorites
+│   ├── ActivePanelModal.tsx  # Hosts the active side panel (prompts / tools / working context)
+│   ├── ConfirmModal.tsx      # Renders currentConfirmModal; buttons resolve the confirmModal promise
+│   ├── WelcomeHeading.tsx    # Greeting shown on the empty home screen
+│   └── AiDisclaimer.tsx      # AI-usage disclaimer footer
+├── header/Header.tsx         # Thread-history toggle (notification dot), new-chat, working-context buttons
+├── input-area/InputArea.tsx  # Auto-sizing textarea, Enter/Shift+Enter, history cycling, send/stop
+├── messages/
+│   ├── MessageArea.tsx       # Scrollable list; buildRenderList() merges messages + traces + apps
+│   ├── UserMessage.tsx       # User bubble
+│   ├── AssistantMessage.tsx  # Markdown-rendered assistant bubble
+│   ├── ToolTraceMessage.tsx  # Collapsible per-turn tool trace
+│   ├── ToolMessage.tsx       # Single tool call (args + result)
+│   ├── McpAppResource.tsx    # Mounts an inline MCP App element
+│   ├── MdFormatter.tsx       # react-markdown + remark-gfm; code via prism-react-renderer
+│   ├── mdUtils.ts            # Markdown helpers
+│   └── prismTwilightTheme.ts # Prism color theme
+├── threads/                  # ThreadHistoryPanel / ThreadHistory / ThreadHistoryListItem
+├── tool/                     # ToolListPanel / ToolListItem
+├── prompt/                   # PromptListPanel / PromptListItem / FavoritePromptList
+├── working-context-panel/WorkingContextPanel.tsx
+├── scroll-area/ScrollArea.tsx   # Scroll container reacting to scrollAnchorRequestId
+└── shared/                   # Icon, IconButton, Modal, SearchInput, ToggleInput, Tooltip, icons.tsx
+```
+
+Components subscribe with narrow selectors via `useIoAssistStore(s => …)` to avoid broad re-renders (the store uses `subscribeWithSelector`).
+
+---
+
+## Utilities
+
+File reference for `src/utils/`:
+
+| File | Purpose |
+|------|---------|
+| `confirmModal.ts` | Promise bridge for the built-in modal. `showConfirmModal(config)` calls the `confirmModal` slice's `showConfirmModal` and returns a `Promise<buttonId \| MODAL_PREEMPTED>`; `ConfirmModal.tsx` resolves it on click. A new request **preempts** an unresolved one with the `MODAL_PREEMPTED` sentinel. |
+| `ioModals.ts` | io.Connect Modals wrapper: `isModalsAvailable()`, `requestModalDialog(options)` (uses `noInputsConfirmationDialog`). |
+| `mcpAppModal.ts` | MCP App recreate prompt (io.Connect modal → built-in fallback). |
+| `messageConverter.ts` | Converts raw backend thread messages → `UIMessage[]`; `extractTextContent()` pulls text from mixed content shapes (also used by sampling). |
+| `messageUtils.ts` | `buildRenderList(...)` merges messages, tool traces, and MCP apps into an ordered render list. |
+| `streamUtils.ts` | Pure tool-trace helpers: `ensureAssistantMessage`, `withToolAppendedToTrace`, `withExecutedToolUpdated`, `withTraceLabel`, `withAllTraceLabelsFinalized`. |
+| `threadUtils.ts` | Groups threads into relative-time buckets for the history panel. |
+| `safeStringify.ts` | `JSON.stringify` with a `String(value)` fallback (for logging). |
+| `logger.ts` | Namespaced logger (`logger.get(name)`), io.Connect logger when registered, console fallback otherwise. |
+
+---
+
+## Styling
+
+- **Tailwind CSS** — `src/styles/index.css` is the entry (`@import 'tailwindcss'`, `@font-face`, `@theme`); `src/styles/defaults.css` defines the CSS variables that back the theme for light and dark mode.
+- **Theme sync** — `initIoConnect` reads/sets `isDarkMode`; the dark-mode class on the document toggles the variable set.
+- **Exported stylesheet** — `@interopio/io-assist-react/styles` (`exports["./styles"]` → `dist/styles.css`) must be imported by the consumer.
+- **Fonts** — Inter is bundled via `@fontsource-variable/inter` (no external CDN fetch, unlike the Angular package).
+- **Code highlighting** — `prism-react-renderer` renders fenced code blocks in `MdFormatter.tsx` using `prismTwilightTheme`.
+
+---
+
+## Build & Tooling
+
+- **Bundler** — Vite library build (`vite.config.ts`). `npm run build` → `dist/`; `npm run dev` → `vite build --watch`.
+- **Entry points** — ESM (`dist/index.js`), CJS (`dist/index.cjs`), types (`dist/index.d.ts`), styles (`dist/styles.css`).
+- **Peer deps** — only `react` / `react-dom` (`>=18`); all io.Connect/ai-web/UI packages are bundled `dependencies`.
+- **Lint** — `npm run lint` (ESLint flat config), `npm run lint:fix`.
+- **Tests** — none in this package at present.
+
+---
+
+## Known Caveats
+
+- **Cross-turn placeholder leakage.** Because one `agent.stream()` runs N turns under a single subscription, `currentMessageId` / `streamedContent` / `hasSyntheticPlaceholder` persist across turns. The `TEXT_MESSAGE_START` "same-turn" check and the `TEXT_MESSAGE_END` reset exist specifically to stop a later turn's text from being appended to the previous turn's bubble (a recurring source of "nothing rendered after I clicked Continue" bugs in sampling/tool-continuation flows). Preserve this logic when refactoring the pipeline.
+- **Tool result field.** AG-UI delivers tool results on `event.content` (string or object), **not** `event.result`. `TOOL_CALL_RESULT` reads `event.content` accordingly.
+- **No config validation.** Malformed configs fail later and less obviously than in the Angular package (which uses Zod). Consider validating in the provider if this becomes a support burden.