@flamingo-stack/openframe-frontend-core 0.0.718 → 0.0.720

package/src/components/features/remote-session/remote-desktop-view.tsx

@@ -4,6 +4,7 @@ import type { ReactNode } from 'react';
 import {
   ChatOffIcon,
   ChatTextIcon,
+  Chevron02DownIcon,
   Collapse02Icon,
   Expand02Icon,
   MonitorIcon,
@@ -19,8 +20,12 @@ import { RemoteDesktopFullscreenToolbar } from './remote-desktop-fullscreen-tool
 /** The page chrome both the view and its skeleton render in. */
 const PAGE_CLASS = 'h-full overflow-hidden px-[var(--spacing-system-l)] pb-[var(--spacing-system-l)]';
 
+/** The header card: the device row, and under it the display row when there is one to pick. */
 const CONTROLS_BAR_CLASS =
-  'flex flex-shrink-0 items-center justify-between gap-[var(--spacing-system-mf)] rounded-md border border-ods-border bg-ods-card px-[var(--spacing-system-mf)] py-[var(--spacing-system-xs)]';
+  'flex flex-shrink-0 flex-col overflow-hidden rounded-md border border-ods-border bg-ods-card';
+
+const CONTROLS_ROW_CLASS =
+  'flex items-center justify-between gap-[var(--spacing-system-mf)] px-[var(--spacing-system-mf)] py-[var(--spacing-system-xs)]';
 
 export interface RemoteDesktopViewProps {
   /** First line of the device header. */
@@ -36,9 +41,13 @@ export interface RemoteDesktopViewProps {
   fullscreen?: boolean;
   onEnterFullscreen: () => void;
   onExitFullscreen: () => void;
-  /** The display switcher's menu; the switcher is hidden while this is empty (a single display). */
+  /**
+   * The display switcher's menu, one entry per separate display. The switcher is
+   * the full-width row under the device row (Figma 2155:109503), and it is left
+   * out while this is empty: one display, or an agent that reports none.
+   */
   displayMenuGroups?: ActionsMenuGroup[];
-  /** The switcher's label, e.g. "Display All" or "Display 2". */
+  /** The switcher's label, e.g. "Display 2", or "Display" before the agent has named one. */
   currentDisplayLabel: string;
   actionsMenuGroups: ActionsMenuGroup[];
   onOpenSettings: () => void;
@@ -86,61 +95,73 @@ export function RemoteDesktopView({
 }: RemoteDesktopViewProps) {
   const controlsBar = (
     <div className={CONTROLS_BAR_CLASS}>
-      <div className="flex min-w-0 items-center gap-[var(--spacing-system-mf)]">
-        <div className="flex-shrink-0 rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-xsf)]">
-          <MonitorIcon className="h-4 w-4 text-ods-text-primary" />
-        </div>
-        <div className="flex min-w-0 flex-col">
-          <TruncateText>{deviceName}</TruncateText>
-          <TruncateText
-            variant="h6"
-            tone="secondary"
-          >{`Desktop • ${organizationName || 'Unknown Customer'}`}</TruncateText>
+      <div className={CONTROLS_ROW_CLASS}>
+        <div className="flex min-w-0 items-center gap-[var(--spacing-system-mf)]">
+          <div className="flex-shrink-0 rounded-md border border-ods-border bg-ods-card p-[var(--spacing-system-xsf)]">
+            <MonitorIcon className="h-4 w-4 text-ods-text-primary" />
+          </div>
+          <div className="flex min-w-0 flex-col">
+            <TruncateText>{deviceName}</TruncateText>
+            <TruncateText
+              variant="h6"
+              tone="secondary"
+            >{`Desktop • ${organizationName || 'Unknown Customer'}`}</TruncateText>
+          </div>
         </div>
-      </div>
-      <div className="flex flex-shrink-0 items-center gap-[var(--spacing-system-xs)]">
-        {displayMenuGroups.length > 0 && (
-          <ActionsMenuDropdown
-            groups={displayMenuGroups}
-            customTrigger={
-              <Button variant="outline" leftIcon={<MonitorIcon className="h-4 w-4 md:h-6 md:w-6" />}>
-                {/* A narrow page keeps the icon and drops the words: the bar never pushes the device's name out. */}
-                <span className="sr-only content-md:not-sr-only">{currentDisplayLabel}</span>
-              </Button>
-            }
+        <div className="flex flex-shrink-0 items-center gap-[var(--spacing-system-xs)]">
+          {onToggleChat && (
+            <Button
+              variant="outline"
+              onClick={onToggleChat}
+              leftIcon={
+                chatOpen ? (
+                  <ChatOffIcon className="h-4 w-4 md:h-6 md:w-6" />
+                ) : (
+                  <ChatTextIcon className="h-4 w-4 md:h-6 md:w-6" />
+                )
+              }
+            >
+              {/* A narrow page keeps the icon and drops the words: the bar never pushes the device's name out. */}
+              <span className="sr-only content-md:not-sr-only">{chatOpen ? 'Close Chat' : 'Open Chat'}</span>
+            </Button>
+          )}
+          <ActionsMenuDropdown groups={actionsMenuGroups} triggerAriaLabel="Actions" />
+          <Button
+            variant="outline"
+            size="icon"
+            aria-label="Settings"
+            onClick={onOpenSettings}
+            leftIcon={<Settings01Icon />}
           />
-        )}
-        {onToggleChat && (
           <Button
             variant="outline"
-            onClick={onToggleChat}
-            leftIcon={
-              chatOpen ? (
-                <ChatOffIcon className="h-4 w-4 md:h-6 md:w-6" />
-              ) : (
-                <ChatTextIcon className="h-4 w-4 md:h-6 md:w-6" />
-              )
-            }
-          >
-            <span className="sr-only content-md:not-sr-only">{chatOpen ? 'Close Chat' : 'Open Chat'}</span>
-          </Button>
-        )}
-        <ActionsMenuDropdown groups={actionsMenuGroups} triggerAriaLabel="Actions" />
-        <Button
-          variant="outline"
-          size="icon"
-          aria-label="Settings"
-          onClick={onOpenSettings}
-          leftIcon={<Settings01Icon />}
-        />
-        <Button
-          variant="outline"
-          size="icon"
-          aria-label={fullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
-          onClick={fullscreen ? onExitFullscreen : onEnterFullscreen}
-          leftIcon={fullscreen ? <Collapse02Icon /> : <Expand02Icon />}
-        />
+            size="icon"
+            aria-label={fullscreen ? 'Exit fullscreen' : 'Enter fullscreen'}
+            onClick={fullscreen ? onExitFullscreen : onEnterFullscreen}
+            leftIcon={fullscreen ? <Collapse02Icon /> : <Expand02Icon />}
+          />
+        </div>
       </div>
+      {/* The monitor selector is a row of its own under the device row, the full
+          width of the card (Figma 2155:109503): the label never competes with the
+          device's name for the header's width. Hidden with one display or none. */}
+      {displayMenuGroups.length > 0 && (
+        <ActionsMenuDropdown
+          groups={displayMenuGroups}
+          align="start"
+          customTrigger={
+            <button
+              type="button"
+              aria-label="Switch display"
+              className="flex w-full items-center gap-[var(--spacing-system-xs)] border-t border-ods-border p-[var(--spacing-system-sf)] text-left text-ods-text-primary outline-none transition-colors hover:bg-ods-bg-hover focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ods-focus"
+            >
+              <MonitorIcon className="h-6 w-6 shrink-0" />
+              <span className="min-w-0 flex-1 truncate text-h4">{currentDisplayLabel}</span>
+              <Chevron02DownIcon className="h-6 w-6 shrink-0" />
+            </button>
+          }
+        />
+      )}
     </div>
   );
 
@@ -189,17 +210,19 @@ export function RemoteDesktopViewSkeleton({ onBack }: Pick<RemoteDesktopViewProp
   return (
     <PageLayout className={PAGE_CLASS} backButton={onBack ? { label: 'Back', onClick: onBack } : undefined}>
       <div className={CONTROLS_BAR_CLASS}>
-        <div className="flex min-w-0 items-center gap-[var(--spacing-system-mf)]">
-          <Skeleton className="h-9 w-9 flex-shrink-0 rounded-md" />
-          <div className="flex min-w-0 flex-col gap-[var(--spacing-system-xxs)]">
-            <Skeleton className="h-5 w-48" />
-            <Skeleton className="h-4 w-36" />
+        <div className={CONTROLS_ROW_CLASS}>
+          <div className="flex min-w-0 items-center gap-[var(--spacing-system-mf)]">
+            <Skeleton className="h-9 w-9 flex-shrink-0 rounded-md" />
+            <div className="flex min-w-0 flex-col gap-[var(--spacing-system-xxs)]">
+              <Skeleton className="h-5 w-48" />
+              <Skeleton className="h-4 w-36" />
+            </div>
+          </div>
+          <div className="flex flex-shrink-0 items-center gap-[var(--spacing-system-xs)]">
+            <Skeleton className="h-11 w-11 rounded-lg md:h-12 md:w-12" />
+            <Skeleton className="h-11 w-11 rounded-lg md:h-12 md:w-12" />
+            <Skeleton className="h-11 w-11 rounded-lg md:h-12 md:w-12" />
           </div>
-        </div>
-        <div className="flex flex-shrink-0 items-center gap-[var(--spacing-system-xs)]">
-          <Skeleton className="h-11 w-11 rounded-lg md:h-12 md:w-12" />
-          <Skeleton className="h-11 w-11 rounded-lg md:h-12 md:w-12" />
-          <Skeleton className="h-11 w-11 rounded-lg md:h-12 md:w-12" />
         </div>
       </div>
 

package/src/components/help-center-pages/trust-center-page.tsx

@@ -45,7 +45,7 @@ import {
 } from '../../types/trust-center';
 import { STICKY_HEADER_OFFSET_PX } from '../../utils/same-page-hash-nav';
 import { useScrollSpy } from '../docs/use-scroll-spy';
-import { FaqSection } from '../faq/faq-section';
+import { FaqSection, type FaqSectionProps } from '../faq/faq-section';
 import { PageShell } from '../layout/article-detail-layout';
 import { PageLayout } from '../layout/page-layout';
 import { StickySectionNav } from '../navigation/sticky-section-nav';
@@ -83,6 +83,8 @@ export interface TrustCenterPageProps {
   title?: string;
   /** Page subtitle. Default the brand-neutral `TRUST_CENTER_TAGLINE` (a host adds its brand here). */
   subtitle?: string;
+  /** The FAQ section's "ask the assistant" card (`FaqSection`'s `ask`): the host states its topic. Absent: no card. */
+  ask?: FaqSectionProps['ask'];
 }
 
 /** One section's page content. Its `h2` is the `TRUST_CENTER_SECTIONS` label — never a literal here. */
@@ -149,6 +151,7 @@ export function TrustCenterPage({
   backButton = false,
   title = TRUST_CENTER_TITLE,
   subtitle = TRUST_CENTER_TAGLINE,
+  ask,
 }: TrustCenterPageProps) {
   const { data, isLoading, error, reload } = useSelfFetch<TrustCenterPublic>(endpoint, {
     initialData,
@@ -232,7 +235,7 @@ export function TrustCenterPage({
       lead: TRUST_SECTION_LEADS.subprocessors,
       render: d => <SubprocessorsSection subprocessors={d.subprocessors} />,
     },
-    faq: { render: d => <FaqSection initialFaqs={d.faqs} heading={null} /> },
+    faq: { render: d => <FaqSection initialFaqs={d.faqs} heading={null} ask={ask} /> },
     contact: { render: () => <ContactSection onContact={() => openRequest(null)} /> },
   };
 

package/src/components/navigation/mingo-ai-button.tsx

@@ -1,7 +1,8 @@
 'use client';
 
 import type React from 'react';
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
+import { useAssistantRuntime } from '../../contexts/assistant-runtime-context';
 import { useVisitorOs } from '../../hooks/ui/use-visitor-os';
 import { cn } from '../../utils';
 import { shortcutLabel, usesCommandKey } from '../../utils/visitor-os';
@@ -78,8 +79,8 @@ export function openAskAi(source?: string, options?: { prompt?: string }): void
  */
 export function MingoAiButton({
   source,
-  icon,
-  label = 'Mingo AI',
+  icon: iconProp,
+  label: labelProp,
   shortcutHint = false,
   variant = 'inline',
   className,
@@ -93,6 +94,22 @@ export function MingoAiButton({
   const inPage = variant === 'button';
 
   const commandKey = visitor.known && usesCommandKey(visitor.os);
+  // The launcher is the assistant's: its name, glyph and the chat it opens are
+  // the assistant runtime's (the host's server-resolved identity and its own
+  // opener), so no launcher types a name or assumes which chat exists. A prop
+  // still wins (a header given its own). The lib holds no name of its own:
+  // with none from either, there is no launcher to render (below). With no
+  // runtime opener the open is the `ask-ai:open` event of `source`.
+  const assistant = useAssistantRuntime();
+  const label = labelProp ?? assistant?.name;
+  const icon = iconProp ?? assistant?.icon;
+  const runtimeOpen = assistant?.open;
+  const eventSource = source ?? assistant?.source;
+  // The latest opener, for the shortcut listener: a host's inline callback must not re-bind it every render.
+  const openRef = useRef<() => void>(() => undefined);
+  useEffect(() => {
+    openRef.current = () => (runtimeOpen ? runtimeOpen({}) : openAskAi(eventSource));
+  });
 
   // The shortcut the key cap shows opens the same chat the click opens.
   useEffect(() => {
@@ -105,11 +122,14 @@ export function MingoAiButton({
       const modifier = commandKey ? event.metaKey && !event.ctrlKey : event.ctrlKey && !event.metaKey;
       if (event.key.toLowerCase() !== 'k' || !modifier) return;
       event.preventDefault();
-      openAskAi(source);
+      openRef.current();
     };
     window.addEventListener('keydown', onKeyDown);
     return () => window.removeEventListener('keydown', onKeyDown);
-  }, [shortcutHint, source, commandKey]);
+  }, [shortcutHint, commandKey]);
+
+  // No name from the host or the runtime: nothing to launch under. The lib invents none.
+  if (!label) return null;
 
   return (
     <Button
@@ -121,7 +141,8 @@ export function MingoAiButton({
       aria-label={label}
       aria-keyshortcuts={shortcutHint && visitor.known ? (commandKey ? 'Meta+K' : 'Control+K') : undefined}
       onClick={e => {
-        openAskAi(source);
+        if (runtimeOpen) runtimeOpen({});
+        else openAskAi(eventSource);
         onClick?.(e);
       }}
       className={cn(

package/src/components/related-content/related-content-section.tsx

@@ -28,12 +28,12 @@
  * `renderSkeletonForType` so the placeholder height matches the loaded card
  * exactly (zero layout shift on resolve).
  *
- * One API call per content type via the shared list-URL builder
- * (`buildListUrl` — injectable; defaults to the lib's byte-parity-tested
- * builder prefixed with `apiBaseUrl`). Fetching uses `useSelfFetch` (plain
- * fetch, NO react-query) so third-party embedders need no QueryClientProvider;
- * cards are imported via DEEP module paths (not the chat barrel) so this
- * chunk never reaches `@tanstack/react-query`.
+ * One API call per page of a content type, carrying only that page's ids, via
+ * the shared list-URL builder (`buildListUrl` — injectable; defaults to the
+ * lib's byte-parity-tested builder prefixed with `apiBaseUrl`). Fetching uses
+ * `useSelfFetch` (plain fetch, NO react-query) so third-party embedders need
+ * no QueryClientProvider; cards are imported via DEEP module paths (not the
+ * chat barrel) so this chunk never reaches `@tanstack/react-query`.
  *
  * The per-type card + skeleton dispatch lives in `./card-registry`
  * (`RELATED_CARD_REGISTRY`): ONE entry per content type, each carrying that
@@ -49,7 +49,7 @@
  */
 
 import type React from 'react';
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { useSelfFetch } from '../../hooks/use-self-fetch';
 import type { ContentRef, ContentRefWithReason } from '../../types/content-ref';
 import {
@@ -246,23 +246,29 @@ function CardForType({
 }
 
 // =============================================================================
-// Fetch all items for a type in ONE server-sorted call, via the injectable
-// list-URL builder. `useSelfFetch` (URL = cache key) replaces the hub's old
-// react-query usage: `enabled` ≙ `url === null`, `!res.ok`/network error ≙
-// `error → items null → group renders nothing`. Accepted deltas vs
-// react-query: no retry/backoff, no focus refetch, no cross-mount cache.
+// Fetch ONE page of a group — only the ids on screen go into the list URL.
+// Pages already fetched are kept by url, so paging back renders without a
+// request. `useSelfFetch` replaces the hub's old react-query usage: `enabled`
+// ≙ `url === null` (no list API → `items: null`), `!res.ok`/network error ≙
+// an empty page. Accepted deltas vs react-query: no retry/backoff, no focus
+// refetch, no cross-mount cache.
 // =============================================================================
 
 function useGroupItems(type: string, refs: ContentRef[], buildUrl: (type: string, ids: string[]) => string | null) {
   const ids = refs.map(r => r.id);
   const url = ids.length > 0 ? buildUrl(type, ids) : null;
-  const { data, isLoading } = useSelfFetch<unknown>(url);
-  const items = data != null ? extractItems(data) : null;
-  return { items, isLoading };
+  const [pages, setPages] = useState<ReadonlyMap<string, unknown[]>>(() => new Map());
+  const cached = url !== null ? pages.get(url) : undefined;
+  const { data, dataUrl, error } = useSelfFetch<unknown>(cached ? null : url);
+  if (data != null && dataUrl !== null && !pages.has(dataUrl)) {
+    setPages(new Map(pages).set(dataUrl, extractItems(data)));
+  }
+  if (url === null) return { items: null, isLoading: false };
+  return { items: cached ?? (error ? [] : null), isLoading: !cached && !error };
 }
 
 // =============================================================================
-// Per-group renderer — one API call, server-sorted, then render cards via the
+// Per-group renderer — one API call per page, then render cards via the
 // dispatcher with per-type skeletons + per-type layout from CONTENT_REF_GROUPS.
 // =============================================================================
 
@@ -325,41 +331,33 @@ function ContentGroup({
    *  its heading too — no orphaned titles. */
   heading: React.ReactNode;
 }) {
-  const { items, isLoading } = useGroupItems(type, refs, buildUrl);
   const config = resolveGroupConfig(type);
   const isListLayout = config.layout === 'list';
   const cardSize = config.gridSize;
 
   // Per-group pagination for big groups (author pages): GROUP_PAGE_SIZE items
-  // per page with the standard Pagination control below the group. Client-side
-  // slicing — useGroupItems already fetched every row in one batched call, so
-  // page flips are instant. Hooks live above every early return (file
-  // convention). Page is clamped so a shrinking refs array (suggestion
-  // refetch) can never strand the view past the last page, and RESET when the
-  // ref set actually changes (shrink→grow must not return to a stale page).
+  // per page with the standard Pagination control below the group, each page
+  // fetched on its own. Back to page 1 whenever the ref set changes (a
+  // suggestion refetch can shrink it) — reset while rendering, so the stale
+  // page is never requested.
   const [page, setPage] = useState(1);
   const refsKey = refs.map(r => r.id).join('|');
-  const prevRefsKeyRef = useRef(refsKey);
-  useEffect(() => {
-    if (prevRefsKeyRef.current !== refsKey) {
-      prevRefsKeyRef.current = refsKey;
-      setPage(1);
-    }
-  }, [refsKey]);
+  const [pagedRefsKey, setPagedRefsKey] = useState(refsKey);
+  if (pagedRefsKey !== refsKey) {
+    setPagedRefsKey(refsKey);
+    setPage(1);
+  }
   const totalGroupPages = pageCount(refs.length, GROUP_PAGE_SIZE);
-  const safePage = Math.min(page, totalGroupPages);
-  const visibleGroupRefs =
-    refs.length > GROUP_PAGE_SIZE ? refs.slice((safePage - 1) * GROUP_PAGE_SIZE, safePage * GROUP_PAGE_SIZE) : refs;
+  const pageRefs = refs.slice((page - 1) * GROUP_PAGE_SIZE, page * GROUP_PAGE_SIZE);
+  const { items, isLoading } = useGroupItems(type, pageRefs, buildUrl);
   const groupPagination =
-    totalGroupPages > 1 ? (
-      <Pagination currentPage={safePage} totalPages={totalGroupPages} onPageChange={setPage} />
-    ) : null;
-
-  // Skeleton gate: `isLoading && !items` — SSR HTML and the client's first
-  // paint render identical skeletons (useSelfFetch starts isLoading=true on
-  // both sides), and once items exist they are never replaced by skeletons.
-  if (isLoading && !items) {
-    const skeletons = visibleGroupRefs.map(r => (
+    totalGroupPages > 1 ? <Pagination currentPage={page} totalPages={totalGroupPages} onPageChange={setPage} /> : null;
+
+  // Skeletons until this page's rows land — SSR HTML and the client's first
+  // paint render identical skeletons (useSelfFetch starts loading on both
+  // sides). The pager stays in place while an unfetched page loads.
+  if (isLoading) {
+    const skeletons = pageRefs.map(r => (
       <div key={r.id}>{renderSkeletonForType(type, cardSize, adminCampaignCard)}</div>
     ));
     return (
@@ -370,11 +368,12 @@ function ContentGroup({
         ) : (
           <div className={gridClassFor(columns)}>{skeletons}</div>
         )}
+        {groupPagination}
       </div>
     );
   }
 
-  if (!items || items.length === 0) return null;
+  if (!items) return null;
 
   // Index fetched rows by id, then render in REF order — refs carry the
   // intended sequence (suggestion mode: the engine's tier order, so
@@ -393,7 +392,7 @@ function ContentGroup({
   };
   const itemById = new Map(items.map(it => [rowKey(it), it]));
 
-  const cards = visibleGroupRefs
+  const cards = pageRefs
     .map(contentRef => {
       const itemId = String(contentRef.id);
       const item = itemById.get(itemId);
@@ -426,9 +425,9 @@ function ContentGroup({
     .filter(Boolean);
 
   if (cards.length === 0) {
-    // Current PAGE resolved zero cards (rows deleted between the ref fetch
-    // and the group fetch, or a stricter list-API gate dropped them). When a
-    // pager exists the user must keep the controls to navigate back —
+    // Current PAGE resolved zero cards (its fetch failed, rows were deleted
+    // between the ref fetch and the page fetch, or a stricter list-API gate
+    // dropped them). When a pager exists the user must keep the controls —
     // dropping the whole group would strand them. A genuinely empty group
     // (no pager) still vanishes with its heading.
     if (groupPagination) {

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

@@ -0,0 +1,84 @@
+'use client';
+
+/**
+ * Assistant runtime context: what a PAGE needs to offer the host's chat
+ * assistant ("Ask Mingo"): whether a chat is there to open, the assistant's
+ * name and glyph, where its questions are read from, and HOW the chat is
+ * opened and asked.
+ *
+ * A sibling of `ChatRuntimeContext` (which configures the chat panel itself)
+ * and `EndpointsRuntimeContext`. It is its own context because its values
+ * change with the visitor (signed in or not, chat mounted or not), and a new
+ * `ChatRuntime` identity re-renders the whole chat tree.
+ *
+ * The NEAREST provider wins, so a page region that carries its own chat (an
+ * embedded chat beside the content) mounts a provider whose `open` opens THAT
+ * chat: every "ask" surface under it (`FaqSection`'s card, `AskPrompts`,
+ * `AskCard`) then opens and fills it, with no prop on any of them.
+ *
+ * No provider, or `available: false`: the "ask" surfaces render nothing.
+ */
+
+import { createContext, useContext, type ReactNode } from 'react';
+
+/** What an "ask" surface asks the chat to do. */
+export interface AssistantOpenRequest {
+  /** A question to send once the chat is open. Absent: the chat only opens. */
+  prompt?: string;
+  /** The topic of the surface that asked (a FAQ's topic, a page section). */
+  topic?: string;
+}
+
+/** What an "ask" surface reports after a question was sent (analytics). */
+export interface AssistantAskEvent {
+  /** The id of the question that was asked. */
+  promptId: string;
+  /** The topic of the surface that asked. */
+  topic?: string;
+}
+
+/** The wording of the card beside a FAQ. `{assistant}` is replaced by the assistant's name. */
+export interface AssistantAskCardCopy {
+  title?: string;
+  description?: string;
+  /** How many questions the card offers. */
+  count?: number;
+}
+
+export interface AssistantRuntime {
+  /** A chat is mounted for this visitor: an "ask" click has something to open. */
+  available: boolean;
+  /** The assistant's configured name. */
+  name?: string | null;
+  /** The assistant's configured glyph. Absent: the packaged Mingo mark. */
+  icon?: ReactNode;
+  /** The chat source the default `open` addresses its `ask-ai:open` event to. */
+  source?: string;
+  /**
+   * GET endpoint the questions are read from:
+   *   `<url>?count=<n>&section=<topic>&exclude=<id,id>` → `{ prompts: AskPrompt[] }`
+   * `section` is ANY string: the host decides what topics exist (the hub: the
+   * `section` attribute of a quick action, set in chat config), so a new topic
+   * needs no change here. Hub: '/api/quick-actions/questions'. Absent: an "ask"
+   * surface shows its launcher with no questions.
+   */
+  askPromptsUrl?: string;
+  /**
+   * Open the chat and, with `prompt`, ask it. Absent: the `ask-ai:open` event
+   * of `source` (`openAskAi`), which the mounted `EmbeddableChat` listens for.
+   * A host whose chat is opened another way (an embedded chat, a different
+   * panel) supplies its own.
+   */
+  open?: (request: AssistantOpenRequest) => void;
+  /** After a question was sent (analytics). */
+  onAsk?: (event: AssistantAskEvent) => void;
+  /** The wording of the card beside a FAQ. Absent: the lib's own. */
+  askCard?: AssistantAskCardCopy;
+}
+
+export const AssistantRuntimeContext = createContext<AssistantRuntime | null>(null);
+
+/** The nearest assistant runtime, or null when no provider is mounted. */
+export function useAssistantRuntime(): AssistantRuntime | null {
+  return useContext(AssistantRuntimeContext);
+}

package/src/contexts/index.ts

@@ -30,4 +30,13 @@ export {
 
 export { ChatRuntimeContext, useChatRuntime, useRequiredChatRuntime, type ChatRuntime } from './chat-runtime-context';
 
+export {
+  AssistantRuntimeContext,
+  useAssistantRuntime,
+  type AssistantAskCardCopy,
+  type AssistantAskEvent,
+  type AssistantOpenRequest,
+  type AssistantRuntime,
+} from './assistant-runtime-context';
+
 export { useOuterOrDefault } from './use-outer-or-default';

package/src/hooks/use-self-fetch.ts

@@ -5,6 +5,9 @@ import { contentFetch } from '../utils/embed-content-fetch';
 
 export interface UseSelfFetchResult<T> {
   data: T | null;
+  /** The url `data` came from (`null` until something lands). While a new url
+   *  loads, `data` still holds the previous one — compare before trusting it. */
+  dataUrl: string | null;
   /** Imperatively patch the fetched data (e.g. optimistic vote updates). */
   setData: Dispatch<SetStateAction<T | null>>;
   isLoading: boolean;
@@ -48,6 +51,7 @@ export function useSelfFetch<T>(
   const initialData = options?.initialData;
   const revalidateOnVisibleAfterMs = options?.revalidateOnVisibleAfterMs;
   const [data, setData] = useState<T | null>(initialData ?? null);
+  const [dataUrl, setDataUrl] = useState<string | null>(initialData !== undefined ? url : null);
   const [isLoading, setIsLoading] = useState(initialData === undefined && url !== null);
   const [error, setError] = useState(false);
   const [reloadKey, setReloadKey] = useState(0);
@@ -78,6 +82,7 @@ export function useSelfFetch<T>(
     // `initialData` is `undefined`.
     if (syncedProps.initialData !== initialData && initialData !== undefined) {
       setData(initialData);
+      setDataUrl(url);
     }
     // Fetching just got disabled — nothing will land to clear the spinner.
     if (syncedProps.url !== url && url === null) {
@@ -101,6 +106,7 @@ export function useSelfFetch<T>(
         const json = (await res.json()) as T;
         if (!cancelled) {
           setData(json);
+          setDataUrl(url);
           dataUrlRef.current = url; // remember the url we now hold data for
           dataAtRef.current = Date.now();
         }
@@ -149,6 +155,7 @@ export function useSelfFetch<T>(
 
   return {
     data,
+    dataUrl,
     setData,
     isLoading,
     error,

package/src/utils/index.ts

@@ -17,6 +17,7 @@ export {
 // source of truth). Re-exported here so existing callers that pull from
 // the barrel keep working without changing imports.
 export { formatDate, formatNumber, formatPrice, formatBytes } from './format';
+export { TRIAL_DAYS, TRIAL_LABELS } from './trial';
 export {
   VENDOR_CLASSIFICATIONS,
   OPENFRAME_CLASSIFICATIONS,

package/src/utils/list-url.ts

@@ -116,6 +116,10 @@ const BUILDERS: Record<string, (ids: string[], base: string) => string> = {
   design_doc: (ids, b) => `${b}/api/design-docs?ids=${ids.join(',')}`,
   openframe_tenant: (ids, b) => `${b}/api/openframe-tenants?ids=${ids.join(',')}`,
   prospect_call: (ids, b) => `${b}/api/prospect-calls?ids=${ids.join(',')}`,
+  // The public website's own pages (live source; ChatRef-shaped items like the objects above).
+  site_page: (ids, b) => `${b}/api/site-pages?ids=${ids.join(',')}`,
+  // The OpenMSP vendor directory (indexed source).
+  vendor: (ids, b) => `${b}/api/vendors/cards?ids=${ids.join(',')}`,
   // Code intelligence — per-object card hydration, same `handleEntityCardList`
   // shape as the internal objects above.
   code_rule: (ids, b) => `${b}/api/code-rules/cards?ids=${ids.join(',')}`,