@flamingo-stack/openframe-frontend-core 0.0.207 → 0.0.208

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

@@ -1,1023 +1,25 @@
 'use client'
 
 /**
- * useEmbeddedChat — the streamed-AI-chat hook for the OSS-lib chat panel.
+ * Backward-compatibility shim.
  *
- * Two key contracts vs hub-side chat hooks:
+ * The canonical SSE/Guide-mode chat adapter has been renamed to
+ * `useSseChatAdapter` and moved to `./use-sse-chat-adapter`. This module
+ * re-exports it under the legacy `useEmbeddedChat` name plus the legacy
+ * options type, so external consumers and barrel imports keep working
+ * without churn.
  *
- *   1. `source` is READ FROM THE RUNTIME, not a parameter. Throws loudly
- *      if `runtime.source` is empty so embedders that forget to wire
- *      identity get an immediate signal rather than a silently-empty
- *      localStorage namespace.
- *
- *   2. Navigation is runtime-provided. The hub-side `useDocSearch` keeps
- *      its own `decideNewTab` + `useDocNavigation.navigate` plumbing for
- *      the search autocomplete (it calls `router.push`). The chat body
- *      doesn't navigate via this hook — click handlers on rendered
- *      cards/chips go through `handleChatNavClick` instead.
- *
- *   3. `tableIdForDocumentType` is INJECTED via the optional
- *      `tableIdForDocumentType` parameter. Hub callers pass the
- *      registry-backed lookup from `lib/config/rag-table-config`;
- *      embedders that don't supply one fall back to
- *      `defaultTableIdForDocumentType` (the lib-baked map covering
- *      every documentType currently registered in the hub) so the
- *      `displayRef` / `discussRef` Ask + Display buttons WORK out of
- *      the box. Override only when you have polymorphic / per-tenant
- *      types the default doesn't cover.
- *
- * Wire format and SSE-parser logic mirror the hub original byte-for-byte
- * so server-side and client-side stay in lockstep across the migration.
- */
-
-import { useState, useEffect, useCallback, useMemo, useRef, type MutableRefObject } from 'react'
-import { useChat, type Message, type StreamFnExtraOptions } from './use-chat'
-import { useRequiredChatRuntime } from '../../../contexts/chat-runtime-context'
-import type { ChatRef } from '../chat-ref.types'
-import { buildChatRefKey } from '../types/chat.types'
-import type { MessageSegment } from '../types/message.types'
-import { fetchSlashCommands, type SlashCommandSummary } from './use-slash-commands'
-import { getChatProxyAuth } from '../utils/chat-proxy-auth-storage'
-import { chatAuthedFetch } from '../utils/chat-authed-fetch'
-import { parseScrollAnchor, type ScrollAnchor } from '../utils/scroll-anchor'
-import { AUTO_CONTINUATION_DIRECTIVE_PREFIX } from '../utils/auto-continuation-directive'
-import { flattenAssistantContent } from '../utils/flatten-assistant-content'
-import { sanitizeTitleForChat } from '../utils/slash-dispatch-utils'
-import { defaultTableIdForDocumentType } from '../utils/source-icons'
-
-// =============================================================================
-// Public types
-// =============================================================================
-
-/** Source identifier — opaque string ID (registry lookup happens in the
- *  hub-side platform-utils, not in lib). */
-export type DocSource = string
-
-export interface ChatSource {
-  index: number
-  name: string
-  path: string
-  documentType: string
-  externalUrl?: string
-  /** Platform that owns the destination at `externalUrl`. */
-  targetPlatform?: string | null
-  /** Primary-key value for single-row chips. */
-  id?: string
-  /** Per-row items for grouped chips. */
-  items?: Array<{
-    id: string
-    documentType: string
-    name: string
-    externalUrl?: string
-    targetPlatform?: string | null
-    /** In-app doc-tree path for markdown / data-room-doc rows so the
-     *  grouped chip's anchor can trigger an in-page doc-tree swap via
-     *  `handleChatNavClick` (parity with single-row chips + cards). */
-    path?: string | null
-  }>
-  /** RagTableConfig.id for this source. */
-  sourceRepo?: string
-  /** Optional display label override returned by the chat API. */
-  label?: string
-}
-
-export interface DocChatMessage {
-  id: string
-  role: 'user' | 'assistant'
-  /** String form for legacy callers that just want the answer text; structured
-   *  segments include thinking blocks too, which the lib's
-   *  ChatMessageEnhanced renders as <ThinkingDisplay> cards. */
-  content: string
-  /** Structured segments. When set, callers should prefer this over `content`. */
-  segments?: MessageSegment[]
-  sources?: ChatSource[]
-  /** Per-row refs for inline object-card rendering. Keyed by
-   *  `<documentType>:<primaryKey>`. Populated for assistant messages only. */
-  chatRefs?: Record<string, ChatRef>
-  /** Per-message viewport-positioning hint emitted by the server. */
-  scrollAnchor?: ScrollAnchor
-  /** When true the message is part of the conversation history but is
-   *  NOT rendered in the chat UI. */
-  hidden?: boolean
-}
-
-/** Streaming phase exposed to the chat shell so it can render a "Thinking with
- *  Sonnet 4.6 · 200K context window" status row above the input box.
- *  - 'idle'      → no in-flight turn
- *  - 'thinking'  → server emitted the leading {status:'thinking'} frame; no
- *                  text token has arrived yet (adaptive-thinking phase)
- *  - 'streaming' → first text token has arrived; model is generating answer */
-export type StreamingPhase = 'idle' | 'thinking' | 'streaming'
-
-/** Per-turn metadata extracted from the streamed metadata frame. */
-export interface ChatTurnMeta {
-  /** Provider key recognized by `<ModelDisplay>` for icon
-   *  selection: 'anthropic' | 'openai' | 'google' (case-insensitive). */
-  provider: string | null
-  modelLabel: string | null
-  contextWindowMaxTokens: number | null
-  /** Input tokens (from message_start). Includes cached tokens. */
-  inputTokens: number | null
-  /** Output tokens (from message_delta). Only known after stream end. */
-  outputTokens: number | null
-  /** Cache hit % (read / total-input × 100). Only known after stream end. */
-  cacheHitRatePct: number | null
-  /** Cross-call usage breakdown extracted from the trailing usage frame. */
-  breakdown: {
-    haikuRewriter?: { input: number; output: number }
-    haikuClassifier?: { input: number; output: number }
-    haikuSummarizer?: { input: number; output: number }
-    routedAnswer?: { model: string; complexity: string; thinkingBudget: number }
-  } | null
-  /** Per-message viewport-positioning hint. */
-  scrollAnchor: ScrollAnchor | null
-  /** Routing decision from the server's `decideRoute`. */
-  routedComplexity: string | null
-  routedThinkingBudget: number | null
-}
-
-/**
- * Optional dependency-injection options for `useEmbeddedChat`.
- *
- *   - `tableIdForDocumentType` — looks up the RagTableConfig.id for an
- *     LLM document type. Used by `displayRef` + `discussRef` to translate
- *     an inline-card click into a server-side entity-id filter.
- *
- *     **Defaults to `defaultTableIdForDocumentType` from
- *     `src/utils/source-icons.ts`** — a lib-baked map covering every
- *     documentType currently registered in the hub's RAG_TABLE_CONFIGS.
- *     This makes Ask / Display work out of the box in embedders without
- *     any callback wiring.
- *
- *     Override only when you have polymorphic / per-tenant document
- *     types that map to a different tableId than the default
- *     (hub-canonical) registry — pass your own `(docType) => tableId`
- *     callback and it wins over the default.
- */
-export interface UseEmbeddedChatOptions {
-  tableIdForDocumentType?: (documentType: string) => string | null
-}
-
-// =============================================================================
-// Internal helpers
-// =============================================================================
-
-/** Single source of truth for a fresh `ChatTurnMeta` row. */
-function createEmptyTurnMeta(): ChatTurnMeta {
-  return {
-    provider: null,
-    modelLabel: null,
-    contextWindowMaxTokens: null,
-    inputTokens: null,
-    outputTokens: null,
-    cacheHitRatePct: null,
-    breakdown: null,
-    scrollAnchor: null,
-    routedComplexity: null,
-    routedThinkingBudget: null,
-  }
-}
-
-/**
- * Escape `<` so the lib's `SimpleMarkdownRenderer` (which uses `rehypeRaw`
- * to pass HTML through) doesn't treat XML-like tokens in Claude's
- * thinking output as React components. Escaping `<` → `&lt;` preserves
- * the visible character without breaking blockquote `>` markers.
- */
-function escapeThinkingTags(text: string): string {
-  return text.replace(/</g, '&lt;')
-}
-
-function createDocStreamFn(
-  source: DocSource,
-  endpoints: { chatStreamUrl: string; approvalToolUrl: string },
-  messagesRef: MutableRefObject<Message[]>,
-  sourcesMapRef: MutableRefObject<Map<number, ChatSource[]>>,
-  refsMapRef: MutableRefObject<Map<number, Record<string, ChatRef>>>,
-  metaMapRef: MutableRefObject<Map<number, ChatTurnMeta>>,
-  setStreamingPhase: (phase: StreamingPhase) => void,
-  bumpMetaTick: () => void,
-  sendCountRef: MutableRefObject<number>,
-) {
-  // CRITICAL: the decoder + buffer MUST live INSIDE the returned async-
-  // generator function (per-call closure), NOT at the factory level. A
-  // rapid send-stop-send sequence with hook-level state would feed the
-  // second stream's first chunk into the first stream's tail buffer,
-  // corrupting metadata-frame parsing.
-  return async function* (
-    message: string,
-    signal?: AbortSignal,
-    extra?: StreamFnExtraOptions,
-  ): AsyncGenerator<MessageSegment> {
-    const currentMessages = messagesRef.current || []
-    // Filter `hidden:true` messages out of the API history. The approval-
-    // action turn injects a hidden user message with `content=''`.
-    // `flattenAssistantContent` joins text-segment arrays into a single
-    // string so the server sees the receipt + auto-continuation Qs.
-    const apiMessages = [
-      ...currentMessages
-        .filter((m) => (m.role === 'user' || m.role === 'assistant') && !m.hidden)
-        .map((m) => ({
-          role: m.role,
-          content:
-            typeof m.content === 'string' ? m.content : flattenAssistantContent(m.content),
-        })),
-      { role: 'user', content: message },
-    ]
-
-    // URL + body branch — approvalAction routes to the approval-tool
-    // endpoint, the standard chat path routes to the chat-stream endpoint.
-    const targetPath = extra?.approvalAction
-      ? endpoints.approvalToolUrl
-      : endpoints.chatStreamUrl
-    // `source` is INTENTIONALLY NOT in the body. The chat route resolves
-    // it server-side via its own platform-detection — tamper-proof binding
-    // so a client on one platform can't POST a different platform's
-    // conversation.
-    const requestBody = extra?.approvalAction
-      ? {
-          proposal_id: extra.approvalAction.proposalId,
-          action: extra.approvalAction.action,
-          messages: currentMessages
-            .filter((m) => (m.role === 'user' || m.role === 'assistant') && !m.hidden)
-            .map((m) => ({
-              role: m.role,
-              content:
-                typeof m.content === 'string'
-                  ? m.content
-                  : flattenAssistantContent(m.content),
-            })),
-        }
-      : {
-          messages: apiMessages,
-          ...(extra?.commandOverride ? { commandOverride: extra.commandOverride } : {}),
-          ...(extra?.pendingAttachments && extra.pendingAttachments.length > 0
-            ? { pendingAttachments: extra.pendingAttachments }
-            : {}),
-        }
-    // `chatAuthedFetch` carries the bearer-act-as headers (+ Supabase
-    // session cookies) — same wrapper `use-chat-attachments` and
-    // `use-chat-identity` use, so all three chat-side fetch sites share
-    // one identity-propagation primitive.
-    const response = await chatAuthedFetch(targetPath, {
-      method: 'POST',
-      body: JSON.stringify(requestBody),
-      signal,
-    })
-
-    if (!response.ok) {
-      throw new Error(`Chat request failed: ${response.status}`)
-    }
-
-    const reader = response.body?.getReader()
-    if (!reader) throw new Error('No response body')
-
-    const decoder = new TextDecoder()
-    let buffer = ''
-    let inText = false
-    // Live thinking accumulator — coalesced to ~20fps to avoid a re-render
-    // storm (Anthropic emits 30-60 deltas/sec).
-    let thinkingAccum = ''
-    let lastThinkingYieldTime = 0
-    let pendingThinkingYield = false
-    const THINKING_YIELD_INTERVAL_MS = 50
-    let trailerBuffer = ''
-    let inTrailer = false
-
-    const sendIdx = sendCountRef.current - 1
-    while (true) {
-      const { done, value } = await reader.read()
-      if (done) break
-
-      const chunk = decoder.decode(value, { stream: true })
-
-      if (!inText) {
-        buffer += chunk
-        while (!inText) {
-          const recIdx = buffer.indexOf('\x1E')
-          const nullIdx = buffer.indexOf('\0')
-          if (recIdx !== -1 && (nullIdx === -1 || recIdx < nullIdx)) {
-            if (pendingThinkingYield) {
-              pendingThinkingYield = false
-              yield { type: 'thinking', text: escapeThinkingTags(thinkingAccum) }
-            }
-            inText = true
-            setStreamingPhase('streaming')
-            const after = buffer.slice(recIdx + 1)
-            buffer = ''
-            if (after) {
-              // The `after` slice may ALSO contain the `\x1F` trailing-
-              // usage sentinel — common for fixed-answer responses where
-              // the whole frame sequence arrives in ONE TCP chunk.
-              const unitIdx = after.indexOf('\x1F')
-              if (unitIdx === -1) {
-                yield { type: 'text', text: after }
-              } else {
-                const textBefore = after.slice(0, unitIdx)
-                const trailerAfter = after.slice(unitIdx + 1)
-                if (textBefore) {
-                  yield { type: 'text', text: textBefore }
-                }
-                inTrailer = true
-                trailerBuffer = trailerAfter
-              }
-            }
-            break
-          }
-          if (nullIdx === -1) break // need more bytes
-          const metaStr = buffer.slice(0, nullIdx)
-          const remaining = buffer.slice(nullIdx + 1)
-          let meta: any
-          try {
-            meta = JSON.parse(metaStr)
-          } catch {
-            // Not JSON — start of answer body.
-            inText = true
-            setStreamingPhase('streaming')
-            if (buffer.length > 0) {
-              yield { type: 'text', text: buffer }
-              buffer = ''
-            }
-            break
-          }
-          if (meta.status === 'thinking') {
-            setStreamingPhase('thinking')
-          } else if (meta.kind === 'thinking-delta' && typeof meta.text === 'string') {
-            thinkingAccum += meta.text
-            const now = Date.now()
-            if (now - lastThinkingYieldTime >= THINKING_YIELD_INTERVAL_MS) {
-              lastThinkingYieldTime = now
-              pendingThinkingYield = false
-              yield { type: 'thinking', text: escapeThinkingTags(thinkingAccum) }
-            } else {
-              pendingThinkingYield = true
-            }
-          } else if (meta.kind === 'usage' && meta.stage === 'start') {
-            mergeTurnMeta(metaMapRef, sendIdx, {
-              inputTokens: meta.input_tokens ?? null,
-            })
-            bumpMetaTick()
-          } else if (
-            meta.kind === 'decision_resolved' &&
-            typeof meta.action === 'string'
-          ) {
-            // Server-driven post-approve / post-reject frame.
-            const action = meta.action === 'rejected' ? 'rejected' : 'approved'
-            const toolName =
-              typeof meta.tool_name === 'string' ? meta.tool_name : undefined
-            const result = (meta.result ?? null) as
-              | { ticket_id?: string; status?: string | null; mirror_synced?: boolean }
-              | null
-            const card = (meta.card ?? null) as
-              | { type?: string; marker?: string; ref?: ChatRef }
-              | null
-            if (card?.ref?.id && card?.type) {
-              const existing = refsMapRef.current.get(sendIdx) ?? {}
-              const key = buildChatRefKey(card.type, card.ref.id)
-              refsMapRef.current.set(sendIdx, { ...existing, [key]: card.ref })
-              bumpMetaTick()
-            }
-            yield {
-              type: 'decision_resolved',
-              action,
-              ok: meta.ok === true,
-              willAutoContinue: meta.willAutoContinue === true,
-              ...(toolName ? { toolName } : {}),
-              ...(result ? { result } : {}),
-              ...(card?.marker ? { marker: card.marker } : {}),
-              ...(card?.ref ? { cardRef: card.ref } : {}),
-              ...(typeof meta.receiptText === 'string'
-                ? { receiptText: meta.receiptText }
-                : {}),
-              proposalId:
-                typeof meta.proposalId === 'string' ? meta.proposalId : undefined,
-            } as any
-          } else if (meta.kind === 'approval_request' && meta.proposalId) {
-            // The model called a write tool. Server persisted the
-            // proposal and sent us a CARD-READY payload.
-            const proposalId = String(meta.proposalId)
-            const toolName = String(meta.toolName ?? 'tool')
-            const headline =
-              typeof meta.title === 'string' && meta.title.length > 0
-                ? meta.title
-                : toolName
-            const rawFields = Array.isArray(meta.fields)
-              ? (meta.fields as Array<{ label?: string; value?: string }>)
-              : []
-            const fields: Array<{ label: string; value: string }> = []
-            for (const f of rawFields) {
-              if (!f || !f.label || !f.value) continue
-              fields.push({ label: f.label, value: f.value })
-            }
-            yield {
-              type: 'approval_request',
-              data: {
-                command: headline,
-                fields,
-                requestId: proposalId,
-                approvalType: toolName,
-              },
-              status: 'pending',
-            } as any
-          } else if (meta.kind === 'text-leading' && typeof meta.text === 'string') {
-            // Model's preamble text (the prose written BEFORE the tool_use
-            // block) — emitted as a standalone text segment.
-            yield { type: 'text', text: meta.text }
-          } else if (meta.kind === 'tool_error') {
-            const msg =
-              typeof meta.message === 'string' && meta.message.length > 0
-                ? meta.message
-                : 'Could not complete the requested action right now.'
-            yield {
-              type: 'text',
-              text: `⚠️ ${msg}`,
-            } as any
-          } else if (meta.kind === 'routing') {
-            if (typeof meta.routedComplexity === 'string') {
-              mergeTurnMeta(metaMapRef, sendIdx, {
-                routedComplexity: meta.routedComplexity,
-                routedThinkingBudget:
-                  typeof meta.routedThinkingBudget === 'number'
-                    ? meta.routedThinkingBudget
-                    : null,
-              })
-              bumpMetaTick()
-            }
-          } else {
-            if (meta.sources) {
-              sourcesMapRef.current.set(sendIdx, meta.sources)
-            }
-            // Per-row refs for inline object cards.
-            if (meta.refs && typeof meta.refs === 'object') {
-              refsMapRef.current.set(sendIdx, meta.refs as Record<string, ChatRef>)
-              bumpMetaTick()
-            }
-            if (
-              meta.modelLabel ||
-              meta.contextWindowMaxTokens ||
-              meta.provider ||
-              meta.model
-            ) {
-              mergeTurnMeta(metaMapRef, sendIdx, {
-                provider: meta.provider ?? null,
-                modelLabel: meta.modelLabel ?? null,
-                contextWindowMaxTokens: meta.contextWindowMaxTokens ?? null,
-              })
-              bumpMetaTick()
-            }
-            const parsedAnchor = parseScrollAnchor(meta.scrollAnchor)
-            if (parsedAnchor !== null) {
-              mergeTurnMeta(metaMapRef, sendIdx, { scrollAnchor: parsedAnchor })
-              bumpMetaTick()
-            }
-          }
-          buffer = remaining
-        }
-      } else if (inTrailer) {
-        trailerBuffer += chunk
-      } else {
-        setStreamingPhase('streaming')
-        // Trailing usage frame uses \x1F (Unit Separator) as a sentinel.
-        const sepIdx = chunk.indexOf('\x1F')
-        if (sepIdx === -1) {
-          yield { type: 'text', text: chunk }
-        } else {
-          const before = chunk.slice(0, sepIdx)
-          const after = chunk.slice(sepIdx + 1)
-          if (before) yield { type: 'text', text: before }
-          inTrailer = true
-          trailerBuffer = after
-        }
-      }
-    }
-    // Stream ended. Flush any pending thinking text that didn't make it
-    // out before the throttle window expired.
-    if (pendingThinkingYield) {
-      pendingThinkingYield = false
-      yield { type: 'thinking', text: escapeThinkingTags(thinkingAccum) }
-    }
-    // Parse trailer if present.
-    if (trailerBuffer.length > 0) {
-      try {
-        const meta = JSON.parse(trailerBuffer)
-        if (
-          meta.kind === 'usage' &&
-          (meta.stage === 'end' || meta.stage === 'display')
-        ) {
-          const breakdown =
-            meta.breakdown && typeof meta.breakdown === 'object'
-              ? {
-                  haikuRewriter:
-                    meta.breakdown.haikuRewriter &&
-                    typeof meta.breakdown.haikuRewriter.input === 'number'
-                      ? meta.breakdown.haikuRewriter
-                      : undefined,
-                  haikuClassifier:
-                    meta.breakdown.haikuClassifier &&
-                    typeof meta.breakdown.haikuClassifier.input === 'number'
-                      ? meta.breakdown.haikuClassifier
-                      : undefined,
-                  haikuSummarizer:
-                    meta.breakdown.haikuSummarizer &&
-                    typeof meta.breakdown.haikuSummarizer.input === 'number'
-                      ? meta.breakdown.haikuSummarizer
-                      : undefined,
-                  routedAnswer:
-                    meta.breakdown.routedAnswer &&
-                    typeof meta.breakdown.routedAnswer.model === 'string'
-                      ? meta.breakdown.routedAnswer
-                      : undefined,
-                }
-              : null
-          mergeTurnMeta(metaMapRef, sendIdx, {
-            inputTokens: meta.input_tokens ?? null,
-            outputTokens: meta.output_tokens ?? null,
-            cacheHitRatePct:
-              typeof meta.hit_rate_pct === 'number' ? meta.hit_rate_pct : null,
-            ...(breakdown ? { breakdown } : {}),
-          })
-          bumpMetaTick()
-        }
-      } catch {
-        // Malformed trailer — silently ignore.
-      }
-    }
-  }
-}
-
-/**
- * Merge partial fields into the per-turn meta map. Preserves existing
- * non-null values so a leading frame's data isn't wiped by a later frame
- * that didn't include it.
- */
-function mergeTurnMeta(
-  ref: MutableRefObject<Map<number, ChatTurnMeta>>,
-  sendIdx: number,
-  partial: Partial<ChatTurnMeta>,
-): void {
-  const prev = ref.current.get(sendIdx) ?? createEmptyTurnMeta()
-  const filtered = Object.fromEntries(
-    Object.entries(partial).filter(([, v]) => v !== undefined && v !== null),
-  ) as Partial<ChatTurnMeta>
-  ref.current.set(sendIdx, { ...prev, ...filtered })
-}
-
-// =============================================================================
-// localStorage persistence
-// =============================================================================
-
-const CHAT_STORAGE_VERSION = 1
-
-/** Storage key — includes the proxy-auth impersonation email when
- *  present so each impersonated customer keeps a SEPARATE chat history. */
-const chatStorageKey = (source: DocSource): string => {
-  const base = `mingo-chat-${source}-v${CHAT_STORAGE_VERSION}`
-  const auth = getChatProxyAuth()
-  if (auth?.email) {
-    return `${base}-u-${encodeURIComponent(auth.email.toLowerCase())}`
-  }
-  return base
-}
-
-/** Sweep stale per-user chat-history keys. Drops any key whose email
- *  differs from the CURRENT proxy-auth identity. */
-function pruneStaleChatStorage(source: DocSource): void {
-  if (typeof window === 'undefined') return
-  try {
-    const currentKey = chatStorageKey(source)
-    const prefix = `mingo-chat-${source}-v${CHAT_STORAGE_VERSION}-u-`
-    const legacy = `mingo-chat-${source}-v${CHAT_STORAGE_VERSION}`
-    const toRemove: string[] = []
-    for (let i = 0; i < window.localStorage.length; i++) {
-      const k = window.localStorage.key(i)
-      if (!k) continue
-      if (!k.startsWith(prefix)) continue
-      if (k === currentKey) continue
-      if (k === legacy) continue
-      toRemove.push(k)
-    }
-    for (const k of toRemove) {
-      window.localStorage.removeItem(k)
-    }
-  } catch {
-    // localStorage access blocked (Safari private mode etc.) — non-fatal.
-  }
-}
-
-interface PersistedChatState {
-  messages: Message[]
-  sources: Array<[number, ChatSource[]]>
-  /** Per-turn refs for inline object cards. */
-  refs?: Array<[number, Record<string, ChatRef>]>
-  sendCount: number
-}
-
-function loadPersistedChat(source: DocSource): PersistedChatState | null {
-  if (typeof window === 'undefined') return null
-  try {
-    const raw = window.localStorage.getItem(chatStorageKey(source))
-    if (!raw) return null
-    const parsed = JSON.parse(raw) as PersistedChatState
-    if (!parsed || !Array.isArray(parsed.messages)) return null
-    // Rehydrate Date objects + run forward-compat migrations.
-    for (const m of parsed.messages) {
-      if (typeof m.timestamp === 'string') m.timestamp = new Date(m.timestamp)
-      // Forward-migration for auto-continuation directive bubbles.
-      if (
-        m.role === 'user' &&
-        !m.hidden &&
-        typeof m.content === 'string' &&
-        m.content.startsWith(AUTO_CONTINUATION_DIRECTIVE_PREFIX)
-      ) {
-        m.hidden = true
-      }
-    }
-    return parsed
-  } catch {
-    return null
-  }
-}
-
-function savePersistedChat(source: DocSource, state: PersistedChatState) {
-  if (typeof window === 'undefined') return
-  try {
-    window.localStorage.setItem(chatStorageKey(source), JSON.stringify(state))
-  } catch {
-    // Quota exceeded or private mode — silently drop.
-  }
-}
-
-// =============================================================================
-// useEmbeddedChat — public hook
-// =============================================================================
-
-/**
- * Stream-driven AI chat hook. Returns the message list, send/stop/clear
- * controls, and per-turn metadata (model name, token counts, routing
- * decision) the lib's `<ChatContainer>` consumes.
- *
- * Source identity comes from `useRequiredChatRuntime().source` — no
- * parameter. Throws if `runtime.source` is empty.
+ * Internal lib code should import directly from `./use-sse-chat-adapter`.
+ * This shim will be removed once all external consumers migrate to the
+ * unified `useChat({ mode })` entry point.
  */
-export function useEmbeddedChat(options?: UseEmbeddedChatOptions) {
-  // Chat-specific code REQUIRES a runtime — the lib's `<HubRuntimeProvider>`
-  // (hub) / embedder's provider must wrap the tree.
-  const runtime = useRequiredChatRuntime()
-  const source = runtime.source
-  if (!source) {
-    throw new Error(
-      '[useEmbeddedChat] runtime.source is required — got empty string. ' +
-        'Wire `source` on your <ChatRuntimeContext.Provider value={...}>. ' +
-        'Hub default: <HubRuntimeProvider source={currentPlatform()}>; ' +
-        'embedded apps: pass your own platform/tenant identifier.',
-    )
-  }
-  // Fall back to the lib-baked hub-canonical map when the embedder
-  // didn't supply an override. Keeps Ask + Display working in any
-  // mount that doesn't have a custom documentType registry. Embedders
-  // with polymorphic / per-tenant types pass their own callback and it
-  // wins.
-  const tableIdForDocumentType =
-    options?.tableIdForDocumentType ?? defaultTableIdForDocumentType
-
-  // Restore persisted state once on mount.
-  const persistedRef = useRef<PersistedChatState | null>(null)
-  if (persistedRef.current === null) {
-    pruneStaleChatStorage(source)
-    persistedRef.current =
-      loadPersistedChat(source) || { messages: [], sources: [], sendCount: 0 }
-  }
-
-  const sourcesMapRef = useRef<Map<number, ChatSource[]>>(
-    new Map(persistedRef.current.sources),
-  )
-  const refsMapRef = useRef<Map<number, Record<string, ChatRef>>>(
-    new Map(persistedRef.current.refs ?? []),
-  )
-  const metaMapRef = useRef<Map<number, ChatTurnMeta>>(new Map())
-  const messagesRef = useRef<Message[]>(persistedRef.current.messages)
-  const sendCountRef = useRef(persistedRef.current.sendCount)
-  const [streamingPhase, setStreamingPhase] = useState<StreamingPhase>('idle')
-  const [metaTick, setMetaTick] = useState(0)
-  const bumpMetaTick = useCallback(() => setMetaTick((t) => t + 1), [])
-
-  const streamFn = useMemo(
-    () =>
-      createDocStreamFn(
-        source,
-        {
-          chatStreamUrl: runtime.endpoints.chatStreamUrl,
-          approvalToolUrl: runtime.endpoints.approvalToolUrl,
-        },
-        messagesRef,
-        sourcesMapRef,
-        refsMapRef,
-        metaMapRef,
-        setStreamingPhase,
-        bumpMetaTick,
-        sendCountRef,
-      ),
-    [
-      source,
-      runtime.endpoints.chatStreamUrl,
-      runtime.endpoints.approvalToolUrl,
-      bumpMetaTick,
-    ],
-  )
-
-  // Per-source tableId → slash-command-id lookup. Hydrated from the
-  // commands endpoint on mount. Used by `displayRef` to translate an
-  // inline-card's Display click into a `/<cmd> display "<value>"`
-  // invocation, picking the canonical command for the row's RAG table.
-  const [cmdIdByTableId, setCmdIdByTableId] = useState<Map<string, string>>(
-    () => new Map(),
-  )
-  const commandsUrl = runtime.endpoints.commandsUrl
-  useEffect(() => {
-    let cancelled = false
-    const ctrl = new AbortController()
-    fetchSlashCommands('', ctrl.signal, commandsUrl)
-      .then((commands) => {
-        if (cancelled) return
-        const buckets = new Map<string, SlashCommandSummary[]>()
-        for (const cmd of commands) {
-          if (!cmd.primarySourceId) continue
-          const arr = buckets.get(cmd.primarySourceId) ?? []
-          arr.push(cmd)
-          buckets.set(cmd.primarySourceId, arr)
-        }
-        const map = new Map<string, string>()
-        for (const [tableId, cmds] of buckets) {
-          const display = cmds.find((c) => c.actions.some((a) => a.id === 'display'))
-          const picked =
-            display ??
-            [...cmds].sort((a, b) => {
-              const ao = a.displayOrder ?? Number.POSITIVE_INFINITY
-              const bo = b.displayOrder ?? Number.POSITIVE_INFINITY
-              return ao - bo
-            })[0]
-          if (picked) map.set(tableId, picked.id)
-        }
-        setCmdIdByTableId(map)
-      })
-      .catch((err) => {
-        if (!cancelled && (err as Error)?.name !== 'AbortError') {
-          console.warn(
-            '[useEmbeddedChat] failed to fetch slash commands for displayRef:',
-            err,
-          )
-        }
-      })
-    return () => {
-      cancelled = true
-      ctrl.abort()
-    }
-  }, [source, commandsUrl])
-
-  // Persist on every messages change. Sources + sendCount live in refs,
-  // so we read their current values at write time.
-  const persist = useCallback(
-    (nextMessages: Message[]) => {
-      savePersistedChat(source, {
-        messages: nextMessages,
-        sources: Array.from(sourcesMapRef.current.entries()),
-        refs: Array.from(refsMapRef.current.entries()),
-        sendCount: sendCountRef.current,
-      })
-    },
-    [source],
-  )
-
-  const {
-    messages,
-    isTyping,
-    isStreaming,
-    sendMessage: chatSendMessage,
-    stopMessage: chatStopMessage,
-    clearMessages: chatClearMessages,
-    hasMessages,
-  } = useChat({
-    useMock: false,
-    assistantName: 'Mingo AI',
-    streamFn,
-    initialMessages: persistedRef.current.messages,
-    onMessagesChange: persist,
-  })
-
-  messagesRef.current = messages
-
-  // Index sources/refs/scrollAnchor by USER-SEND count (`sendIdx`), not
-  // by assistant-message count. Each user send produces exactly ONE
-  // refsMapRef entry server-side, but it can produce MULTIPLE assistant
-  // messages on the client (main RAG reply + post-approve card +
-  // auto-continuation prose). Counting USER sends and mapping every
-  // following assistant message to that index keeps the lookup stable.
-  let sendIdx = -1
-  const docMessages: DocChatMessage[] = messages.map((m) => {
-    const segments = Array.isArray(m.content) ? (m.content as MessageSegment[]) : undefined
-    const content =
-      typeof m.content === 'string'
-        ? m.content
-        : Array.isArray(m.content)
-          ? m.content
-              .filter((s) => s.type === 'text')
-              .map((s) => (s as { type: 'text'; text: string }).text)
-              .join('')
-          : ''
-
-    let sources: ChatSource[] | undefined
-    let chatRefs: Record<string, ChatRef> | undefined
-    let scrollAnchor: ScrollAnchor | undefined
-    if (m.role === 'user' && !m.hidden) {
-      sendIdx++
-    }
-    if (m.role === 'assistant') {
-      const lookupIdx = sendIdx >= 0 ? sendIdx : 0
-      sources = sourcesMapRef.current.get(lookupIdx)
-      // The receipt path stamps `chatRefs` directly onto the assistant
-      // message in useChat. Prefer that message-bound copy when present;
-      // falls back to per-turn refs map.
-      chatRefs = m.chatRefs ?? refsMapRef.current.get(lookupIdx)
-      scrollAnchor =
-        (metaMapRef.current.get(lookupIdx)?.scrollAnchor as ScrollAnchor | null) ??
-        undefined
-    }
-
-    return {
-      id: m.id,
-      role: m.role as 'user' | 'assistant',
-      content,
-      ...(segments ? { segments } : {}),
-      ...(sources ? { sources } : {}),
-      ...(chatRefs ? { chatRefs } : {}),
-      ...(scrollAnchor ? { scrollAnchor } : {}),
-      ...(m.hidden ? { hidden: true } : {}),
-    }
-  })
-
-  type SendMessageOptions = StreamFnExtraOptions
-
-  const sendMessage = useCallback(
-    (
-      text: string,
-      options?: SendMessageOptions,
-      messageOptions?: { hidden?: boolean },
-    ) => {
-      sendCountRef.current++
-      setStreamingPhase('thinking')
-      chatSendMessage(text, options, messageOptions)
-    },
-    [chatSendMessage],
-  )
-
-  /**
-   * "Display" callback for inline cards whose registry entry sets
-   * `displayAction: true`. Parallel to `discussRef` but emits a
-   * `/<cmd> display "<title>"` slash command instead of the Discuss
-   * prose. Resolution of the slash command id for the ref's documentType
-   * happens via the `cmdIdByTableId` map hydrated from the commands
-   * endpoint.
-   *
-   * `tableIdForDocumentType` is always defined here — either the
-   * embedder-supplied override OR the lib-baked
-   * `defaultTableIdForDocumentType` fallback. Unknown documentTypes
-   * still short-circuit gracefully via the `tableId === null` check
-   * below.
-   */
-  const displayRef = useCallback(
-    (reference: ChatRef) => {
-      const tableId = tableIdForDocumentType(reference.type)
-      if (!tableId) {
-        console.warn(
-          `[useEmbeddedChat] displayRef: no tableId for documentType="${reference.type}"; ignoring click`,
-        )
-        return
-      }
-      const cmdId = cmdIdByTableId.get(tableId)
-      if (!cmdId) {
-        console.warn(
-          `[useEmbeddedChat] displayRef: no slash command for tableId="${tableId}" source="${source}"; ignoring click`,
-        )
-        return
-      }
-      const refSlug =
-        typeof reference.metadata?.slug === 'string' &&
-        reference.metadata.slug.length > 0
-          ? reference.metadata.slug
-          : ''
-      const queryValue =
-        refSlug || sanitizeTitleForChat(reference.title) || reference.id
-      // Escape `\` BEFORE `"` so a trailing backslash can't smuggle a
-      // close-quote past parsers that honor JS-style escapes. Matches
-      // `formatSingularLookupInvocation`'s pattern in slash-dispatch-utils.
-      const escaped = queryValue
-        .replace(/\\/g, '\\\\')
-        .replace(/"/g, '\\"')
-      const text = `/${cmdId} display "${escaped}"`
-      sendMessage(text)
-    },
-    [sendMessage, source, cmdIdByTableId, tableIdForDocumentType],
-  )
-
-  /**
-   * "Discuss" affordance for ObjectCard. Synthesizes a natural-language
-   * prompt ("Tell me more about <title>"); the structured
-   * `commandOverride.entityIdFilter` is sent server-side via the request
-   * body so retrieval narrows to the named row.
-   *
-   * `tableIdForDocumentType` is always defined here — either the
-   * embedder-supplied override OR the lib-baked default. Unknown
-   * documentTypes still short-circuit via the `tableId === null` check.
-   */
-  const discussRef = useCallback(
-    (reference: ChatRef) => {
-      const tableId = tableIdForDocumentType(reference.type)
-      if (!tableId) {
-        console.warn(
-          `[useEmbeddedChat] discussRef: no tableId for documentType="${reference.type}"; ignoring click`,
-        )
-        return
-      }
-      const refId = (reference.id ?? '').trim()
-      if (!refId) {
-        console.warn(
-          `[useEmbeddedChat] discussRef: empty reference.id for type="${reference.type}"; ignoring click`,
-        )
-        return
-      }
-      // RETRIEVAL IS STRICTLY PRIMARY-KEY-DRIVEN. The visible prose
-      // ("Tell me more about <title>") is UX-only; retrieval narrows
-      // via `entityIdFilter` before the LLM is invoked.
-      const sanitizedTitle = sanitizeTitleForChat(reference.title)
-      const prompt = `Tell me more about ${sanitizedTitle || 'this item'}`
-      sendMessage(prompt, {
-        commandOverride: { entityIdFilter: { tableId, id: refId } },
-      })
-    },
-    [sendMessage, tableIdForDocumentType],
-  )
-
-  const stopMessage = useCallback(() => {
-    chatStopMessage()
-    setStreamingPhase('idle')
-  }, [chatStopMessage])
-
-  const clearMessages = useCallback(() => {
-    sourcesMapRef.current.clear()
-    refsMapRef.current.clear()
-    metaMapRef.current.clear()
-    sendCountRef.current = 0
-    setStreamingPhase('idle')
-    // Force the latestMeta useMemo to recompute with the cleared map.
-    bumpMetaTick()
-    chatClearMessages()
-    // Clear persisted state too so the next mount starts fresh.
-    if (typeof window !== 'undefined') {
-      try {
-        window.localStorage.removeItem(chatStorageKey(source))
-      } catch {}
-    }
-  }, [chatClearMessages, source, bumpMetaTick])
-
-  // Reset to idle whenever both flags drop off.
-  useEffect(() => {
-    if (!isTyping && !isStreaming && streamingPhase !== 'idle') {
-      setStreamingPhase('idle')
-    }
-  }, [isTyping, isStreaming, streamingPhase])
-
-  // Resolve the active turn's metadata.
-  const latestMeta = useMemo(
-    () =>
-      metaMapRef.current.get(sendCountRef.current - 1) ??
-      metaMapRef.current.get(sendCountRef.current - 2) ??
-      null,
-    [metaTick, streamingPhase],
-  )
 
-  return {
-    messages: docMessages,
-    isLoading: isTyping || isStreaming,
-    sendMessage,
-    /** "Discuss" affordance for ObjectCard. */
-    discussRef,
-    /** "Display" counterpart of `discussRef`. */
-    displayRef,
-    stopMessage,
-    clearMessages,
-    streamingPhase,
-    /** Provider key for the lib's `<ModelDisplay>` icon. */
-    currentProvider: latestMeta?.provider ?? null,
-    currentModelLabel: latestMeta?.modelLabel ?? null,
-    currentContextWindowMaxTokens: latestMeta?.contextWindowMaxTokens ?? null,
-    /** Input tokens (known after server's message_start frame; null until). */
-    currentInputTokens: latestMeta?.inputTokens ?? null,
-    /** Output tokens (known only after server's trailing usage frame). */
-    currentOutputTokens: latestMeta?.outputTokens ?? null,
-    /** Cache hit % (read / total-input × 100). null during streaming. */
-    currentCacheHitRatePct: latestMeta?.cacheHitRatePct ?? null,
-    /** Cross-call usage breakdown (Haiku rewriter/classifier/summarizer
-     *  token counts). null until the trailing usage frame lands. */
-    currentUsageBreakdown: latestMeta?.breakdown ?? null,
-  }
-}
+export {
+  useSseChatAdapter as useEmbeddedChat,
+  type UseSseChatAdapterOptions as UseEmbeddedChatOptions,
+  type ChatSource,
+  type DocChatMessage,
+  type DocSource,
+  type ChatTurnMeta,
+  type StreamingPhase,
+} from './use-sse-chat-adapter'