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

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

@@ -1,49 +1,46 @@
-<!-- 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.
+<!-- 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.
 
 ## Key Components
 
-### 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`
+| 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` |
 
 ## Usage Example
 
 ```typescript
-// Preferred: import everything from the barrel
+// Typical consumer — import directly from the module index
 import {
   useUnifiedChat,
   useChatAttachments,
-  useProxiedImageUrl,
-} from '@openframe/chat-hooks'
+  useSlashCommands,
+} from '@flamingo/chat-hooks'
 
 function ChatPanel({ modes, activeMode }) {
-  const { messages, send } = useUnifiedChat({ modes, activeMode })
-  const { attachments, addAttachment } = useChatAttachments()
-  const proxied = useProxiedImageUrl(rawImageUrl)
+  const chat = useUnifiedChat({ modes, activeMode })
+  const attachments = useChatAttachments()
+  const slashCommands = useSlashCommands()
 
-  return <ChatUI messages={messages} onSend={send} />
+  // ...
+}
+
+// Advanced: direct transport access
+import { useNatsChatAdapter } from '@flamingo/chat-hooks'
+
+function CustomTransportPanel() {
+  const nats = useNatsChatAdapter({ /* config */ })
+  // ...
 }
 ```
 
-> **Note:** For standard usage, prefer `useUnifiedChat`. The adapter hooks (`useSSEChatAdapter`, `useNatsChatAdapter`) are exposed for advanced cases requiring direct transport access.
+## 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.

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

@@ -1,71 +1,52 @@
-<!-- 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.
+<!-- 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`
-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
+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
 
-### Core Config Fields
+### `UseNatsChatAdapterOptions`
+- `active` — gates the live subscription; keeps message state alive while the mode is hidden
 
-| 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
+### `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
-        ↓
-config.publishUserMessage  → consumer-owned send (HTTP/NATS)
+useNatsDialogSubscription  →  live NATS event tail
+         ↓
+decodeNatsChunk + reducer  →  chunk → ChatStreamEvent → state
+         ↓
+useChunkCatchup            →  back-fills missed chunks on reconnect/activation
 ```
 
+Returns a full `UnifiedChatState` object including `messages`, `isLoading`, `streamingPhase`, `sendMessage`, `stopMessage`, and `clearMessages`.
+
 ## Usage Example
 
 ```typescript
-// 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 }),
-    })
+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,
   },
-  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),
-})
+  { active: isNatsModeVisible },
+)
 ```
 
-> **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)
+> **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/__tests__/__snapshots__/conversation-id-persistence-golden.test.ts.snap

@@ -0,0 +1,37 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`server-history hydration (materializes through the reducer) > rebuilds messages + sendIdx-keyed refs + send counter from the transcript 1`] = `
+[
+  {
+    "content": "open a ticket for the broken printer",
+    "id": "hydrated-1",
+    "role": "user",
+  },
+  {
+    "chatRefs": {
+      "ticket:77": {
+        "id": "77",
+        "metadata": {
+          "status": "OPEN",
+        },
+        "title": "Broken printer",
+        "type": "ticket",
+        "url": null,
+      },
+    },
+    "content": "✅ Approved — ticket created: [card://ticket:77]",
+    "id": "hydrated-2",
+    "role": "assistant",
+  },
+  {
+    "content": "what is the pricing?",
+    "id": "hydrated-3",
+    "role": "user",
+  },
+  {
+    "content": "Pricing starts at $99/month per site.",
+    "id": "hydrated-4",
+    "role": "assistant",
+  },
+]
+`;

package/src/components/chat/hooks/__tests__/chunk-catchup-dialog-staleness.test.ts

@@ -0,0 +1,92 @@
+/**
+ * A catch-up fetch is async and the active dialog can change while it is in
+ * flight — switching dialogs is the ordinary interaction, not an edge case.
+ *
+ * `useChunkCatchup` already knows about staleness, but only in its `finally`:
+ * the processing loop ran FIRST and unconditionally. Everything downstream of
+ * it is bound to the CURRENT dialog — `onChunkReceived` is read through a ref
+ * the adapter reassigns every render, and the seq bookkeeping refs were just
+ * re-armed by `resetChunkTracking` for the newly-entered dialog — so a fetch
+ * that resolved late wrote dialog A's transcript into dialog B, and pushed B's
+ * seq cursor to A's JetStream sequence. Since the reducer drops anything at or
+ * below `lastAppliedSeq`, and A's stream position is unrelated to B's, that can
+ * silently discard B's own live chunks for the rest of the session.
+ *
+ * The same applies to the flags: finalizing `hasCompletedInitialCatchup` /
+ * `bufferUntilInitialCatchupComplete` on a stale fetch ends the NEW dialog's
+ * buffering window early, and draining `chunkBuffer` hands B's buffered live
+ * deliveries to A's stale batch.
+ */
+import { describe, it, expect, vi } from 'vitest'
+import { renderHook, act } from '@testing-library/react'
+import { useChunkCatchup } from '../use-chunk-catchup'
+import type { ChunkData } from '../../types'
+
+type Deferred = {
+  promise: Promise<ChunkData[]>
+  resolve: (chunks: ChunkData[]) => void
+}
+
+function deferred(): Deferred {
+  let resolve!: (chunks: ChunkData[]) => void
+  const promise = new Promise<ChunkData[]>((r) => {
+    resolve = r
+  })
+  return { promise, resolve }
+}
+
+const textChunk = (text: string, streamSeq: number, sequenceId: number): ChunkData =>
+  ({ type: 'TEXT', text, streamSeq, sequenceId }) as unknown as ChunkData
+
+describe('useChunkCatchup — dialog staleness', () => {
+  it('does not deliver a catchup that resolved after the dialog changed', async () => {
+    const onChunkReceived = vi.fn()
+    const pending = deferred()
+    const fetchChunks = vi.fn((dialogId: string) =>
+      dialogId === 'A' ? pending.promise : Promise.resolve([]),
+    )
+
+    const { result, rerender } = renderHook(
+      ({ dialogId }: { dialogId: string }) =>
+        useChunkCatchup({ dialogId, onChunkReceived, fetchChunks }),
+      { initialProps: { dialogId: 'A' } },
+    )
+
+    // Dialog A starts its catch-up…
+    let catchup!: Promise<unknown>
+    await act(async () => {
+      catchup = result.current.catchUpChunks()
+    })
+    expect(fetchChunks).toHaveBeenCalledWith('A', expect.anything(), undefined)
+
+    // …the user switches to B while A's fetch is still open…
+    rerender({ dialogId: 'B' })
+
+    // …and only then does A's fetch land, carrying A's own transcript.
+    await act(async () => {
+      pending.resolve([textChunk('SECRET FROM DIALOG A', 100001, 100001)])
+      await catchup
+    })
+
+    expect(onChunkReceived).not.toHaveBeenCalled()
+  })
+
+  it('still delivers a catchup for the dialog that is current when it lands', () => {
+    const onChunkReceived = vi.fn()
+    const fetchChunks = vi.fn(() =>
+      Promise.resolve([textChunk('B REAL CONTENT', 50001, 50001)]),
+    )
+
+    const { result } = renderHook(() =>
+      useChunkCatchup({ dialogId: 'B', onChunkReceived, fetchChunks }),
+    )
+
+    return act(async () => {
+      await result.current.catchUpChunks()
+    }).then(() => {
+      // Positive control: the guard must not swallow the normal path.
+      expect(onChunkReceived).toHaveBeenCalledTimes(1)
+      expect(onChunkReceived.mock.calls[0][0]).toMatchObject({ text: 'B REAL CONTENT' })
+    })
+  })
+})