@flamingo-stack/openframe-frontend-core 0.0.204 → 0.0.205

package/src/components/ui/hover-dropdown.tsx

@@ -0,0 +1,258 @@
+'use client'
+
+import React, { useState, useRef, useCallback } from 'react'
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface HoverDropdownItem {
+  label: string
+  icon?: React.ReactNode
+  href?: string
+  /**
+   * Target platform for the row's link — threaded through to the caller's
+   * `renderAnchor` slot, which decides how to route (same tab vs new tab,
+   * embed-aware open, etc.). Plain UI dropdown — no internal click rule.
+   */
+  targetPlatform?: string | null
+  /**
+   * In-app doc-tree path for `markdown` / `data_room_doc` refs. Threaded
+   * through to the caller's `renderAnchor` so chat consumers can wire it
+   * into `handleChatNavClick` and trigger an in-page doc-tree swap
+   * (parity with source chips and inline cards).
+   */
+  path?: string | null
+  /**
+   * @deprecated Pass `targetPlatform` to the consumer's `renderAnchor` and
+   * let it decide. Kept on the item shape for caller-side decisions but
+   * unused by this component.
+   */
+  alwaysNewTab?: boolean
+  onClick?: () => void
+  /** Optional secondary action rendered as a small icon-button at the
+   *  right edge of the row. Independent of the row's primary click target
+   *  — clicking the secondary button does NOT navigate. */
+  secondaryAction?: {
+    icon: React.ReactNode
+    label: string
+    onClick: () => void
+  }
+}
+
+export interface HoverDropdownRenderAnchorArgs {
+  href: string
+  targetPlatform?: string | null
+  /** In-app doc-tree path — chat consumers forward to `handleChatNavClick`
+   *  for doc-tree swap parity with chips + inline cards. */
+  path?: string | null
+  alwaysNewTab?: boolean
+  className: string
+  children: React.ReactNode
+}
+
+interface HoverDropdownProps {
+  /** The trigger element — dropdown appears on hover */
+  children: React.ReactNode
+  /** Items to show in the dropdown */
+  items: HoverDropdownItem[]
+  /** Dropdown position relative to trigger (default: 'top') */
+  side?: 'top' | 'bottom'
+  /** Delay in ms before hiding on mouse leave (default: 200) */
+  hideDelay?: number
+  /** Additional className for the dropdown container */
+  className?: string
+  /**
+   * Optional anchor renderer for rows that have an `href`. Chat consumers
+   * supply a `<NavLinkAnchorViaRuntime>`-backed renderer so clicks route
+   * through the chat runtime; non-chat consumers can skip this and rely
+   * on the default plain `<a>`.
+   */
+  renderAnchor?: (args: HoverDropdownRenderAnchorArgs) => React.ReactNode
+}
+
+// =============================================================================
+// Component
+// =============================================================================
+
+/**
+ * Generic hover dropdown — shows a list of clickable items on hover.
+ *
+ * Uses fixed positioning with getBoundingClientRect for proper placement
+ * inside containers with overflow hidden (e.g., Sheet, modals).
+ *
+ * Usage:
+ *   <HoverDropdown items={[{ label: 'Blog Post', href: '/blog/1' }]}>
+ *     <span>Blog Posts (5)</span>
+ *   </HoverDropdown>
+ */
+function DefaultAnchor({
+  href,
+  className,
+  children,
+}: HoverDropdownRenderAnchorArgs) {
+  return (
+    <a href={href} className={className}>
+      {children}
+    </a>
+  )
+}
+
+export function HoverDropdown({
+  children,
+  items,
+  side = 'top',
+  hideDelay = 200,
+  className,
+  renderAnchor,
+}: HoverDropdownProps) {
+  const [open, setOpen] = useState(false)
+  const timeoutRef = useRef<ReturnType<typeof setTimeout>>(undefined)
+  const containerRef = useRef<HTMLDivElement>(null)
+
+  const show = useCallback(() => {
+    clearTimeout(timeoutRef.current)
+    setOpen(true)
+  }, [])
+
+  const hide = useCallback(() => {
+    timeoutRef.current = setTimeout(() => setOpen(false), hideDelay)
+  }, [hideDelay])
+
+  if (items.length === 0) return <>{children}</>
+
+  // Click handler — touch / mobile (no hover) + desktop users who
+  // expect clicking a chip to open a menu. Toggles the dropdown state
+  // so a second click closes it. `stopPropagation` prevents the click
+  // from bubbling to ancestor handlers (the chip's parent message
+  // bubble shouldn't react to chip clicks).
+  const toggle = useCallback((e: React.MouseEvent) => {
+    e.stopPropagation()
+    clearTimeout(timeoutRef.current)
+    setOpen((prev) => !prev)
+  }, [])
+
+  const renderAnchorFn = renderAnchor ?? DefaultAnchor
+
+  return (
+    <div
+      ref={containerRef}
+      className="relative inline-flex"
+      onMouseEnter={show}
+      onMouseLeave={hide}
+      onClick={toggle}
+    >
+      {children}
+      {open && (
+        <div
+          className={`fixed z-[9999] min-w-[220px] max-w-[340px] max-h-[420px] overflow-y-auto rounded-lg bg-ods-card border border-ods-border shadow-xl p-1 ${className || ''}`}
+          ref={(el) => {
+            if (!el || !containerRef.current) return
+            const rect = containerRef.current.getBoundingClientRect()
+            const elHeight = el.offsetHeight
+            const elWidth = el.offsetWidth
+
+            // Try to place to the right of the trigger first
+            const spaceRight = window.innerWidth - rect.right
+            const spaceLeft = rect.left
+            const fitsRight = spaceRight >= elWidth + 8
+            const fitsLeft = spaceLeft >= elWidth + 8
+
+            if (fitsRight || (!fitsLeft && spaceRight >= spaceLeft)) {
+              // Place to the right
+              el.style.left = `${rect.right + 4}px`
+              el.style.top = `${Math.min(Math.max(rect.top, 8), window.innerHeight - elHeight - 8)}px`
+            } else if (fitsLeft) {
+              // Place to the left
+              el.style.left = `${rect.left - elWidth - 4}px`
+              el.style.top = `${Math.min(Math.max(rect.top, 8), window.innerHeight - elHeight - 8)}px`
+            } else {
+              // Fallback: place above or below
+              const left = Math.min(Math.max(rect.left, 8), window.innerWidth - elWidth - 8)
+              el.style.left = `${left}px`
+              if (side === 'top' || window.innerHeight - rect.bottom < elHeight + 8) {
+                el.style.top = `${Math.max(rect.top - elHeight - 4, 8)}px`
+              } else {
+                el.style.top = `${rect.bottom + 4}px`
+              }
+            }
+          }}
+        >
+          {items.map((item, i) => {
+            const content = (
+              <>
+                {item.icon && <span className="flex-shrink-0 [&_svg]:size-3.5">{item.icon}</span>}
+                <span className="truncate flex-1 min-w-0">{item.label}</span>
+              </>
+            )
+
+            // Each row is a flex container: primary action (link or button)
+            // occupies the left expanding region; the optional secondary
+            // action ("Ask") sits at the right as a sibling icon-button so
+            // its click is independent of the primary navigation.
+            const rowClass = 'group flex w-full items-center gap-1.5 pl-2 pr-1 py-1.5 rounded text-[11px] text-ods-text-secondary hover:bg-ods-accent/10 transition-colors text-left'
+            const primaryClass = 'flex flex-1 items-center gap-1.5 min-w-0 hover:text-ods-accent cursor-pointer no-underline'
+
+            const secondary = item.secondaryAction ? (
+              <button
+                onClick={(e) => {
+                  e.preventDefault()
+                  e.stopPropagation()
+                  item.secondaryAction!.onClick()
+                }}
+                aria-label={item.secondaryAction.label}
+                title={item.secondaryAction.label}
+                className="flex-shrink-0 inline-flex items-center justify-center h-5 w-5 rounded text-ods-text-secondary opacity-60 hover:opacity-100 hover:text-ods-text-primary hover:bg-ods-accent/15 transition-opacity [&_svg]:size-3"
+              >
+                {item.secondaryAction.icon}
+              </button>
+            ) : null
+
+            if (item.href) {
+              // Caller supplies the anchor renderer (defaults to plain <a>).
+              // Chat consumers wire `NavLinkAnchorViaRuntime` here so clicks
+              // route through the chat runtime.
+              return (
+                <div key={i} className={rowClass}>
+                  {renderAnchorFn({
+                    href: item.href,
+                    targetPlatform: item.targetPlatform,
+                    path: item.path,
+                    alwaysNewTab: item.alwaysNewTab,
+                    className: primaryClass,
+                    children: content,
+                  })}
+                  {secondary}
+                </div>
+              )
+            }
+
+            // Item has no primary action — render the label as a
+            // non-interactive span. The secondary Ask button remains
+            // active, so the row is still useful for rows that have no
+            // public viewer URL but DO have a working Ask drill-in.
+            if (!item.onClick) {
+              return (
+                <div key={i} className={rowClass}>
+                  <span className={`${primaryClass} cursor-default hover:!text-ods-text-secondary`}>
+                    {content}
+                  </span>
+                  {secondary}
+                </div>
+              )
+            }
+
+            return (
+              <div key={i} className={rowClass}>
+                <button onClick={item.onClick} className={primaryClass}>
+                  {content}
+                </button>
+                {secondary}
+              </div>
+            )
+          })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/components/ui/image-gallery-modal.tsx

@@ -3,7 +3,7 @@
 import { useState, useEffect } from 'react';
 import { Modal, Button } from './index';
 import { ChevronLeft, ChevronRight } from 'lucide-react';
-import Image from 'next/image';
+import Image from '../../embed-shims/next-image';
 
 interface ImageGalleryModalProps {
   images: string[];

package/src/components/ui/index.ts

@@ -54,6 +54,7 @@ export * from './status-indicator'
 export * from './toaster'
 // TODO: Add other UI components as they are moved to ui-kit
 export * from './skeleton'
+export * from './hover-dropdown'
 // Chat components
 export * from '../chat'
 export * from '../layout/list-page-layout'

package/src/components/ui/markdown-editor.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import React, { useRef, useCallback, useState, useEffect } from "react"
-import dynamic from "next/dynamic"
+import dynamic from "../../embed-shims/next-dynamic"
 import { Loader2, Upload } from "lucide-react"
 import { cn } from "../../utils/cn"
 

package/src/components/ui/more-actions-menu.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import React from 'react'
-import Link from 'next/link'
+import Link from '../../embed-shims/next-link'
 import { cn } from '../../utils/cn'
 import { Ellipsis01Icon } from '../icons-v2-generated'
 import { Button } from './button'

package/src/components/ui/organization-card.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import React from "react"
-import Link from "next/link"
+import Link from "../../embed-shims/next-link"
 import { Monitor } from "lucide-react"
 import { cn } from "../../utils/cn"
 import { EntityImage } from "./entity-image"

package/src/components/ui/simple-markdown-renderer.tsx

@@ -8,7 +8,7 @@ import remarkBreaks from 'remark-breaks';
 import rehypeHighlight from 'rehype-highlight';
 import rehypeRaw from 'rehype-raw';
 import { visit } from 'unist-util-visit';
-import Image from 'next/image';
+import Image from '../../embed-shims/next-image';
 import { AlertCircleIcon } from '../icons-v2-generated';
 import { cn } from '../../utils/cn';
 
@@ -794,16 +794,64 @@ export const SimpleMarkdownRenderer: React.FC<SimpleMarkdownRendererProps> = ({
     },
 
     // --- images ---
+    // Inline content image renderer. Used by blog posts, docs, AND chat
+    // messages (where users may attach screenshots / photos via the +
+    // attachment button).
+    //
+    // Sizing rules (2025-2026 best practice — Claude.ai, ChatGPT,
+    // iMessage, Slack, Discord inline image patterns):
+    //
+    //   - CAP max-width at 400px so inline images don't blow out the
+    //     message column on wide panels. Click-to-expand opens a
+    //     full-resolution modal for users who need detail.
+    //   - CAP max-height at 400px so portrait-orientation images
+    //     don't dominate vertical space (a 1000x3000 phone screenshot
+    //     would otherwise push the next message off-screen).
+    //   - Small images render at NATURAL pixel size — a 64x64
+    //     thumbnail stays 64x64, not stretched to fill the column.
+    //   - `object-contain` preserves aspect ratio when both dimensions
+    //     are constrained (long landscape, tall portrait).
+    //
+    // Implementation: Next.js `<Image>` — the project's canonical
+    // image primitive. Gives us:
+    //   - WebP/AVIF format conversion for modern browsers (smaller
+    //     bytes for the same visual quality).
+    //   - Responsive `srcset` via the `sizes` prop (browser picks the
+    //     right variant for the viewport).
+    //   - Automatic lazy-loading (`loading="lazy"` by default, mid-
+    //     page images skipped until they near the viewport).
+    //   - Automatic `decoding="async"` so image decode doesn't block
+    //     paint.
+    //
+    // `width={400} height={400}` props are REQUIRED by Next.js
+    // `<Image>` (non-`fill` mode throws without them) but they're
+    // effectively a CEILING here, not the display size — the CSS
+    // overrides (`w-auto h-auto max-w-full max-h-[400px]`) drive
+    // the actual rendered size. The inline `style={{ width: 'auto',
+    // height: 'auto' }}` is belt-and-suspenders: Next.js Image sets
+    // matching HTML `width`/`height` attributes on the rendered
+    // `<img>` and inline style wins over both HTML attributes AND
+    // utility classes regardless of CSS-specificity surprises.
+    //
+    // Layout reservation trade-off: until image bytes arrive, the
+    // browser may reserve a placeholder box up to 400x400 (the props'
+    // intrinsic-ratio hint). Once loaded, the box collapses to the
+    // natural size if smaller. This is the standard Next.js Image
+    // behavior across the codebase — accepted for the optimizer +
+    // responsive-srcset benefits. Chat attachments hosted in side
+    // panels see this only on first render of a fresh attachment
+    // (cached re-renders pop in without a perceptible shift).
     img: ({ src, alt }: any) => {
       if (!src || typeof src !== 'string' || src.trim() === '') return null;
       return (
         <Image
           src={src}
           alt={alt ?? 'No image available'}
-          width={896}
-          height={200}
-          sizes="(max-width: 896px) 100vw, 896px"
-          className="max-w-full h-auto rounded-lg"
+          width={400}
+          height={400}
+          sizes="(max-width: 400px) 100vw, 400px"
+          className="max-w-full max-h-[400px] w-auto h-auto rounded-lg object-contain"
+          style={{ width: 'auto', height: 'auto' }}
         />
       );
     },

package/src/components/ui/square-avatar.tsx

@@ -1,18 +1,9 @@
 "use client"
 
 import * as React from "react";
-import Image from "next/image";
+import Image from "../../embed-shims/next-image";
 import { cn } from "../../utils/cn";
-
-// Extract initials from a name (first letter of first and last word)
-const getInitials = (name?: string): string => {
-  if (!name) return '';
-  const words = name.trim().split(/\s+/);
-  if (words.length === 1) {
-    return words[0].charAt(0).toUpperCase();
-  }
-  return (words[0].charAt(0) + words[words.length - 1].charAt(0)).toUpperCase();
-};
+import { getFirstLastInitials } from "../../utils/format";
 
 interface SquareAvatarProps extends React.HTMLAttributes<HTMLDivElement> {
   src?: string;
@@ -58,7 +49,7 @@ const SquareAvatar = React.memo(React.forwardRef<HTMLDivElement, SquareAvatarPro
           'flex items-center justify-center text-xs font-medium text-ods-text-secondary',
           src && 'hidden'
         )}>
-          {getInitials(fallback || alt) || '?'}
+          {getFirstLastInitials(fallback || alt) || '?'}
         </div>
         {src && (
           <Image

package/src/components/ui/tab-navigation.tsx

@@ -1,7 +1,7 @@
 'use client'
 
 import React, { useState, useEffect, useMemo, useRef, useCallback } from 'react'
-import { useSearchParams, useRouter, usePathname } from 'next/navigation'
+import { useSearchParams, useRouter, usePathname } from '../../embed-shims/next-navigation'
 import { cn } from '../../utils/cn'
 
 export interface TabItem {

package/src/components/ui/table/table-row.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import Link from 'next/link'
+import Link from '../../../embed-shims/next-link'
 import React from 'react'
 import { cn } from '../../../utils/cn'
 import { Checkbox } from '../checkbox'

package/src/components/unified-filter-logic.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { useSearchParams, useRouter } from "next/navigation"
+import { useSearchParams, useRouter } from "../embed-shims/next-navigation"
 import { useTransition } from "react"
 
 /**

package/src/components/unified-pagination.tsx

@@ -1,6 +1,6 @@
 "use client"
 
-import { useRouter, useSearchParams, usePathname } from "next/navigation"
+import { useRouter, useSearchParams, usePathname } from "../embed-shims/next-navigation"
 import { Pagination } from "./pagination"
 
 interface UnifiedPaginationProps {

package/src/components/user-summary-stub.tsx

@@ -1,6 +1,6 @@
 "use client";
 
-import Image from "next/image";
+import Image from "../embed-shims/next-image";
 import { getProxiedImageUrl } from "../utils/image-proxy-stub";
 
 interface Props {

package/src/components/vendor-display-button.tsx

@@ -2,7 +2,7 @@
 
 import { Button } from "./ui/button"
 import { getVendorLogo, VendorWithMedia } from "../utils/vendor-media-stub"
-import Image from "next/image"
+import Image from "../embed-shims/next-image"
 import { getProxiedImageUrl } from "../utils/image-proxy-stub"
 
 interface VendorDisplayButtonProps {

package/src/components/vendor-icon.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import React from 'react'
-import Image from 'next/image'
+import Image from '../embed-shims/next-image'
 import { cn } from "../utils/cn"
 import { getVendorLogo, VendorWithMedia } from '../utils/vendor-media-stub'
 import { getProxiedImageUrl } from '../utils/image-proxy-stub'

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

@@ -0,0 +1,163 @@
+'use client'
+
+/**
+ * Chat runtime context — single seam for embedding the chat panel in a
+ * different host (e.g. user1.openframe.ai reverse-proxying API calls
+ * under /api/mingo-guide/* to hub.openframe.ai/api/*).
+ *
+ * Three concerns, one context:
+ *   1. API endpoints: chatStreamUrl / approvalToolUrl / commandsUrl /
+ *      buildListUrl + attachment endpoints + chat-identity. The chat
+ *      reads them from runtime; hub vs embedded app supply different
+ *      strings via different providers.
+ *   2. Navigation mode + callbacks: 'host' or 'embed' mode. Host wires
+ *      its own router/docNav via the optional `navigate` callback
+ *      (plain function, NOT a hook); embed forces new-tab via
+ *      `defaultContentOrigin` + lib's `resolveExternalNavigation`.
+ *   3. Identity context: only `source` (required for localStorage
+ *      namespacing). The display identity (greeting first-name etc.)
+ *      comes from the server via `useChatIdentity()` — never injected
+ *      client-side, so it always matches the server-resolved auth.
+ *
+ * Sibling of EndpointsRuntimeContext (announcement bar, contact form,
+ * access codes). Each runtime stays an independent React context so
+ * embedders can opt into either feature without forcing the other.
+ *
+ * IMPORTANT for embedders: memoize the value passed to
+ * `<ChatRuntimeContext.Provider value={...}>` (e.g. via React.useMemo).
+ * Every change to its reference identity invalidates downstream
+ * `useMemo` consumers (the chat input's slash-commands binding,
+ * useNavLink's embed-resolution memo, useDocChat's streamFn factory).
+ * The hub's `<HubRuntimeProvider>` already memoizes correctly with
+ * stable deps. Embedded apps that build the value inline on each render
+ * will pay an avoidable re-render cost across the entire chat tree.
+ */
+
+import { createContext, useContext, type ReactNode } from 'react'
+
+/**
+ * Runtime config consumed by the chat panel.
+ */
+export interface ChatRuntime {
+  endpoints: {
+    /** POST streaming chat. Hub: '/api/docs/chat'. */
+    chatStreamUrl: string
+    /** POST agent approve/reject. Hub: '/api/chat/agent/confirm-tool'. */
+    approvalToolUrl: string
+    /** GET slash-command catalog. Hub: '/api/docs/commands'. */
+    commandsUrl: string
+    /** Build entity-card list URL for a content type + ids. Hub delegates
+     *  to the rag-table-config registry; embedded app provides its own
+     *  per-type URL builder against the reverse proxy. Returns null when
+     *  the type has no list endpoint (caller skips rendering). */
+    buildListUrl: (type: string, ids: string[]) => string | null
+    /** Chat-attachment endpoints — added for the v2 attachment feature.
+     *
+     *  Three concerns:
+     *    - `attachmentUploadUrl` — POSTed by the chat-attachment hook
+     *      to mint a Supabase signed-upload-URL + HMAC view token.
+     *    - `attachmentViewUrlPrefix` — embedded in markdown URLs the
+     *      chat hosts in user message bubbles (`![]()` / `[Attached]`).
+     *      Stored in chat history; chosen at SEND time. In host mode the
+     *      relative `/api/storage/view/chat-attachments/` is sufficient
+     *      (same-origin); embedders supply an absolute hub URL so the
+     *      browser can fetch cross-origin.
+     *    - `chatIdentityUrl` — GET endpoint the `useChatIdentity` hook
+     *      hits to learn the `{authTier, source, attachmentsEnabled}`
+     *      capability bag for the current session. */
+    attachmentUploadUrl: string
+    attachmentViewUrlPrefix: string
+    chatIdentityUrl: string
+    /** Optional URL prefix for the image proxy (`<prefix>?url=<external>`).
+     *  When unset, lib's `getProxiedImageUrl` returns the original URL
+     *  unchanged. Hub default: '/api/image-proxy'. Embedders that don't
+     *  host an image-proxy route leave this undefined → images load
+     *  directly cross-origin (CORS-permitting). */
+    imageProxyUrlPrefix?: string
+    /** Optional list of hostnames that should bypass the image proxy
+     *  (rendered direct). Hub uses ['openmsp.ai']; embedders typically
+     *  leave it unset. Matches the `skipDomains` parameter of
+     *  `getProxiedImageUrl`. */
+    imageProxySkipDomains?: string[]
+  }
+  navigation: {
+    /** ONE knob, two behaviors:
+     *  - 'host' = use the host page's existing click-routing untouched.
+     *    The chat panel calls `navigate?.()` for in-app routing.
+     *  - 'embed' = guest inside another app: short-circuit at the top
+     *    of click handlers to force new-tab + absolutize via
+     *    resolveExternalNavigation. */
+    mode: 'host' | 'embed'
+    /** Embed-only fallback origin for relative URLs whose target platform
+     *  can't be inferred. Used by resolveExternalNavigation when
+     *  `targetPlatform` is null — without this, a relative `/foo` href would
+     *  window.open against the embedder's origin, which is WRONG.
+     *  Set to your content host (e.g. 'https://hub.openframe.ai').
+     *  Required by the embedded app whenever mode='embed'. */
+    defaultContentOrigin?: string
+    /** Override for opening external URLs. MUST BE SYNCHRONOUS —
+     *  Safari/Firefox block popups opened outside a direct user gesture.
+     *  Default: window.open(href, '_blank', 'noopener,noreferrer'). */
+    openExternal?: (href: string) => void
+    /** Optional in-app navigation callback (host-mode only).
+     *  Returns `true` if the host handled the click in-app
+     *  (router.push + docNav.navigate); returns `false`, `undefined`,
+     *  or `void` → lib falls back to window.location.assign(href).
+     *  Hub wires this via HubRuntimeProvider's HubNavigationWiring;
+     *  embedders not in Next.js leave it undefined. */
+    navigate?: (input: { href: string; path?: string | null; targetPlatform?: string | null }) => boolean | void
+    /** Optional new-tab decision callback. Returns true → lib opens in
+     *  new tab; false → same tab via `navigate`. Hub wires the existing
+     *  `decideNewTab` logic from use-nav-link.tsx (re-imports the pure
+     *  helper from lib). Embedders may omit; lib defaults to:
+     *  same-origin/same-platform → same tab, else new tab. */
+    decideNewTab?: (args: { href: string; targetPlatform?: string | null }) => boolean
+  }
+  /** Chat source identifier — REQUIRED. Used for localStorage
+   *  namespacing (`mingo-chat-<source>-v1`). Hub sets via
+   *  `currentPlatform()`; embedders set explicitly.
+   *  `useEmbeddedChat()` throws if source is empty/missing. */
+  source: string
+  // NOTE: No `user` field. The chat's display identity (greeting
+  // first-name, etc.) comes from the SERVER-resolved auth via
+  // `useChatIdentity()` — the same identity the server uses to
+  // authorize requests. Letting embedders pass a client-side `user`
+  // would let it desync from the actual auth tier, causing greetings
+  // like "Hey Bob" while the server treats the session as
+  // alice@example.com. Single source of truth: the server.
+}
+
+export const ChatRuntimeContext = createContext<ChatRuntime | null>(null)
+
+/**
+ * Returns the active runtime, or null when no provider is mounted.
+ * NULL is a first-class value — it signals "no chat runtime configured."
+ * Optional consumers fall back to no-op behavior; strict consumers
+ * use `useRequiredChatRuntime` (below).
+ */
+export function useChatRuntime(): ChatRuntime | null {
+  return useContext(ChatRuntimeContext)
+}
+
+/**
+ * Strict variant used INSIDE the chat panel. Throws if no provider.
+ * The hub guarantees one exists by mounting `<HubRuntimeProvider>` at
+ * root; the embedded app mounts its own `<ChatRuntimeContext.Provider>`
+ * at the tree root. In Jest / Storybook tests that render chat
+ * internals directly, wrap with `<HubRuntimeProvider>` (hub defaults)
+ * or supply `<ChatRuntimeContext.Provider value={mockedRuntime}>`.
+ */
+export function useRequiredChatRuntime(): ChatRuntime {
+  const v = useContext(ChatRuntimeContext)
+  if (!v) {
+    throw new Error(
+      '[chat-runtime] hook called outside a <ChatRuntimeContext.Provider>. ' +
+        'The hub mounts <HubRuntimeProvider> at root — this only fires when ' +
+        'chat internals are rendered above the provider tree. ' +
+        'Fix: ensure the rendering subtree descends from the runtime provider. ' +
+        'In tests/Storybook: wrap with <HubRuntimeProvider> or supply ' +
+        'a <ChatRuntimeContext.Provider value={mockedRuntime}>.',
+    )
+  }
+  return v
+}