@flamingo-stack/openframe-frontend-core 0.0.213 → 0.0.214

package/src/components/chat/hooks/.use-chunk-catchup.md

@@ -1,55 +1,53 @@
-<!-- source-hash: 9776b4038d8695da9d5a33a4dc05d48b -->
-A React hook for managing chunk synchronization during real-time chat dialog loading, handling buffering, deduplication, and proper ordering of message chunks from both NATS streams and API catchup.
+<!-- source-hash: a64b1bda14e5000a8167e43f4d2c233d -->
+Manages NATS message chunk buffering and catchup for dialog loading, ensuring chunks arriving during initial fetch are buffered, deduplicated, ordered by sequence ID, and processed without gaps or duplicates.
 
 ## Key Components
 
-- **useChunkCatchup**: Main hook that orchestrates chunk catchup during dialog loading
-- **processChunk**: Processes individual chunks with optional buffering during catchup
-- **catchUpChunks**: Fetches historical chunks from API and merges with buffered realtime chunks
-- **flushBufferedRealtimeChunks**: Processes buffered chunks after catchup completion
-- **resetChunkTracking**: Resets all internal state for new dialog sessions
-- **startInitialBuffering**: Enables buffering mode for initial catchup phase
+| Export | Type | Description |
+|--------|------|-------------|
+| `useChunkCatchup` | Hook | Main hook orchestrating chunk buffering, catchup fetching, deduplication, and ordered processing |
+| `makeSeqKey` | Helper | Generates a unique tracking key from `messageType`, `chunkType`, and `sequenceId` |
+| `makeBatchDedupKey` | Helper | Generates a composite deduplication key covering all relevant chunk fields |
+| `getChatTypeMessageType` | Helper | Maps a `ChatType` to its corresponding `NatsMessageType` |
+
+### Hook Return API (`UseChunkCatchupReturn`)
+
+| Method | Description |
+|--------|-------------|
+| `catchUpChunks(fromSequenceId?)` | Fetches historical chunks from the API and merges with buffered NATS chunks |
+| `processChunk(chunk, messageType, forceProcess?)` | Processes a single chunk, buffering it if catchup is still in progress |
+| `startInitialBuffering()` | Activates the buffer so live NATS chunks are held during initial fetch |
+| `isBufferingActive()` | Returns `true` if buffering is currently active |
+| `resetChunkTracking()` | Clears all sequence tracking and buffer state |
+| `resetAndCatchUp()` | Resets guards and re-fetches from the last known sequence — use after reconnection |
+| `processedCount` | Number of successfully processed sequence keys |
 
 ## Usage Example
 
 ```typescript
-import { useChunkCatchup } from './use-chunk-catchup'
-import { CHAT_TYPE } from '../types'
-
-function ChatDialog({ dialogId, fetchChunks }) {
-  const {
-    catchUpChunks,
-    processChunk,
-    resetChunkTracking,
-    startInitialBuffering,
-    isBufferingActive
-  } = useChunkCatchup({
-    dialogId,
-    onChunkReceived: (chunk, messageType) => {
-      console.log('Processing chunk:', chunk)
-      // Handle the chunk in your UI
-    },
-    chatTypes: [CHAT_TYPE.CLIENT, CHAT_TYPE.ADMIN],
-    fetchChunks: async (dialogId, chatType, fromSeqId) => {
-      return await api.fetchDialogChunks(dialogId, chatType, fromSeqId)
-    }
-  })
-
-  // Start catchup when dialog loads
-  useEffect(() => {
-    if (dialogId) {
-      startInitialBuffering()
-      catchUpChunks()
-    }
-  }, [dialogId])
-
-  // Process realtime chunks from NATS
-  const handleNatsChunk = useCallback((chunk, messageType) => {
-    processChunk(chunk, messageType)
-  }, [processChunk])
-
-  return <div>Chat content...</div>
-}
-```
-
-The hook handles complex scenarios like preventing duplicate chunks, maintaining sequence order, buffering realtime chunks during catchup, and finding complete message boundaries to ensure proper synchronization.
+const {
+  catchUpChunks,
+  processChunk,
+  startInitialBuffering,
+  resetAndCatchUp,
+} = useChunkCatchup({
+  dialogId: 'dialog-123',
+  chatTypes: [CHAT_TYPE.CLIENT, CHAT_TYPE.ADMIN],
+  fetchChunks: async (dialogId, chatType, fromSequenceId) => {
+    return await api.getChunks(dialogId, chatType, fromSequenceId)
+  },
+  onChunkReceived: (chunk, messageType) => {
+    dispatch(appendChunk({ chunk, messageType }))
+  },
+})
+
+// On dialog open: buffer live chunks while fetching history
+startInitialBuffering()
+await catchUpChunks()
+
+// On NATS message received:
+processChunk(incomingChunk, 'message')
+
+// On reconnect: re-fetch missed chunks from last known position
+await resetAndCatchUp()
+```

package/src/components/chat/hooks/.use-close-on-navigation.md

@@ -0,0 +1,44 @@
+<!-- source-hash: a2a5f2990aca87eef1bd65cbfd43d85e -->
+Closes a layout-mounted overlay (modal, drawer, dropdown, side panel) automatically when the URL pathname changes, preventing stale body-level scroll/pointer-event locks on the new page.
+
+## Key Components
+
+### `useCloseOnNavigation(close, pathname)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `close` | `() => void` | Stable callback that triggers the overlay's close flow |
+| `pathname` | `string \| null` | Current route pathname; threading this makes the hook router-agnostic |
+
+**Behaviour:**
+- **Skip-first-render** — uses `initializedRef` to record the initial pathname without firing `close()`, preventing a spurious close on mount
+- **Real change only** — compares against `prevPathnameRef` and calls `close()` only when the pathname actually changes
+- `close` is intentionally excluded from the `useEffect` dependency array; callers must pass a stable (memoized or ref-stable) callback
+
+## Usage Example
+
+```typescript
+// Lib (router-agnostic, direct usage):
+import { useCloseOnNavigation } from '@/lib/hooks/use-close-on-navigation'
+
+function MyDrawer() {
+  const [isOpen, setIsOpen] = useState(false)
+  const pathname = usePathname() // or useLocation(), window.location.pathname, etc.
+
+  useCloseOnNavigation(() => setIsOpen(false), pathname)
+
+  return <Drawer open={isOpen} onClose={() => setIsOpen(false)} />
+}
+```
+
+```typescript
+// Hub wrapper (binds Next.js router once, re-exports a cleaner API):
+import { usePathname } from 'next/navigation'
+import { useCloseOnNavigation as libUseCloseOnNavigation } from '@lib/hooks/use-close-on-navigation'
+
+export function useCloseOnNavigation(close: () => void) {
+  return libUseCloseOnNavigation(close, usePathname())
+}
+```
+
+> **Layout-shell only** — do not call this from page-level components. Pages unmount on navigation naturally; this hook exists solely for overlays that persist in the root layout across route changes.

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

@@ -0,0 +1,48 @@
+<!-- source-hash: 24f090768a3d572fe819879e60f540e1 -->
+Provides animated expand/collapse behavior for a container element by measuring content height and toggling `max-height` with a CSS transition.
+
+## Key Components
+
+### `UseCollapsibleOptions`
+Configuration interface for the hook:
+- `expanded` — controls whether the content is expanded or collapsed
+- `collapsedHeight` — collapsed height in pixels or `"1lh"` (one line-height); defaults to `0`
+- `disableTransition` — skips the CSS transition when `true`; defaults to `false`
+- `durationMs` — transition duration in milliseconds; defaults to `200`
+
+### `useCollapsible(options)`
+Main hook that returns:
+- `innerRef` — ref callback to attach to the collapsible content `div`
+- `isOverflowing` — `true` when content height exceeds the collapsed height (useful for showing "show more" triggers)
+- `containerStyle` — computed `CSSProperties` object with `overflow`, `max-height`, and `transition` to spread onto the wrapper element
+
+**`"1lh"` handling:** When `collapsedHeight` is `"1lh"`, the hook measures the inner element's `lineHeight` via `getComputedStyle` and uses the resolved pixel value instead of the raw CSS unit. This prevents the outer element's line-height from leaking adjacent content past the clip boundary.
+
+A `ResizeObserver` watches the inner element and re-measures on size changes, keeping `contentHeight` accurate.
+
+## Usage Example
+
+```typescript
+function CollapsibleText({ text }: { text: string }) {
+  const [expanded, setExpanded] = useState(false)
+
+  const { innerRef, containerStyle, isOverflowing } = useCollapsible({
+    expanded,
+    collapsedHeight: "1lh",
+    durationMs: 300,
+  })
+
+  return (
+    <div>
+      <div style={containerStyle}>
+        <div ref={innerRef}>{text}</div>
+      </div>
+      {isOverflowing && (
+        <button onClick={() => setExpanded(!expanded)}>
+          {expanded ? "Show less" : "Show more"}
+        </button>
+      )}
+    </div>
+  )
+}
+```

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

@@ -0,0 +1,32 @@
+<!-- source-hash: 01d63c5d1bf9f446d2f4c5d33842b562 -->
+Backward-compatibility shim that re-exports `useSseChatAdapter` under the legacy `useEmbeddedChat` name, preserving external consumer compatibility during the migration to the unified `useChat` API.
+
+## Key Components
+
+| Export | Alias / Origin | Description |
+|--------|---------------|-------------|
+| `useEmbeddedChat` | `useSseChatAdapter` | Legacy hook name for the SSE/Guide-mode chat adapter |
+| `UseEmbeddedChatOptions` | `UseSseChatAdapterOptions` | Legacy options type alias |
+| `ChatSource` | `./use-sse-chat-adapter` | Chat source type |
+| `DocChatMessage` | `./use-sse-chat-adapter` | Document chat message type |
+| `DocSource` | `./use-sse-chat-adapter` | Document source type |
+| `ChatTurnMeta` | `./use-sse-chat-adapter` | Chat turn metadata type |
+| `StreamingPhase` | `./use-sse-chat-adapter` | Streaming phase enum/type |
+
+## Usage Example
+
+```typescript
+// ⚠️ Legacy import — works but will be removed after migration
+import { useEmbeddedChat, UseEmbeddedChatOptions } from './use-embedded-chat'
+
+// ✅ Preferred — import directly from the canonical module
+import { useSseChatAdapter } from './use-sse-chat-adapter'
+
+// ✅ Future — use the unified entry point
+import { useChat } from './use-chat'
+const chat = useChat({ mode: 'sse' })
+```
+
+## Migration Notes
+
+> **Deprecation notice:** Internal library code should import directly from `./use-sse-chat-adapter`. This shim will be removed once all consumers migrate to the unified `useChat({ mode })` entry point.

package/src/components/chat/hooks/.use-jetstream-dialog-subscription.md

@@ -0,0 +1,40 @@
+<!-- source-hash: dcf2e60dac262a108cfeb8aa720addd1 -->
+Subscribes a React component to a NATS JetStream ephemeral ordered consumer for a specific chat dialog, managing connection lifecycle, reconnection backoff, and sequence-aware resumption.
+
+## Key Components
+
+- **`useJetStreamDialogSubscription`** — Primary hook export. Manages a shared NATS WebSocket connection (ref-counted singleton) and an ephemeral JetStream `OrderedConsumer` scoped to `chat.{dialogId}.{topic}`.
+- **`SharedConnection`** — Module-level singleton tracking the active NATS client, ref count, and deferred close/retry timers to avoid redundant reconnects across component instances.
+- **`acquireClient`** — Increments the shared connection ref count (or creates a new client if the URL changed), cancelling any pending close timer.
+- **`releaseClient`** — Decrements the ref count and schedules a deferred close (`SHARED_CLOSE_DELAY_MS`) when the last consumer releases the connection.
+- **Connection effect** — Drives `connect()` / status-listener lifecycle; implements jittered exponential backoff with optional fast-retry leading attempts via `reconnectionBackoff`.
+- **Subscription effect** — Recreates the ephemeral consumer on each `isConnected` transition, resuming from `highestStreamSeq + 1` to avoid replaying or skipping chunks.
+
+## Usage Example
+
+```typescript
+const { isConnected, isSubscribed, reconnectionCount, currentStreamSeq } =
+  useJetStreamDialogSubscription({
+    enabled: true,
+    dialogId: 'dialog-abc123',
+    topic: 'events',
+    optStartSeq: lastKnownSeq,         // null → live-tail (DeliverPolicy.New)
+    getNatsWsUrl: () => 'wss://nats.example.com',
+    onEvent: (data) => console.log('chunk received', data),
+    onConnect: () => console.log('connected'),
+    onDisconnect: () => console.log('disconnected'),
+    reconnectionBackoff: {
+      fastRetries: 3,
+      fastRetryDelayMs: 200,
+      initialDelayMs: 500,
+      maxDelayMs: 30_000,
+      multiplier: 2,
+    },
+    inactiveThresholdMs: 5 * 60_000,
+  })
+```
+
+## Notes
+
+- Protocol-level `-ERR` events (e.g. ACL violations) are logged as warnings but do **not** trigger reconnect, preventing auth-refresh loops.
+- The shared connection singleton is module-scoped, so multiple hook instances sharing the same WebSocket URL reuse one NATS client.

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

@@ -0,0 +1,52 @@
+<!-- source-hash: 6c5780e92306ea381bac35aaf97c435f -->
+Provides the NATS/Mingo-mode transport adapter for the unified chat surface, implementing the `UnifiedChatState` contract so the `useChat({ mode })` dispatcher can switch between NATS and SSE adapters without shell-side branching.
+
+## Key Components
+
+### `UseNatsChatAdapterConfig`
+Consumer-supplied configuration interface covering:
+- `dialogId` — active conversation identifier
+- `getNatsWsUrl` — factory returning the NATS WebSocket URL
+- `publishUserMessage` — consumer-owned send callback (HTTP POST or NATS publish)
+- `fetchChunks` — optional historical chunk fetcher for catchup
+- `clientConfig` — optional NATS auth credentials
+- `enableThinking` / `batchApprovalsEnabled` — processor feature flags
+
+### `UseNatsChatAdapterOptions`
+- `active` — gates the live subscription; keeps message state alive while the mode is hidden
+
+### `useNatsChatAdapter(config, options)`
+Main hook. Composes three internal hooks:
+
+```text
+useNatsDialogSubscription  →  live NATS event tail
+         ↓
+useRealtimeChunkProcessor  →  chunk → MessageSegment[]
+         ↓
+useChunkCatchup            →  back-fills missed chunks on reconnect/activation
+```
+
+Returns a full `UnifiedChatState` object including `messages`, `isLoading`, `streamingPhase`, `sendMessage`, `stopMessage`, and `clearMessages`.
+
+## Usage Example
+
+```typescript
+const chatState = useNatsChatAdapter(
+  {
+    dialogId: 'dialog-abc123',
+    getNatsWsUrl: () => `wss://nats.example.com`,
+    publishUserMessage: async (text, { dialogId }) => {
+      await fetch('/api/chat', {
+        method: 'POST',
+        body: JSON.stringify({ text, dialogId }),
+      })
+    },
+    fetchChunks: ({ dialogId, after }) =>
+      fetch(`/api/chunks?dialogId=${dialogId}&after=${after}`).then(r => r.json()),
+    batchApprovalsEnabled: true,
+  },
+  { active: isNatsModeVisible },
+)
+```
+
+> **Note:** `publishUserMessage` is intentionally consumer-owned — the adapter only handles optimistic UI updates and phase transitions; the actual transport is wired externally.

package/src/components/chat/hooks/.use-nats-dialog-subscription.md

@@ -1,46 +1,65 @@
-<!-- source-hash: d26d0ac33fd6e63fb5ae010dfb6982cf -->
-A React hook for managing NATS WebSocket connections and subscriptions to real-time dialog events. Provides shared connection pooling, automatic reconnection, and subscription lifecycle management.
+<!-- source-hash: 9e073aef3e517df1b4ab46b93212f4cb -->
+Provides a React hook for managing NATS WebSocket dialog subscriptions with shared connection pooling, automatic reconnection with exponential backoff, and multi-topic support.
 
 ## Key Components
 
-- **`useNatsDialogSubscription`** - Main hook for subscribing to NATS dialog topics
-- **`buildNatsWsUrl`** - Utility function for constructing NATS WebSocket URLs
-- **Shared Connection Management** - Automatic connection pooling with reference counting
-- **Subscription Handlers** - Message processing for dialog events and admin messages
+### `useNatsDialogSubscription(options)`
+The primary exported hook that manages the full lifecycle of a NATS dialog subscription.
+
+**Parameters (`UseNatsDialogSubscriptionOptions`):**
+
+| Option | Description |
+|--------|-------------|
+| `enabled` | Toggles the connection/subscription on or off |
+| `dialogId` | The dialog ID to subscribe to (e.g., `chat.<dialogId>.<topic>`) |
+| `topics` | Array of `NatsMessageType` values to subscribe to (default: `['message']`) |
+| `onEvent` | Callback fired when a NATS message is received |
+| `onConnect` / `onDisconnect` | Lifecycle callbacks for connection state changes |
+| `onSubscribed` | Fired when subscriptions are successfully established |
+| `onBeforeReconnect` | Async hook called before each reconnection attempt (e.g., token refresh) |
+| `getNatsWsUrl` | Factory function returning the WebSocket URL |
+| `clientConfig` | Optional NATS client config overrides (`name`, `user`, `pass`) |
+| `reconnectionBackoff` | Configures retry delays: `fastRetries`, `initialDelayMs`, `maxDelayMs`, `multiplier` |
+
+**Returns (`UseNatsDialogSubscriptionReturn`):** `{ isConnected, isSubscribed, reconnectionCount }`
+
+### `SharedConnection` (module-level singleton)
+A module-scoped singleton that reference-counts active consumers sharing the same WebSocket URL, with a deferred close delay (`SHARED_CLOSE_DELAY_MS`) to avoid reconnect churn during component remounts.
 
 ## Usage Example
 
 ```typescript
-import { useNatsDialogSubscription, buildNatsWsUrl } from './use-nats-dialog-subscription'
+import { useNatsDialogSubscription } from './use-nats-dialog-subscription'
 
-function DialogComponent({ dialogId, authToken }) {
-  const { isConnected, isSubscribed } = useNatsDialogSubscription({
-    enabled: Boolean(dialogId),
+function DialogListener({ dialogId }: { dialogId: string }) {
+  const { isConnected, isSubscribed, reconnectionCount } = useNatsDialogSubscription({
+    enabled: true,
     dialogId,
     topics: ['message', 'admin-message'],
-    getNatsWsUrl: () => buildNatsWsUrl(
-      'https://api.example.com',
-      { token: authToken, includeAuthParam: true }
-    ),
-    onEvent: (data, messageType) => {
-      console.log(`Received ${messageType}:`, data)
+    getNatsWsUrl: () => 'ws://nats.example.com:4223',
+    onEvent: (event, messageType) => {
+      console.log(`[${messageType}]`, event)
+    },
+    onConnect: () => console.log('NATS connected'),
+    onDisconnect: () => console.log('NATS disconnected'),
+    onBeforeReconnect: async () => {
+      await refreshAuthToken() // e.g., refresh JWT before retry
+    },
+    reconnectionBackoff: {
+      fastRetries: 3,
+      fastRetryDelayMs: 500,
+      initialDelayMs: 1000,
+      maxDelayMs: 30000,
+      multiplier: 2,
     },
-    onConnect: () => console.log('Connected to NATS'),
-    onDisconnect: () => console.log('Disconnected from NATS'),
-    clientConfig: {
-      name: 'my-app',
-      user: 'client',
-      pass: 'secret'
-    }
   })
 
-  return (
-    <div>
-      Status: {isConnected ? 'Connected' : 'Disconnected'}
-      Subscribed: {isSubscribed ? 'Yes' : 'No'}
-    </div>
-  )
+  return <div>Connected: {isConnected ? 'Yes' : 'No'} | Reconnects: {reconnectionCount}</div>
 }
 ```
 
-The hook automatically handles connection sharing across multiple instances, reconnection on failures, and cleanup when components unmount or dialog IDs change.
+## Notes
+
+- Reconnection uses **jittered exponential backoff** (`delay * (0.5 + random * 0.5)`) to avoid thundering herd scenarios.
+- Callbacks (`onEvent`, `onConnect`, etc.) are stored in stable refs, so they never trigger reconnection when their identity changes.
+- The shared connection is scoped per WebSocket URL — switching URLs tears down the old connection before establishing a new one.

package/src/components/chat/hooks/.use-proxied-image-url.md

@@ -0,0 +1,40 @@
+<!-- source-hash: cc0502db44c43b65b6de8507cd22cc50 -->
+A React hook that wraps `getProxiedImageUrl` by reading proxy configuration (`proxyPrefix` and `skipDomains`) from the ambient `ChatRuntimeContext`, eliminating the need to manually pass proxy config at each call site.
+
+## Key Components
+
+### `useProxiedImageUrl(url)`
+- **Input:** `string | null | undefined` — the image URL to potentially proxy
+- **Output:** `string` — the proxied URL, or `''` for null/undefined input
+- **Behavior:** Always passes `directHttps: true`, meaning HTTPS URLs are returned as-is. For cases requiring proxied HTTPS URLs, use `getProxiedImageUrl` from `@flamingo-stack/openframe-frontend-core/utils` directly with hardcoded config.
+
+## Usage Example
+
+```typescript
+// ✅ Standard usage — inside a component rendered within ChatRuntimeContext.Provider
+function AvatarImage({ imageUrl }: { imageUrl: string }) {
+  const proxiedUrl = useProxiedImageUrl(imageUrl)
+  return <img src={proxiedUrl} alt="avatar" />
+}
+
+// ✅ Handles null/undefined gracefully
+function OptionalImage({ imageUrl }: { imageUrl?: string | null }) {
+  const proxiedUrl = useProxiedImageUrl(imageUrl) // returns '' if nullish
+  return proxiedUrl ? <img src={proxiedUrl} alt="preview" /> : null
+}
+
+// ❌ Never call inside a loop — violates Rules of Hooks
+items.map(item => useProxiedImageUrl(item.url)) // WRONG
+
+// ✅ For map/loop patterns, use the pure utility instead
+import { getProxiedImageUrl } from '@flamingo-stack/openframe-frontend-core/utils'
+items.map(item => getProxiedImageUrl(item.url, { proxyPrefix, skipDomains }))
+```
+
+## Constraints
+
+| Constraint | Detail |
+|---|---|
+| Must be inside `ChatRuntimeContext.Provider` | Uses `useRequiredChatRuntime()` — throws if context is missing |
+| `directHttps: true` always set | HTTPS URLs bypass the proxy; use pure util to override |
+| Top-level call only | Standard Rules of Hooks apply — no loops or conditionals |

package/src/components/chat/hooks/.use-realtime-chunk-processor.md

@@ -1,47 +1,50 @@
-<!-- source-hash: 2cb4b6bbac4078d643ed0550733c9b7d -->
-A React hook for processing real-time NATS message chunks into structured message segments, handling approvals, tool executions, and error states with accumulator-based state management.
+<!-- source-hash: e37a3772ece6c09122bfe5d89ce800e0 -->
+Real-time NATS streaming chunk processor hook that converts raw streaming messages into typed message segments, managing stream state, tool execution, and approval workflows.
 
 ## Key Components
 
-- **`useRealtimeChunkProcessor`** - Main hook that processes streaming chunks and manages message state
-- **`processChunk`** - Core function that parses incoming chunks and updates message segments
-- **`MessageSegmentAccumulator`** - State manager for building up message segments from streaming data
-- **Action handlers** - Support for text, tool execution, approval requests, metadata, and error chunks
-- **Approval management** - Tracks pending and escalated approvals with status updates
+| Export | Type | Description |
+|--------|------|-------------|
+| `useRealtimeChunkProcessor` | Hook | Primary hook for processing NATS stream chunks into UI-ready message segments |
+| `accumulatorRef` | Internal Ref | Holds a `MessageSegmentAccumulator` instance that tracks and builds segments across chunk events |
+| `isInStreamRef` | Internal Ref | Tracks whether a `MESSAGE_START`/`MESSAGE_END` boundary is active |
+| `hasEverStreamedRef` | Internal Ref | Distinguishes cold-start vs. resumed-dialog continuation mode |
+| `pendingEscalatedRef` | Internal Ref | Tracks escalated (non-display) approval requests awaiting results |
+
+### Handled Chunk Actions
+
+| Action | Behavior |
+|--------|----------|
+| `message_start` / `message_end` | Opens/closes stream window, resets segment accumulator |
+| `text` / `thinking` | Appends to accumulator; uses append mode post-stream |
+| `tool_execution` | Routes to accumulator in-stream, or `onToolExecuted` post-stream |
+| `approval_request` | Renders inline or escalates based on `displayApprovalTypes` |
+| `approval_batch` | Renders batch card or unfolds into legacy cards if `batchApprovalsEnabled = false` |
+| `approval_result` | Resolves escalated or inline approvals, updates accumulator status |
+| `error` | Parses error detail and emits error segment |
 
 ## Usage Example
 
 ```typescript
-import { useRealtimeChunkProcessor } from './use-realtime-chunk-processor'
-
-function ChatComponent() {
-  const processor = useRealtimeChunkProcessor({
-    callbacks: {
-      onSegmentsUpdate: (segments) => setMessageSegments(segments),
-      onStreamStart: () => setIsStreaming(true),
-      onStreamEnd: () => setIsStreaming(false),
-      onApprove: (requestId) => handleApproval(requestId, true),
-      onReject: (requestId) => handleApproval(requestId, false),
-      onError: (error, message) => console.error('Stream error:', error)
-    },
-    displayApprovalTypes: ['CLIENT'],
-    approvalStatuses: { 'req-123': 'approved' },
-    initialState: previousChatState
-  })
-
-  // Process incoming NATS chunks
-  useEffect(() => {
-    natsConnection.subscribe((chunk) => {
-      processor.processChunk(chunk)
-    })
-  }, [processor])
-
-  return (
-    <div>
-      {processor.getSegments().map(segment => 
-        <MessageSegment key={segment.id} segment={segment} />
-      )}
-    </div>
-  )
-}
-```
+const { processChunk } = useRealtimeChunkProcessor({
+  callbacks: {
+    onSegmentsUpdate: (segments, opts) => updateMessage(segments, opts),
+    onStreamStart: () => setStreaming(true),
+    onStreamEnd: () => setStreaming(false),
+    onApprove: (requestId) => approveToolCall(requestId),
+    onReject: (requestId) => rejectToolCall(requestId),
+    onEscalatedApproval: (requestId, data) => notifyTechnician(requestId, data),
+    onApprovalResolved: (requestId, status) => syncStatus(requestId, status),
+    onError: (error) => console.error(error),
+  },
+  displayApprovalTypes: ['CLIENT'],
+  approvalStatuses: { 'req-123': 'pending' },
+  enableThinking: false,
+  batchApprovalsEnabled: true,
+})
+
+// Feed raw NATS chunks directly
+natsSubscription.on('message', (msg) => processChunk(msg.data))
+```
+
+> **Note:** `batchApprovalsEnabled` defaults to `true`. Pass `false` to fall back to legacy per-call approval cards. Consumers using `onApprovalResolved` should omit `onSegmentsUpdate` handling for approval results to avoid bubble overwrites during status flips.

package/src/components/chat/hooks/.use-slash-commands.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 433665c60d11f92235ffb1f5227d3b44 -->
+Debounced React hook and stateless fetch helper for slash-command autocomplete suggestions in the OpenFrame chat interface.
+
+## Key Components
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `fetchSlashCommands` | `async function` | Stateless fetch wrapper; resolves suggestions from a caller-supplied `commandsUrl`, returns empty array on any non-2xx response |
+| `useSlashCommands` | React hook | Debounced (150ms), cancellable hook returning `{ commands, loading }` |
+| `SlashCommandSummary` | Re-exported type | Canonical summary shape for a slash command |
+| `SlashCommandSummaryAction` | Re-exported type | Action payload within a summary |
+| `SlashCommandActionId` | Re-exported type | Identifier type for actions |
+
+## Usage Example
+
+```typescript
+import {
+  useSlashCommands,
+  fetchSlashCommands,
+} from "@flamingo-stack/openframe-frontend-core/components/chat/hooks";
+import { useChatRuntime } from "./chat-runtime";
+
+// Hook usage (preferred in React components)
+function SlashCommandDropdown({ prefix }: { prefix: string | null }) {
+  const { endpoints } = useChatRuntime();
+  const { commands, loading } = useSlashCommands(prefix, endpoints.commandsUrl);
+
+  if (loading) return <Spinner />;
+  return <CommandList items={commands} />;
+}
+
+// Stateless usage (e.g. outside React, in a server action test)
+const ctrl = new AbortController();
+const suggestions = await fetchSlashCommands(
+  "res",
+  ctrl.signal,
+  "/api/mingo-guide/commands",
+);
+```
+
+## Notes
+
+- `commandsUrl` has **no default** — always supply via `useChatRuntime().endpoints.commandsUrl`
+- URL resolution uses `new URL(commandsUrl, window.location.origin)`, supporting both relative and absolute URLs
+- Non-2xx responses (401, 403, 429) return `[]` silently — no error toasts
+- `AbortError` on unmount/dependency change is swallowed; other errors emit a `console.warn`

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

@@ -0,0 +1,34 @@
+<!-- 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.
+
+## 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 |
+
+## Usage Example
+
+```typescript
+import { useSseChatAdapter } 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({
+  tableIdForDocumentType: (docType) =>
+    myTenantRegistry[docType] ?? null,
+})
+
+// Consume the returned UnifiedChatState
+const { messages, sendMessage, isStreaming, streamingPhase } = chatState
+```
+
+> **Note:** `source` is read automatically from `ChatRuntimeContext` — no parameter needed. If `runtime.source` is empty the hook throws immediately to surface misconfigured embedders early.