@flamingo-stack/openframe-frontend-core 0.0.210 → 0.0.212-snapshot.20260528112413

package/src/nats/shared-connection.ts

@@ -0,0 +1,285 @@
+import { createNatsClient, type NatsClient, type NatsStatus, type NatsStatusEvent } from './nats'
+
+export const NATS_DEFAULTS = {
+  SHARED_CLOSE_DELAY_MS: 3000,
+  CONNECT_TIMEOUT_MS: 10_000,
+  PING_INTERVAL_MS: 30_000,
+  MAX_PING_OUT: 3,
+  RETRY_INITIAL_DELAY_MS: 1000,
+  RETRY_MAX_DELAY_MS: 30_000,
+  RETRY_MULTIPLIER: 2,
+} as const
+
+export interface NatsReconnectionBackoff {
+  /** Number of fast retries before exponential phase kicks in. Default: 0. */
+  fastRetries?: number
+  /** Delay used during the fast-retry phase. Default: RETRY_INITIAL_DELAY_MS. */
+  fastRetryDelayMs?: number
+  /** Base delay for the exponential phase. Default: RETRY_INITIAL_DELAY_MS. */
+  initialDelayMs?: number
+  /** Upper cap on any single retry delay. Default: RETRY_MAX_DELAY_MS. */
+  maxDelayMs?: number
+  /** Per-attempt multiplier during exponential phase. Default: RETRY_MULTIPLIER. */
+  multiplier?: number
+}
+
+export interface SharedConnection {
+  wsUrl: string
+  client: NatsClient
+  connectPromise: Promise<void> | null
+  refCount: number
+  closeTimer: ReturnType<typeof setTimeout> | null
+  retryTimer: ReturnType<typeof setTimeout> | null
+  /**
+   * Identity of the consumer driving reconnect. When set, other consumers
+   * should observe status only and skip their own scheduleRetry — otherwise
+   * each disconnect triggers multiple concurrent connect() calls racing over
+   * connectPromise.
+   */
+  retryOwner: object | null
+}
+
+export interface AcquireClientOptions {
+  name?: string
+  user?: string
+  pass?: string
+  connectTimeoutMs?: number
+  pingIntervalMs?: number
+  maxPingOut?: number
+}
+
+export interface ReleaseClientOptions {
+  delayMs?: number
+}
+
+let shared: SharedConnection | null = null
+
+export function getSharedConnection(): SharedConnection | null {
+  return shared
+}
+
+export function acquireClient(url: string, opts?: AcquireClientOptions): SharedConnection {
+  if (shared?.wsUrl !== url) {
+    if (shared) {
+      if (shared.closeTimer) clearTimeout(shared.closeTimer)
+      const old = shared
+      shared = null
+      void old.client.close().catch(() => {})
+    }
+
+    const {
+      name = 'openframe-frontend',
+      user = 'machine',
+      pass = '',
+      connectTimeoutMs = NATS_DEFAULTS.CONNECT_TIMEOUT_MS,
+      pingIntervalMs = NATS_DEFAULTS.PING_INTERVAL_MS,
+      maxPingOut = NATS_DEFAULTS.MAX_PING_OUT,
+    } = opts ?? {}
+
+    const client = createNatsClient({
+      servers: url,
+      name,
+      user,
+      pass,
+      connectTimeoutMs,
+      reconnect: false,
+      pingIntervalMs,
+      maxPingOut,
+    })
+
+    shared = {
+      wsUrl: url,
+      client,
+      connectPromise: null,
+      refCount: 0,
+      closeTimer: null,
+      retryTimer: null,
+      retryOwner: null,
+    }
+  }
+
+  shared.refCount += 1
+  if (shared.closeTimer) {
+    clearTimeout(shared.closeTimer)
+    shared.closeTimer = null
+  }
+  return shared
+}
+
+export function releaseClient(url: string, opts?: ReleaseClientOptions): void {
+  if (!shared || shared.wsUrl !== url) return
+
+  shared.refCount = Math.max(0, shared.refCount - 1)
+  if (shared.refCount > 0) return
+
+  const delay = opts?.delayMs ?? NATS_DEFAULTS.SHARED_CLOSE_DELAY_MS
+  shared.closeTimer = setTimeout(() => {
+    const s = shared
+    shared = null
+    if (s) {
+      if (s.retryTimer) {
+        clearTimeout(s.retryTimer)
+        s.retryTimer = null
+      }
+      void s.client.close().catch(() => {})
+    }
+  }, delay)
+}
+
+export function getSharedConnectionFor(url: string | null | undefined): SharedConnection | null {
+  if (!url) return null
+  return shared && shared.wsUrl === url ? shared : null
+}
+
+// ---------------------------------------------------------------------------
+// Connection lifecycle: retry + status loop, shared by NatsProvider and the
+// chat hooks. Each consumer that wants to drive reconnect creates an
+// ownerToken and calls startConnectionLifecycle(). The first caller to claim
+// retryOwner runs the actual retry loop; subsequent claimants observe status
+// only. When the owner unmounts and releases retryOwner, the next status
+// event lets a surviving consumer pick up ownership opportunistically.
+// ---------------------------------------------------------------------------
+
+export interface ConnectionLifecycleOptions {
+  conn: SharedConnection
+  wsUrl: string
+  onBeforeReconnect?: () => Promise<void> | void
+  backoff?: NatsReconnectionBackoff
+  getFreshUrl: () => string | null
+  /** Called on every status change (after closed-guard). */
+  onStatusChange?: (status: NatsStatus, evt: NatsStatusEvent) => void
+  /**
+   * Decide which statuses should trigger a retry attempt. Defaults to closed +
+   * disconnected. Override to skip 'error' (JetStream protocol errors that
+   * don't close the WS) or include it.
+   */
+  shouldRetryOn?: (status: NatsStatus) => boolean
+}
+
+export interface ConnectionLifecycleHandle {
+  /** Stop observing status, clear any pending retry, release ownership if held. */
+  stop(): void
+}
+
+const defaultShouldRetryOn = (status: NatsStatus) => status === 'closed' || status === 'disconnected'
+
+export function startConnectionLifecycle(options: ConnectionLifecycleOptions): ConnectionLifecycleHandle {
+  const { conn, wsUrl } = options
+  // Each lifecycle gets its own identity for retry ownership. The first lifecycle to claim
+  // an unowned connection drives reconnect; later attachers observe status only until the
+  // owner releases (see opportunistic claim in scheduleRetry).
+  const ownerToken = {}
+  if (!conn.retryOwner) conn.retryOwner = ownerToken
+
+  let closed = false
+  let retryAttempt = 0
+
+  function emitSynthetic(status: NatsStatus) {
+    if (closed) return
+    options.onStatusChange?.(status, { status })
+    if (status === 'connected') {
+      retryAttempt = 0
+    }
+  }
+
+  function scheduleRetry() {
+    if (closed) return
+    if (getSharedConnectionFor(wsUrl) !== conn) return
+    if (!conn.retryOwner) conn.retryOwner = ownerToken
+    if (conn.retryOwner !== ownerToken) return
+
+    if (conn.retryTimer) {
+      clearTimeout(conn.retryTimer)
+      conn.retryTimer = null
+    }
+
+    const cfg = options.backoff ?? {}
+    const fastRetries = cfg.fastRetries ?? 0
+    const fastDelay = cfg.fastRetryDelayMs ?? NATS_DEFAULTS.RETRY_INITIAL_DELAY_MS
+    const baseDelay = cfg.initialDelayMs ?? NATS_DEFAULTS.RETRY_INITIAL_DELAY_MS
+    const maxDelay = cfg.maxDelayMs ?? NATS_DEFAULTS.RETRY_MAX_DELAY_MS
+    const multiplier = cfg.multiplier ?? NATS_DEFAULTS.RETRY_MULTIPLIER
+
+    const delay =
+      retryAttempt < fastRetries
+        ? fastDelay
+        : Math.min(baseDelay * multiplier ** (retryAttempt - fastRetries), maxDelay)
+    const jitteredDelay = delay * (0.5 + Math.random() * 0.5)
+    retryAttempt++
+
+    conn.retryTimer = setTimeout(async () => {
+      conn.retryTimer = null
+      if (closed) return
+      if (getSharedConnectionFor(wsUrl) !== conn) return
+
+      try {
+        await options.onBeforeReconnect?.()
+      } catch {
+        // continue regardless of token-refresh outcome
+      }
+      if (closed) return
+      if (getSharedConnectionFor(wsUrl) !== conn) return
+
+      const freshUrl = options.getFreshUrl()
+      if (freshUrl !== wsUrl) return
+
+      try {
+        conn.connectPromise = null
+        conn.connectPromise = conn.client.connect()
+        await conn.connectPromise
+        if (!closed && getSharedConnectionFor(wsUrl) === conn) {
+          retryAttempt = 0
+        }
+      } catch {
+        conn.connectPromise = null
+        if (!closed && getSharedConnectionFor(wsUrl) === conn) {
+          scheduleRetry()
+        }
+      }
+    }, jitteredDelay)
+  }
+
+  const shouldRetryOn = options.shouldRetryOn ?? defaultShouldRetryOn
+
+  const unsubStatus = conn.client.onStatus((evt) => {
+    if (closed) return
+    options.onStatusChange?.(evt.status, evt)
+    if (evt.status === 'connected') {
+      retryAttempt = 0
+    }
+    if (shouldRetryOn(evt.status)) {
+      scheduleRetry()
+    }
+  })
+
+  if (conn.client.isConnected()) {
+    emitSynthetic('connected')
+  }
+
+  void (async () => {
+    try {
+      conn.connectPromise ||= conn.client.connect()
+      await conn.connectPromise
+    } catch {
+      conn.connectPromise = null
+      if (closed) return
+
+      emitSynthetic('disconnected')
+      scheduleRetry()
+    }
+  })()
+
+  return {
+    stop() {
+      closed = true
+      unsubStatus()
+      if (conn.retryTimer) {
+        clearTimeout(conn.retryTimer)
+        conn.retryTimer = null
+      }
+      if (conn.retryOwner === ownerToken) {
+        conn.retryOwner = null
+      }
+    },
+  }
+}

package/src/nats/use-nats-subscription.ts

@@ -0,0 +1,99 @@
+'use client'
+
+import * as React from 'react'
+import type { JsMsg, Msg, NatsSubscribeOptions } from './nats'
+import { useOptionalNats } from './nats-provider'
+
+export interface UseNatsSubscriptionOptions extends NatsSubscribeOptions {
+  enabled?: boolean
+}
+
+export interface UseNatsSubscriptionReturn {
+  isSubscribed: boolean
+  isReady: boolean
+}
+
+/**
+ * Subscribe to a NATS subject using the shared connection from <NatsProvider>.
+ * Automatically (re)subscribes when the connection becomes ready, when the
+ * subject changes, and after reconnections.
+ */
+export function useNatsSubscription(
+  subject: string | null,
+  onMessage: (msg: Msg) => void | Promise<void>,
+  options?: UseNatsSubscriptionOptions,
+): UseNatsSubscriptionReturn {
+  const nats = useOptionalNats()
+  const handlerRef = React.useRef(onMessage)
+  React.useEffect(() => {
+    handlerRef.current = onMessage
+  }, [onMessage])
+
+  const [isSubscribed, setIsSubscribed] = React.useState(false)
+
+  const enabled = options?.enabled !== false
+  const queue = options?.queue
+  const max = options?.max
+  const reconnectionCount = nats?.reconnectionCount ?? 0
+  const isReady = !!nats?.isReady
+  const client = nats?.client ?? null
+
+  React.useEffect(() => {
+    if (!client || !isReady || !subject || !enabled) {
+      setIsSubscribed(false)
+      return
+    }
+
+    const sub = client.subscribeBytes(
+      subject,
+      (msg) => handlerRef.current(msg),
+      { queue, max },
+    )
+    setIsSubscribed(true)
+
+    return () => {
+      setIsSubscribed(false)
+      try {
+        sub.unsubscribe()
+      } catch {
+        // ignore
+      }
+    }
+    // reconnectionCount intentionally in deps: re-subscribe after reconnect
+  }, [client, isReady, subject, enabled, queue, max, reconnectionCount])
+
+  return { isSubscribed, isReady }
+}
+
+export type UseNatsJsonSubscriptionOptions = UseNatsSubscriptionOptions
+
+export function useNatsJsonSubscription<T = unknown>(
+  subject: string | null,
+  onPayload: (payload: T, msg: Msg) => void | Promise<void>,
+  options?: UseNatsJsonSubscriptionOptions,
+): UseNatsSubscriptionReturn {
+  const handlerRef = React.useRef(onPayload)
+  React.useEffect(() => {
+    handlerRef.current = onPayload
+  }, [onPayload])
+
+  const decoderRef = React.useRef<TextDecoder | null>(null)
+  if (!decoderRef.current && typeof TextDecoder !== 'undefined') {
+    decoderRef.current = new TextDecoder()
+  }
+
+  const wrapped = React.useCallback(async (msg: Msg) => {
+    const decoder = decoderRef.current
+    if (!decoder) return
+    try {
+      const parsed = JSON.parse(decoder.decode(msg.data)) as T
+      await handlerRef.current(parsed, msg)
+    } catch {
+      // ignore malformed payloads
+    }
+  }, [])
+
+  return useNatsSubscription(subject, wrapped, options)
+}
+
+export type NatsJsMsg = JsMsg

package/src/stories/EmbeddableChat.stories.tsx

@@ -35,7 +35,7 @@ function createMockRuntime(): ChatRuntime {
       buildListUrl: () => null,
       attachmentUploadUrl: '/__story__/upload',
       attachmentViewUrlPrefix: '/__story__/view/',
-      chatIdentityUrl: '/__story__/identity',
+      identityUrl: '/__story__/identity',
     },
     navigation: {
       mode: 'embed',

package/src/utils/index.ts

@@ -200,3 +200,15 @@ export { fetchPriorityProp, type FetchPriorityValue } from './fetch-priority'
 // server-safe (no JSX, no contexts/* imports); imported by route-page
 // `metadata` exports + the shared `<DevSectionView>` chrome.
 export * from './dev-sections'
+
+// Canonical "smooth scroll element into view with sticky-chrome
+// offset" helper. Single source of truth across the lib + hub for
+// pre-computed-target scrolling — see `scroll-into-view.ts` for the
+// rationale (TL;DR: window.scrollTo({top, behavior:'smooth'}) with a
+// pre-computed pixel value avoids the mid-animation jitter that
+// `element.scrollIntoView()` produces when layout shifts during the
+// scroll).
+export {
+  type ScrollElementIntoViewOptions,
+  scrollElementIntoView,
+} from './scroll-into-view'

package/src/utils/scroll-into-view.ts

@@ -0,0 +1,74 @@
+/**
+ * `scrollElementIntoView` — canonical "smooth scroll element to top
+ * of viewport, account for sticky chrome, optionally adjust for
+ * known layout shifts" helper.
+ *
+ * Before this util existed, ~3 different call sites in the lib + hub
+ * had the same 5-line snippet copy-pasted with subtle differences:
+ *
+ *   - `useUnifiedNav` same-URL re-scroll branch (hub)
+ *   - `<HelpCenterCard>` click-to-expand (lib, with cross-row
+ *     layout-shift adjustment)
+ *   - Future ticket-row / docs anchor scrolls
+ *
+ * The canonical pattern is `window.scrollTo({top, behavior:'smooth'})`
+ * with a pre-computed pixel target — NOT `element.scrollIntoView()`.
+ * Pre-computing the target lets the browser run a clean uninterrupted
+ * smooth animation to a fixed pixel value. `scrollIntoView` re-targets
+ * continuously as the page layout shifts during the animation, which
+ * causes visible jitter when content above the target is also moving
+ * (a sibling collapsing, an async image loading, …).
+ *
+ * The `adjustTargetY` callback is the escape hatch for cases where
+ * the consumer KNOWS about an upcoming layout shift and can compute
+ * the correct FINAL target before the animation starts. Example: in
+ * `HelpCenterCard`, clicking row B while row A above is currently
+ * expanded — A's drawer collapses simultaneously with B's expansion,
+ * shifting B's tile up by A's drawer height. The consumer passes
+ * `adjustTargetY: raw => raw - getAboveDrawerHeight()` and the
+ * browser smooth-scrolls to the post-collapse position directly.
+ */
+
+export interface ScrollElementIntoViewOptions {
+  /** Pixels to subtract from the target element's `top` so it lands
+   *  BELOW sticky chrome. Defaults to 0. Pass `96` (matches
+   *  `scroll-mt-24`) for the standard hub header offset. */
+  headerOffset?: number
+  /** Scroll animation style. Defaults to `'smooth'`. Use `'instant'`
+   *  for imperative jumps where animation would feel laggy (deep
+   *  link land, programmatic focus moves). */
+  behavior?: ScrollBehavior
+  /** Optional adjustment applied to the computed pixel target. The
+   *  callback receives the "raw" Y (`element.top + scrollY -
+   *  headerOffset`) and returns the FINAL pixel target. Use this
+   *  when the caller knows about a layout shift that will happen
+   *  between the call and the animation completing — the browser's
+   *  smooth-scroll commits to a single pixel value, so providing the
+   *  post-shift target up front lands the element correctly even as
+   *  content above it moves. */
+  adjustTargetY?: (rawTargetY: number) => number
+}
+
+/**
+ * Scroll the page so `target` lands at the top of the viewport,
+ * accounting for sticky chrome via `headerOffset`. Returns void; the
+ * scroll runs async via the browser's smooth-scroll engine.
+ *
+ * Accepts:
+ *   - `HTMLElement` — direct reference (most common from `useRef`).
+ *   - `null` / `undefined` — no-op so callers can pass refs without
+ *     defensive branching.
+ *
+ * SSR-safe: short-circuits when `window` is undefined.
+ */
+export function scrollElementIntoView(
+  target: HTMLElement | null | undefined,
+  options: ScrollElementIntoViewOptions = {},
+): void {
+  if (typeof window === 'undefined' || !target) return
+  const { headerOffset = 0, behavior = 'smooth', adjustTargetY } = options
+  const rawTargetY =
+    target.getBoundingClientRect().top + window.scrollY - headerOffset
+  const finalY = adjustTargetY ? adjustTargetY(rawTargetY) : rawTargetY
+  window.scrollTo({ top: Math.max(0, finalY), behavior })
+}

package/dist/chunk-6RZYJICV.cjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-6RZYJICV.cjs","../src/contexts/chat-runtime-context.tsx"],"names":[],"mappings":"AAAA,qFAAY;AACZ;AACA;ACiCA,8BAA0D;AA8FnD,IAAM,mBAAA,EAAqB,kCAAA,IAAsC,CAAA;AAQjE,SAAS,cAAA,CAAA,EAAqC;AACnD,EAAA,OAAO,+BAAA,kBAA6B,CAAA;AACtC;AAUO,SAAS,sBAAA,CAAA,EAAsC;AACpD,EAAA,MAAM,EAAA,EAAI,+BAAA,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;ADjJA;AACA;AACE;AACA;AACA;AACF,kJAAC","file":"/home/runner/work/openframe-oss-lib/openframe-oss-lib/openframe-frontend-core/dist/chunk-6RZYJICV.cjs","sourcesContent":[null,"'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\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    /** GET slash-command catalog. Hub: '/api/docs/commands'. */\n    commandsUrl: 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     *    - `chatIdentityUrl` — GET endpoint the `useChatIdentity` hook\n     *      hits to learn the `{authTier, source, attachmentsEnabled}`\n     *      capability bag for the current session. */\n    attachmentUploadUrl: string\n    attachmentViewUrlPrefix: string\n    chatIdentityUrl: 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  }\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  /** Chat source identifier — REQUIRED. Used for localStorage\n   *  namespacing (`mingo-chat-<source>-v1`). Hub sets via\n   *  `currentPlatform()`; embedders set explicitly.\n   *  `useEmbeddedChat()` throws if source is empty/missing. */\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"]}

package/dist/chunk-7L4DWM7P.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/contexts/chat-runtime-context.tsx"],"sourcesContent":["'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\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    /** GET slash-command catalog. Hub: '/api/docs/commands'. */\n    commandsUrl: 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     *    - `chatIdentityUrl` — GET endpoint the `useChatIdentity` hook\n     *      hits to learn the `{authTier, source, attachmentsEnabled}`\n     *      capability bag for the current session. */\n    attachmentUploadUrl: string\n    attachmentViewUrlPrefix: string\n    chatIdentityUrl: 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  }\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  /** Chat source identifier — REQUIRED. Used for localStorage\n   *  namespacing (`mingo-chat-<source>-v1`). Hub sets via\n   *  `currentPlatform()`; embedders set explicitly.\n   *  `useEmbeddedChat()` throws if source is empty/missing. */\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"],"mappings":";;;AAmCA,SAAS,eAAe,kBAAkC;AA8FnD,IAAM,qBAAqB,cAAkC,IAAI;AAQjE,SAAS,iBAAqC;AACnD,SAAO,WAAW,kBAAkB;AACtC;AAUO,SAAS,yBAAsC;AACpD,QAAM,IAAI,WAAW,kBAAkB;AACvC,MAAI,CAAC,GAAG;AACN,UAAM,IAAI;AAAA,MACR;AAAA,IAMF;AAAA,EACF;AACA,SAAO;AACT;","names":[]}