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

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

@@ -1,40 +1,75 @@
-<!-- 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.
+<!-- source-hash: 82efaf1b62d0b5740b96c9d4e6160b6a -->
+React hook that manages a JetStream ephemeral OrderedConsumer subscription for a chat dialog stream, handling connection lifecycle, reconnection with sequence resumption, and NATS client sharing.
 
 ## 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.
+### `useJetStreamDialogSubscription`
+
+The single exported hook. Accepts `UseJetStreamDialogSubscriptionOptions` and returns `UseJetStreamDialogSubscriptionReturn`.
+
+**State tracked:**
+
+| State | Description |
+|---|---|
+| `isConnected` | Whether the NATS WebSocket connection is live |
+| `isSubscribed` | Whether the JetStream consumer is active |
+| `reconnectionCount` | Increments on each successful reconnect |
+| `currentStreamSeq` | Highest stream sequence number observed |
+
+**Internal refs (stable across renders):**
+
+- `clientRef` — shared `NatsClient` instance
+- `subscriptionRef` — active `JetStreamSubscriptionHandle`
+- `highestStreamSeqRef` — tracks max stream sequence for gap-free resume
+
+**Effect order (declaration order matters):**
+
+1. **Connection effect** — acquires/releases the shared NATS client when `enabled` or `wsUrl` changes; drives the `startConnectionLifecycle` which emits status events.
+2. **Dialog reset effect** — resets `highestStreamSeqRef` when `dialogId` changes so a new dialog never inherits a stale start sequence.
+3. **Subscription effect** — creates or recreates the ephemeral consumer when `isConnected`, `dialogId`, `topic`, `streamName`, or `reconnectionCount` change.
+
+**Deliver policy logic:**
+
+```text
+highestStreamSeqRef set  →  DeliverPolicy.ByStartSequence @ (highestSeq + 1)
+optStartSeq provided     →  DeliverPolicy.ByStartSequence @ (optStartSeq + 1)
+neither                  →  DeliverPolicy.New (live tail only)
+```
 
 ## 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,
-  })
+import { useJetStreamDialogSubscription } from './use-jetstream-dialog-subscription'
+
+function ChatPane({ dialogId }: { dialogId: string }) {
+  const { isConnected, isSubscribed, currentStreamSeq } =
+    useJetStreamDialogSubscription({
+      enabled: true,
+      dialogId,
+      topic: 'chunks',
+      optStartSeq: 42,           // resume after sequence 42
+      getNatsWsUrl: () => 'wss://nats.example.com',
+      onEvent: (payload, topic) => {
+        console.log(`[${topic}] seq=${payload.streamSeq}`, payload)
+      },
+      onConnect: () => console.log('NATS connected'),
+      onDisconnect: () => console.log('NATS disconnected'),
+      inactiveThresholdMs: 3 * 60_000, // 3-minute consumer TTL
+    })
+
+  return (
+    <p>
+      {isConnected ? '🟢' : '🔴'} connected |{' '}
+      {isSubscribed ? 'subscribed' : 'pending'} | seq {currentStreamSeq ?? '–'}
+    </p>
+  )
+}
 ```
 
-## Notes
+## Reconnection Behavior
+
+On reconnect the consumer is **not** recreated from `optStartSeq`; instead it resumes from `highestStreamSeqRef.current + 1`, guaranteeing no chunk is replayed or skipped. Only a `dialogId` change resets that pointer back to `optStartSeq` (or live-tail).
+
+The hook retries only on `closed` / `disconnected` NATS status events. Protocol-level `-ERR` events (e.g. permission violations on `CONSUMER.CREATE`) are logged as warnings without triggering the reconnection loop.
 
-- 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.
+> **Source:** [`use-jetstream-dialog-subscription.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-jetstream-dialog-subscription.ts)

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

@@ -1,52 +1,71 @@
-<!-- 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.
+<!-- source-hash: 3fbde71f6e5fc7f9b4576423ebdb08e2 -->
+Thin wrapper that wires together NATS subscriptions, real-time chunk processing, and dialog management into a single `UnifiedChatState` object for the Mingo/NATS transport mode of the unified chat surface.
 
 ## 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
+Primary configuration interface with two operational modes:
+- **Bare-transport mode** — caller supplies `dialogId` explicitly and owns dialog lifecycle (original v0 API, used by Tauri Fae Chat)
+- **Managed-dialog mode** — caller supplies `fetchDialogs` and related callbacks; the adapter owns dialog state, pagination, and history
 
-### `UseNatsChatAdapterOptions`
-- `active` — gates the live subscription; keeps message state alive while the mode is hidden
+### Core Config Fields
 
-### `useNatsChatAdapter(config, options)`
-Main hook. Composes three internal hooks:
+| Field | Required | Description |
+|-------|----------|-------------|
+| `getNatsWsUrl` | ✅ | Returns the NATS WebSocket URL or `null` to suspend |
+| `publishUserMessage` | ✅ | Consumer-owned send callback (HTTP POST or NATS publish) |
+| `dialogId` | ❌ | Explicit dialog ID (bare-transport mode) |
+| `fetchDialogs` | ❌ | Enables managed-dialog mode with sidebar support |
+| `fetchDialogMessages` | ❌ | Populates history on dialog switch |
+| `topics` | ❌ | NATS subject suffixes to tail (default: `['message']`) |
+
+### Supporting Interfaces
+
+- **`FetchDialogsParams`** / **`FetchDialogsResult`** — paginated dialog list with cursor-based pagination
+- **`FetchDialogMessagesParams`** / **`FetchDialogMessagesResult`** — paginated message history with optional `tokenUsage`
+
+### Composition Stack
 
 ```text
-useNatsDialogSubscription  →  live NATS event tail
-         ↓
-useRealtimeChunkProcessor  →  chunk → MessageSegment[]
-         ↓
-useChunkCatchup            →  back-fills missed chunks on reconnect/activation
+useNatsDialogSubscription  → live NATS event tail
+        ↓
+useRealtimeChunkProcessor  → chunk → MessageSegment[]
+        ↓
+useChunkCatchup            → back-fills missed chunks on reconnect
+        ↓
+config.publishUserMessage  → consumer-owned send (HTTP/NATS)
 ```
 
-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,
+// Bare-transport mode (v0 — Tauri Fae Chat)
+const chatState = useNatsChatAdapter({
+  dialogId: activeDialogId,
+  getNatsWsUrl: () => `wss://nats.example.com`,
+  publishUserMessage: async (text, { dialogId }) => {
+    await fetch(`/api/chat/${dialogId}/message`, {
+      method: 'POST',
+      body: JSON.stringify({ text }),
+    })
   },
-  { active: isNatsModeVisible },
-)
+  topics: ['admin-message'],
+})
+
+// Managed-dialog mode (openframe-frontend / EmbeddableChat)
+const chatState = useNatsChatAdapter({
+  getNatsWsUrl: () => natsUrl,
+  publishUserMessage: sendMessage,
+  fetchDialogs: async ({ cursor, limit }) => api.listDialogs({ cursor, limit }),
+  fetchDialogMessages: async ({ dialogId, cursor }) =>
+    api.getMessages(dialogId, { cursor }),
+  createDialog: () => api.createDialog(),
+  deleteDialog: (id) => api.deleteDialog(id),
+  approveRequest: (requestId) => api.approve(requestId),
+  rejectRequest: (requestId, reason) => api.reject(requestId, reason),
+})
 ```
 
-> **Note:** `publishUserMessage` is intentionally consumer-owned — the adapter only handles optimistic UI updates and phase transitions; the actual transport is wired externally.
+> **Note:** Set `topics: ['admin-message']` for Mingo/admin deployments. The default `'message'` topic is for Fae client-chat. Mismatched topics cause the assistant to hang in the `thinking` phase indefinitely.
+
+**Source:** [`use-nats-chat-adapter.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-nats-chat-adapter.ts)

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

@@ -1,65 +1,81 @@
-<!-- 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.
+<!-- source-hash: 33e3e72c7a8bed6ac4ea84dd9600a0c6 -->
+React hook that manages a NATS WebSocket subscription for a specific dialog, handling connection lifecycle, automatic reconnection, and multi-topic message subscriptions.
 
 ## Key Components
 
 ### `useNatsDialogSubscription(options)`
-The primary exported hook that manages the full lifecycle of a NATS dialog subscription.
 
-**Parameters (`UseNatsDialogSubscriptionOptions`):**
+Primary hook that establishes and maintains a shared NATS client connection and subscribes to one or more topics scoped to a `dialogId`.
+
+**Options (`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.
+|---|---|
+| `enabled` | Enables/disables the connection |
+| `dialogId` | Target dialog ID; topics are subscribed as `chat.<dialogId>.<topic>` |
+| `topics` | Array of `NatsMessageType` values (defaults to `['message']`) |
+| `onEvent` | Callback fired with each decoded JSON message and its topic type |
+| `onConnect` / `onDisconnect` | Connection lifecycle callbacks |
+| `onSubscribed` | Fired once all topic subscriptions are active |
+| `onBeforeReconnect` | Called before each reconnection attempt |
+| `getNatsWsUrl` | Function returning the current WebSocket URL |
+| `clientConfig` | NATS client credentials (`name`, `user`, `pass`) |
+| `reconnectionBackoff` | Backoff strategy for reconnection attempts |
+
+**Returns (`UseNatsDialogSubscriptionReturn`):**
+
+| Field | Type | Description |
+|---|---|---|
+| `isConnected` | `boolean` | Whether the NATS client is currently connected |
+| `isSubscribed` | `boolean` | Whether topic subscriptions are active |
+| `reconnectionCount` | `number` | Number of reconnections since mount |
+
+**Key implementation details:**
+- Resolves the WebSocket URL synchronously each render to avoid re-running effects on callback identity changes (e.g. silent token rotations)
+- Stabilizes all callbacks via `useRef` to prevent unnecessary subscription teardowns
+- Joins `topics` to a string key (`topicsKey`) so the subscription effect only re-runs when topic content changes, not on inline array re-allocations
+- Uses a shared NATS client pool (`acquireClient` / `releaseClient`) — multiple hook instances sharing the same URL reuse the same connection
+
+### `buildNatsWsUrl(apiBaseUrl, options?)`
+
+Utility that constructs a NATS WebSocket URL from an HTTP/HTTPS base URL.
 
 ## Usage Example
 
 ```typescript
-import { useNatsDialogSubscription } from './use-nats-dialog-subscription'
-
-function DialogListener({ dialogId }: { dialogId: string }) {
-  const { isConnected, isSubscribed, reconnectionCount } = useNatsDialogSubscription({
-    enabled: true,
-    dialogId,
-    topics: ['message', 'admin-message'],
-    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,
-    },
-  })
-
-  return <div>Connected: {isConnected ? 'Yes' : 'No'} | Reconnects: {reconnectionCount}</div>
+import {
+  useNatsDialogSubscription,
+  buildNatsWsUrl,
+} from './use-nats-dialog-subscription'
+
+function DialogListener({ dialogId, token }: { dialogId: string; token: string }) {
+  const { isConnected, isSubscribed, reconnectionCount } =
+    useNatsDialogSubscription({
+      enabled: true,
+      dialogId,
+      topics: ['message', 'typing'],
+      getNatsWsUrl: () =>
+        buildNatsWsUrl('https://api.example.com', {
+          token,
+          includeAuthParam: true,
+          source: 'dashboard',
+        }),
+      onEvent: (payload, topic) => {
+        console.log(`[${topic}]`, payload)
+      },
+      onConnect: () => console.log('NATS connected'),
+      onDisconnect: () => console.log('NATS disconnected'),
+    })
+
+  return (
+    <div>
+      Connected: {String(isConnected)} | Subscribed: {String(isSubscribed)} |
+      Reconnections: {reconnectionCount}
+    </div>
+  )
 }
 ```
 
-## Notes
+## Source
 
-- 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.
+[`use-nats-dialog-subscription.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-nats-dialog-subscription.ts)

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

@@ -1,50 +1,77 @@
-<!-- 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.
+<!-- source-hash: 681c783784fdc89f0c86eb3e539c482b -->
+Processes real-time NATS streaming chunks into structured message segments, managing streaming state, approval flows, direct-mode barriers, and tool execution events for AI assistant chat interfaces.
 
 ## Key Components
 
-| 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 |
+### `useRealtimeChunkProcessor(options)`
 
-### Handled Chunk Actions
+Main hook export. Accepts `UseRealtimeChunkProcessorOptions` and returns `UseRealtimeChunkProcessorReturn`.
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `callbacks` | `object` | required | Event handlers (`onSegmentsUpdate`, `onStreamStart`, `onStreamEnd`, `onApprove`, `onReject`, etc.) |
+| `displayApprovalTypes` | `string[]` | `['CLIENT']` | Approval types rendered inline; others are escalated |
+| `approvalStatuses` | `object` | `{}` | Current status map keyed by `requestId` |
+| `initialState` | `object` | — | Hydrates accumulator for resumed dialogs |
+| `batchApprovalsEnabled` | `boolean` | `true` | Renders batch approvals as a single card; `false` unfolds into individual cards |
+| `isDirectMode` | `boolean` | `false` | Activates the direct-mode barrier, dropping AI assistant chunks |
+
+### Internal Refs
+
+| Ref | Purpose |
+|---|---|
+| `accumulatorRef` | `MessageSegmentAccumulator` instance managing segment state |
+| `isInStreamRef` | Tracks open/closed stream window (`MESSAGE_START` → `MESSAGE_END`) |
+| `hasEverStreamedRef` | Distinguishes cold-start vs. post-stream continuation for append mode |
+| `directModeFlagRef` / `sawDirectMessageRef` | Direct-mode barrier gate |
+| `directTeardownFiredRef` | One-shot guard: ensures teardown fires exactly once on barrier entry |
+| `pendingEscalatedRef` | Map of escalated approval requests not shown inline |
+
+### Supported 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 |
+|---|---|
+| `message_start` / `message_end` | Opens/closes stream, resets accumulator |
+| `text` / `thinking` | Appends to accumulator; uses append-mode after `MESSAGE_END` |
+| `tool_execution` | Routes in-stream to accumulator; post-stream to `onToolExecuted` callback |
+| `approval_request` | Inline or escalated based on `displayApprovalTypes` |
+| `approval_batch` | Single batch card, legacy card fan-out, or escalated |
+| `metadata` | Forwarded directly to `onMetadata` |
+| `direct_message` | Activates direct-mode barrier |
 
 ## Usage Example
 
 ```typescript
 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),
+    onSegmentsUpdate: (segments, meta) => setSegments(segments),
+    onStreamStart: () => setIsStreaming(true),
+    onStreamEnd: () => setIsStreaming(false),
+    onApprove: (requestId) => approveAction(requestId),
+    onReject: (requestId) => rejectAction(requestId),
+    onEscalatedApproval: (requestId, data) => notifyAdmin(requestId, data),
+    onToolExecuted: (segment) => updateToolCard(segment),
+    onAgentBusy: () => showTypingIndicator(),
+    onMetadata: (meta) => handleMetadata(meta),
   },
   displayApprovalTypes: ['CLIENT'],
-  approvalStatuses: { 'req-123': 'pending' },
-  enableThinking: false,
   batchApprovalsEnabled: true,
+  isDirectMode: false,
+  approvalStatuses: { 'req-123': 'approved' },
 })
 
-// Feed raw NATS chunks directly
-natsSubscription.on('message', (msg) => processChunk(msg.data))
+// Wire to your NATS subscription
+natsSubscription.onMessage((rawChunk) => {
+  processChunk(rawChunk)
+})
 ```
 
-> **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.
+## Direct-Mode Barrier
+
+When `isDirectMode` is `true` or a `direct_message` chunk arrives, the hook drops all subsequent AI-assistant chunks (everything not in `DIRECT_MODE_ALLOWED`). Teardown fires exactly once — clearing the typing indicator, composer lock, and in-progress bubble — even if no stream is currently open (e.g., during post-approval tool execution).
+
+## Source
+
+[`use-realtime-chunk-processor.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-realtime-chunk-processor.ts)

package/src/components/chat/hooks/.use-scripted-stream.md

@@ -0,0 +1,46 @@
+<!-- source-hash: 98664d575bf2457a305eb811747ed93c -->
+Playback clock hook that advances through pre-built `StreamFrame` arrays like a live stream, holding each frame for its configured delay before revealing the next, then parking on the final frame.
+
+## Key Components
+
+- **`useScriptedStream(frames, resetKey, enabled)`** — Core hook. Returns the currently active `StreamFrame` based on elapsed playback.
+  - `frames` — Ordered array of `StreamFrame` objects (built externally via `buildStreamFrames`).
+  - `resetKey` — Restarts playback from frame 0 on identity change (new conversation). Preserves index when the same conversation grows (e.g. an appended continuation resumes seamlessly).
+  - `enabled` — When `false`, skips to the final frame immediately.
+- **`EMPTY_FRAME`** — Sentinel idle frame returned when no frames are available.
+- **`prefersReducedMotion()`** — Detects `prefers-reduced-motion: reduce` media query; bypasses animation and jumps straight to the last frame.
+
+## Behavior Details
+
+| Condition | Result |
+|---|---|
+| `enabled === false` or reduced motion | Jumps to last frame immediately |
+| `frames` grows mid-playback | Effect re-runs, resumes from current index into new frames |
+| `frames` shrinks before reset lands | Index is clamped to prevent out-of-bounds access |
+| `frames.length === 0` | Returns `EMPTY_FRAME` |
+
+## Usage Example
+
+```typescript
+import { useScriptedStream } from './use-scripted-stream'
+import { buildStreamFrames } from '../utils/scripted-stream'
+
+function ChatPreview({ conversation }: { conversation: Conversation }) {
+  const frames = buildStreamFrames(conversation.messages)
+
+  // resetKey changes when a new conversation is selected
+  const frame = useScriptedStream(frames, conversation.id)
+
+  return (
+    <ChatWindow
+      messages={frame.messages}
+      isTyping={frame.typing}
+      phase={frame.phase}
+    />
+  )
+}
+```
+
+## Source
+
+[`use-scripted-stream.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-scripted-stream.ts)

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

@@ -1,46 +1,53 @@
-<!-- source-hash: 433665c60d11f92235ffb1f5227d3b44 -->
-Debounced React hook and stateless fetch helper for slash-command autocomplete suggestions in the OpenFrame chat interface.
+<!-- source-hash: aa7b6d85f5c19e25d82b750caeada18b -->
+Provides slash-command autocomplete capabilities via a stateless fetch helper, a debounced React hook, and a cached registry hook for deduped session-scoped command lookups.
 
 ## 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 |
+| Export | Kind | Description |
+|---|---|---|
+| `fetchSlashCommands` | `async function` | Stateless fetch wrapper. Resolves `commandsUrl` against `window.location.origin`, appends `?q=prefix`, uses `embedAuthedFetch` for bearer/cookie auth. Returns `SlashCommandSummary[]` or `[]` on non-2xx; re-throws `AbortError` so react-query treats cancellation correctly. |
+| `useSlashCommands` | React hook | Debounced (150 ms), cancellable hook. Returns `{ commands, loading }`. Clears state when `prefix` is `null`; aborts in-flight requests on dependency change or unmount. |
+| `useSlashCommandRegistry` | React hook | Full registry fetch (empty prefix) backed by react-query with `staleTime`/`gcTime: Infinity`. All consumers in one chat surface share a single cache entry. Accepts `{ enabled }` to gate the fetch (e.g. skip in Mingo mode). Returns `{ commands, loading, loaded }`. |
+| `SlashCommandSummary` | Re-exported type | Canonical type from `component.types`; re-exported so callers avoid reaching into the internal types path. |
+| `SlashCommandSummaryAction` | Re-exported type | Action shape within a `SlashCommandSummary`. |
+| `SlashCommandActionId` | Re-exported type | Discriminated identifier for a command action. |
 
 ## Usage Example
 
 ```typescript
 import {
   useSlashCommands,
+  useSlashCommandRegistry,
   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);
+// 1. Debounced autocomplete — renders as the user types "/…"
+function SlashAutocomplete({ prefix }: { prefix: string | null }) {
+  const { commandsUrl } = useChatRuntime().endpoints;
+  const { commands, loading } = useSlashCommands(prefix, 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",
-);
+// 2. Session-scoped registry — deduped across all consumers
+function WelcomePanel() {
+  const { commandsUrl } = useChatRuntime().endpoints;
+  const { commands, loaded } = useSlashCommandRegistry(commandsUrl, {
+    enabled: activeMode === "guide",
+  });
+
+  if (!loaded) return <Skeleton />;
+  return <OnboardingCards commands={commands} />;
+}
+
+// 3. One-shot fetch (e.g. SSE adapter, outside React)
+const ac = new AbortController();
+const cmds = await fetchSlashCommands("dep", ac.signal, commandsUrl);
 ```
 
 ## 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`
+- `commandsUrl` is **always required** — sourced from `useChatRuntime().endpoints.commandsUrl`. No default exists.
+- Auth is handled transparently by [`embedAuthedFetch`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/utils/embed-authed-fetch.ts); no host-side `fetch` patching needed.
+- Any non-abort failure degrades silently to an empty list — a flaky commands endpoint never breaks chat or blocks the welcome UI in a loading state.