@flamingo-stack/openframe-frontend-core 0.0.481 → 0.0.482

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

@@ -1,34 +1,45 @@
-<!-- source-hash: c000c5cabcd81a500ce236944b8c4464 -->
-Provides the SSE/Guide-mode transport adapter for the unified chat surface, implementing `UnifiedChatState` by consuming server-sent events from the chat stream endpoint and mapping them into structured `DocChatMessage` segments, sources, refs, and per-turn metadata.
+<!-- source-hash: b64329bea22eab16802f8dbf5b7a58c5 -->
+Provides the SSE (Server-Sent Events) transport adapter for the unified chat surface, implementing `UnifiedChatState` for Guide mode. Serves as the canonical replacement for the legacy `useEmbeddedChat` hook following the unified-chat refactor.
 
 ## Key Components
 
-| Export | Type | Description |
-|--------|------|-------------|
-| `useSseChatAdapter` | Hook | Primary hook — reads `source` from runtime context, manages SSE stream lifecycle, slash commands, and turn metadata |
-| `DocChatMessage` | Interface | Full message shape including `segments`, `sources`, `chatRefs`, and `scrollAnchor` |
-| `ChatSource` | Interface | Per-citation source descriptor with support for single-row and grouped chips |
-| `ChatTurnMeta` | Interface | Per-turn LLM metadata (provider, token counts, cache hit rate, routing decision) |
-| `UseSseChatAdapterOptions` | Interface | DI options — primarily `tableIdForDocumentType` override for non-standard RAG table configs |
-| `StreamingPhase` | Type (re-export) | Streaming lifecycle phase, re-exported from `unified-chat-state.types` for backward compatibility |
-| `createDocStreamFn` | Internal factory | Builds the per-call async generator that POSTs to the SSE endpoint and yields `MessageSegment` chunks |
+### Exported Types
+
+- **`DocSource`** — Opaque string identifier for a chat source (registry lookup handled server-side)
+- **`ChatSource`** — Structured source metadata including document type, navigation paths, grouped chip items, and platform targeting
+- **`DocChatMessage`** — Chat message shape with structured `segments`, `sources`, `chatRefs`, and `scrollAnchor` support
+- **`ChatTurnMeta`** — Per-turn metadata extracted from the streamed metadata frame (model, token counts, cache hit rate, routing decisions)
+- **`StreamingPhase`** — Re-exported from `unified-chat-state.types` for backward-compatible imports
+- **`UseSseChatAdapterOptions`** — DI options; notably `tableIdForDocumentType` for RAG table lookups
+- **`UseSseChatAdapterRuntimeOptions`** — Runtime gate (`active`) to suppress background slash-command fetches in inactive modes
+
+### Internal Helpers
+
+- **`createEmptyTurnMeta()`** — Factory for a zeroed `ChatTurnMeta` object
+- **`escapeThinkingTags(text)`** — Escapes `<` to `&lt;` so Claude's thinking-block XML tokens don't break `rehypeRaw` rendering
+- **`createDocStreamFn(...)`** — Factory that produces a per-call async generator handling SSE stream consumption, approval-action routing, and message history filtering (hidden messages excluded from wire format)
 
 ## Usage Example
 
 ```typescript
 import { useSseChatAdapter } from './use-sse-chat-adapter'
+import type { UseSseChatAdapterOptions } from './use-sse-chat-adapter'
 
-// Basic — tableIdForDocumentType defaults to the lib-baked map
-const chatState = useSseChatAdapter()
-
-// With custom document type registry (per-tenant override)
-const chatState = useSseChatAdapter({
+// Optional: override the default RAG table lookup for per-tenant types
+const options: UseSseChatAdapterOptions = {
   tableIdForDocumentType: (docType) =>
-    myTenantRegistry[docType] ?? null,
-})
+    myTenantRegistry.tableIdFor(docType) ?? null,
+}
 
-// Consume the returned UnifiedChatState
-const { messages, sendMessage, isStreaming, streamingPhase } = chatState
+const chatState = useSseChatAdapter(options, { active: true })
 ```
 
-> **Note:** `source` is read automatically from `ChatRuntimeContext` — no parameter needed. It is optional: an empty `source` falls back to a stable constant (`DEFAULT_CHAT_SOURCE`) for the localStorage history namespace and is never sent on the wire (the hub resolves source server-side).
+**Key behavioral contracts:**
+
+- `source` is read from runtime context, never sent on the wire — the hub resolves it server-side via `currentPlatform()`
+- `tableIdForDocumentType` defaults to `defaultTableIdForDocumentType` (lib-baked map), so Ask / Display buttons work in embedders without any wiring
+- The SSE decoder/buffer lives inside the per-call closure to prevent cross-stream buffer corruption on rapid send-stop-send sequences
+
+## Source
+
+[`use-sse-chat-adapter.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-sse-chat-adapter.ts)

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

@@ -1,57 +1,67 @@
-<!-- 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.
+<!-- source-hash: bed5f9e4619da46892b2552f6d7eb1d6 -->
+Unified entry point hook that dispatches chat state between two transport adapters — SSE/Guide and NATS/Mingo — based on the `activeMode` flag, while keeping both hooks always mounted to satisfy React's rules of hooks.
 
 ## 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
-```
+### `ChatMode`
+Union type `'guide' | 'mingo'` discriminating the active transport.
+
+### `UseUnifiedChatModes`
+Per-mode configuration object. Each slot is optional — omitting a key leaves that adapter idle with a stable no-op fallback.
+
+| Field | Type | Description |
+|---|---|---|
+| `guide` | `UseSseChatAdapterOptions` | SSE transport config (reads ambient `ChatRuntimeContext`) |
+| `mingo` | `UseNatsChatAdapterConfig` | NATS transport config with explicit dialog ID and publish callback |
+
+### `UseUnifiedChatOptions`
+Hook input shape.
+
+| Field | Description |
+|---|---|
+| `modes` | Per-mode configs |
+| `activeMode` | Which transport is live |
+| `mingoStateOverride` | Host-owned `UnifiedChatState` injected in place of internal NATS state, allowing state to survive panel unmounts |
+
+### `useUnifiedChat(options)`
+Main hook. Returns a stable `UnifiedChatState` composed of:
+- **Active adapter state** — messages, streaming phase, token usage, connection
+- **Stable action callbacks** — `sendMessage`, `stopMessage`, `clearMessages`, `discussRef`, `displayRef`
+- **Dialog management** — `selectDialog`, `startNewDialog`, `deleteDialog`, `renameDialog`, `archiveDialog`, `loadMoreDialogs`, `setDialogScope`, `reloadDialogs`, `loadMoreMessages`
+- **Approvals** — `approveRequest`, `rejectRequest`
+
+Callbacks are bound through `activeStateRef` (a live ref updated every render) so their identities remain referentially stable across streaming chunks, preventing unnecessary downstream re-renders.
 
 ## Usage Example
 
 ```typescript
 // Guide-only consumer
-const chat = useUnifiedChat({
+const chatState = useUnifiedChat({
   activeMode: 'guide',
   modes: {
-    guide: { /* UseSseChatAdapterOptions */ },
+    guide: { systemPrompt: 'You are a helpful guide.' },
   },
 })
 
-// Dual-mode consumer (mode toggle lives in the shell component)
-const chat = useUnifiedChat({
-  activeMode: currentMode, // 'guide' | 'mingo'
+// Dual-mode consumer with host-managed Mingo state
+const chatState = useUnifiedChat({
+  activeMode: currentMode,          // 'guide' | 'mingo'
   modes: {
-    guide: {},
+    guide: { systemPrompt: '...' },
     mingo: {
-      dialogId: 'dialog-abc',
-      getNatsWsUrl: () => 'wss://nats.example.com',
-      publishUserMessage: async (msg) => publishToNats(msg),
+      dialogId: activeDialogId,
+      getNatsWsUrl: () => natsWsUrl,
+      publishUserMessage: (msg) => natsClient.publish(msg),
     },
   },
+  mingoStateOverride: storeBackedMingoState, // survives panel unmounts
 })
 
-chat.sendMessage('How do I reset a password?')
+chatState.sendMessage('Hello!', { attachments: [] })
 ```
 
-## Key Behaviours
+## Notes
 
-- **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.
+- **Both hooks always run** regardless of `activeMode`; the inactive adapter receives a disabled fallback config and an `active: false` flag, keeping it completely idle while preserving its local message buffer for seamless mode-flips.
+- `mingoStateOverride` is the recommended seam for hosts that manage Mingo state externally (e.g., in a Zustand store); pass it without `modes.mingo` to avoid opening a redundant NATS subscription.
+- Mode-toggle UI is not part of this hook — it belongs in the `<MingoChat>` shell component.

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

@@ -1,62 +1,70 @@
-<!-- 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.
+<!-- source-hash: 76966dd4845d1486e56288fc8033df68 -->
+Defines TypeScript interfaces for API interactions and React hook contracts used in the OpenFrame real-time chat and NATS messaging system.
 
 ## Key Components
 
-### 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`
+### Hook Option Interfaces
+- **`UseChunkCatchupOptions`** — Configuration for chunk catch-up logic, including dialog ID, chunk callbacks, chat type filters, and an optional custom fetch function
+- **`UseNatsDialogSubscriptionOptions`** — NATS WebSocket subscription config with reconnection backoff tuning, auth lifecycle hooks, and client credentials
+- **`UseJetStreamDialogSubscriptionOptions`** — JetStream-specific variant adding stream name, sequence-based replay (`optStartSeq`), and consumer inactivity threshold
+- **`UseRealtimeChunkProcessorOptions`** — Controls chunk processing behavior: approval type routing, batch approvals, direct-mode barrier, and initial accumulator state for reconnection
+
+### Hook Return Interfaces
+- **`UseChunkCatchupReturn`** — Exposes `catchUpChunks`, `processChunk`, `resetAndCatchUp`, and buffering state controls
+- **`UseNatsDialogSubscriptionReturn`** / **`UseJetStreamDialogSubscriptionReturn`** — Connection/subscription status and reconnection counters; JetStream variant also tracks `currentStreamSeq`
+- **`UseRealtimeChunkProcessorReturn`** — `processChunk`, `getSegments`, `reset`, and `updateApprovalStatus`
+
+### Callback & Metadata Interfaces
+- **`RealtimeChunkCallbacks`** — Comprehensive event callback surface covering stream lifecycle (`onStreamStart`, `onStreamEnd`), message types (user, direct, system), tool execution (`onToolExecuted`, `onAgentBusy`), approval flows (`onApprove`, `onReject`, `onEscalatedApproval`, `onApprovalResolved`), token usage, and dialog closure
+- **`SegmentsUpdateMetadata`** — Carries append mode, compaction flags, and JetStream `streamSeq` for history deduplication
 
 ## Usage Example
 
 ```typescript
-const options: UseRealtimeChunkProcessorOptions = {
-  callbacks: {
-    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),
+import type {
+  UseNatsDialogSubscriptionOptions,
+  UseRealtimeChunkProcessorOptions,
+  RealtimeChunkCallbacks,
+} from './api.types'
+
+const callbacks: RealtimeChunkCallbacks = {
+  onStreamStart: () => setStreaming(true),
+  onStreamEnd: () => setStreaming(false),
+  onSegmentsUpdate: (segments, meta) => {
+    if (meta?.append) appendSegments(segments)
+    else setSegments(segments)
   },
-  batchApprovalsEnabled: true,
+  onToolExecuted: (segment) => mergeToolResult(segment),
+  onApprovalResolved: (requestId, status, approvalType) => {
+    updateApprovalCard(requestId, status)
+  },
+}
+
+const processorOptions: UseRealtimeChunkProcessorOptions = {
+  callbacks,
   displayApprovalTypes: ['CLIENT'],
-  enableThinking: false,
+  batchApprovalsEnabled: true,
+  initialState: {
+    existingSegments: historicalSegments,
+    executingTools: new Map(),
+  },
 }
 
 const natsOptions: UseNatsDialogSubscriptionOptions = {
   enabled: true,
   dialogId: 'dialog-123',
+  topics: ['message'],
   getNatsWsUrl: () => 'wss://nats.example.com',
+  onBeforeReconnect: async () => refreshAuthToken(),
   reconnectionBackoff: {
     fastRetries: 3,
     fastRetryDelayMs: 500,
-    maxDelayMs: 30000,
+    maxDelayMs: 30_000,
     multiplier: 2,
   },
-  onBeforeReconnect: async () => refreshAuthToken(),
 }
-```
+```
+
+## Source
+
+[`api.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/api.types.ts)

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

@@ -1,23 +1,32 @@
-<!-- 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.
+<!-- source-hash: 6e41e4185d4db0023220e65666ddad33 -->
+Defines core enumerations, constants, interfaces, and utility functions for the OpenFrame chat system, covering chat types, message roles, approval workflows, connection states, and SSE event shapes.
 
 ## Key Components
 
-| 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`) |
+### Constants & Types
+
+| Export | Values | Description |
+|---|---|---|
+| `CHAT_TYPE` | `CLIENT_CHAT`, `ADMIN_AI_CHAT` | Distinguishes client vs. admin chat sessions |
+| `OWNER_TYPE` | `CLIENT`, `ADMIN`, `ASSISTANT` | Identifies who owns a message |
+| `MESSAGE_ROLE` | `user`, `assistant`, `error`, `system` | Standard LLM-style message roles |
+| `ASSISTANT_TYPE` | `fae`, `mingo` | Flamingo AI assistants (Fae = client, Mingo = technician) |
+| `AUTHOR_TYPE` | `user`, `admin`, `fae`, `mingo`, `system` | Granular message authorship |
+| `APPROVAL_STATUS` | `pending`, `approved`, `rejected`, `cancelled` | Lifecycle states for approval workflows |
+| `APPROVAL_BLOCK_VARIANT` | `admin`, `client` | Controls approval block rendering — `admin` shows full command/script preview; `client` shows only title and status pill |
+| `CONNECTION_STATUS` | `connecting`, `connected`, `disconnected`, `reconnecting`, `closed`, `error` | Real-time connection lifecycle states |
+
+### Interfaces
+
+- **`MessageOwner`** — Typed owner identity including `OwnerType`, optional `machineId`, `userId`, AI model, and user profile (with avatar resolution delegated to the host)
+- **`TextEventData`** / **`ToolExecutionEventData`** / **`SSEEventData`** — Wire-shape types for server-sent events carrying streamed text or tool execution state
+- **`QuickAction`** — Shape for quick-action chips (`id` + `text`)
+
+### Utility Functions
+
+- **`buildChatRefKey(docType, externalId)`** — Constructs canonical `${docType}:${externalId}` keys for the `chatRefs` map, keeping writer and reader logic consistent
+- **`isStructuredContent(content)`** — Type guard distinguishing segment arrays from plain strings
+- **`normalizeContent(content)`** — Coerces `string | MessageSegment[]` into a uniform `MessageSegment[]`
 
 ## Usage Example
 
@@ -25,32 +34,45 @@ Defines core constants, enums, types, and utility functions for the Flamingo cha
 import {
   CHAT_TYPE,
   MESSAGE_ROLE,
-  ASSISTANT_TYPE,
   APPROVAL_STATUS,
-  CONNECTION_STATUS,
+  APPROVAL_BLOCK_VARIANT,
   buildChatRefKey,
   isStructuredContent,
   normalizeContent,
+  type MessageOwner,
+  type SSEEventData,
 } from './chat.types'
 
-// Route to the correct AI assistant based on chat context
-const assistant =
-  chatType === CHAT_TYPE.CLIENT ? ASSISTANT_TYPE.FAE : ASSISTANT_TYPE.MINGO
+// Route a message to the correct chat surface
+const chatType = CHAT_TYPE.ADMIN // 'ADMIN_AI_CHAT'
+
+// Build a chatRef lookup key for an inline card marker
+const refKey = buildChatRefKey('ticket', 'TKT-1042') // 'ticket:TKT-1042'
 
-// Build a chatRefs lookup key matching inline [card://ticket:42] markers
-const refKey = buildChatRefKey('ticket', '42') // → "ticket:42"
+// Normalize mixed content for rendering
+const segments = normalizeContent('Hello, how can I help?')
+// [{ type: 'text', text: 'Hello, how can I help?' }]
 
-// Normalize incoming content before rendering
-const segments = normalizeContent(message.content)
-// → always MessageSegment[], safe to iterate
+// Type-safe approval state check
+const status = APPROVAL_STATUS.PENDING // 'pending'
 
-// Check approval before displaying an action
-if (approval === APPROVAL_STATUS.PENDING) {
-  showApprovalBanner()
+// Render the correct approval block for the viewer
+const variant = APPROVAL_BLOCK_VARIANT.CLIENT // hides raw commands from end user
+
+// Typed SSE handler
+function handleSSEEvent(event: SSEEventData) {
+  if (event.type === 'TEXT') {
+    console.log(event.text)
+  } else if (event.type === 'EXECUTED_TOOL') {
+    console.log(event.toolFunction, event.success)
+  }
 }
 
-// Handle SSE connection lifecycle
-if (status === CONNECTION_STATUS.RECONNECTING) {
-  showReconnectingSpinner()
+// Typed message owner
+const owner: MessageOwner = {
+  type: 'ASSISTANT',
+  model: 'gpt-4o',
 }
-```
+```
+
+**Source:** [`chat.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat.types.ts)

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

@@ -1,36 +1,28 @@
-<!-- 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.
+<!-- source-hash: 52722b23adea0f711cad3e8a0dc8725a -->
+Defines all TypeScript prop interfaces and component types used across the chat UI library, covering containers, headers, messages, and inline rendering extension points.
 
 ## Key Components
 
-### 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)
+| Export | Kind | Description |
+|---|---|---|
+| `NavLinkAnchorComponent` | Type | Host-supplied anchor component for markdown link routing inside messages |
+| `ChatContainerProps` | Interface | Props for the root chat wrapper `<div>` |
+| `ChatHeaderProps` | Interface | Full header configuration: identity, connection status, ticket info, MSP branding, skeleton states |
+| `ChatHeaderTicketInfo` | Interface | Ticket title, meta, status, lifecycle color/kind displayed in the header |
+| `ConnectionIndicatorProps` | Interface | Single `status` prop for the connection badge |
+| `ChatMessageEnhancedProps` | Interface | Rich message bubble: role, content segments, approval handling, entity cards, mentions, context chips, anchor override |
+| `ChatMessageListProps` | Interface | Scrollable thread list: messages, auto/pin scroll, pagination, approval footer, avatar display |
 
 ## Usage Example
 
 ```typescript
 import type {
-  ChatMessageListProps,
   ChatHeaderProps,
+  ChatMessageEnhancedProps,
   NavLinkAnchorComponent,
-  SlashCommandsProp,
 } from './component.types'
 
-// Host-supplied anchor delegates routing to app router
+// Host-supplied router-aware anchor
 const NavLinkAnchor: NavLinkAnchorComponent = ({ href, className, children }) => (
   <a href={href} className={className}>{children}</a>
 )
@@ -38,23 +30,31 @@ const NavLinkAnchor: NavLinkAnchorComponent = ({ href, className, children }) =>
 const headerProps: ChatHeaderProps = {
   userName: 'Mingo AI',
   connectionStatus: 'connected',
-  fullWidth: true,   // fills narrow side panel
-  bare: true,        // no card chrome inside Drawer
+  fullWidth: true,
+  bare: false,
+  isLoading: false,
+  ticketInfo: {
+    title: 'Laptop won't boot',
+    statusName: 'In Progress',
+    statusKind: 'in_progress',
+  },
 }
 
-const listProps: ChatMessageListProps = {
-  messages,
-  fullWidth: true,
-  hasNextPage: true,
-  isFetchingNextPage: false,
-  onLoadMore: fetchOlderMessages,
-  renderEntityCard: (ref) => <EntityCard reference={ref} />,
+const messageProps: ChatMessageEnhancedProps = {
+  role: 'assistant',
+  content: 'Checking diagnostics…',
+  assistantType: 'mingo',
+  approvalVariant: 'admin',
   NavLinkAnchor,
+  renderMention: ({ marker, id }) => <EntityChip marker={marker} id={id} />,
+  onApprove: async (requestId) => { await approveRequest(requestId) },
 }
+```
 
-const slashCommands: SlashCommandsProp = {
-  fetchCommands: async (prefix, signal) =>
-    fetch(`/api/docs/commands?q=${prefix}`, { signal }).then(r => r.json()),
-  resolveSourceIcon: (sourceId) => iconRegistry[sourceId],
-}
-```
+## Notes
+
+- `ChatMessageEnhancedProps.chatRefs` + `renderEntityCard` enable inline `[card://<type>:<id>]` expansion without the library holding any entity-specific knowledge.
+- `ChatHeaderProps.fullWidth` / `bare` decouple layout from legacy centered-narrow defaults — set both when embedding in a narrow side panel.
+- `NavLinkAnchorComponent` is intentionally loose (`any` spread at the call site) so host implementations can declare extra routing props (`path`, `targetPlatform`) without TypeScript friction.
+
+**Source:** [`component.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/component.types.ts)

package/src/components/chat/types/.context-item.types.md

@@ -0,0 +1,61 @@
+<!-- source-hash: 2c3df3f602c538f0cb46b662593cc722 -->
+Defines TypeScript interfaces for the chat composer's entity-context picker system, establishing the contract between the library's picker UI and the host application's data layer.
+
+## Key Components
+
+| Export | Kind | Purpose |
+|---|---|---|
+| `ChatContextEntityType` | Interface | Represents a selectable entity type (Device, Script, Ticket) shown in the picker's first-level list |
+| `ChatContextItem` | Interface | A concrete selected context item (one device, one script) with stable backend ID and display metadata |
+| `ContextItemsRenderArgs` | Interface | Arguments passed to `renderItems` for the active entity type, including query state and selection callbacks |
+| `ChatContextPickerConfig` | Interface | Host-provided configuration that activates the full picker UI — entity types, render delegate, selection cap, and optional file upload |
+
+## Architecture
+
+The library owns the **picker shell** (dropdown chrome, entity-type list, search field, Suspense/skeleton/error boundary); the host owns **data** via `renderItems`. The host wires config into `<EmbeddableChat contextPicker={…}>` and receives selections back through `sendMessage(text, { contextItems })`.
+
+```mermaid
+graph LR
+    Host["Host App"] -->|"ChatContextPickerConfig"| Composer["EmbeddableChat"]
+    Composer -->|"ContextItemsRenderArgs"| renderItems["renderItems(args)"]
+    renderItems -->|"ContextItemsList"| Composer
+    Composer -->|"contextItems: ChatContextItem[]"| Send["sendMessage()"]
+```
+
+## Usage Example
+
+```typescript
+const contextPicker: ChatContextPickerConfig = {
+  entityTypes: [
+    { type: 'DEVICE', label: 'Device', marker: 'device', icon: <DeviceIcon /> },
+    { type: 'SCRIPT', label: 'Script', marker: 'kb', icon: <ScriptIcon /> },
+  ],
+  maxItems: 5,
+  renderItems: ({ type, query, selectedKeys, onToggle, atLimit }) => (
+    <DeviceItemsList
+      query={query}
+      selectedKeys={selectedKeys}
+      onToggle={onToggle}
+      atLimit={atLimit}
+    />
+  ),
+  onUploadFile: () => openFilePicker(),
+}
+
+// Wire into the composer
+<EmbeddableChat contextPicker={contextPicker} />
+
+// Received on send
+sendMessage(text, {
+  contextItems: [{ type: 'DEVICE', id: 'elk-prod-07', label: 'ELK-PROD-07' }]
+})
+```
+
+## Notes
+
+- `ChatContextEntityType.marker` maps to the backend's `@marker:id` mention vocabulary; falls back to lowercased `type` when omitted
+- `ContextItemsRenderArgs.selectedKeys` uses a composite `"${type}:${id}"` key format
+- Host render components may **suspend** — the picker wraps `renderItems` in `<Suspense>` with a skeleton fallback plus an error boundary
+- The picker is **inert** unless `contextPicker` is supplied to `<EmbeddableChat>`
+
+**Source:** [`context-item.types.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/context-item.types.ts)