@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214-snapshot.20260528192313

package/src/components/chat/hooks/.use-sse.md

@@ -0,0 +1,60 @@
+<!-- source-hash: cbf092b126eb212162fd68f7341c0c6d -->
+A React hook that manages Server-Sent Events (SSE) streaming for chat messages, handling abort control, error states, and async generator-based chunk processing.
+
+## Key Components
+
+### Types & Interfaces
+
+| Export | Description |
+|--------|-------------|
+| `StreamFnExtraOptions` | Per-call options: `commandOverride`, `approvalAction` (tool approval/rejection routing), `pendingAttachments` (chat file uploads) |
+| `StreamFn` | Async generator signature `(message, signal?, extra?) => AsyncGenerator<MessageSegment>` |
+| `UseSSEOptions` | Hook config: `useMock`, `debugMode`, `streamFn` |
+
+### Hook Return Values
+
+| Value | Type | Description |
+|-------|------|-------------|
+| `streamMessage` | `AsyncGenerator fn` | Initiates streaming with fresh `AbortController` per call |
+| `isStreaming` | `boolean` | Streaming in-progress state |
+| `error` | `string \| null` | Last error message (AbortErrors are suppressed) |
+| `abort` | `() => void` | Cancels active stream and terminates upstream fetch |
+| `reset` | `() => void` | Resets hook state |
+
+## Usage Example
+
+```typescript
+import { useSSE } from './use-sse'
+import { createDocStreamFn } from './use-embedded-chat'
+
+function ChatComponent() {
+  const streamFn = createDocStreamFn({ sessionId: 'abc123' })
+  const { streamMessage, isStreaming, error, abort } = useSSE({
+    useMock: false,
+    streamFn,
+  })
+
+  const handleSend = async (message: string) => {
+    for await (const chunk of streamMessage(message, {
+      commandOverride: { command: '/discuss', payload: cardId },
+      pendingAttachments: stagedFiles,
+    })) {
+      appendChunk(chunk)
+    }
+  }
+
+  return (
+    <>
+      <button onClick={() => handleSend('Hello')}>Send</button>
+      {isStreaming && <button onClick={abort}>Stop</button>}
+      {error && <p>{error}</p>}
+    </>
+  )
+}
+```
+
+## Notes
+
+- `useMock: true` without a `streamFn` throws loudly by design — mock implementations must be provided by the host application
+- `AbortController` is created fresh per `streamMessage` call; the ref guards against race conditions in rapid send→stop→send sequences
+- `approvalAction` routes to `/api/chat/agent/confirm-tool` instead of `/api/docs/chat` for tool approval flows

package/src/components/chat/hooks/.use-unified-chat.md

@@ -0,0 +1,57 @@
+<!-- source-hash: 5f44f9c9a190ae929c177b9308e2bf01 -->
+Single public entry-point hook that dispatches chat state and actions to either the SSE/Guide or NATS/Mingo transport adapter based on the active mode, while always satisfying React's rules of hooks by keeping both adapters mounted.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `useUnifiedChat` | Hook | Primary hook — returns a stable `UnifiedChatState` for the active transport |
+| `ChatMode` | Type | `'guide'` (SSE) or `'mingo'` (NATS) |
+| `UseUnifiedChatModes` | Interface | Per-mode config slots; each is optional |
+| `UseUnifiedChatOptions` | Interface | `{ modes, activeMode }` passed to the hook |
+
+## Architecture
+
+```mermaid
+graph TD
+    Consumer["Consumer Component"] --> UUC["useUnifiedChat"]
+    UUC --> SSE["useSseChatAdapter\n(guide mode)"]
+    UUC --> NATS["useNatsChatAdapter\n(mingo mode)"]
+    SSE -->|"active when guide"| ActiveState["UnifiedChatState\n(returned)"]
+    NATS -->|"active when mingo"| ActiveState
+    SSE -.->|"idle / buffered"| Inactive["Inactive Adapter\n(state preserved)"]
+    NATS -.->|"idle / buffered"| Inactive
+```
+
+## Usage Example
+
+```typescript
+// Guide-only consumer
+const chat = useUnifiedChat({
+  activeMode: 'guide',
+  modes: {
+    guide: { /* UseSseChatAdapterOptions */ },
+  },
+})
+
+// Dual-mode consumer (mode toggle lives in the shell component)
+const chat = useUnifiedChat({
+  activeMode: currentMode, // 'guide' | 'mingo'
+  modes: {
+    guide: {},
+    mingo: {
+      dialogId: 'dialog-abc',
+      getNatsWsUrl: () => 'wss://nats.example.com',
+      publishUserMessage: async (msg) => publishToNats(msg),
+    },
+  },
+})
+
+chat.sendMessage('How do I reset a password?')
+```
+
+## Key Behaviours
+
+- **Both adapters always mount** — inactive adapter holds its message buffer, so flipping `activeMode` restores the user to exactly where they left off in each conversation.
+- **Disabled fallback** — if a mode's config slot is `undefined`, a stable no-op default is injected (ref-stabilised for NATS, constant for SSE) to prevent hook churn.
+- **Stable return identity** — all callbacks are `useCallback`-wrapped and the final object is `useMemo`-stabilised; consumers receive a referentially stable `UnifiedChatState` on every render.

package/src/components/chat/types/.api.types.md

@@ -1,48 +1,62 @@
-<!-- source-hash: a73867ba07ef4db1732d63872e920f29 -->
-Comprehensive TypeScript definitions for API interactions and React hooks in a chat system with real-time messaging capabilities. Includes types for NATS subscriptions, chunk processing, dialog management, and approval workflows.
+<!-- source-hash: 60ad035125eceb97fa074f58783d5bc8 -->
+Defines TypeScript interfaces for API interactions and React hook contracts used across Flamingo's chat and dialog systems, covering NATS/JetStream subscriptions, real-time chunk processing, and REST-style request/response shapes.
 
 ## Key Components
 
-**Hook Options:**
-- `UseChunkCatchupOptions` - Configuration for catching up on missed message chunks
-- `UseNatsDialogSubscriptionOptions` - NATS WebSocket subscription configuration with client settings
-- `UseRealtimeChunkProcessorOptions` - Real-time message processing with approval filtering
-
-**Hook Return Types:**
-- `UseChunkCatchupReturn` - Chunk catchup functionality with buffering controls
-- `UseNatsDialogSubscriptionReturn` - Connection status for NATS subscriptions
-- `UseRealtimeChunkProcessorReturn` - Message segment processing and approval management
-
-**API Request/Response Types:**
-- Chat API endpoints (`ChatAPIRequest`, `ChatAPIResponse`)
-- Dialog management (`DialogCreateRequest`, `DialogListResponse`)
-- Approval workflows (`ApprovalRequest`, `ApprovalResponse`)
-- Settings management (`ChatSettings`, `UpdateSettingsRequest`)
-
-**Callback Interfaces:**
-- `RealtimeChunkCallbacks` - Comprehensive event handlers for streaming, metadata, approvals, and escalations
+### Hook Options
+| Interface | Purpose |
+|---|---|
+| `UseChunkCatchupOptions` | Configure chunk catch-up replay with optional custom fetch function |
+| `UseNatsDialogSubscriptionOptions` | Core NATS WebSocket subscription config with reconnection backoff tuning |
+| `UseJetStreamDialogSubscriptionOptions` | JetStream-based subscription with sequence-based resume support |
+| `UseRealtimeChunkProcessorOptions` | Controls how streaming chunks are parsed, including approval routing and batch mode |
+
+### Hook Return Types
+| Interface | Purpose |
+|---|---|
+| `UseChunkCatchupReturn` | Exposes catchup, processing, and buffering controls |
+| `UseNatsDialogSubscriptionReturn` | Connection state and reconnection counter |
+| `UseJetStreamDialogSubscriptionReturn` | Connection state plus current stream sequence |
+| `UseRealtimeChunkProcessorReturn` | Chunk processing, segment access, and approval status management |
+
+### Callbacks
+- **`RealtimeChunkCallbacks`** — Rich event callback map for streaming events: `onStreamStart`, `onStreamEnd`, `onSegmentsUpdate`, `onTokenUsage`, `onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`, `onToolExecuted`, `onDialogClosed`, and more.
+
+### API Request/Response Types
+- **Chat** — `ChatAPIRequest` / `ChatAPIResponse`
+- **Dialogs** — `DialogCreateRequest/Response`, `DialogListRequest/Response`
+- **Approvals** — `ApprovalRequest` / `ApprovalResponse`
+- **Settings** — `ChatSettings`, `UpdateSettingsRequest/Response`
 
 ## Usage Example
 
 ```typescript
-// Configure real-time chunk processing
-const processorOptions: UseRealtimeChunkProcessorOptions = {
+const options: UseRealtimeChunkProcessorOptions = {
   callbacks: {
-    onStreamStart: () => console.log('Stream started'),
-    onSegmentsUpdate: (segments) => updateUI(segments),
-    onApprove: async (requestId) => await approveRequest(requestId),
-    onEscalatedApproval: (id, data) => handleEscalation(id, data)
+    onSegmentsUpdate: (segments, meta) => {
+      if (meta?.append) appendToLastMessage(segments)
+      else setSegments(segments)
+    },
+    onApprovalResolved: (requestId, status, approvalType) => {
+      updateApprovalBadge(requestId, status)
+    },
+    onTokenUsage: (data) => console.log('Tokens used:', data),
+  },
+  batchApprovalsEnabled: true,
+  displayApprovalTypes: ['CLIENT'],
+  enableThinking: false,
+}
+
+const natsOptions: UseNatsDialogSubscriptionOptions = {
+  enabled: true,
+  dialogId: 'dialog-123',
+  getNatsWsUrl: () => 'wss://nats.example.com',
+  reconnectionBackoff: {
+    fastRetries: 3,
+    fastRetryDelayMs: 500,
+    maxDelayMs: 30000,
+    multiplier: 2,
   },
-  displayApprovalTypes: ['CLIENT', 'ADMIN'],
-  initialState: {
-    existingSegments: previousSegments,
-    pendingApprovals: new Map()
-  }
-};
-
-// Dialog creation request
-const createDialog: DialogCreateRequest = {
-  name: 'Support Session',
-  metadata: { customer: 'user123', priority: 'high' }
-};
+  onBeforeReconnect: async () => refreshAuthToken(),
+}
 ```

package/src/components/chat/types/.chat.types.md

@@ -1,47 +1,56 @@
-<!-- source-hash: 64e087729cbab55280b984028a72489d -->
-Core TypeScript type definitions for Flamingo's AI-powered chat system, providing strongly-typed constants and interfaces for chat operations across MSP platform interactions.
+<!-- source-hash: 38493d239449552957a80bb746221c21 -->
+Defines core constants, enums, types, and utility functions for the Flamingo chat system, covering chat participants, message roles, connection states, and SSE wire shapes.
 
 ## Key Components
 
-- **CHAT_TYPE** - Defines client and admin chat channel types
-- **OWNER_TYPE** - Specifies message ownership (CLIENT, ADMIN, ASSISTANT)
-- **MESSAGE_ROLE** - Standard chat roles (user, assistant, system, error)
-- **ASSISTANT_TYPE** - Flamingo AI assistants (Fae for clients, Mingo for technicians)
-- **APPROVAL_STATUS** - Chat message approval workflow states
-- **CONNECTION_STATUS** - WebSocket connection state management
-- **MessageOwner** - Interface for tracking message attribution and metadata
+| Export | Kind | Description |
+|--------|------|-------------|
+| `CHAT_TYPE` / `ChatType` | Const + Type | Distinguishes `CLIENT_CHAT` from `ADMIN_AI_CHAT` contexts |
+| `OWNER_TYPE` / `OwnerType` | Const + Type | Message ownership: `CLIENT`, `ADMIN`, or `ASSISTANT` |
+| `MESSAGE_ROLE` / `MessageRole` | Const + Type | Conversation roles: `user`, `assistant`, `error`, `system` |
+| `ASSISTANT_TYPE` / `AssistantType` | Const + Type | AI assistants: `fae` (client-facing) and `mingo` (technician-facing) |
+| `AUTHOR_TYPE` / `AuthorType` | Const + Type | Full author roster including `user`, `admin`, `fae`, `mingo`, `system` |
+| `APPROVAL_STATUS` / `ChatApprovalStatus` | Const + Type | Approval workflow states: `pending`, `approved`, `rejected` |
+| `CONNECTION_STATUS` / `ConnectionStatus` | Const + Type | WebSocket/SSE lifecycle states |
+| `MessageOwner` | Interface | Identifies who owns a message, with optional user profile fields |
+| `buildChatRefKey` | Function | Builds canonical `docType:externalId` keys for `chatRefs` map lookups |
+| `isStructuredContent` | Function | Type guard — checks if `MessageContent` is a `MessageSegment[]` |
+| `normalizeContent` | Function | Coerces string or segment array to a uniform `MessageSegment[]` |
+| `TextEventData` / `ToolExecutionEventData` / `SSEEventData` | Interfaces + Union | Wire shapes for SSE streaming events |
+| `QuickAction` | Interface | Shape for quick-reply chip components (`id` + `text`) |
 
 ## Usage Example
 
 ```typescript
-import { 
-  CHAT_TYPE, 
-  MESSAGE_ROLE, 
-  ASSISTANT_TYPE, 
-  MessageOwner,
-  ConnectionStatus 
+import {
+  CHAT_TYPE,
+  MESSAGE_ROLE,
+  ASSISTANT_TYPE,
+  APPROVAL_STATUS,
+  CONNECTION_STATUS,
+  buildChatRefKey,
+  isStructuredContent,
+  normalizeContent,
 } from './chat.types'
 
-// Create a client chat message
-const clientMessage = {
-  role: MESSAGE_ROLE.USER,
-  content: "Help with server issues",
-  chatType: CHAT_TYPE.CLIENT
-}
+// Route to the correct AI assistant based on chat context
+const assistant =
+  chatType === CHAT_TYPE.CLIENT ? ASSISTANT_TYPE.FAE : ASSISTANT_TYPE.MINGO
 
-// Define assistant response owner
-const faeOwner: MessageOwner = {
-  type: OWNER_TYPE.ASSISTANT,
-  machineId: 'fae-01',
-  model: ASSISTANT_TYPE.FAE
-}
+// Build a chatRefs lookup key matching inline [card://ticket:42] markers
+const refKey = buildChatRefKey('ticket', '42') // → "ticket:42"
 
-// Handle connection states
-const handleConnectionChange = (status: ConnectionStatus) => {
-  if (status === CONNECTION_STATUS.CONNECTED) {
-    console.log('Chat service ready')
-  }
+// Normalize incoming content before rendering
+const segments = normalizeContent(message.content)
+// → always MessageSegment[], safe to iterate
+
+// Check approval before displaying an action
+if (approval === APPROVAL_STATUS.PENDING) {
+  showApprovalBanner()
 }
-```
 
-This type system ensures type safety across Flamingo's chat components while supporting both client-facing (Fae) and technician-focused (Mingo) AI interactions within the unified OpenFrame platform.
+// Handle SSE connection lifecycle
+if (status === CONNECTION_STATUS.RECONNECTING) {
+  showReconnectingSpinner()
+}
+```

package/src/components/chat/types/.component.types.md

@@ -1,61 +1,60 @@
-<!-- source-hash: ba9f2a73586812d02d2b98db0ff1f6f0 -->
-TypeScript component prop interface definitions for a comprehensive chat UI system, providing type safety for React components used in AI-powered chat interfaces with approval workflows, tool execution displays, and dialog management.
+<!-- source-hash: 141d208f153f42ac4e3acd48496b0621 -->
+Defines all TypeScript prop and ref types for the chat UI component library, covering containers, headers, messages, message lists, inputs, and slash command affordances.
 
 ## Key Components
 
-**Core Chat Props**:
-- `ChatContainerProps` - Main chat wrapper with HTML div attributes
-- `ChatHeaderProps` - Header with user info, settings, and connection status
-- `ChatMessageEnhancedProps` - Enhanced messages supporting segments, typing states, and approval callbacks
-- `ChatMessageListProps` - Message list with scrolling, loading states, and approval handling
-- `ChatInputProps` - Text input with send functionality and response states
-
-**Specialized Component Props**:
-- `ToolExecutionDisplayProps` - Expandable tool execution results display
-- `ApprovalRequestMessageProps` - Interactive approval request with status handling
-- `ConnectionIndicatorProps` - Real-time connection status indicator
-- `ChatTypingIndicatorProps` - Animated typing indicator with customizable appearance
-- `ChatQuickActionProps` - Action buttons with hint animations and loading states
-
-**Navigation & Management**:
-- `ChatSidebarProps` - Dialog list with infinite scroll and creation states
-- `DialogListItemProps` - Individual dialog items with selection and unread counts
-- `ModelDisplayProps` - AI model information display with provider details
+### Core Component Props
+- **`ChatContainerProps`** — Extends `HTMLAttributes<HTMLDivElement>` for the root chat wrapper
+- **`ChatHeaderProps`** — Full header configuration including user info, connection status, ticket info, `fullWidth`, and `bare` display modes
+- **`ChatMessageEnhancedProps`** — Per-message props including role, content (`string | MessageSegment[]`), entity card rendering, and markdown link routing
+- **`ChatMessageListProps`** — Message list with infinite scroll, approval handling, avatar display, and forwarded `renderEntityCard`/`NavLinkAnchor` props
+- **`ChatMessageListRef`** — Imperative handle exposing `scrollToBottom`, `getScrollPosition`, and `setScrollPosition`
+- **`ConnectionIndicatorProps`** — Wraps `ConnectionStatus` for the connection state badge
+
+### Slash Commands
+- **`SlashCommandsProp`** — Consumer-supplied `fetchCommands` callback and optional `resolveSourceIcon` for autocomplete
+- **`SlashCommandSummary`** — Server-resolved command descriptor with `actions`, `argumentHint`, `label`, `displayOrder`, and `iconName`
+- **`SlashCommandActionId`** — String-literal union: `'browse' | 'search' | 'find' | 'display'`
+- **`SlashCommandSourceMeta`** — Icon component + label pair returned by `resolveSourceIcon`
+
+### Routing
+- **`NavLinkAnchorComponent`** — Host-supplied anchor component for markdown links, enabling unified routing (soft same-origin nav, new-tab cross-origin)
 
 ## Usage Example
 
 ```typescript
-import type { 
-  ChatMessageEnhancedProps, 
-  ChatInputProps, 
-  ApprovalRequestMessageProps 
+import type {
+  ChatMessageListProps,
+  ChatHeaderProps,
+  NavLinkAnchorComponent,
+  SlashCommandsProp,
 } from './component.types'
 
-// Enhanced message with approval handling
-const messageProps: ChatMessageEnhancedProps = {
-  role: 'assistant',
-  content: [
-    { type: 'text', content: 'Here is the analysis:' },
-    { 
-      type: 'approval_request', 
-      data: { requestId: 'req_123', action: 'execute_command' } 
-    }
-  ],
-  assistantType: 'mingo',
-  onApprove: async (requestId) => {
-    await approveRequest(requestId)
-  },
-  onReject: (requestId) => {
-    rejectRequest(requestId)
-  }
+// Host-supplied anchor delegates routing to app router
+const NavLinkAnchor: NavLinkAnchorComponent = ({ href, className, children }) => (
+  <a href={href} className={className}>{children}</a>
+)
+
+const headerProps: ChatHeaderProps = {
+  userName: 'Mingo AI',
+  connectionStatus: 'connected',
+  fullWidth: true,   // fills narrow side panel
+  bare: true,        // no card chrome inside Drawer
+}
+
+const listProps: ChatMessageListProps = {
+  messages,
+  fullWidth: true,
+  hasNextPage: true,
+  isFetchingNextPage: false,
+  onLoadMore: fetchOlderMessages,
+  renderEntityCard: (ref) => <EntityCard reference={ref} />,
+  NavLinkAnchor,
 }
 
-// Chat input with send handling
-const inputProps: ChatInputProps = {
-  onSend: (message) => sendMessage(message),
-  sending: false,
-  awaitingResponse: true,
-  maxRows: 4,
-  placeholder: "Ask Mingo anything..."
+const slashCommands: SlashCommandsProp = {
+  fetchCommands: async (prefix, signal) =>
+    fetch(`/api/docs/commands?q=${prefix}`, { signal }).then(r => r.json()),
+  resolveSourceIcon: (sourceId) => iconRegistry[sourceId],
 }
 ```

package/src/components/chat/types/.index.md

@@ -1,36 +1,29 @@
-<!-- source-hash: aea0bf978ce55f3fb2871d4071c7fd48 -->
-This TypeScript file serves as the main export barrel for type definitions, providing a centralized entry point for importing all types used throughout the system's chat, messaging, component, network, processing, and API layers.
+<!-- source-hash: 20e5ae4b1dc4695977d9dc1f7ed04663 -->
+Central barrel export file that re-exports all TypeScript types and interfaces from the chat module's type definitions.
 
 ## Key Components
 
-The file re-exports types from six specialized modules:
-
-- **chat.types** - Chat-related type definitions and interfaces
-- **message.types** - Message structure and formatting types  
-- **component.types** - UI component and React component types
-- **network.types** - Network request/response and connection types
-- **processing.types** - Data processing and transformation types
-- **api.types** - API endpoint and service interface types
+| Export Source | Description |
+|---|---|
+| `chat.types` | Core chat session and conversation types |
+| `message.types` | Message structure and content types |
+| `component.types` | UI component prop and state types |
+| `network.types` | Network request/response types |
+| `processing.types` | Message processing and transformation types |
+| `api.types` | API contract and endpoint types |
+| `entities` | Domain entity definitions |
+| `unified-chat-state.types` | Unified state management types for chat |
 
 ## Usage Example
 
 ```typescript
-// Import specific types from the barrel export
-import { ChatMessage, ApiResponse, ComponentProps } from './types'
-
-// Or import all types with namespace
-import * as Types from './types'
-
-// Use the imported types
-const message: Types.ChatMessage = {
-  id: '123',
-  content: 'Hello world',
-  timestamp: new Date()
-}
-
-const apiCall = async (): Promise<Types.ApiResponse> => {
-  // API implementation
-}
+// Import any chat-related type directly from the module root
+import {
+  ChatSession,
+  Message,
+  UnifiedChatState,
+  ApiResponse
+} from '@/types/chat'
 ```
 
-This barrel export pattern simplifies imports across the codebase by allowing consumers to import multiple related types from a single source rather than importing from individual type files.
+> All types are available from a single import path — no need to reference individual type files directly.

package/src/components/chat/types/.message.types.md

@@ -1,62 +1,72 @@
-<!-- source-hash: 85b8ef73de713600cd760aa44e399e60 -->
-This file defines comprehensive TypeScript types for message handling in a chat system that supports AI assistants, tool execution, and approval workflows.
+<!-- source-hash: 08cea50ef9b44d5ac821b066fa03a785 -->
+Defines all message-related TypeScript types, interfaces, and constants used across the Flamingo chat system — covering message lifecycle events, tool execution, approval flows, and rendered content segments.
 
 ## Key Components
 
-**Core Message Types:**
-- `MESSAGE_TYPE` - Constants for all message types (TEXT, EXECUTING_TOOL, APPROVAL_REQUEST, etc.)
-- `MessageData` - Union type for all possible message data structures from GraphQL/API
-- `MessageSegment` - Union type for different content segments (text, tool execution, approval requests, errors)
-- `ProcessedMessage` - Processed message structure for UI display
-- `HistoricalMessage` - Message structure for chat history storage
+### Constants
+- **`MESSAGE_TYPE`** — Enum-like const object for all message event types (e.g. `TEXT`, `THINKING`, `EXECUTING_TOOL`, `APPROVAL_REQUEST`, `ERROR`, `CONTEXT_COMPACTION_*`, etc.)
+- **`SCROLL_ANCHOR`** — Viewport positioning hint (`top` | `bottom`) controlling chat scroll behavior per message
 
-**Tool Execution Types:**
-- `ToolExecutionData` - Structure for tool execution parameters and results
-- `ExecutingToolMessageData` / `ExecutedToolMessageData` - API message data for tool operations
+### Tool Execution
+- **`ToolExecutionData`** — Payload for `EXECUTING_TOOL` / `EXECUTED_TOOL` events, including tool identity, parameters, and optional merge ID
+- **`ExecutingToolState`** — In-flight snapshot held between execution events to preserve `toolTitle` across merge
 
-**Approval System Types:**
-- `ApprovalRequestData` - Structure for approval requests with commands and explanations
-- `ApprovalResultData` - Structure for approval responses
-- `ApprovalRequestSegment` - UI segment with approval callbacks
+### Approval Flow
+- **`ApprovalRequestData`** / **`ApprovalResultData`** — Single-tool approval request/result payloads
+- **`ApprovalBatchData`** / **`PendingToolCallData`** / **`ApprovalBatchExecutionState`** — Batch approval structures for multi-tool proposals with per-tool execution tracking
+
+### Message Segments (UI Rendering)
+- **`MessageSegment`** — Union of `TextSegment`, `ThinkingSegment`, `ToolExecutionSegment`, `ApprovalRequestSegment`, `ApprovalBatchSegment`, `ErrorSegment`, `ContextCompactionSegment`
+- **`MessageContent`** — `string | MessageSegment[]`
+
+### Wire / API Data Types
+- **`MessageData`** — Discriminated union of all backend-sourced message data shapes (`TextMessageData`, `ExecutingToolMessageData`, `ApprovalRequestMessageData`, `AIMetadataMessageData`, etc.)
+- **`TokenUsageData`** — Input/output/total/context token counts
+
+### Core Message Interfaces
+- **`Message`** — Primary chat message object with role, content, scroll anchor, `chatRefs` for entity cards, and `hidden` flag for synthetic continuation turns
+- **`ProcessedMessage`** — Normalized display-ready message derived from raw history
+- **`HistoricalMessage`** — Raw persisted message shape from GraphQL/API
 
 ## Usage Example
 
 ```typescript
-// Creating a text message
-const textMessage: Message = {
-  id: 'msg-123',
-  role: 'assistant',
-  content: 'Hello! How can I help you today?',
-  assistantType: 'MINGO',
-  timestamp: new Date()
-}
+import {
+  MESSAGE_TYPE,
+  SCROLL_ANCHOR,
+  type Message,
+  type MessageSegment,
+  type ApprovalBatchData
+} from './message.types'
 
-// Creating a tool execution message
-const toolMessage: ProcessedMessage = {
-  id: 'msg-456',
-  role: 'assistant',
-  content: [{
-    type: 'tool_execution',
+// Build a message with mixed content segments
+const segments: MessageSegment[] = [
+  { type: 'text', text: 'Creating a ticket for you...' },
+  {
+    type: 'approval_batch',
     data: {
-      type: 'EXECUTING_TOOL',
-      integratedToolType: 'file_system',
-      toolFunction: 'readFile',
-      parameters: { path: '/config/settings.json' }
-    }
-  }],
-  timestamp: new Date()
-}
-
-// Creating an approval request segment
-const approvalSegment: ApprovalRequestSegment = {
-  type: 'approval_request',
-  data: {
-    command: 'sudo rm -rf /tmp/cache',
-    explanation: 'Clear temporary cache files',
-    approvalRequestId: 'req-789'
-  },
-  onApprove: async (requestId) => {
-    console.log(`Approved request: ${requestId}`)
+      approvalRequestId: 'req_123',
+      approvalType: 'CLIENT',
+      toolCalls: [
+        {
+          toolExecutionRequestId: 'exec_456',
+          toolName: 'create_ticket',
+          toolTitle: 'Create Support Ticket',
+          requiresApproval: true,
+          approvalType: 'CLIENT',
+        }
+      ]
+    },
+    status: 'PENDING',
+    onApprove: async (id) => console.log('Approved:', id),
   }
+]
+
+const msg: Message = {
+  id: 'msg_789',
+  role: 'assistant',
+  content: segments,
+  scrollAnchor: SCROLL_ANCHOR.TOP,
+  timestamp: new Date(),
 }
 ```