@flamingo-stack/openframe-frontend-core 0.0.212 → 0.0.213-snapshot.20260528174436

package/src/components/chat/hooks/.use-chat-card-item.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 4c8bb965154478fda34b9e6e30abb929 -->
+Fetches a fully-mapped content item for an inline chat card by reusing the same list-API endpoint as public-facing pages (`/blog`, `/podcasts`, `/roadmap`, etc.), ensuring a single source of truth for item shape and joins.
+
+## Key Components
+
+### `useChatCardItem<T>(type, id)`
+Primary hook. Builds the list URL via `runtime.endpoints.buildListUrl`, fires a TanStack Query fetch, and returns the matched item. Deduplicated by `['chat-card-item', type, id]` query key — multiple references to the same `(type, id)` within one chat message produce a single network request. `refetchOnWindowFocus` is disabled to avoid wasteful re-fetches as the chat panel is toggled.
+
+### `extractItems(data)`
+Normalizes heterogeneous API response shapes (`{ items }`, `{ posts }`, `{ campaigns }`, `{ completed, inProgress }`, `{ data }`, or bare arrays) into a flat `unknown[]`. Single normalization point for all content types.
+
+### `extractItemId(type, item)`
+Resolves the primary key from a fetched item, handling both `id` and `external_id` fields for ClickUp-backed types (`roadmap_item`, `delivery_item`, `internal_task`).
+
+### `UseChatCardItemResult<T>`
+Return type interface exposing `item`, `isLoading`, and `isError`.
+
+## Usage Example
+
+```typescript
+import { useChatCardItem } from './use-chat-card-item'
+
+interface BlogPost {
+  id: string
+  title: string
+  author: string
+}
+
+function ChatBlogCard({ id }: { id: string }) {
+  const { item, isLoading, isError } = useChatCardItem<BlogPost>('post', id)
+
+  if (isLoading) return <Spinner />
+  if (isError || !item) return <ErrorCard />
+
+  return <BlogCardPreview title={item.title} author={item.author} />
+}
+```
+
+> **Runtime dependency:** The hook reads `runtime.endpoints.buildListUrl` from `ChatRuntimeContext`. Hub environments wire the registry-driven builder directly; embedded apps supply a per-type URL builder pointing at the reverse proxy.

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

@@ -0,0 +1,45 @@
+<!-- source-hash: b3bbee124a5b530f9a19e9b047eec040 -->
+Fetches and surfaces the current chat session's identity tier (`authTier`, `source`, `attachmentsEnabled`, `user`) via a lightweight `useEffect`/`useState` hook — no client-side cache by design.
+
+## Key Components
+
+### Interfaces
+
+- **`ChatIdentityResponse`** — Wire shape mirroring the hub's `/api/auth/identity` route response. Includes `authTier` (`'session' | 'bearer-act-as' | 'anon'`), `source`, `attachmentsEnabled` (server-computed), and a nullable `user` object with optional `firstName`, `lastName`, and `avatarUrl`.
+- **`ChatIdentitySurface`** — Extends `ChatIdentityResponse` with an `isLoading` boolean for skeleton/spinner states.
+
+### Hook
+
+- **`useChatIdentity()`** — Reads the identity endpoint URL from `useRequiredChatRuntime()`, fires an authenticated fetch via `chatAuthedFetch`, and returns identity data merged with `isLoading`. Falls back to `ANON_DEFAULTS` on errors or non-OK responses — never throws.
+
+### Constants
+
+- **`ANON_DEFAULTS`** — Safe fallback (`authTier: 'anon'`, `attachmentsEnabled: false`, `user: null`) used during loading and on any fetch failure.
+
+## Usage Example
+
+```typescript
+import { useChatIdentity } from './use-chat-identity'
+
+function AttachmentButton() {
+  const { isLoading, attachmentsEnabled, user } = useChatIdentity()
+
+  if (isLoading) return <Spinner />
+  if (!attachmentsEnabled) return null
+
+  return (
+    <button>
+      Attach file {user?.firstName ? `(${user.firstName})` : ''}
+    </button>
+  )
+}
+```
+
+## Design Notes
+
+| Concern | Decision |
+|---|---|
+| Caching | None — avoids stale identity across credential rotations |
+| Error handling | Falls back to anon defaults; never throws |
+| Credential changes | Re-fetches automatically when `proxyEmail` (from `localStorage`) changes |
+| `attachmentsEnabled` | Computed server-side; consumers read it directly without combining fields |

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

@@ -0,0 +1,58 @@
+<!-- source-hash: c1d1e8fb922837f8d57888644f4624f5 -->
+Manages the client-side chat state for an AI assistant conversation, handling message streaming, tool approval workflows, and adaptive thinking display via SSE.
+
+## Key Components
+
+### `UseChatOptions`
+Configuration interface for the hook:
+- `useMock` / `debugMode` — toggle mock/debug SSE modes
+- `assistantName` / `assistantAvatar` — customize assistant identity
+- `streamFn` — override default SSE transport with a custom function
+- `initialMessages` — seed conversation state (e.g., from `localStorage`)
+- `onMessagesChange` — persistence callback triggered on every message update
+
+### `useChat(options)`
+Primary hook returning:
+
+| Return Value | Type | Description |
+|---|---|---|
+| `messages` | `Message[]` | Full conversation history |
+| `isTyping` | `boolean` | True until first text chunk arrives |
+| `isStreaming` | `boolean` | True while SSE stream is active |
+| `sseError` | `Error \| null` | Stream-level error state |
+| `sendMessage` | `fn` | Send a user turn, optionally hidden |
+| `abort` | `fn` | Cancel the active stream |
+| `reset` | `fn` | Reset SSE state |
+
+### `sendMessage(text, extra?, options?)`
+Appends a user message, creates an optimistic assistant placeholder, then iterates the SSE stream, handling three segment types:
+- **`text`** — accumulates into the last assistant message
+- **`thinking`** — prepended as a thinking card (always before answer text)
+- **`approval_request`** — renders a tool-approval card with `onApprove`/`onReject` callbacks
+- **`decision_resolved`** — flips approval card status and appends a receipt to the current turn
+
+## Usage Example
+
+```typescript
+import { useChat } from './use-chat'
+
+function ChatWidget() {
+  const { messages, isTyping, sendMessage, abort } = useChat({
+    assistantName: 'Mingo',
+    initialMessages: JSON.parse(localStorage.getItem('chat') ?? '[]'),
+    onMessagesChange: (msgs) => localStorage.setItem('chat', JSON.stringify(msgs)),
+    streamFn: myCustomStreamFn, // optional: bypass default SSE
+  })
+
+  return (
+    <div>
+      {messages.map((m) => <MessageBubble key={m.id} message={m} />)}
+      {isTyping && <TypingIndicator />}
+      <button onClick={() => sendMessage('Hello!')}>Send</button>
+      <button onClick={abort}>Stop</button>
+    </div>
+  )
+}
+```
+
+> **Hidden turns**: Pass `{ hidden: true }` to `sendMessage` for post-approval auto-continuation — the user message is added to LLM context but not rendered in the UI, keeping the visible thread clean.

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 |