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

package/src/components/chat/entity-cards/.use-entity-card-link.md

@@ -0,0 +1,51 @@
+<!-- source-hash: b340dcdf795a4dde839c90b56d635b69 -->
+Resolves `target` and `rel` anchor attributes for entity cards by delegating the same-tab vs. new-tab decision to the `ChatRuntime` navigation callback, eliminating the need for hub-side wrapper components.
+
+## Key Components
+
+### `useEntityCardLink(args): EntityCardLinkProps`
+
+Primary hook that computes anchor link attributes using a two-priority resolution strategy:
+
+1. **Explicit override** — If `target` or `rel` props are passed directly, they win immediately. A missing `rel` is auto-paired with `'noopener noreferrer'` when `target='_blank'` to prevent tabnabbing.
+2. **Runtime decision** — Falls back to `computeIsNewTab(runtime, href, targetPlatform)`, which mirrors the click handler in `executeNavigation`, keeping the rendered anchor and the click behavior in sync. Returns `{ target: undefined, rel: undefined }` (same-tab) when no runtime is mounted.
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `UseEntityCardLinkArgs` | Input: `href`, optional `targetPlatform`, optional explicit `target`/`rel` overrides |
+| `EntityCardLinkProps` | Output: resolved `target` and `rel` values for spreading onto an anchor element |
+
+## Usage Example
+
+```typescript
+import { useEntityCardLink } from './use-entity-card-link'
+
+function BlogCard({ href, targetPlatform }: Props) {
+  const { target, rel } = useEntityCardLink({ href, targetPlatform })
+
+  return (
+    <a href={href} target={target} rel={rel}>
+      Read Post
+    </a>
+  )
+}
+
+// Explicit override — runtime decision skipped entirely
+function ExternalCard({ href }: Props) {
+  const { target, rel } = useEntityCardLink({
+    href,
+    target: '_blank',
+    // rel auto-paired to 'noopener noreferrer'
+  })
+
+  return <a href={href} target={target} rel={rel}>Open</a>
+}
+```
+
+## Notes
+
+- Requires `HubRuntimeProvider` (or a compatible embed shim) to be mounted for runtime-derived decisions.
+- Result is memoized on `[target, rel, href, targetPlatform, runtime]` — safe to call in render.
+- Source: [`use-entity-card-link.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-entity-card-link.ts)

package/src/components/chat/entity-cards/.use-entity-card-placeholder.md

@@ -0,0 +1,47 @@
+<!-- source-hash: 7663c5ccc0601f548ad7c5ca061e0918 -->
+Thin wrapper around `useOgPlaceholderUrl` that resolves the correct OG placeholder URL for entity cards, allowing an explicit `placeholderUrl` prop to override the runtime-derived value.
+
+## Key Components
+
+### `UseEntityCardPlaceholderArgs`
+Interface defining hook inputs:
+- `title` — entity title used as the placeholder label
+- `placeholderUrl` — explicit override; when provided (including `null`), skips runtime derivation
+- `siteName` — optional site name displayed under the title
+- `aspect` — output aspect ratio: `'wide'` (default, catalog cards) or `'square'` (compact chat-inline cards)
+
+### `useEntityCardPlaceholder`
+Hook that delegates URL construction to `useOgPlaceholderUrl` but applies a priority rule: an explicitly passed `placeholderUrl` (even `null`) always wins over the derived value. Only `undefined` falls through to the runtime default.
+
+## Usage Example
+
+```typescript
+// Catalog card — derive URL from title at runtime
+const placeholderSrc = useEntityCardPlaceholder({
+  title: 'Microsoft 365 Business Premium',
+  siteName: 'Flamingo',
+  aspect: 'wide',
+})
+
+// Chat-inline card — caller pre-resolves and passes explicit URL
+const placeholderSrc = useEntityCardPlaceholder({
+  title: 'Entity Name',
+  placeholderUrl: 'https://cdn.example.com/placeholder.png',
+  aspect: 'square',
+})
+
+// Suppress placeholder entirely (e.g. real OG image already loaded)
+const placeholderSrc = useEntityCardPlaceholder({
+  title: 'Entity Name',
+  placeholderUrl: null, // returns null; runtime default skipped
+})
+```
+
+## Priority Logic
+
+```text
+placeholderUrl !== undefined  →  return placeholderUrl (string or null)
+placeholderUrl === undefined  →  return derived URL from useOgPlaceholderUrl
+```
+
+**Source:** [`use-entity-card-placeholder.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-entity-card-placeholder.ts)

package/src/components/chat/entity-cards/.what-i-shipped-card.md

@@ -0,0 +1,43 @@
+<!-- source-hash: 87d21aee30c9242f0b77a2542d0ce5fa -->
+Shared UI card component for rendering "What I Shipped" entries consistently across both the people-hub owner dashboard and the related-content rail, ensuring zero visual drift between surfaces.
+
+## Key Components
+
+### Interfaces
+
+- **`WhatIShippedCardData`** — Minimal data contract the card renders; satisfied by both hub dashboard entries and hydrated related-content rows.
+- **`WhatIShippedCardProps`** — Card props including `entry`, optional OG `placeholderUrl`, owner `actions`, `anchorProps` for click-through links, and `className`.
+
+### Exports
+
+- **`WhatIShippedCard`** — Primary card component. Wraps `AdminContentCard` with canonical field mapping: cover image (`featured_image` → `main_video_thumbnail` fallback → OG placeholder), 140-char truncated summary, status badge, author avatar/name, and formatted reporting month. Supports two modes:
+  - **Dashboard mode** — pass `actions` for owner action row.
+  - **Related-rail mode** — pass `anchorProps` to make the entire card a clickable link. Do not combine with `actions` to avoid nested interactive elements.
+- **`WhatIShippedCardSkeleton`** — Pulse-animated loading skeleton matching the card's `AdminContentCard` shape (3:2 cover + title/summary/meta lines). Used by the related-content rail during hydration to prevent layout shift.
+
+### Constants
+
+- **`STATUS_BADGE_CLASS`** — Maps `published`, `draft`, and `archived` status strings to their respective ODS color tokens.
+
+## Usage Example
+
+```typescript
+// Dashboard (owner actions)
+<WhatIShippedCard
+  entry={entry}
+  placeholderUrl={ogPlaceholderUrl}
+  actions={<button onClick={handleEdit}>Edit</button>}
+/>
+
+// Related-content rail (click-through link)
+<WhatIShippedCard
+  entry={entry}
+  placeholderUrl={buildOgPlaceholderUrl(entry)}
+  anchorProps={{ href: `/shipped/${entry.id}` }}
+/>
+
+// Loading state
+<WhatIShippedCardSkeleton className="col-span-1" />
+```
+
+**Source:** [`what-i-shipped-card.tsx`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/what-i-shipped-card.tsx)

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`, `useRealtimeChunkProcessor`, `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-chat-card-item.md

@@ -1,19 +1,22 @@
-<!-- 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.
+<!-- source-hash: 00398183d82e9f61b3c8434476f51469 -->
+Fetches and caches a single content item for inline chat card rendering by hitting the same list-API endpoints used by public pages (`/blog`, `/case-studies`, `/podcasts`, etc.), ensuring a consistent data shape with full relational 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.
+### `UseChatCardItemResult<T>`
+Return type interface exposing:
+- `item: T | undefined` — the resolved content item
+- `isLoading: boolean` — TanStack Query loading state
+- `isError: boolean` — TanStack Query error state
 
-### `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.
+### `useChatCardItem<T>(type, id)`
+Primary hook. Resolves the list URL via `runtime.endpoints.buildListUrl`, fetches through `embedAuthedFetch` (preserving auth credentials), extracts the matching item, and returns the typed result.
 
-### `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`.
+**Key behaviors:**
+- **Deduplication** — queries are keyed by `['chat-card-item', type, id]`; multiple references to the same content in one chat message produce a single network request
+- **Auth-aware fetching** — uses `embedAuthedFetch` (not bare `fetch`) to traverse the `EmbedAuthAdapter` (cookie/Bearer/401-retry), preventing blank cards behind a gateway
+- **Streaming-safe caching** — `staleTime: 5min` / `gcTime: 30min` prevents skeleton flashes on every chunk as markdown re-parses during streaming assistant messages
+- **No focus refetching** — `refetchOnWindowFocus: false` avoids wasteful re-fetches when users toggle the chat panel
 
 ## Usage Example
 
@@ -23,17 +26,27 @@ import { useChatCardItem } from './use-chat-card-item'
 interface BlogPost {
   id: string
   title: string
-  author: string
+  slug: string
+  author: { name: string }
 }
 
 function ChatBlogCard({ id }: { id: string }) {
-  const { item, isLoading, isError } = useChatCardItem<BlogPost>('post', id)
+  const { item, isLoading, isError } = useChatCardItem<BlogPost>('blog', id)
 
-  if (isLoading) return <Spinner />
-  if (isError || !item) return <ErrorCard />
+  if (isLoading) return <CardSkeleton />
+  if (isError || !item) return null
 
-  return <BlogCardPreview title={item.title} author={item.author} />
+  return <BlogCard post={item} />
 }
 ```
 
-> **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.
+## Dependencies
+
+| Dependency | Role |
+|---|---|
+| `@tanstack/react-query` | Query lifecycle, deduplication, caching |
+| `useRequiredChatRuntime` | Provides `buildListUrl` per content type |
+| `embedAuthedFetch` | Auth-aware fetch (cookie / Bearer / retry) |
+| `extractItems` / `extractItemId` | Normalizes list-API response envelope |
+
+**Source:** [`src/.../use-chat-card-item.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/src/hooks/use-chat-card-item.ts)

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

@@ -0,0 +1,59 @@
+<!-- source-hash: 18f2ec0cf9ed75af0e8e8ae198973c29 -->
+Manages the dialog-history concerns for the chat panel, including archive navigation, read-only archived conversation mode, and rename/archive/restore confirmation modals — keeping `EmbeddableChat` as a thin orchestration layer.
+
+## Key Components
+
+### `UseChatDialogManagerArgs`
+Input interface wiring adapter callbacks into the manager:
+
+| Field | Type | Description |
+|---|---|---|
+| `dialogs` | `ReadonlyArray<DialogItem>` | Active (non-archived) dialogs |
+| `activeDialogId` | `string \| null \| undefined` | Currently open dialog |
+| `selectDialog` | `(id: string \| null) => void` | Opens a dialog by id |
+| `clearMessages` | `() => void` | Resets active conversation |
+| `renameDialog` | `(id, title) => Promise<void>` | Renames a dialog |
+| `archiveDialog` | `(id) => Promise<void>` | Archives a dialog |
+| `fetchArchivedDialogs` | `(params) => Promise<FetchDialogsResult>` | Optional; gates archive UI |
+| `unarchiveDialog` | `(id) => Promise<void>` | Optional; gates restore UI |
+
+### `useChatDialogManager`
+The primary hook. Returns a flat object of state and handlers consumed directly by the chat panel JSX.
+
+**Key return groups:**
+
+- **Archive page** — `archiveOpen`, `archivedDialogs`, `archivedCursor`, `archivedLoading`, `archivedPending`, `openArchive`, `closeArchive`, `loadArchivedPage`, `handleArchivedSelect`
+- **Current-chat navigation** — `handleSelectDialog`, `isOpeningDialog`, `handleBack`, `resetToNewChat`, `activeDialog`
+- **Archived conversation mode** — `isViewingArchived`
+- **Action modals** — `renameTarget`, `archiveTarget`, `restoreTarget` (+ setters), `handleConfirmRename`, `handleConfirmArchive`, `handleConfirmRestore`
+
+## Usage Example
+
+```typescript
+const dialogManager = useChatDialogManager({
+  dialogs,
+  activeDialogId,
+  selectDialog,
+  clearMessages,
+  renameDialog,
+  archiveDialog,
+  fetchArchivedDialogs,
+  unarchiveDialog,
+})
+
+// Open archive page
+dialogManager.openArchive()
+
+// Load next page of archived dialogs
+await dialogManager.loadArchivedPage(dialogManager.archivedCursor ?? undefined)
+
+// Trigger archive confirmation modal
+dialogManager.setArchiveTarget(someDialog)
+await dialogManager.handleConfirmArchive()
+```
+
+> **Note:** `loadArchivedPage` uses a monotonic request ID (`archivedRequestIdRef`) to prevent stale responses from clobbering newer results during overlapping background refresh and pagination fetches. A 120 ms skeleton delay avoids flashing the empty state on cached/fast first-page loads.
+
+## Source
+
+[`use-chat-dialog-manager.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-chat-dialog-manager.ts)

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

@@ -1,45 +1,57 @@
-<!-- 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.
+<!-- source-hash: 733d42822ee9220c6eefe2050f96cda5 -->
+Provides the `ChatIdentitySurface` capability bag (`authTier`, `source`, `attachmentsEnabled`, `user`) for the current chat session, enabling client UI elements to gate on identity tiers without requiring a chat message first.
 
 ## 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.
+| Export | Type | Description |
+|---|---|---|
+| `ChatIdentityResponse` | Interface | Wire-shape mirroring the hub's `/api/auth/identity` response |
+| `ChatIdentitySurface` | Interface | Extends `ChatIdentityResponse` with `isLoading`; never throws |
+| `ChatIdentityProvider` | Component | Optional context provider that resolves identity once for an entire React subtree |
+| `useChatIdentity` | Hook | Returns the `ChatIdentitySurface` bag; reads from a parent provider when present, otherwise self-fetches |
 
 ## Usage Example
 
+**Standalone (self-fetching):**
+
 ```typescript
 import { useChatIdentity } from './use-chat-identity'
 
 function AttachmentButton() {
   const { isLoading, attachmentsEnabled, user } = useChatIdentity()
 
-  if (isLoading) return <Spinner />
+  if (isLoading) return <Skeleton />
   if (!attachmentsEnabled) return null
+  return <button>Attach file</button>
+}
+```
+
+**Shared provider for independent React subtrees:**
+
+```typescript
+import { ChatIdentityProvider, useChatIdentity } from './use-chat-identity'
 
+// Mount once inside ChatRuntimeContext.Provider, near your embed root.
+// Pass enabled={false} to defer fetching until the chat drawer opens.
+function AppShell({ children }: { children: ReactNode }) {
   return (
-    <button>
-      Attach file {user?.firstName ? `(${user.firstName})` : ''}
-    </button>
+    <ChatIdentityProvider enabled={drawerOpen}>
+      {children}
+    </ChatIdentityProvider>
   )
 }
+
+// Any descendant — even in a separate router outlet — shares the
+// single resolution instead of issuing its own request.
+function TicketCenterAuthed() {
+  const { user } = useChatIdentity()
+  return <span>{user?.firstName ?? ''}</span>
+}
 ```
 
-## Design Notes
+## Behavior 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 |
+- **No client-side cache.** Uses plain `useState`/`useEffect`; refetches on credential rotation (`proxyEmail` change) and never persists stale identity.
+- **Always safe to render.** Failures and non-OK responses fall back to `ANON_DEFAULTS` (`authTier: 'anon'`, `attachmentsEnabled: false`, `user: null`).
+- **`attachmentsEnabled` is server-computed.** Consumers must not derive it from `authTier` + `source` themselves.
+- Endpoint URL is read from `useRequiredChatRuntime().endpoints.identityUrl`, allowing reverse-proxy overrides per embed.

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

@@ -1,53 +1,70 @@
-<!-- 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.
+<!-- source-hash: 97d203340db2c0a0d6f8b3dc8d30c054 -->
+Manages chunk buffering, deduplication, and ordered replay of NATS message chunks during dialog catchup, ensuring historical and live-streamed chunks are merged without gaps or duplicates.
 
 ## Key Components
 
-| 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 |
+### Internal Helpers
+
+- **`makeSeqKey(messageType, chunkType, sequenceId)`** — Generates a composite key for sequence-level deduplication across message types.
+- **`makeBatchDedupKey(item)`** — Generates a broader deduplication key for batch processing, incorporating text, tool, and approval fields.
+- **`getChatTypeMessageType(chatType)`** — Maps a `ChatType` to its corresponding `NatsMessageType` (`admin-message` or `message`).
+
+### Hook: `useChunkCatchup`
+
+**Parameters** (`UseChunkCatchupOptions`):
+
+| Parameter | Description |
+|---|---|
+| `dialogId` | Active dialog identifier |
+| `onChunkReceived` | Callback fired for each processed chunk |
+| `chatTypes` | Array of chat types to fetch (default: `[CHAT_TYPE.CLIENT]`) |
+| `fetchChunks` | Async function to retrieve historical chunks from the API |
+
+**Internal Refs:**
+
+| Ref | Purpose |
+|---|---|
+| `processedSequenceKeys` | Tracks already-processed sequence keys to prevent duplicates |
+| `lastSequenceIdByType` | Per-`NatsMessageType` resume checkpoint (prevents cross-stream offset contamination) |
+| `fetchingInProgress` | Guards against concurrent fetches |
+| `pendingCatchupRef` | Queues a second catchup requested during an in-flight fetch |
+| `chunkBuffer` | Buffers live NATS chunks arriving during catchup |
+
+**Returned Callbacks** (`UseChunkCatchupReturn`):
+
+- **`processChunk(chunk, messageType, forceProcess?)`** — Routes an incoming chunk to the buffer or directly to `onChunkReceived`, recording its sequence key.
+- **`flushBufferedRealtimeChunks()`** — Drains the buffer after catchup, sorting chunks so id-less live chunks appear after sequenced history.
+- **`catchUpChunks(fromSequenceId?)`** — Orchestrates the full catchup flow: fetches historical chunks per chat type using per-type checkpoints, merges with buffered live chunks, sorts, deduplicates, and processes in order up to the last complete message boundary.
 
 ## Usage Example
 
 ```typescript
-const {
-  catchUpChunks,
-  processChunk,
-  startInitialBuffering,
-  resetAndCatchUp,
-} = useChunkCatchup({
-  dialogId: 'dialog-123',
+const { processChunk, catchUpChunks } = useChunkCatchup({
+  dialogId: 'dialog-abc123',
   chatTypes: [CHAT_TYPE.CLIENT, CHAT_TYPE.ADMIN],
   fetchChunks: async (dialogId, chatType, fromSequenceId) => {
-    return await api.getChunks(dialogId, chatType, fromSequenceId)
+    const res = await api.getChunks({ dialogId, chatType, fromSequenceId })
+    return res.chunks
   },
   onChunkReceived: (chunk, messageType) => {
-    dispatch(appendChunk({ chunk, messageType }))
+    appendChunkToTranscript(chunk, messageType)
   },
 })
 
-// On dialog open: buffer live chunks while fetching history
-startInitialBuffering()
+// Called when a live NATS message arrives
+natsSubscription.on('message', (chunk, messageType) => {
+  processChunk(chunk, messageType)
+})
+
+// Called on dialog load or reconnect
 await catchUpChunks()
+```
+
+## Notes
 
-// On NATS message received:
-processChunk(incomingChunk, 'message')
+- Per-type sequence tracking (`lastSequenceIdByType`) prevents a faster stream's high sequence ID from skipping chunks in a slower, independently-numbered stream (legacy Redis transport behaviour).
+- Pending catchup requests are queued rather than dropped to avoid permanent transcript gaps on double-reconnect.
+- Chunks without a `sequenceId` are treated as the newest live events and sorted after all sequenced history.
+- Deduplication only applies to chunks carrying a `sequenceId`; id-less streaming deltas are always preserved to avoid silent content loss.
 
-// On reconnect: re-fetch missed chunks from last known position
-await resetAndCatchUp()
-```
+**Source:** [`use-chunk-catchup.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/use-chunk-catchup.ts)

package/src/components/chat/hooks/.use-empty-state-config.md

@@ -0,0 +1,39 @@
+<!-- source-hash: 36dc058eabd4b8150553ed538a51cbd3 -->
+Provides the client-side hook and fetch helper for loading per-platform chat empty-state configuration (greeting, quick-action chips, RAG table IDs) in both host (SSR props) and cross-origin embed (REST fetch) scenarios.
+
+## Key Components
+
+### Interfaces
+
+| Interface | Purpose |
+|---|---|
+| `EmptyStateQuickAction` | A single quick-action chip — `id`, `label`, `prompt`, plus optional icon (glyph name, URL, or props) |
+| `EmptyStateIcon` | Agent identity icon resolved by `<EntityIcon>` on the empty state |
+| `EmptyStateConfig` | Wire shape of `GET /api/docs/empty-state`; fields: `name`, `icon`, `greeting`, `enabledRagTableIds`, `quickActions`, `suggestedQueries` |
+
+### Functions
+
+- **`fetchEmptyStateConfig(signal, emptyStateUrl)`** — Bare GET via `embedAuthedFetch`. Returns `EMPTY_STATE_FALLBACK` on any non-2xx; logs 5xx errors without surfacing toasts; re-throws `AbortError` for react-query cancellation.
+- **`useEmptyStateConfig(emptyStateUrl, options?)`** — React hook wrapping the fetch in a react-query query. Keyed on `emptyStateUrl`; `staleTime`/`gcTime: Infinity` makes the result static per session. `enabled: false` skips the network call entirely and returns the fallback immediately.
+
+## Usage Example
+
+```typescript
+// Embed mode — fetch config from the host's empty-state endpoint
+const { config, loading, loaded } = useEmptyStateConfig(
+  runtime.endpoints.emptyStateUrl,
+  { enabled: true },
+);
+
+if (loaded) {
+  console.log(config.greeting);       // Admin-edited greeting or null
+  console.log(config.quickActions);   // EmptyStateQuickAction[]
+  console.log(config.enabledRagTableIds); // string[]
+}
+
+// Host mode — URL is undefined; skip the fetch, use SSR props instead
+const { config } = useEmptyStateConfig(undefined, { enabled: false });
+// config === EMPTY_STATE_FALLBACK, loaded === true immediately
+```
+
+> **Note:** Pass `enabled: false` in host (SSR) mode where `emptyStateUrl` is unset. The hook will never fire a network request and `loaded` will be `true` immediately, so downstream components can unconditionally read `config` without a loading guard.