@flamingo-stack/openframe-frontend-core 0.0.498-1506.4000.1 → 0.0.498

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

@@ -1,46 +1,49 @@
-<!-- source-hash: d1cebe46eff04115f214c16b75a69467 -->
-Barrel export file for the chat hooks module, re-exporting all public hooks from their individual files into a single `'use client'` entry point.
+<!-- source-hash: 31ada6e53cd71ce93d35361e48559a56 -->
+Barrel export file (`'use client'`) that re-exports all React hooks from the chat hooks module, providing a single import surface for consumers.
 
 ## Key Components
 
-| Export Group | Hooks |
-|---|---|
-| **Realtime / Streaming** | `useChunkCatchup`, `useJetstreamDialogSubscription`, `useNatsDialogSubscription` |
-| **UI Utilities** | `useCollapsible`, `useCloseOnNavigation`, `useChatCardItem` |
-| **Chat Core** | `useChat`, `useSSE`, `useChatIdentity`, `useChatAttachments`, `useChatAttachmentImageGallery`, `useSlashCommands` |
-| **Transport Adapters** | `useSSEChatAdapter`, `useNatsChatAdapter` |
-| **Unified Surface** | `useUnifiedChat` (primary), `useEmbeddedChat` (legacy SSE alias) |
-| **Image Proxy** | `useProxiedImageUrl` |
+### Streaming & Real-time Hooks
+- **`useChunkCatchup`** — Replays missed chunks after reconnection
+- **`useScriptedStream`** — Drives scripted/mock streaming sequences
+- **`useRealtimeChunkProcessor`** — Processes incoming real-time message chunks
+- **`useJetstreamDialogSubscription`** / **`useNatsDialogSubscription`** — NATS/JetStream transport subscriptions
+- **`useCollapsible`** — Collapsible UI state management
+
+### Chat Core Hooks
+- **`useChat`** / **`useSSE`** — Core chat and Server-Sent Events hooks (ported from hub, without `MockChatService`/`useChatConfig`)
+- **`useSlashCommands`** — Slash command parsing and dispatch
+- **`useEmptyStateConfig`** — Empty state configuration
+- **`useChatAttachments`** / **`useChatAttachmentImageGallery`** — File attachment handling and image gallery
+- **`useChatIdentity`** — Chat user/agent identity resolution
+- **`useChatCardItem`** — Chat card rendering state
+- **`useCloseOnNavigation`** — Dismisses dialogs/panels on route change
+
+### Unified Chat Surface
+- **`useUnifiedChat`** — Primary public hook; selects transport by `activeMode`
+- **`useSSEChatAdapter`** / **`useNatsChatAdapter`** — Transport adapters (SSE and NATS)
+- **`useEmbeddedChat`** — Legacy SSE alias for embedded surfaces
+
+### Utilities
+- **`useProxiedImageUrl`** — Resolves proxied image URLs from `ChatRuntime.endpoints`
 
 ## Usage Example
 
 ```typescript
-// Typical consumer — import directly from the module index
+// Preferred: import everything from the barrel
 import {
   useUnifiedChat,
   useChatAttachments,
-  useSlashCommands,
-} from '@flamingo/chat-hooks'
+  useProxiedImageUrl,
+} from '@openframe/chat-hooks'
 
 function ChatPanel({ modes, activeMode }) {
-  const chat = useUnifiedChat({ modes, activeMode })
-  const attachments = useChatAttachments()
-  const slashCommands = useSlashCommands()
+  const { messages, send } = useUnifiedChat({ modes, activeMode })
+  const { attachments, addAttachment } = useChatAttachments()
+  const proxied = useProxiedImageUrl(rawImageUrl)
 
-  // ...
-}
-
-// Advanced: direct transport access
-import { useNatsChatAdapter } from '@flamingo/chat-hooks'
-
-function CustomTransportPanel() {
-  const nats = useNatsChatAdapter({ /* config */ })
-  // ...
+  return <ChatUI messages={messages} onSend={send} />
 }
 ```
 
-## Notes
-
-- Marked `'use client'` — safe for React Server Component trees; hooks run only on the client.
-- `useUnifiedChat` is the recommended entry point for new consumers; `useEmbeddedChat` is the legacy SSE alias kept for backward compatibility.
-- `useProxiedImageUrl` reads proxy config from `ChatRuntime.endpoints`, keeping image-proxy resolution consistent between hub and embedder environments.
+> **Note:** For standard usage, prefer `useUnifiedChat`. The adapter hooks (`useSSEChatAdapter`, `useNatsChatAdapter`) are exposed for advanced cases requiring direct transport access.

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
-         ↓
-decodeNatsChunk + reducer  →  chunk → ChatStreamEvent → state
-         ↓
-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-realtime-chunk-processor.md

@@ -0,0 +1,77 @@
+<!-- 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
+
+### `useRealtimeChunkProcessor(options)`
+
+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, 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, 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'],
+  batchApprovalsEnabled: true,
+  isDirectMode: false,
+  approvalStatuses: { 'req-123': 'approved' },
+})
+
+// Wire to your NATS subscription
+natsSubscription.onMessage((rawChunk) => {
+  processChunk(rawChunk)
+})
+```
+
+## 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/index.ts

@@ -5,6 +5,7 @@ export * from './use-collapsible'
 export * from './use-scripted-stream'
 export * from './use-jetstream-dialog-subscription'
 export * from './use-nats-dialog-subscription'
+export * from './use-realtime-chunk-processor'
 
 // Chat hooks migrated from hub `hooks/*` (Task #7).
 export * from './use-slash-commands'

package/src/components/chat/hooks/use-chat.ts

@@ -1,13 +1,5 @@
 'use client'
 
-/**
- * @deprecated Phase 3 of the chat unification moved the SSE adapter off this
- * hook — its trailing-assistant merge + `decision_resolved` receipt path now
- * live in `../stream/chat-stream-reducer` (transport: 'sse'). No lib-internal
- * code consumes `useChat`/`useSSE` anymore; they remain exported for external
- * consumers until Phase 4 migrates them, then get deleted (Phase 6).
- */
-
 import { useState, useCallback, useEffect, useRef } from 'react'
 import { useSSE, type StreamFn, type StreamFnExtraOptions } from './use-sse'
 import type {

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

@@ -217,33 +217,8 @@ export function useChunkCatchup({
       })
       
       const allChunkResults = await Promise.all(chunkPromises)
-
-      // STALENESS GATE — the FIRST thing after the await, because everything
-      // below this line is bound to the CURRENTLY active dialog, not to the one
-      // this fetch was issued for:
-      //   - `onChunkReceivedRef.current` is reassigned every render, so it
-      //     routes into whichever dialog's reducer is mounted now;
-      //   - `processedSequenceKeys` / `lastSequenceId` / `lastSequenceIdByType`
-      //     were re-armed by `resetChunkTracking` for the new dialog;
-      //   - `chunkBuffer` holds the NEW dialog's buffered live deliveries;
-      //   - `hasCompletedInitialCatchup` / `bufferUntilInitialCatchupComplete`
-      //     govern the NEW dialog's buffering window.
-      // So a fetch that resolved after a dialog switch used to write dialog A's
-      // transcript into dialog B AND advance B's seq cursor to A's JetStream
-      // sequence — and because the reducer drops any event at or below
-      // `lastAppliedSeq`, an unrelated (higher) position permanently discards
-      // B's own live chunks. Switching dialogs mid-fetch is the ordinary
-      // interaction, not an edge case.
-      //
-      // The `finally` below already handles stale bookkeeping correctly (it
-      // keeps the new dialog's cycle intact and only discards a pending entry
-      // belonging to THIS dialog); it still runs on this early return. The
-      // guard could not live there — by then the chunks had already been
-      // applied.
-      if (dialogId !== dialogIdRef.current) return
-
       const allCatchupChunks: BufferedChunk[] = allChunkResults.flat()
-
+      
       if (allCatchupChunks.length === 0) {
         flushBufferedRealtimeChunks()
         bufferUntilInitialCatchupComplete.current = false