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

package/src/components/chat/hooks/index.ts

@@ -39,3 +39,15 @@ export * from './use-embedded-chat';
 // `ChatRuntime.endpoints`, so hub vs. embedders share one image-proxy
 // resolver.
 export * from './use-proxied-image-url';
+export {
+  ASK_PROMPTS_DEFAULT_COUNT,
+  assistantAvailable,
+  buildAskPromptsUrl,
+  useAskPrompts,
+  useAssistantOpen,
+  useShownAskPromptIds,
+  useShownAskPrompts,
+  type AskPromptsResponse,
+  type UseAskPromptsOptions,
+  type UseAskPromptsResult,
+} from './use-ask-prompts';

package/src/components/chat/hooks/use-ask-prompts.ts

@@ -0,0 +1,188 @@
+'use client';
+
+import { useCallback, useId, useLayoutEffect, useSyncExternalStore } from 'react';
+import {
+  useAssistantRuntime,
+  type AssistantOpenRequest,
+  type AssistantRuntime,
+} from '../../../contexts/assistant-runtime-context';
+import { useSelfFetch } from '../../../hooks/use-self-fetch';
+import { openAskAi } from '../../navigation/mingo-ai-button';
+import type { AskPrompt } from '../ask-prompts';
+
+/** The answer of a host's questions endpoint (`AssistantRuntime.askPromptsUrl`). */
+export interface AskPromptsResponse {
+  prompts: AskPrompt[];
+}
+
+/** How many questions an "ask" surface offers when nothing states a number. */
+export const ASK_PROMPTS_DEFAULT_COUNT = 3;
+
+/** The questions URL: the host's endpoint with the surface's count, topic and exclusions. */
+export function buildAskPromptsUrl(
+  base: string,
+  { count, topic, exclude = [] }: { count: number; topic?: string; exclude?: readonly string[] },
+): string {
+  const params = new URLSearchParams({ count: String(count) });
+  if (topic) params.set('section', topic);
+  if (exclude.length > 0) params.set('exclude', exclude.join(','));
+  return `${base}${base.includes('?') ? '&' : '?'}${params.toString()}`;
+}
+
+/** An "ask" surface has something to open: a runtime is mounted and its chat is there. */
+export function assistantAvailable(assistant: AssistantRuntime | null): assistant is AssistantRuntime {
+  return !!assistant?.available;
+}
+
+export interface UseAskPromptsOptions {
+  /**
+   * What the surface is about: ANY string the host's endpoint knows (sent as
+   * `section`). Questions written for it are picked first. Absent: general ones.
+   */
+  topic?: string;
+  count?: number;
+  /** Ids of questions never to pick (the ones the page already shows). */
+  exclude?: readonly string[];
+  /** False: nothing is fetched yet (the surface is not ready to pick). Default true. */
+  enabled?: boolean;
+}
+
+export interface UseAskPromptsResult {
+  prompts: AskPrompt[];
+  /** True until the pick has landed (or failed). False where nothing is fetched. */
+  isLoading: boolean;
+  /** The host has a questions endpoint and a chat to ask: questions can exist here. */
+  supported: boolean;
+}
+
+/**
+ * The questions an "ask" surface offers, picked by the HOST for this visit
+ * (`AssistantRuntime.askPromptsUrl`). One pick per mount: read once, never
+ * cached, so a visitor keeps the same questions while the page is open and
+ * gets a new pick next time. A failed read leaves the list empty. No chat, or
+ * no endpoint: nothing is fetched and the list is empty.
+ */
+export function useAskPrompts({
+  topic,
+  count = ASK_PROMPTS_DEFAULT_COUNT,
+  exclude,
+  enabled = true,
+}: UseAskPromptsOptions = {}): UseAskPromptsResult {
+  const assistant = useAssistantRuntime();
+  const base = assistantAvailable(assistant) ? assistant.askPromptsUrl : undefined;
+  const url = base && enabled ? buildAskPromptsUrl(base, { count, topic, exclude }) : null;
+  const { data, isLoading } = useSelfFetch<AskPromptsResponse>(url);
+  return { prompts: data?.prompts ?? [], isLoading: !!base && (!enabled || isLoading), supported: !!base };
+}
+
+/**
+ * How an "ask" surface opens the chat and asks it: its own `onOpen`, else the
+ * nearest assistant runtime's `open`, else the `ask-ai:open` event of the
+ * runtime's source (the mounted `EmbeddableChat`). The surface's topic rides
+ * every request, so a host with several chats can tell them apart.
+ */
+export function useAssistantOpen(
+  topic?: string,
+  onOpen?: (request: AssistantOpenRequest) => void,
+): (request: { prompt?: string }) => void {
+  const assistant = useAssistantRuntime();
+  const runtimeOpen = assistant?.open;
+  const source = assistant?.source;
+  return useCallback(
+    (request: { prompt?: string }) => {
+      const full: AssistantOpenRequest = { ...request, topic };
+      if (onOpen) onOpen(full);
+      else if (runtimeOpen) runtimeOpen(full);
+      else openAskAi(source, request);
+    },
+    [onOpen, runtimeOpen, source, topic],
+  );
+}
+
+// ─── The questions the page already shows ────────────────────────────────────
+// Every surface that shows questions says which ones (`useShownAskPrompts`), so
+// a later surface (the FAQ's card) never repeats one, with no wiring by the
+// host. One list per QUESTIONS ENDPOINT (the runtime's `askPromptsUrl`): two
+// assistants on one page read different questions, and never leave out each
+// other's ids. A module store, read through React's external-store hook.
+// `null` for a surface = it is still picking.
+
+const NO_IDS: readonly string[] = [];
+
+/** One endpoint's list: which questions each surface shows, and who is listening. */
+interface ShownList {
+  set(surface: string, ids: readonly string[] | null): void;
+  remove(surface: string): void;
+  subscribe(listener: () => void): () => void;
+  read(): readonly string[] | null;
+}
+
+function createShownList(): ShownList {
+  const bySurface = new Map<string, readonly string[] | null>();
+  const listeners = new Set<() => void>();
+  let snapshot: readonly string[] | null = NO_IDS;
+  const publish = (): void => {
+    const lists = [...bySurface.values()];
+    const next = lists.some(list => list === null) ? null : lists.flatMap(list => list ?? []);
+    const same = next === null ? snapshot === null : snapshot !== null && next.join(',') === snapshot.join(',');
+    if (same) return;
+    snapshot = next === null ? null : next.length > 0 ? next : NO_IDS;
+    for (const listener of listeners) listener();
+  };
+  return {
+    set(surface, ids) {
+      bySurface.set(surface, ids);
+      publish();
+    },
+    remove(surface) {
+      bySurface.delete(surface);
+      publish();
+    },
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    read: () => snapshot,
+  };
+}
+
+const shownLists = new Map<string, ShownList>();
+
+/** The list a surface belongs to: the questions endpoint of its assistant runtime. */
+function useShownList(): ShownList {
+  const scope = useAssistantRuntime()?.askPromptsUrl ?? '';
+  let list = shownLists.get(scope);
+  if (!list) {
+    list = createShownList();
+    shownLists.set(scope, list);
+  }
+  return list;
+}
+
+/**
+ * Say which questions this surface shows. `null`: it is still picking, so a
+ * surface that must not repeat them waits. Pass `undefined` to say nothing
+ * (the surface shows no questions here).
+ */
+export function useShownAskPrompts(ids: readonly string[] | null | undefined): void {
+  const surface = useId();
+  const list = useShownList();
+  const key = ids === undefined ? undefined : ids === null ? null : ids.join(',');
+  // A layout effect: the list holds this surface before any reader's own effects run.
+  useLayoutEffect(() => {
+    if (key === undefined) return undefined;
+    list.set(surface, key === null ? null : key ? key.split(',') : NO_IDS);
+    return () => list.remove(surface);
+  }, [list, surface, key]);
+}
+
+/** The ids of the questions the page's other surfaces of the same assistant show; `null` while one is still picking. */
+export function useShownAskPromptIds(): readonly string[] | null {
+  const list = useShownList();
+  return useSyncExternalStore(list.subscribe, list.read, () => NO_IDS);
+}
+
+/** Tests only: forget every surface. */
+export function resetShownAskPrompts(): void {
+  shownLists.clear();
+}

package/src/components/chat/index.ts

@@ -24,6 +24,7 @@ export * from './chat-message-skeleton';
 
 export * from './quick-action-chip';
 export * from './ask-prompts';
+export * from './assistant-ask-prompts';
 export * from './quick-action-marquee';
 export * from './quick-action-wall';
 export * from './chat-ticket-list';

package/src/components/chat/utils/icon-library.tsx

@@ -91,6 +91,11 @@ const OpenmspLogoIcon: IconComponent = ({ size = 16, className }) => (
   />
 );
 const FlamingoLogoIcon = sizedLogo(FlamingoLogo);
+// The same mark as a GLYPH: it takes the colour of the slot it sits in, like every icon beside it (a source
+// chip, a command row, a card), where the brand pink would be the one coloured icon in the list.
+const FlamingoLogoGreyIcon: IconComponent = ({ size = 16, className, color }) => (
+  <FlamingoLogo className={className} fill={color ?? 'currentColor'} style={{ width: size, height: size }} />
+);
 // The two community marks size themselves through a `size` prop, the resolver's own contract.
 // Major League GitHub draws its mark in the theme's text colour on its own site
 // (its header, hero and footer), never in an accent: so does every glyph of it.
@@ -174,6 +179,7 @@ export const ICON_ALIASES: Record<string, IconComponent> = {
   'tmcg-logo': TmcgLogoIcon,
   flamingo: FlamingoLogoIcon,
   'flamingo-logo': FlamingoLogoIcon,
+  'flamingo-logo-grey': FlamingoLogoGreyIcon,
   megaphone: Megaphone,
   bell: Bell,
   info: Info,

package/src/components/faq/faq-ask-card.tsx

@@ -0,0 +1,115 @@
+'use client';
+
+import { useMemo, useState } from 'react';
+import {
+  AssistantRuntimeContext,
+  useAssistantRuntime,
+  type AssistantOpenRequest,
+  type AssistantRuntime,
+} from '../../contexts/assistant-runtime-context';
+import { useInView } from '../../hooks/ui/use-in-view';
+import { AskCard } from '../chat/ask-prompts';
+import {
+  assistantAvailable,
+  ASK_PROMPTS_DEFAULT_COUNT,
+  useAskPrompts,
+  useAssistantOpen,
+  useShownAskPromptIds,
+} from '../chat/hooks/use-ask-prompts';
+
+/** The card beside a FAQ, as a host may shape it. Every field is optional. */
+export interface FaqAskOptions {
+  /**
+   * What this FAQ is about: ANY string the host's questions endpoint knows (it
+   * is sent as `section`, and reported with every click). Questions written
+   * for the topic are picked first. Whoever renders the FAQ passes it. Absent:
+   * the entity the FAQ is attached to (`FaqSection`'s `entityType`). With
+   * neither, the FAQ has no card: the lib names no topic of its own.
+   */
+  topic?: string;
+  /**
+   * Ids of questions never to offer. Absent: the ones the page's other "ask"
+   * surfaces show (`AssistantAskPrompts` rows say so themselves), which the
+   * card waits for. `null`: wait.
+   */
+  exclude?: readonly string[] | null;
+  /** How many questions the card offers. Absent: the runtime's, else three. */
+  count?: number;
+  /** The card's wording. `{assistant}` is replaced by the assistant's name. Absent: the runtime's, else the lib's. */
+  title?: string;
+  description?: string;
+  /**
+   * How the chat is opened and asked from THIS card. Absent: the assistant
+   * runtime's `open`, else the `ask-ai:open` event of its source. A FAQ that
+   * sits beside its own chat (an embedded one) passes that chat's opener.
+   */
+  onOpen?: (request: AssistantOpenRequest) => void;
+}
+
+/** The lib's own wording, when neither the host nor the runtime states it. */
+const DEFAULT_ASK_CARD = {
+  title: 'Still deciding?',
+  description: '{assistant} answers from our docs and customer stories.',
+} as const;
+
+/** How far below the viewport the card is when it picks its questions. */
+const PICK_ROOT_MARGIN = '600px';
+
+const fillAssistant = (text: string, name: string) => text.split('{assistant}').join(name);
+
+/** True when a FAQ under this runtime shows the card: a chat to open, and a name for the card's words. */
+export function faqAskCardShown(assistant: AssistantRuntime | null): assistant is AssistantRuntime {
+  return assistantAvailable(assistant) && !!assistant.name;
+}
+
+/**
+ * The "ask the assistant" card of a FAQ: the assistant's identity and the
+ * chat's opener from the nearest assistant runtime, its questions from the
+ * host's endpoint. It picks ONCE, when the card first comes near the viewport:
+ * by then the page above has said which questions it shows itself, and a
+ * visitor who never reaches the FAQ costs no request. The card is the same
+ * height before and after the questions arrive. A host with no questions
+ * endpoint gets the launcher with no questions.
+ */
+export function FaqAskCard({ topic, exclude, count, title, description, onOpen }: FaqAskOptions & { topic: string }) {
+  const assistant = useAssistantRuntime();
+  const { ref, inView } = useInView<HTMLDivElement>({ rootMargin: PICK_ROOT_MARGIN });
+  const [reached, setReached] = useState(false);
+  if (inView && !reached) setReached(true);
+
+  const shownElsewhere = useShownAskPromptIds();
+  const excluded = exclude === undefined ? shownElsewhere : exclude;
+  const slots = count ?? assistant?.askCard?.count ?? ASK_PROMPTS_DEFAULT_COUNT;
+  const { prompts, isLoading, supported } = useAskPrompts({
+    topic,
+    count: slots,
+    exclude: excluded ?? undefined,
+    enabled: reached && excluded !== null,
+  });
+  const open = useAssistantOpen(topic, onOpen);
+  // The card's launcher opens the same chat as its questions, with the card's topic: it reads the runtime.
+  const scoped = useMemo(() => (assistant ? { ...assistant, open } : null), [assistant, open]);
+
+  if (!faqAskCardShown(assistant) || !assistant.name) return null;
+  const name = assistant.name;
+  const cardDescription = description ?? assistant.askCard?.description ?? DEFAULT_ASK_CARD.description;
+  return (
+    <AssistantRuntimeContext.Provider value={scoped}>
+      <div ref={ref}>
+        <AskCard
+          title={fillAssistant(title ?? assistant.askCard?.title ?? DEFAULT_ASK_CARD.title, name)}
+          description={cardDescription ? fillAssistant(cardDescription, name) : undefined}
+          prompts={prompts}
+          // Fixed slots, one question per row: chip skeletons until the pick lands, the same box after.
+          count={supported ? slots : 0}
+          loading={isLoading}
+          source={assistant.source}
+          label={name}
+          icon={assistant.icon}
+          onOpen={open}
+          onAsk={prompt => assistant.onAsk?.({ promptId: prompt.id, topic })}
+        />
+      </div>
+    </AssistantRuntimeContext.Provider>
+  );
+}

package/src/components/faq/faq-document-page.tsx

@@ -23,7 +23,7 @@
 import { useRouter } from '../../embed-shims/next-navigation';
 import type { Faq } from '../../types/faq';
 import { PageShell, PageLayout } from '../ui';
-import { FaqSection } from './faq-section';
+import { FaqSection, type FaqSectionProps } from './faq-section';
 import type { FaqSchemaOptions } from './json-ld';
 
 export interface FaqDocumentPageProps {
@@ -54,6 +54,9 @@ export interface FaqDocumentPageProps {
   entityId?: number | string;
   /** Minimum FAQ count before the section renders (forwarded to `FaqSection`). */
   minResults?: number;
+  /** The "ask the assistant" card beside the questions (forwarded to `FaqSection`): `false` switches it off, an
+   *  object states its topic, wording and the chat it opens. */
+  ask?: FaqSectionProps['ask'];
 }
 
 export function FaqDocumentPage({
@@ -67,6 +70,7 @@ export function FaqDocumentPage({
   entityType,
   entityId,
   minResults,
+  ask,
   shell = true,
 }: FaqDocumentPageProps) {
   const router = useRouter();
@@ -93,6 +97,7 @@ export function FaqDocumentPage({
         entityType={entityType}
         entityId={entityId}
         minResults={minResults}
+        ask={ask}
       />
     </PageLayout>
   );

package/src/components/faq/faq-section.tsx

@@ -2,6 +2,7 @@
 
 import type React from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useAssistantRuntime } from '../../contexts/assistant-runtime-context';
 import Link from '../../embed-shims/next-link';
 import { useScrollToHash } from '../../hooks/use-scroll-to-hash';
 import { useSelfFetch } from '../../hooks/use-self-fetch';
@@ -13,6 +14,7 @@ import { navigateSamePageHash, STICKY_HEADER_OFFSET_PX } from '../../utils/same-
 import { buildSuggestionUrl } from '../../utils/suggestion-url';
 import { FaqAccordion, type FaqItem } from '../faq-accordion';
 import { SECTION_HEADING_CLASS } from '../layout/page-heading';
+import { FaqAskCard, faqAskCardShown, type FaqAskOptions } from './faq-ask-card';
 import { buildFaqJsonLdFromFaqs, type FaqSchemaOptions } from './json-ld';
 
 export interface FaqSectionProps {
@@ -48,12 +50,24 @@ export interface FaqSectionProps {
    *  ('' = same-origin relative). */
   apiBaseUrl?: string;
   /**
-   * A block beside the questions (an "ask the assistant" card). From the
-   * content `lg` step the heading, the category nav and this block form a left
-   * column and the questions the right one; below it the block follows the
-   * questions. Absent: the single-column layout, unchanged.
+   * A block beside the questions, in place of the "ask the assistant" card.
+   * From the content `lg` step the heading, the category nav and this block
+   * form a left column and the questions the right one; below it the block
+   * follows the questions.
    */
   aside?: React.ReactNode;
+  /**
+   * The "ask the assistant" card beside the questions. Shown wherever the
+   * host's assistant runtime says a chat is there to open
+   * (`AssistantRuntimeContext`: its name, glyph, questions endpoint and
+   * opener) AND the FAQ has a topic: `ask.topic` (any string the host's
+   * questions endpoint knows), else the `entityType` the FAQ is attached to.
+   * No runtime or no topic: the FAQ is the single column it always was; the
+   * lib names no topic of its own. `false` switches the card off; the object
+   * also states the questions to leave out, the wording and the chat it opens
+   * (`onOpen`). An `aside` takes the card's place.
+   */
+  ask?: false | FaqAskOptions;
 }
 
 const DEFAULT_HEADING_TEXT = 'Frequently Asked Questions';
@@ -392,8 +406,16 @@ export function FaqSection({
   className,
   minResults,
   apiBaseUrl = '',
-  aside,
+  aside: asideProp,
+  ask,
 }: FaqSectionProps) {
+  const assistant = useAssistantRuntime();
+  // The host's own block wins; else the card, where a chat is there to open and the FAQ has a topic
+  // (an empty topic is no topic, as the questions request reads it).
+  const askTopic = ask === false ? undefined : ask?.topic || entityType;
+  const aside =
+    asideProp ??
+    (ask !== false && askTopic && faqAskCardShown(assistant) ? <FaqAskCard {...ask} topic={askTopic} /> : undefined);
   const url = buildFaqsUrl(entityType, entityId, minResults, apiBaseUrl);
   // Memoized — useSelfFetch re-syncs on [initialData]; a fresh per-render
   // wrapper object would setState-loop under re-rendering parents.

package/src/components/faq/index.ts

@@ -11,3 +11,4 @@
 // block and exposed via "./components/faq/json-ld" in package.json#exports.)
 export { FaqSection, type FaqSectionProps } from './faq-section';
 export { FaqDocumentPage, type FaqDocumentPageProps } from './faq-document-page';
+export { FaqAskCard, type FaqAskOptions } from './faq-ask-card';

package/src/components/features/auth/auth-benefits-panel.tsx

@@ -2,6 +2,7 @@
 
 import type { ReactNode } from 'react';
 import { cn } from '../../../utils/cn';
+import { TRIAL_LABELS } from '../../../utils/trial';
 import { OpenFrameLogo } from '../../icons';
 import { FileOffIcon } from '../../icons-v2-generated/documents/file-off-icon';
 import { CreditCardXmarkIcon } from '../../icons-v2-generated/finance/credit-card-xmark-icon';
@@ -29,10 +30,10 @@ const DEFAULT_DESCRIPTION =
   'All your core ops in one place - built for MSPs who are done duct-taping tools together. Unified stack, AI-ready, no vendor tax. Just solid software that lets you run lean and fast.';
 
 const DEFAULT_BENEFITS: AuthBenefit[] = [
-  { icon: <CreditCardXmarkIcon />, label: 'No card required' },
-  { icon: <XmarkAltIcon />, label: 'Cancel Anytime' },
-  { icon: <FlaskVialIcon />, label: '14 day free trial' },
-  { icon: <FileOffIcon />, label: 'No Contract' },
+  { icon: <CreditCardXmarkIcon />, label: TRIAL_LABELS.noCard },
+  { icon: <XmarkAltIcon />, label: TRIAL_LABELS.cancel },
+  { icon: <FlaskVialIcon />, label: TRIAL_LABELS.length },
+  { icon: <FileOffIcon />, label: TRIAL_LABELS.noContract },
 ];
 
 /**

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/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);
+}