@flamingo-stack/openframe-frontend-core 0.0.488 → 0.0.489

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

@@ -40,17 +40,21 @@
  */
 
 import { useState, useEffect, useCallback, useMemo, useRef, type MutableRefObject } from 'react'
-import { useChat, type Message, type StreamFnExtraOptions } from './use-chat'
+import { useChat, 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 { useSlashCommandRegistry, type SlashCommandSummary } from './use-slash-commands'
-import { getChatProxyAuth } from '../utils/chat-proxy-auth-storage'
 import { chatAuthedFetch } from '../utils/chat-authed-fetch'
+import {
+  createChatConversationStorage,
+  pruneStaleChatConversationStorage,
+  type PersistedChatConversation,
+} from '../utils/chat-conversation-storage'
+import type { LocalStorageAdapter } from '../../../utils/local-storage-adapter'
+import { useChatHistoryHydration } from './use-chat-history-hydration'
 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'
 import type {
@@ -146,6 +150,10 @@ export interface ChatTurnMeta {
   /** Routing decision from the server's `decideRoute`. */
   routedComplexity: string | null
   routedThinkingBudget: number | null
+  /** Server-computed conversation trace id (`chat_conversations.id` for this
+   *  thread), echoed in the leading metadata frame. Stable across turns of
+   *  one thread — the correlation handle for transcripts/analytics. */
+  conversationId: string | null
 }
 
 /**
@@ -199,6 +207,7 @@ function createEmptyTurnMeta(): ChatTurnMeta {
     scrollAnchor: null,
     routedComplexity: null,
     routedThinkingBudget: null,
+    conversationId: null,
   }
 }
 
@@ -215,13 +224,14 @@ function escapeThinkingTags(text: string): string {
 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>,
+  conversationIdRef: MutableRefObject<string | null>,
+  conversationStorage: LocalStorageAdapter<PersistedChatConversation>,
 ) {
   // CRITICAL: the decoder + buffer MUST live INSIDE the returned async-
   // generator function (per-call closure), NOT at the factory level. A
@@ -233,22 +243,6 @@ function createDocStreamFn(
     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
@@ -258,26 +252,30 @@ function createDocStreamFn(
     // 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.
+    //
+    // The server is the single source of conversation history: it re-reads
+    // `chat_messages` by conversation id on every turn. The wire therefore
+    // carries ONLY the new user message — never the prior conversation.
+    // The conversation id is SERVER-minted: the first message of a session
+    // sends none, the server mints one and echoes it in the leading metadata
+    // frame (captured below into `conversationIdRef`), and every later turn
+    // echoes it back.
+    const conversationId = conversationIdRef.current
     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),
-            })),
+          // Always present here — an approval can only happen inside an
+          // established conversation (the proposal turn captured the id).
+          conversationId,
         }
       : {
-          messages: apiMessages,
+          messages: [{ role: 'user', content: message }],
           ...(extra?.commandOverride ? { commandOverride: extra.commandOverride } : {}),
           ...(extra?.pendingAttachments && extra.pendingAttachments.length > 0
             ? { pendingAttachments: extra.pendingAttachments }
             : {}),
+          ...(conversationId ? { conversationId } : {}),
         }
     // `chatAuthedFetch` carries the bearer-act-as headers (+ Supabase
     // session cookies) — same wrapper `use-chat-attachments` and
@@ -489,6 +487,18 @@ function createDocStreamFn(
               })
               bumpMetaTick()
             }
+            // Server-minted conversation id, echoed on every turn. On the
+            // session's FIRST turn this is where the client learns its id —
+            // capture it and persist it so later turns and future visits
+            // continue the same conversation.
+            if (typeof meta.conversationId === 'string' && meta.conversationId) {
+              if (conversationIdRef.current !== meta.conversationId) {
+                conversationIdRef.current = meta.conversationId
+                conversationStorage.save({ conversationId: meta.conversationId })
+              }
+              mergeTurnMeta(metaMapRef, sendIdx, { conversationId: meta.conversationId })
+              bumpMetaTick()
+            }
             const parsedAnchor = parseScrollAnchor(meta.scrollAnchor)
             if (parsedAnchor !== null) {
               mergeTurnMeta(metaMapRef, sendIdx, { scrollAnchor: parsedAnchor })
@@ -587,94 +597,25 @@ function mergeTurnMeta(
 }
 
 // =============================================================================
-// localStorage persistence
+// Local persistence — the server-issued conversation id ONLY
 // =============================================================================
+//
+// The ONLY thing persisted locally is the conversation id the SERVER minted
+// and echoed in the leading metadata frame of the session's first turn.
+// The client never generates ids. Message history lives server-side in
+// `chat_conversations` / `chat_messages` (recorded turn-by-turn by the chat
+// route) and is rehydrated on mount via `GET <chatStreamUrl>/history`.
+// localStorage never stores messages, sources, refs, or send counts —
+// the server transcript is the single source of truth for history.
 
-const CHAT_STORAGE_VERSION = 1
-
-/** localStorage history namespace used when no `source` is configured on the
+/** localStorage namespace used when no `source` is configured on the
  *  runtime. Embedders are platform-agnostic (see `ChatRuntime.source`), so any
  *  stable string works here — the hub passes its real platform instead. */
 const DEFAULT_CHAT_SOURCE = 'embed'
 
-/** 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.
-  }
-}
+// Persistence itself lives in `../utils/chat-conversation-storage.ts` (built
+// on the lib-standard `createLocalStorageAdapter`); the mount-time history
+// rebuild lives in `./use-chat-history-hydration.ts`.
 
 // =============================================================================
 // useSseChatAdapter — public hook
@@ -698,10 +639,10 @@ export function useSseChatAdapter(
   // (hub) / embedder's provider must wrap the tree.
   const runtime = useRequiredChatRuntime()
   // `source` is OPTIONAL — embedders are platform-agnostic (see ChatRuntime.source).
-  // Here it's used ONLY for the localStorage history namespace + client-side meta
-  // labels; it is NEVER sent on the wire (the hub resolves source server-side via
-  // currentPlatform()). Fall back to a stable constant so the persistence key stays
-  // well-formed when the embedder leaves source unset.
+  // Here it's used ONLY for the conversation-id localStorage namespace + client-side
+  // meta labels; it is NEVER sent on the wire (the hub resolves source server-side
+  // via currentPlatform()). Fall back to a stable constant so the persistence key
+  // stays well-formed when the embedder leaves source unset.
   const source = runtime.source || DEFAULT_CHAT_SOURCE
   // Fall back to the lib-baked hub-canonical map when the embedder
   // didn't supply an override. Keeps Ask + Display working in any
@@ -711,23 +652,24 @@ export function useSseChatAdapter(
   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 }
+  // Restore the server-issued conversation id once on mount. Null = no
+  // conversation yet — the FIRST send goes out without an id, the server
+  // mints one, and the metadata-frame capture (in the stream fn) stores it.
+  // The client NEVER generates ids. This is the ONLY local persistence —
+  // message history hydrates from the server transcript below.
+  const conversationStorage = useMemo(() => createChatConversationStorage(source), [source])
+  const conversationIdRef = useRef<string | null>(null)
+  const restoredConversationRef = useRef(false)
+  if (!restoredConversationRef.current) {
+    restoredConversationRef.current = true
+    pruneStaleChatConversationStorage(source)
+    conversationIdRef.current = conversationStorage.load()?.conversationId ?? null
   }
 
-  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 sourcesMapRef = useRef<Map<number, ChatSource[]>>(new Map())
+  const refsMapRef = useRef<Map<number, Record<string, ChatRef>>>(new Map())
   const metaMapRef = useRef<Map<number, ChatTurnMeta>>(new Map())
-  const messagesRef = useRef<Message[]>(persistedRef.current.messages)
-  const sendCountRef = useRef(persistedRef.current.sendCount)
+  const sendCountRef = useRef(0)
   const [streamingPhase, setStreamingPhase] = useState<StreamingPhase>('idle')
   const [metaTick, setMetaTick] = useState(0)
   const bumpMetaTick = useCallback(() => setMetaTick((t) => t + 1), [])
@@ -740,19 +682,21 @@ export function useSseChatAdapter(
           chatStreamUrl: runtime.endpoints.chatStreamUrl,
           approvalToolUrl: runtime.endpoints.approvalToolUrl,
         },
-        messagesRef,
         sourcesMapRef,
         refsMapRef,
         metaMapRef,
         setStreamingPhase,
         bumpMetaTick,
         sendCountRef,
+        conversationIdRef,
+        conversationStorage,
       ),
     [
       source,
       runtime.endpoints.chatStreamUrl,
       runtime.endpoints.approvalToolUrl,
       bumpMetaTick,
+      conversationStorage,
     ],
   )
 
@@ -792,20 +736,6 @@ export function useSseChatAdapter(
     return map
   }, [slashCommands])
 
-  // 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,
@@ -813,16 +743,32 @@ export function useSseChatAdapter(
     sendMessage: chatSendMessage,
     stopMessage: chatStopMessage,
     clearMessages: chatClearMessages,
+    hydrateMessages,
     hasMessages,
   } = useChat({
     useMock: false,
     assistantName: 'Mingo AI',
     streamFn,
-    initialMessages: persistedRef.current.messages,
-    onMessagesChange: persist,
   })
 
-  messagesRef.current = messages
+  // ─── Server hydration (history SSOT) ───
+  // Mount-time rebuild of the message list from the server transcript — the
+  // single store of conversation history. Extracted to its own hook; see
+  // `use-chat-history-hydration.ts` for the full contract + failure
+  // semantics (a miss starts the UI empty, never loses server context).
+  const historyUrl =
+    runtime.endpoints.chatHistoryUrl ??
+    `${runtime.endpoints.chatStreamUrl.replace(/\/+$/, '')}/history`
+  const { isHydratingHistory, hydratedKeyRef } = useChatHistoryHydration({
+    active,
+    source,
+    historyUrl,
+    conversationIdRef,
+    refsMapRef,
+    sendCountRef,
+    hydrateMessages,
+    bumpMetaTick,
+  })
 
   // Index sources/refs/scrollAnchor by USER-SEND count (`sendIdx`), not
   // by assistant-message count. Each user send produces exactly ONE
@@ -1008,17 +954,17 @@ export function useSseChatAdapter(
     refsMapRef.current.clear()
     metaMapRef.current.clear()
     sendCountRef.current = 0
+    // New chat = drop the stored conversation id. The old row stays frozen
+    // server-side; the NEXT send goes out id-less and the server mints a
+    // fresh conversation (echoed back and re-captured then).
+    conversationIdRef.current = null
+    conversationStorage.clear()
+    hydratedKeyRef.current = null
     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])
+  }, [chatClearMessages, conversationStorage, hydratedKeyRef, bumpMetaTick])
 
   // Reset to idle whenever both flags drop off.
   useEffect(() => {
@@ -1047,6 +993,8 @@ export function useSseChatAdapter(
     stopMessage,
     clearMessages,
     streamingPhase,
+    /** True while the mount-time rebuild from the server transcript runs. */
+    isHydratingHistory,
     /** Provider key for the lib's `<ModelDisplay>` icon. */
     currentProvider: latestMeta?.provider ?? null,
     currentModelLabel: latestMeta?.modelLabel ?? null,
@@ -1061,12 +1009,11 @@ export function useSseChatAdapter(
      *  token counts). null until the trailing usage frame lands. */
     currentUsageBreakdown: latestMeta?.breakdown ?? null,
     // ─── Dialog management — stubs for v1 ────────────────────────────────
-    // Guide mode currently keeps its history in `localStorage` opaquely
-    // under the hood (`runtime.source` namespaced key). Surfacing that
-    // history as a structured dialog list is a follow-up; for now the
-    // shape is satisfied with empty defaults so the unified contract
-    // type-checks and EmbeddableChat hides sidebar affordances when
-    // `dialogs.length === 0`.
+    // Guide mode keeps ONE server-side conversation per stored id
+    // (`chat_conversations`, hydrated on mount). Surfacing multiple threads
+    // as a structured dialog list is a follow-up; for now the shape is
+    // satisfied with empty defaults so the unified contract type-checks and
+    // EmbeddableChat hides sidebar affordances when `dialogs.length === 0`.
     dialogs: SSE_EMPTY_DIALOGS,
     activeDialogId: null,
     selectDialog: noopSelectDialog,

package/src/components/chat/types/unified-chat-state.types.ts

@@ -251,6 +251,12 @@ export interface UnifiedChatState {
   /** Granular phase for the "Thinking..."/"Streaming..." status row above input. */
   streamingPhase: StreamingPhase
 
+  /** True while the adapter is rebuilding the message list from the
+   *  server-side transcript store (SSE/Guide mount-time hydration). Optional —
+   *  transports without server hydration (NATS manages its own dialog
+   *  loading) never set it. */
+  isHydratingHistory?: boolean
+
   // ─── Actions ──────────────────────────────────────────────────────────────
   sendMessage: (
     text: string,

package/src/components/chat/utils/chat-conversation-storage.ts

@@ -0,0 +1,83 @@
+/**
+ * Chat conversation-id persistence — the SSE/Guide chat's ONLY local state.
+ *
+ * The stored value is the SERVER-minted conversation id echoed in the chat
+ * stream's leading metadata frame; the client never generates ids. Message
+ * history itself lives server-side (`chat_conversations` / `chat_messages`)
+ * and is rehydrated via the history endpoint — see
+ * `use-chat-history-hydration.ts`.
+ *
+ * Built on the lib-standard `createLocalStorageAdapter` (SSR guard,
+ * try/catch, quota-failure logging, dynamic namespacing) instead of raw
+ * `window.localStorage`. The namespace resolver runs on EVERY read/write, so
+ * a proxy-auth identity switch mid-page automatically re-partitions the key.
+ *
+ * Key shape: `mingo-chat-<source>[-u-<email>].conversation`
+ */
+
+import {
+  createLocalStorageAdapter,
+  type LocalStorageAdapter,
+} from '../../../utils/local-storage-adapter'
+import { getChatProxyAuth } from './chat-proxy-auth-storage'
+
+export interface PersistedChatConversation {
+  conversationId: string
+}
+
+const STORAGE_KEY = 'conversation'
+
+const namespaceFor = (source: string): string => {
+  const base = `mingo-chat-${source}`
+  const auth = getChatProxyAuth()
+  return auth?.email ? `${base}-u-${encodeURIComponent(auth.email.toLowerCase())}` : base
+}
+
+/** One adapter per chat `source` (= platform). Memoize per mount. */
+export function createChatConversationStorage(
+  source: string,
+): LocalStorageAdapter<PersistedChatConversation> {
+  return createLocalStorageAdapter<PersistedChatConversation>({
+    key: STORAGE_KEY,
+    namespace: () => namespaceFor(source),
+    validate: (parsed): parsed is PersistedChatConversation =>
+      !!parsed &&
+      typeof (parsed as PersistedChatConversation).conversationId === 'string' &&
+      (parsed as PersistedChatConversation).conversationId.length > 0,
+    logTag: '[chat-conversation-storage]',
+  })
+}
+
+/**
+ * Sweep THIS source's stale keys: the other-identity variants (base vs
+ * impersonation), and retired key shapes from before the server-minted-id
+ * design (raw `mingo-chat-<source>` and versioned `-v1`/`-v2` full-history
+ * stores). Boundary-aware: a hyphen-extended sibling source (`flamingo` vs
+ * `flamingo-teaser`) is NOT this source's namespace and must never be swept.
+ *
+ * Raw storage enumeration is unavoidable here — the adapter abstraction is
+ * per-key and Web Storage only exposes iteration on the raw object.
+ */
+export function pruneStaleChatConversationStorage(source: string): void {
+  if (typeof window === 'undefined') return
+  try {
+    const base = `mingo-chat-${source}`
+    const currentKey = `${namespaceFor(source)}.${STORAGE_KEY}`
+    const ownedKey = (k: string) =>
+      k === base || // retired raw key (pre-adapter shape)
+      k === `${base}.${STORAGE_KEY}` || // current no-identity shape
+      k.startsWith(`${base}-u-`) || // per-identity shapes (current + retired)
+      k.startsWith(`${base}-v`) // retired versioned full-history shapes
+    const toRemove: string[] = []
+    for (let i = 0; i < window.localStorage.length; i++) {
+      const k = window.localStorage.key(i)
+      if (!k) continue
+      if (ownedKey(k) && k !== currentKey) toRemove.push(k)
+    }
+    for (const k of toRemove) {
+      window.localStorage.removeItem(k)
+    }
+  } catch {
+    // localStorage access blocked (Safari private mode etc.) — non-fatal.
+  }
+}

package/src/contexts/chat-runtime-context.tsx

@@ -57,6 +57,14 @@ export interface ChatRuntime {
     listEngagementsUrl?: string
     /** GET slash-command catalog. Hub: '/api/docs/commands'. */
     commandsUrl: string
+    /** GET server-side conversation history (`?conversationId=<id>`) — the
+     *  chat panel's mount-time hydration read against the server transcript
+     *  store (localStorage keeps only the server-issued conversation id).
+     *  OPTIONAL — defaults to `<chatStreamUrl>/history`, which is correct for
+     *  same-origin hosts AND for reverse-proxy embedders (the proxied chat
+     *  prefix covers it). Set explicitly only when the history route lives
+     *  elsewhere. */
+    chatHistoryUrl?: string
     /** GET RAG-search endpoint behind `<DocSearchBar>` (the in-source search
      *  bar mounted by `<DocViewer>` / `<DocsHubPage>` when `showAIChat` is on).
      *  Hub: '/api/docs/search'. OPTIONAL — falls back to the hub path so

package/dist/chunk-2B6773QM.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-2B6773QM.cjs","../src/contexts/endpoints-runtime-context.tsx","../src/contexts/chat-runtime-context.tsx"],"names":["createContext","useContext"],"mappings":"AAAA,qFAAY;AACZ;AACA;ACqBA,8BAA0C;AAenC,IAAM,wBAAA,EAA0B,kCAAA,IAA2C,CAAA;AAO3E,SAAS,mBAAA,CAAA,EAA+C;AAC7D,EAAA,OAAO,+BAAA,uBAAkC,CAAA;AAC3C;AASO,SAAS,2BAAA,CAAA,EAAgD;AAC9D,EAAA,MAAM,EAAA,EAAI,+BAAA,uBAAkC,CAAA;AAC5C,EAAA,GAAA,CAAI,CAAC,CAAA,EAAG;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,IAIF,CAAA;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;ADlDA;AACA;AEiBA;AA0MO,IAAM,mBAAA,EAAqBA,kCAAAA,IAAsC,CAAA;AAQjE,SAAS,cAAA,CAAA,EAAqC;AACnD,EAAA,OAAOC,+BAAAA,kBAA6B,CAAA;AACtC;AAUO,SAAS,sBAAA,CAAA,EAAsC;AACpD,EAAA,MAAM,EAAA,EAAIA,+BAAAA,kBAA6B,CAAA;AACvC,EAAA,GAAA,CAAI,CAAC,CAAA,EAAG;AACN,IAAA,MAAM,IAAI,KAAA;AAAA,MACR;AAAA,IAMF,CAAA;AAAA,EACF;AACA,EAAA,OAAO,CAAA;AACT;AF7OA;AACA;AACE;AACA;AACA;AACA;AACA;AACA;AACF,mUAAC","file":"/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-2B6773QM.cjs","sourcesContent":[null,"'use client'\n\n/**\n * Endpoints runtime — sibling of ChatRuntime. Carries the API path\n * literals consumed by oss-lib components/hooks/utils so a host\n * application can override them (e.g. when running behind a reverse\n * proxy as `user1.openframe.ai` → `/api/mingo-guide/*`).\n *\n * The hub mounts `<HubRuntimeProvider>` at root with the\n * canonical hub paths; an embedded app mounts its own provider with\n * remapped paths. The pattern mirrors ChatRuntimeContext exactly:\n *\n *   - `useEndpointsRuntime()` returns null when no provider is mounted.\n *     For optional consumers that should gracefully no-op without one.\n *   - `useRequiredEndpointsRuntime()` throws on missing provider — for\n *     hooks/components that cannot function without endpoints.\n *\n * IMPORTANT for embedders: memoize the value passed to\n * `<EndpointsRuntimeContext.Provider value={...}>` (e.g. React.useMemo).\n * Reference changes invalidate downstream effect dependency arrays and\n * trigger unnecessary re-fetches.\n */\n\nimport { createContext, useContext } from 'react'\n\nexport interface EndpointsRuntime {\n  /** GET active announcement (used by `<AnnouncementBar>` mount fetch + refocus revalidation). */\n  announcementsUrl: string\n  accessCode: {\n    /** POST validate access code. */\n    validateUrl: string\n    /** POST consume / redeem access code after registration. */\n    consumeUrl: string\n  }\n  /** POST contact-form submission. */\n  contactUrl: string\n}\n\nexport const EndpointsRuntimeContext = createContext<EndpointsRuntime | null>(null)\n\n/**\n * Optional read — returns null when no provider is mounted. Use for\n * surfaces that should silently skip the fetch (e.g. announcement\n * polling on a page rendered outside the provider tree).\n */\nexport function useEndpointsRuntime(): EndpointsRuntime | null {\n  return useContext(EndpointsRuntimeContext)\n}\n\n/**\n * Strict variant — throws on missing provider. Use for consumers that\n * cannot function without an endpoint (form submission, code\n * validation). In tests/Storybook, wrap with the hub's\n * `<HubRuntimeProvider>` or a stub\n * `<EndpointsRuntimeContext.Provider value={mockedEndpoints}>`.\n */\nexport function useRequiredEndpointsRuntime(): EndpointsRuntime {\n  const v = useContext(EndpointsRuntimeContext)\n  if (!v) {\n    throw new Error(\n      '[endpoints-runtime] hook called outside an <EndpointsRuntimeContext.Provider>. ' +\n        'Hub: mount <HubRuntimeProvider> in your providers tree. ' +\n        'Embedded app: mount your own provider with proxied URLs at the tree root. ' +\n        'Tests/Storybook: wrap render() in <EndpointsRuntimeContext.Provider value={mocked}>.',\n    )\n  }\n  return v\n}\n","'use client'\n\n/**\n * Chat runtime context — single seam for embedding the chat panel in a\n * different host (e.g. user1.openframe.ai reverse-proxying API calls\n * under /api/mingo-guide/* to hub.openframe.ai/api/*).\n *\n * Three concerns, one context:\n *   1. API endpoints: chatStreamUrl / approvalToolUrl / commandsUrl /\n *      buildListUrl + attachment endpoints + chat-identity. The chat\n *      reads them from runtime; hub vs embedded app supply different\n *      strings via different providers.\n *   2. Navigation mode + callbacks: 'host' or 'embed' mode. Host wires\n *      its own router/docNav via the optional `navigate` callback\n *      (plain function, NOT a hook); embed forces new-tab via\n *      `defaultContentOrigin` + lib's `resolveExternalNavigation`.\n *   3. Identity context: only `source` (required for localStorage\n *      namespacing). The display identity (greeting first-name etc.)\n *      comes from the server via `useChatIdentity()` — never injected\n *      client-side, so it always matches the server-resolved auth.\n *\n * Sibling of EndpointsRuntimeContext (announcement bar, contact form,\n * access codes). Each runtime stays an independent React context so\n * embedders can opt into either feature without forcing the other.\n *\n * IMPORTANT for embedders: memoize the value passed to\n * `<ChatRuntimeContext.Provider value={...}>` (e.g. via React.useMemo).\n * Every change to its reference identity invalidates downstream\n * `useMemo` consumers (the chat input's slash-commands binding,\n * useNavLink's embed-resolution memo, useDocChat's streamFn factory).\n * The hub's `<HubRuntimeProvider>` already memoizes correctly with\n * stable deps. Embedded apps that build the value inline on each render\n * will pay an avoidable re-render cost across the entire chat tree.\n */\n\nimport { createContext, useContext, type ReactNode } from 'react'\n\nimport type { ComposeContentUrl } from '../utils/content-href'\n\n/**\n * Runtime config consumed by the chat panel.\n */\nexport interface ChatRuntime {\n  endpoints: {\n    /** POST streaming chat. Hub: '/api/docs/chat'. */\n    chatStreamUrl: string\n    /** POST agent approve/reject. Hub: '/api/chat/agent/confirm-tool'. */\n    approvalToolUrl: string\n    /** Customer-ticket agent endpoints (Help Center). OPTIONAL — when unset,\n     *  the ticket hooks fall back to the bare hub paths\n     *  (`/api/chat/agent/{find-ticket,ticket-action,list-engagements}`).\n     *  Embedders behind a reverse proxy set these to their proxied paths\n     *  (e.g. `/content/api/chat/agent/...`) so tickets route through the SAME\n     *  endpoint config + proxy as every other endpoint. */\n    findTicketUrl?: string\n    ticketActionUrl?: string\n    listEngagementsUrl?: string\n    /** GET slash-command catalog. Hub: '/api/docs/commands'. */\n    commandsUrl: string\n    /** GET RAG-search endpoint behind `<DocSearchBar>` (the in-source search\n     *  bar mounted by `<DocViewer>` / `<DocsHubPage>` when `showAIChat` is on).\n     *  Hub: '/api/docs/search'. OPTIONAL — falls back to the hub path so\n     *  same-origin Next.js hosts don't need to set it. Cross-origin embedders\n     *  set their proxied path so the search bar routes through the same\n     *  reverse proxy as everything else. Same pattern as `findTicketUrl`. */\n    docsSearchUrl?: string\n    /** POST internal-link resolver. The in-source markdown renderer (lib or\n     *  custom) calls `<DocViewer>`'s `handlers.onResolveLink(href, currentPath)`\n     *  for relative hrefs like `./getting-started/intro.md` — that callback\n     *  posts to this URL with `{ link, currentPath, source }` and expects a\n     *  `ResolveLinkResult` back. Hub: '/api/docs/resolve-link'. OPTIONAL — same\n     *  fall-back chain as `docsSearchUrl`: prop override → runtime → default. */\n    docsResolveLinkUrl?: string\n    /** GET per-platform empty-state config (admin-edited in\n     *  `/admin/chat-config`): `{ greeting, enabledRagTableIds, suggestedQueries }`.\n     *  Hub: '/api/docs/empty-state'. OPTIONAL — the in-app (host-mode) chat\n     *  injects these values as SSR props instead, so it leaves this unset.\n     *  Cross-origin EMBEDDERS (no server hop) set it to their proxied path\n     *  (e.g. '/content/api/docs/empty-state') so `<EmbeddableChat>` can fetch\n     *  the greeting / quick-action chips / RAG-source filter at runtime. When\n     *  unset, the chat falls back to the explicit `emptyStateGreeting` /\n     *  `suggestedQueries` / `enabledRagTableIds` props (or in-code defaults). */\n    emptyStateUrl?: string\n    /** Build the per-agent display-config URL for an OpenFrame AI agent\n     *  (Fae/Mingo). OPTIONAL. The returned endpoint MUST be byte-compatible\n     *  with the empty-state wire shape ({ greeting, suggestedQueries,\n     *  enabledRagTableIds }). When set AND `EmbeddableChat` receives an\n     *  `activeAgentSlug` in embed mode, the chat fetches THIS url instead of\n     *  `emptyStateUrl` to render the selected agent's greeting + suggested\n     *  prompts (the \"agent mode\" URL override). Hub: `(slug) =>\n     *  '/api/ai-agents/' + encodeURIComponent(slug)`. */\n    aiAgentConfigUrl?: (slug: string) => string\n    /** Build entity-card list URL for a content type + ids. Hub delegates\n     *  to the rag-table-config registry; embedded app provides its own\n     *  per-type URL builder against the reverse proxy. Returns null when\n     *  the type has no list endpoint (caller skips rendering). */\n    buildListUrl: (type: string, ids: string[]) => string | null\n    /** Chat-attachment endpoints — added for the v2 attachment feature.\n     *\n     *  Three concerns:\n     *    - `attachmentUploadUrl` — POSTed by the chat-attachment hook\n     *      to mint a Supabase signed-upload-URL + HMAC view token.\n     *    - `attachmentViewUrlPrefix` — embedded in markdown URLs the\n     *      chat hosts in user message bubbles (`![]()` / `[Attached]`).\n     *      Stored in chat history; chosen at SEND time. In host mode the\n     *      relative `/api/storage/view/chat-attachments/` is sufficient\n     *      (same-origin); embedders supply an absolute hub URL so the\n     *      browser can fetch cross-origin.\n     *    - `identityUrl` — GET endpoint the `useChatIdentity` hook\n     *      hits to learn the `{authTier, source, attachmentsEnabled}`\n     *      capability bag for the current session. Used beyond chat\n     *      (tickets / contact form / any embedded surface that needs\n     *      to identify the proxied customer), so the name has no\n     *      \"chat\" prefix even though the consuming hook still does. */\n    attachmentUploadUrl: string\n    attachmentViewUrlPrefix: string\n    identityUrl: string\n    /** Optional URL prefix for the image proxy (`<prefix>?url=<external>`).\n     *  When unset, lib's `getProxiedImageUrl` returns the original URL\n     *  unchanged. Hub default: '/api/image-proxy'. Embedders that don't\n     *  host an image-proxy route leave this undefined → images load\n     *  directly cross-origin (CORS-permitting). */\n    imageProxyUrlPrefix?: string\n    /** Optional list of hostnames that should bypass the image proxy\n     *  (rendered direct). Hub uses ['openmsp.ai']; embedders typically\n     *  leave it unset. Matches the `skipDomains` parameter of\n     *  `getProxiedImageUrl`. */\n    imageProxySkipDomains?: string[]\n    /** Optional base URL for the branded og-placeholder image route — the\n     *  DEFAULT cover-image fallback for entity cards with no image. The lib\n     *  appends `?title=…` (+ `w`/`h` for square slots) itself, so this is\n     *  the base, NOT a full URL: relative (`/api/og-placeholder`) for same-\n     *  origin hosts, or the proxied path (`/content/api/og-placeholder`) for\n     *  cross-origin embedders. May carry baked-in query params (preserved when\n     *  the lib layers `title`/dimensions on top) — but per-platform brand\n     *  colors are NO LONGER baked here; the `/api/og-placeholder` route\n     *  resolves them server-side from the platform. Most hosts leave this unset\n     *  and let the lib derive the base from `imageProxyUrlPrefix`.\n     *\n     *  OPTIONAL — when unset the lib derives the base from the sibling\n     *  `imageProxyUrlPrefix` (same API base, route name swapped), then falls\n     *  back to the relative `/api/og-placeholder`. So an embedder that already\n     *  proxies images needs NO og-placeholder wiring. See\n     *  `resolveOgPlaceholderBase` / `buildOgPlaceholderUrl` in `../utils`. */\n    ogPlaceholderUrl?: string\n    /** Supabase storage origin (e.g. `https://xyz.supabase.co`) — used\n     *  by `useVideoWarmup` to scope the `<link rel=\"preload\" as=\"video\">`\n     *  hint to MP4s the deployment actually hosts. Hub wires it via\n     *  `getSupabaseStorageOrigin()`; embedders without a Supabase\n     *  storage origin leave it unset (preload is then skipped; Mux/\n     *  YouTube preconnect still fires). */\n    supabaseStorageOrigin?: string\n  }\n  navigation: {\n    /** ONE knob, two behaviors:\n     *  - 'host' = use the host page's existing click-routing untouched.\n     *    The chat panel calls `navigate?.()` for in-app routing.\n     *  - 'embed' = guest inside another app: short-circuit at the top\n     *    of click handlers to force new-tab + absolutize via\n     *    resolveExternalNavigation. */\n    mode: 'host' | 'embed'\n    /** Embed-only fallback origin for relative URLs whose target platform\n     *  can't be inferred. Used by resolveExternalNavigation when\n     *  `targetPlatform` is null — without this, a relative `/foo` href would\n     *  window.open against the embedder's origin, which is WRONG.\n     *  Set to your content host (e.g. 'https://hub.openframe.ai').\n     *  Required by the embedded app whenever mode='embed'. */\n    defaultContentOrigin?: string\n    /** Override for opening external URLs. MUST BE SYNCHRONOUS —\n     *  Safari/Firefox block popups opened outside a direct user gesture.\n     *  Default: window.open(href, '_blank', 'noopener,noreferrer'). */\n    openExternal?: (href: string) => void\n    /** Optional in-app navigation callback (host-mode only).\n     *  Returns `true` if the host handled the click in-app\n     *  (router.push + docNav.navigate); returns `false`, `undefined`,\n     *  or `void` → lib falls back to window.location.assign(href).\n     *  Hub wires this via HubRuntimeProvider's HubNavigationWiring;\n     *  embedders not in Next.js leave it undefined. */\n    navigate?: (input: { href: string; path?: string | null; targetPlatform?: string | null }) => boolean | void\n    /** Optional new-tab decision callback. Returns true → lib opens in\n     *  new tab; false → same tab via `navigate`. Hub wires the existing\n     *  `decideNewTab` logic from use-nav-link.tsx (re-imports the pure\n     *  helper from lib). Embedders may omit; lib defaults to:\n     *  same-origin/same-platform → same tab, else new tab. */\n    decideNewTab?: (args: { href: string; targetPlatform?: string | null }) => boolean\n  }\n  /** Optional content-URL composer. Returns the platform-aware href +\n   *  target-platform tuple for a content entity. Hub wires this to its\n   *  `buildContentURL(type, slug, extractPrimaryPlatform(platforms))`\n   *  pipeline so the lib catalog/detail views can derive cross-\n   *  platform hrefs without knowing the hub's platform topology\n   *  (openmsp.ai / openframe.app / flamingo.run / tmcg).\n   *\n   *  THE single content-href authority for every embeddable surface — page\n   *  views (onboarding catalog/detail, releases) AND chat cards / chips /\n   *  search results all resolve content links through this one seam, so a\n   *  given type lands in the SAME place regardless of where it's rendered.\n   *  Embedders wire `makeComposeContentUrl({ hostedTypes, contentOrigin })`;\n   *  omit it and lib views fall back to a same-origin relative path\n   *  (`buildDefaultHref`).\n   *\n   *  Takes a single `ComposeContentUrlInput`: `type` + `identifier` (page\n   *  views pass the slug; chat rows pass the id + `externalUrl`, whose path\n   *  yields the slug for in-app routing) + optional `platforms` /\n   *  `externalUrl` / `targetPlatform`. */\n  composeContentUrl?: ComposeContentUrl\n  /** Per-`documentType` doc-viewer targets — the UNIFIED, DYNAMIC replacement for\n   *  the single `chipBasePlatform` prop. Maps a doc-table documentType\n   *  (`'markdown'`, `'data_room_doc'`, …) → `{ platform, basePath }` for the PUBLIC\n   *  doc viewer that hosts it. Doc chips with no `externalUrl` resolve PER ROW to\n   *  `getBaseUrl(platform)/<basePath>/<path>`, so a chat mixing several doc sources\n   *  sends EACH to its own home (markdown→flamingo/knowledge-base,\n   *  data_room_doc→company-hub/data-room) instead of one static fallback. The hub\n   *  may keep using `chipBasePlatform` (one doc source per platform); embedders that\n   *  surface multiple doc sources wire this. Threaded into `resolveSourceRowCTA`. */\n  docPlatformTargets?: Record<string, { platform: string; basePath: string }>\n  /** Chat source / platform identifier — OPTIONAL. The hub sets it from\n   *  `currentPlatform()`; EMBEDDERS leave it unset and stay platform-agnostic.\n   *\n   *  It is NOT required for chat to work. The wire resolves source server-side\n   *  (`/docs/chat|search|commands` reject any client `source`); the\n   *  same-tab-vs-new-tab link decision falls back to an origin comparison when\n   *  it's absent (`decideNewTab` → `isCrossOriginUrl`); and the localStorage\n   *  history namespace falls back to a stable constant. Set it only where the\n   *  client legitimately needs to know its platform a priori — i.e. the hub,\n   *  where several platforms share related origins so \"same platform\" can't be\n   *  inferred from a URL alone. */\n  source?: string\n  // NOTE: No `user` field. The chat's display identity (greeting\n  // first-name, etc.) comes from the SERVER-resolved auth via\n  // `useChatIdentity()` — the same identity the server uses to\n  // authorize requests. Letting embedders pass a client-side `user`\n  // would let it desync from the actual auth tier, causing greetings\n  // like \"Hey Bob\" while the server treats the session as\n  // alice@example.com. Single source of truth: the server.\n}\n\nexport const ChatRuntimeContext = createContext<ChatRuntime | null>(null)\n\n/**\n * Returns the active runtime, or null when no provider is mounted.\n * NULL is a first-class value — it signals \"no chat runtime configured.\"\n * Optional consumers fall back to no-op behavior; strict consumers\n * use `useRequiredChatRuntime` (below).\n */\nexport function useChatRuntime(): ChatRuntime | null {\n  return useContext(ChatRuntimeContext)\n}\n\n/**\n * Strict variant used INSIDE the chat panel. Throws if no provider.\n * The hub guarantees one exists by mounting `<HubRuntimeProvider>` at\n * root; the embedded app mounts its own `<ChatRuntimeContext.Provider>`\n * at the tree root. In Jest / Storybook tests that render chat\n * internals directly, wrap with `<HubRuntimeProvider>` (hub defaults)\n * or supply `<ChatRuntimeContext.Provider value={mockedRuntime}>`.\n */\nexport function useRequiredChatRuntime(): ChatRuntime {\n  const v = useContext(ChatRuntimeContext)\n  if (!v) {\n    throw new Error(\n      '[chat-runtime] hook called outside a <ChatRuntimeContext.Provider>. ' +\n        'The hub mounts <HubRuntimeProvider> at root — this only fires when ' +\n        'chat internals are rendered above the provider tree. ' +\n        'Fix: ensure the rendering subtree descends from the runtime provider. ' +\n        'In tests/Storybook: wrap with <HubRuntimeProvider> or supply ' +\n        'a <ChatRuntimeContext.Provider value={mockedRuntime}>.',\n    )\n  }\n  return v\n}\n"]}