@flamingo-stack/openframe-frontend-core 0.0.725 → 0.0.727

package/src/components/chat/assistant-ask-prompts.tsx

@@ -1,74 +1,119 @@
 'use client';
 
-import { useMemo } from 'react';
 import {
   AssistantRuntimeContext,
   useAssistantRuntime,
   type AssistantOpenRequest,
 } from '../../contexts/assistant-runtime-context';
-import { AskPrompts, type AskPromptsProps } from './ask-prompts';
-import {
-  assistantAvailable,
-  ASK_PROMPTS_DEFAULT_COUNT,
-  useAskPrompts,
-  useAssistantOpen,
-  useShownAskPrompts,
-} from './hooks/use-ask-prompts';
+import { AskCard, AskPrompts, type AskPromptsProps } from './ask-prompts';
+import { assistantAvailable, ASK_PROMPTS_DEFAULT_COUNT, useAskSurface } from './hooks/use-ask-prompts';
+
+/** The lib's own wording of the card, 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;
+
+const fillAssistant = (text: string, name: string) => text.split('{assistant}').join(name);
 
 export interface AssistantAskPromptsProps extends Pick<AskPromptsProps, 'align' | 'fadeColor' | 'className'> {
-  /** What this row is about: any string the host's questions endpoint knows. Reported with every click. */
+  /**
+   * How the surface looks. `row` (default): the launcher, then the questions,
+   * for a page section. `card`: the "still deciding?" card beside a list of
+   * questions (a FAQ), with a title, a line of description and the launcher.
+   */
+  variant?: 'row' | 'card';
+  /** What this surface is about: any string the host's questions endpoint knows. Reported with every click. */
   topic?: string;
-  /** How many questions the row offers: the same number of slots on every load. */
+  /** How many questions it offers: the same number of slots on every load. Absent: three (a card: the runtime's, else three). */
   count?: number;
+  /**
+   * Ids of questions never to offer. Absent: the ones the page's other "ask"
+   * surfaces show, which this one waits for. `null`: wait.
+   */
+  exclude?: readonly string[] | null;
+  /** False: the surface does not pick yet (its host is waiting for it to be reached). Default true. */
+  enabled?: boolean;
   /** The launcher's name. Absent: the assistant's configured name, else the launcher's default. */
   label?: string;
-  /** Something else the row waits for (the host is still reading the name it will show). */
+  /** Something else the surface waits for (the host is still reading the name it will show). */
   loading?: boolean;
-  /** How the chat is opened from THIS row. Absent: the assistant runtime's opener. */
+  /** A 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 from THIS surface. Absent: the assistant runtime's opener. */
   onOpen?: (request: AssistantOpenRequest) => void;
 }
 
 /**
- * A row of questions for the host's assistant, wired by itself: the launcher
- * with the assistant's name and glyph, then the questions the host picked for
- * this row's `topic`, each opening the chat and asking it. Everything comes
- * from the nearest assistant runtime (`AssistantRuntimeContext`): whether a
- * chat is there, the identity, the questions endpoint and the opener. While
- * the pick is on its way the row is the SAME block (a chip skeleton in every
- * slot), so nothing moves when the questions land. The row tells the page
- * which questions it shows, so the FAQ's card never repeats one. Nothing
- * renders with no chat, or once the pick has settled empty.
+ * THE "ask the assistant" surface, wired by itself: a row of questions in a
+ * page section, or the card beside a FAQ (`variant`). Everything comes from
+ * the nearest assistant runtime (`AssistantRuntimeContext`) through ONE hook,
+ * `useAskSurface`: whether a chat is there, the identity, the questions the
+ * host picked for this surface's `topic`, the opener and the click report.
+ * Surfaces of one page pick one after another and never show a question
+ * another already shows, so two of them may share a topic. While a pick is on
+ * its way the surface is the SAME block (a chip skeleton in every slot), so
+ * nothing moves when the questions land.
+ *
+ * Nothing renders with no chat. A row also renders nothing with no questions
+ * endpoint, or once its pick has settled empty; a card needs the assistant's
+ * name for its words, and with no endpoint is the launcher alone.
  */
 export function AssistantAskPrompts({
+  variant = 'row',
   topic,
-  count = ASK_PROMPTS_DEFAULT_COUNT,
+  count,
+  exclude,
+  enabled,
   label,
   loading = false,
+  title,
+  description,
   onOpen,
   align,
   fadeColor,
   className,
 }: AssistantAskPromptsProps) {
+  const card = variant === 'card';
   const assistant = useAssistantRuntime();
-  const { prompts, isLoading, supported } = useAskPrompts({ topic, count });
-  const open = useAssistantOpen(topic, onOpen);
-  const shown = assistantAvailable(assistant) && supported;
-  // Nothing to say where the row shows nothing; `null` while its pick is on its way.
-  useShownAskPrompts(shown ? (isLoading ? null : prompts.map(prompt => prompt.id)) : undefined);
-  // The row's launcher opens the same chat as its questions, with the row's topic: it reads the runtime.
-  const scoped = useMemo(() => (assistant ? { ...assistant, open } : null), [assistant, open]);
-  if (!assistantAvailable(assistant) || !supported) return null;
+  const slots = count ?? (card ? assistant?.askCard?.count : undefined) ?? ASK_PROMPTS_DEFAULT_COUNT;
+  const ask = useAskSurface({ topic, count: slots, exclude, enabled, onOpen });
+  if (!assistantAvailable(assistant)) return null;
+
+  const shared = {
+    prompts: ask.prompts,
+    loading: ask.isLoading || loading,
+    source: assistant.source,
+    icon: assistant.icon,
+    onOpen: ask.open,
+    onAsk: ask.reportAsk,
+  };
+  if (card) {
+    const name = label ?? assistant.name;
+    if (!name) return null;
+    const words = description ?? assistant.askCard?.description ?? DEFAULT_ASK_CARD.description;
+    return (
+      <AssistantRuntimeContext.Provider value={ask.scoped}>
+        <AskCard
+          {...shared}
+          title={fillAssistant(title ?? assistant.askCard?.title ?? DEFAULT_ASK_CARD.title, name)}
+          description={words ? fillAssistant(words, name) : undefined}
+          // Fixed slots, one question per row: chip skeletons until the pick lands, the same box after.
+          count={ask.supported ? slots : 0}
+          label={name}
+          className={className}
+        />
+      </AssistantRuntimeContext.Provider>
+    );
+  }
+  if (!ask.supported) return null;
   return (
-    <AssistantRuntimeContext.Provider value={scoped}>
+    <AssistantRuntimeContext.Provider value={ask.scoped}>
       <AskPrompts
-        prompts={prompts}
-        loading={isLoading || loading}
-        count={count}
-        source={assistant.source}
+        {...shared}
+        count={slots}
         label={label ?? assistant.name ?? undefined}
-        icon={assistant.icon}
-        onOpen={open}
-        onAsk={prompt => assistant.onAsk?.({ promptId: prompt.id, topic })}
         align={align}
         fadeColor={fadeColor}
         className={className}

package/src/components/chat/entity-cards/dispatch.tsx

@@ -61,29 +61,14 @@ import { MingoIcon } from '../../icons';
 import { ArrowRightUpIcon } from '../../icons-v2-generated/arrows/arrow-right-up-icon';
 import { ClickupLogoIcon } from '../../icons-v2-generated/brand-logos/clickup-logo-icon';
 import { SlackLogoGreyIcon } from '../../icons-v2-generated/brand-logos/slack-logo-grey-icon';
-import { ChartBar01VerIcon } from '../../icons-v2-generated/charts/chart-bar-01-ver-icon';
-import { ChartPieIcon } from '../../icons-v2-generated/charts/chart-pie-icon';
 import { PresentationBarIcon } from '../../icons-v2-generated/charts/presentation-bar-icon';
 import { PresentationLineIcon } from '../../icons-v2-generated/charts/presentation-line-icon';
-import { BracketCurlyCheckIcon } from '../../icons-v2-generated/coding/bracket-curly-check-icon';
 import { CodeIcon } from '../../icons-v2-generated/coding/code-icon';
-import { CodeSquareIcon } from '../../icons-v2-generated/coding/code-square-icon';
-import { CodingBranchIcon } from '../../icons-v2-generated/coding/coding-branch-icon';
 import { CodingCommitIcon } from '../../icons-v2-generated/coding/coding-commit-icon';
-import { CodingMergeIcon } from '../../icons-v2-generated/coding/coding-merge-icon';
 import { CodingPullRequestIcon } from '../../icons-v2-generated/coding/coding-pull-request-icon';
-import { PackageIcon } from '../../icons-v2-generated/coding/package-icon';
-import { CallIcon } from '../../icons-v2-generated/communication/call-icon';
-import { ChatQuoteIcon } from '../../icons-v2-generated/communication/chat-quote-icon';
 import { CalendarIcon } from '../../icons-v2-generated/date-and-time/calendar-icon';
-import { ClipboardListIcon } from '../../icons-v2-generated/documents/clipboard-list-icon';
-import { Copy01Icon } from '../../icons-v2-generated/documents/copy-01-icon';
-import { FileCodeIcon } from '../../icons-v2-generated/documents/file-code-icon';
 import { FileContentIcon } from '../../icons-v2-generated/documents/file-content-icon';
 import { NewspaperIcon } from '../../icons-v2-generated/documents/newspaper-icon';
-import { BankIcon } from '../../icons-v2-generated/finance/bank-icon';
-import { CoinsExchangeCurrencyIcon } from '../../icons-v2-generated/finance/coins-exchange-currency-icon';
-import { MoneyBillDollarIcon } from '../../icons-v2-generated/finance/money-bill-dollar-icon';
 import { MicrophoneIcon } from '../../icons-v2-generated/household/microphone-icon';
 import { AlertTriangleIcon } from '../../icons-v2-generated/interface/alert-triangle-icon';
 import { EyeIcon } from '../../icons-v2-generated/interface/eye-icon';
@@ -113,10 +98,9 @@ import { resolveCardDestination } from '../utils/card-destination';
 import { resolveHrefForRuntime } from '../utils/chat-nav-resolution';
 import { executeNavigation } from '../utils/execute-navigation';
 import { clickupTaskUrl } from '../utils/external-app-urls';
-import { resolveIcon } from '../utils/icon-library';
 import { computeIsNewTab, buildAnchorProps } from '../utils/nav-anchor-props';
 import { readFetchedCardTitle } from '../utils/resolve-fetched-card-href';
-import { getSourceLabel, SOURCE_ICON_NAMES } from '../utils/source-icons';
+import { defaultTableIdForDocumentType, getSourceLabel, SOURCE_ICON_NAMES } from '../utils/source-icons';
 import { resolveSourceIcon, sourceRowCtxFromRuntime } from '../utils/source-row-cta';
 import { BlockCard } from './block-card';
 import { BlogCardSkeleton } from './blog-card';
@@ -1393,18 +1377,16 @@ function refHydratedEntry(
   };
 }
 
+/** The leading glyph carries the type signal (the badge pill is dropped); it is the SOURCE's icon (`sourceGlyph`). */
 interface FinancialCardConfig {
   label: string;
-  /** Per-type leading glyph — carries the type signal now that the
-   *  badge pill is dropped. */
-  icon: () => React.ReactNode;
 }
 const FINANCIAL_CARD_CONFIGS: Record<string, FinancialCardConfig> = {
-  financial_kpi: { label: 'Financial KPI', icon: () => <ChartBar01VerIcon size={24} /> },
-  cap_table: { label: 'Cap table entry', icon: () => <ChartPieIcon size={24} /> },
-  profit_loss: { label: 'P&L period', icon: () => <MoneyBillDollarIcon size={24} /> },
-  balance_sheet: { label: 'Balance sheet', icon: () => <BankIcon size={24} /> },
-  cash_flow: { label: 'Cash flow', icon: () => <CoinsExchangeCurrencyIcon size={24} /> },
+  financial_kpi: { label: 'Financial KPI' },
+  cap_table: { label: 'Cap table entry' },
+  profit_loss: { label: 'P&L period' },
+  balance_sheet: { label: 'Balance sheet' },
+  cash_flow: { label: 'Cash flow' },
 };
 /** Expand a per-family config map into registry entries — ONE loop shell
  *  for every card family (financial, github, program, roadmap); adding a
@@ -1423,7 +1405,7 @@ function financialRegistryEntries(): Record<string, ChatCardRegistryEntry> {
     refHydratedEntry(docType, cfg.label, (displayRef, opts) => (
       <GenericFinancialChatCard
         chatRef={displayRef}
-        icon={cfg.icon()}
+        icon={sourceGlyph(docType)}
         isNewTab={opts.isNewTab}
         discuss={opts.discuss}
       />
@@ -1463,11 +1445,13 @@ const GITHUB_CARD_CONFIGS: Record<string, GitHubCardConfig> = {
 interface GlyphCardConfig {
   label: string;
   /**
-   * The card's leading glyph. It is handed the hydrated ref, so a type whose
-   * records carry their own mark (a vendor's logo, a page's menu icon) draws
-   * that and keeps a generic glyph for a record without one.
+   * ONLY for a type whose records carry their own mark (a vendor's logo, a
+   * page's menu icon): it is handed the hydrated ref and draws that mark.
+   * Every other type leaves it out and gets its SOURCE's icon
+   * (`sourceGlyph`): the one `SOURCE_ICON_NAMES` entry its chip draws too, so
+   * a card and its chip can never show different icons.
    */
-  icon: (ref?: ChatRef) => React.ReactNode;
+  icon?: (ref?: ChatRef) => React.ReactNode;
   /**
    * Video-bearing ref types: render the media card (cover from the ref's
    * `metadata.videoPoster`, else the host's OG placeholder; the type label as the
@@ -1481,41 +1465,51 @@ interface GlyphCardConfig {
  *  (`/api/design-docs`, `/api/openframe-tenants`, `/api/prospect-calls` — ChatRef-shaped items,
  *  same preset as github / slack). Adding one = one line here + the
  *  `list-url.ts` builder + the `source-icons.ts` label / icon / type entries. */
-/** The OpenFrame logo every OpenFrame surface uses (the `openframe` icon name). */
-const OpenFrameGlyph = resolveIcon('openframe');
 const REF_GLYPH_CARD_CONFIGS: Record<string, GlyphCardConfig> = {
-  openframe_tenant: { label: 'OpenFrame tenant', icon: () => <OpenFrameGlyph size={24} /> },
-  prospect_call: { label: 'Prospect call', icon: () => <CallIcon size={24} />, media: true },
+  openframe_tenant: { label: 'OpenFrame tenant' },
+  prospect_call: { label: 'Prospect call', media: true },
   // Code intelligence (product-hub internal): the review rules a repository is
   // held to, the repositories themselves, and one row per deployment
   // environment. Glyph cards like their siblings — none of the three has a
   // cover image, and a rule is read in the admin screen it links to.
-  code_rule: { label: 'Code rule', icon: () => <BracketCurlyCheckIcon size={24} /> },
-  code_repo: { label: 'Repository', icon: () => <CodingBranchIcon size={24} /> },
-  code_deployment: { label: 'Deployment', icon: () => <PackageIcon size={24} /> },
+  code_rule: { label: 'Code rule' },
+  code_repo: { label: 'Repository' },
+  code_deployment: { label: 'Deployment' },
   // The graph's own objects: one source file's public surface, one public
   // symbol, a near-duplicate cluster, and a pull request's blast radius.
   // Glyph cards for the same reason as their three siblings — none carries a
   // cover image, and each links to the admin screen that renders it in full.
-  code_file: { label: 'Code file', icon: () => <FileCodeIcon size={24} /> },
-  code_symbol: { label: 'Code symbol', icon: () => <CodeSquareIcon size={24} /> },
-  code_duplicate: { label: 'Duplicate code', icon: () => <Copy01Icon size={24} /> },
-  code_impact: { label: 'Change impact', icon: () => <CodingPullRequestIcon size={24} /> },
+  code_file: { label: 'Code file' },
+  code_symbol: { label: 'Code symbol' },
+  code_duplicate: { label: 'Duplicate code' },
+  code_impact: { label: 'Change impact' },
   // A change set: pull requests across repositories declared as one change, with the ClickUp tasks and design
   // docs its pull requests are attached to. ONE card for it wherever a set is shown (chat, a design doc's page).
-  change_set: { label: 'Change set', icon: () => <CodingMergeIcon size={24} /> },
+  change_set: { label: 'Change set' },
   // A page of the public website (pricing, product, legal, and every page the navigation lists), read live
   // from the data the page shows. A glyph card: a page has no cover of its own, and the card opens the page.
   site_page: { label: 'Website page', icon: ref => <SitePageGlyph iconName={refText(ref, 'icon_name')} /> },
   // What OpenFrame charges, read live from its billing: the plan in force, or one AI model's token exchange
   // rate. A glyph card; it opens the pricing page.
-  openframe_price: { label: 'OpenFrame price', icon: () => <OpenFrameGlyph size={24} /> },
+  openframe_price: { label: 'OpenFrame price' },
   // A vendor (product) of the OpenMSP directory. A glyph card; it opens the vendor's page there.
   vendor: { label: 'Vendor', icon: ref => <VendorGlyph title={ref?.title ?? ''} logoUrl={refText(ref, 'logo_url')} /> },
 };
+/**
+ * A card type's icon: its SOURCE's, resolved exactly as the source's chip
+ * resolves it (`resolveSourceIcon` over `SOURCE_ICON_NAMES`). One name per
+ * source, one resolver, so a card and its chip always match.
+ */
+function sourceGlyph(docType: string): React.ReactNode {
+  const { Icon } = resolveSourceIcon({ sourceRepo: defaultTableIdForDocumentType(docType), documentType: docType });
+  return <Icon className="size-6" />;
+}
+
 function refGlyphRegistryEntries(): Record<string, ChatCardRegistryEntry> {
-  return registryEntries(REF_GLYPH_CARD_CONFIGS, (cfg, docType) =>
-    refHydratedEntry(docType, cfg.label, (displayRef, opts) =>
+  return registryEntries(REF_GLYPH_CARD_CONFIGS, (config, docType) => {
+    const glyph = config.icon ?? (() => sourceGlyph(docType));
+    const cfg = config;
+    return refHydratedEntry(docType, cfg.label, (displayRef, opts) =>
       cfg.media ? (
         <EntityMingoCard
           title={displayRef.title}
@@ -1524,7 +1518,7 @@ function refGlyphRegistryEntries(): Record<string, ChatCardRegistryEntry> {
             displayRef.metadata?.videoPoster,
             opts.extras?.buildOgPlaceholderUrl?.(displayRef.title ?? '') ?? null,
           )}
-          fallbackIcon={cfg.icon(displayRef)}
+          fallbackIcon={glyph(displayRef)}
           status={{ label: cfg.label, variant: 'grey' }}
           chatRef={displayRef}
           isNewTab={opts.isNewTab}
@@ -1532,15 +1526,10 @@ function refGlyphRegistryEntries(): Record<string, ChatCardRegistryEntry> {
           menuAriaLabel={`${cfg.label} actions`}
         />
       ) : (
-        <GlyphChatCard
-          chatRef={displayRef}
-          icon={cfg.icon(displayRef)}
-          isNewTab={opts.isNewTab}
-          discuss={opts.discuss}
-        />
+        <GlyphChatCard chatRef={displayRef} icon={glyph(displayRef)} isNewTab={opts.isNewTab} discuss={opts.discuss} />
       ),
-    ),
-  );
+    );
+  });
 }
 
 /** People-hub employee feeds hydrate from their EXISTING list APIs
@@ -1558,9 +1547,9 @@ function fetchedEmployeeEntryDisplayRef(item: unknown, chatRef: ChatRef): ChatRe
   return { ...chatRef, title, preview: preview.length > 0 ? preview : chatRef.preview };
 }
 const EMPLOYEE_ENTRY_CARD_CONFIGS: Record<string, GlyphCardConfig> = {
-  what_i_shipped: { label: 'What I Shipped', icon: () => <Rocket02Icon size={24} /> },
-  how_i_work: { label: 'How I Work', icon: () => <ClipboardListIcon size={24} /> },
-  ai_prompt: { label: 'Squawkbox', icon: () => <ChatQuoteIcon size={24} /> },
+  what_i_shipped: { label: 'What I Shipped' },
+  how_i_work: { label: 'How I Work' },
+  ai_prompt: { label: 'Squawkbox' },
 };
 function employeeEntryRegistryEntries(): Record<string, ChatCardRegistryEntry> {
   return registryEntries(EMPLOYEE_ENTRY_CARD_CONFIGS, (cfg, docType) => ({
@@ -1571,7 +1560,7 @@ function employeeEntryRegistryEntries(): Record<string, ChatCardRegistryEntry> {
     render: (item, chatRef, opts) => (
       <GlyphChatCard
         chatRef={fetchedEmployeeEntryDisplayRef(item, chatRef)}
-        icon={cfg.icon()}
+        icon={sourceGlyph(docType)}
         isNewTab={opts.isNewTab}
         discuss={opts.discuss}
       />

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

@@ -45,9 +45,10 @@ export {
   buildAskPromptsUrl,
   useAskPrompts,
   useAssistantOpen,
-  useShownAskPromptIds,
-  useShownAskPrompts,
+  useAskSurface,
   type AskPromptsResponse,
   type UseAskPromptsOptions,
   type UseAskPromptsResult,
+  type UseAskSurfaceOptions,
+  type UseAskSurfaceResult,
 } from './use-ask-prompts';

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useId, useLayoutEffect, useSyncExternalStore } from 'react';
+import { useCallback, useId, useLayoutEffect, useMemo, useState, useSyncExternalStore } from 'react';
 import {
   useAssistantRuntime,
   type AssistantOpenRequest,
@@ -71,8 +71,10 @@ export function useAskPrompts({
   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 };
+  const { data, dataUrl, error } = useSelfFetch<AskPromptsResponse>(url);
+  // Landed for THIS url (or failed): never the frame between a url appearing and its fetch starting.
+  const landed = url !== null && (dataUrl === url || error);
+  return { prompts: landed ? (data?.prompts ?? []) : [], isLoading: !!base && !landed, supported: !!base };
 }
 
 /**
@@ -99,90 +101,172 @@ export function useAssistantOpen(
   );
 }
 
-// ─── 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.
+// ─── One pick at a time, and never a question twice ──────────────────────────
+// Every surface that offers questions (a row in a section, the FAQ's card)
+// takes a TURN before it picks, in the order the surfaces came to need one:
+// document order for the ones a page mounts together, later for one that waits
+// to be reached (the FAQ's card). A surface picks once every surface ahead of
+// it has settled, and leaves out every question the page already shows. So no
+// two surfaces of a page can show the same question, whatever their topics,
+// with no wiring by the host. One queue per QUESTIONS ENDPOINT (the runtime's
+// `askPromptsUrl`): two assistants on one page read different questions, and
+// never wait for or leave out each other's. A module store, read through
+// React's external-store hook.
 
-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;
+/** One endpoint's queue: each surface's turn and the questions it settled on (`null`: not yet). */
+interface AskQueue {
+  enter(surface: string): void;
+  settle(surface: string, ids: readonly string[] | null): void;
+  leave(surface: string): void;
   subscribe(listener: () => void): () => void;
-  read(): readonly string[] | null;
+  /**
+   * What `surface` must leave out, as a comma-joined list ('' for nothing),
+   * once it may pick; `null` while it has no turn or a surface ahead of it is
+   * still picking. A string, so React can compare two readings.
+   */
+  turnOf(surface: string): string | null;
 }
 
-function createShownList(): ShownList {
-  const bySurface = new Map<string, readonly string[] | null>();
+function createAskQueue(): AskQueue {
+  const entries = new Map<string, { turn: number; ids: readonly string[] | null }>();
   const listeners = new Set<() => void>();
-  let snapshot: readonly string[] | null = NO_IDS;
+  let next = 0;
   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);
+    enter(surface) {
+      if (entries.has(surface)) return;
+      entries.set(surface, { turn: next++, ids: null });
       publish();
     },
-    remove(surface) {
-      bySurface.delete(surface);
+    settle(surface, ids) {
+      const entry = entries.get(surface);
+      if (!entry || (entry.ids?.join(',') ?? null) === (ids?.join(',') ?? null)) return;
+      entry.ids = ids;
       publish();
     },
+    leave(surface) {
+      if (entries.delete(surface)) publish();
+    },
     subscribe(listener) {
       listeners.add(listener);
       return () => listeners.delete(listener);
     },
-    read: () => snapshot,
+    turnOf(surface) {
+      const own = entries.get(surface);
+      if (!own) return null;
+      const shown: string[] = [];
+      for (const [other, entry] of entries) {
+        if (other === surface) continue;
+        if (entry.ids === null) {
+          if (entry.turn < own.turn) return null;
+          continue;
+        }
+        shown.push(...entry.ids);
+      }
+      return shown.join(',');
+    },
   };
 }
 
-const shownLists = new Map<string, ShownList>();
+const askQueues = new Map<string, AskQueue>();
 
-/** The list a surface belongs to: the questions endpoint of its assistant runtime. */
-function useShownList(): ShownList {
+/** The queue a surface belongs to: the questions endpoint of its assistant runtime. */
+function useAskQueue(): AskQueue {
   const scope = useAssistantRuntime()?.askPromptsUrl ?? '';
-  let list = shownLists.get(scope);
-  if (!list) {
-    list = createShownList();
-    shownLists.set(scope, list);
+  let queue = askQueues.get(scope);
+  if (!queue) {
+    queue = createAskQueue();
+    askQueues.set(scope, queue);
   }
-  return list;
+  return queue;
+}
+
+export interface UseAskSurfaceOptions {
+  /** What the surface is about (see `UseAskPromptsOptions.topic`). */
+  topic?: string;
+  count?: number;
+  /**
+   * Ids of questions never to offer. Absent: the ones the page's other
+   * surfaces show, which this one waits for. A list: exactly those, picked at
+   * once with no wait (the surfaces after it still leave its questions out).
+   * `null`: the surface waits and never picks.
+   */
+  exclude?: readonly string[] | null;
+  /** False: the surface is not ready to pick yet (it takes its turn when it is). Default true. */
+  enabled?: boolean;
+  /** How the chat is opened from THIS surface. Absent: the assistant runtime's opener. */
+  onOpen?: (request: AssistantOpenRequest) => void;
+}
+
+export interface UseAskSurfaceResult extends UseAskPromptsResult {
+  /** The nearest assistant runtime; `null` with none mounted. */
+  assistant: AssistantRuntime | null;
+  /** The same runtime with THIS surface's opener: what the surface's launcher reads. */
+  scoped: AssistantRuntime | null;
+  /** Opens the chat (and asks, with a prompt), carrying the surface's topic. */
+  open: (request: { prompt?: string }) => void;
+  /** Reports a question that was asked (the runtime's `onAsk`, with the topic). */
+  reportAsk: (prompt: AskPrompt) => void;
 }
 
 /**
- * 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).
+ * THE wiring of an "ask" surface, whatever it looks like: the assistant
+ * runtime, the surface's questions (picked on its turn, never one the page
+ * already shows), the opener and the click report. `AssistantAskPrompts` is its
+ * one component; nothing else picks questions for a page.
  */
-export function useShownAskPrompts(ids: readonly string[] | null | undefined): void {
+export function useAskSurface({
+  topic,
+  count = ASK_PROMPTS_DEFAULT_COUNT,
+  exclude,
+  enabled = true,
+  onOpen,
+}: UseAskSurfaceOptions = {}): UseAskSurfaceResult {
+  const assistant = useAssistantRuntime();
   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.
+  const queue = useAskQueue();
+  const picks = assistantAvailable(assistant) && !!assistant.askPromptsUrl && enabled && exclude !== null;
+
+  // A layout effect: surfaces a page mounts together take their turns in document order.
   useLayoutEffect(() => {
-    if (key === undefined) return undefined;
-    list.set(surface, key === null ? null : key ? key.split(',') : NO_IDS);
-    return () => list.remove(surface);
-  }, [list, surface, key]);
-}
+    if (!picks) return undefined;
+    queue.enter(surface);
+    return () => queue.leave(surface);
+  }, [queue, surface, picks]);
+
+  const turn = useSyncExternalStore(
+    queue.subscribe,
+    () => queue.turnOf(surface),
+    () => null,
+  );
+  // ONE pick per mount: what the page showed when this surface's turn came is what it leaves out, for good.
+  const [shownAtTurn, setShownAtTurn] = useState<string | null>(null);
+  if (picks && turn !== null && shownAtTurn === null) setShownAtTurn(turn);
+  const leftOut = useMemo(() => exclude ?? (shownAtTurn ? shownAtTurn.split(',') : undefined), [exclude, shownAtTurn]);
+
+  const { prompts, isLoading, supported } = useAskPrompts({
+    topic,
+    count,
+    exclude: leftOut,
+    // Told exactly what to leave out, a surface needs nobody's pick: it never waits for a turn.
+    enabled: picks && (exclude !== undefined || shownAtTurn !== null),
+  });
+  const settled = picks && !isLoading ? prompts.map(prompt => prompt.id).join(',') : null;
+  useLayoutEffect(() => {
+    queue.settle(surface, settled === null ? null : settled ? settled.split(',') : []);
+  }, [queue, surface, settled]);
 
-/** 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);
+  const open = useAssistantOpen(topic, onOpen);
+  const scoped = useMemo(() => (assistant ? { ...assistant, open } : null), [assistant, open]);
+  const onAsk = assistant?.onAsk;
+  const reportAsk = useCallback((prompt: AskPrompt) => onAsk?.({ promptId: prompt.id, topic }), [onAsk, topic]);
+  // A surface that waits (not reached, or told to) is loading wherever questions can exist.
+  return { assistant, scoped, prompts, isLoading: supported && (!picks || isLoading), supported, open, reportAsk };
 }
 
 /** Tests only: forget every surface. */
-export function resetShownAskPrompts(): void {
-  shownLists.clear();
+export function resetAskSurfaces(): void {
+  askQueues.clear();
 }