@wix/himalaya-cli 0.1036.0 → 0.1038.0

package/templates/gym-fitness-owner/tier5-src/_shared/aria-chat.ts

@@ -37,8 +37,13 @@ import {
   functionCallsOf,
   getConversationMessages,
   getConversations,
+  itemsOf,
+  listInstalledProviders,
+  mentionReference,
   messageText,
   messagesOf,
+  providersOf,
+  queryItems,
   sendFunctionCallResults,
   sendMessage,
   triggerAssistantMessage,
@@ -47,6 +52,8 @@ import {
   type Attachment,
   type ConversationMessage,
   type ConversationSummary,
+  type ItemsQuery,
+  type MessageReference,
   type SendMessageResponse,
 } from "@himalaya/wix-genie-chat";
 import {
@@ -68,6 +75,8 @@ import { isWebUrl, stripMarkdown } from "./aria-widget-model.js";
 import { NO_WIDGET, activeWidgetOf, asyncAdvanced, type SubtreeSlot, type WidgetOptionRow, type WidgetView }
   from "./aria-widget-view.js";
 import { substituteSelection } from "./aria-widget-model.js";
+import { MENTION_PAGE_SIZE, allowlisted, emptyMentionModel, mentionView,
+  type MentionItemRow, type MentionLabels, type MentionModel, type MentionProvider, type MentionView } from "./aria-mentions.js";
 import { isTransportFailure, ownerTransportFailureText } from "./owner-load-error.js";
 import { LOCAL_ID_PREFIX, createRowMemo, mintLocalId, transcriptKeys, type RowMemo } from "./aria-hot-path.js";
 
@@ -102,6 +111,11 @@ export interface AriaBubble {
    *  that right-aligns the owner renders two templates and collapses one. */
   notUser: boolean;
   notAria: boolean;
+  /** What the turn MENTIONED — "@Blue Dress · @Maya Chen" — read off the
+   *  references stored beside the text. Empty (and `refsHidden`) on every turn
+   *  that mentioned nothing, which is every assistant turn. */
+  refs: string;
+  refsHidden: boolean;
   /** What a screen reader says for the row: the author, then the words. A
    *  screen that draws the speaker only as a bubble and a side of the screen
    *  (`messageStyle: 'userBubble'`) has no visible author line to read, and
@@ -161,6 +175,10 @@ export interface AriaChatState {
   /** Text of the optimistic user bubble awaiting reconciliation with the server
    *  transcript. Empty when nothing is in flight. */
   _pending: string;
+  /** The optimistic bubble's mention line, so a tick that re-appends the
+   *  bubble before the server echoes the turn does not drop what it mentioned.
+   *  Read only while `_pending` is set. */
+  _pendingRefs: string;
   /** The file names the in-flight message was sent with, so the optimistic
    *  bubble keeps its attachment line across every tick until the server's own
    *  copy of the turn replaces it. */
@@ -223,6 +241,10 @@ export interface AriaChatState {
    *  every time the transcript is, which is what makes "one active widget"
    *  true by construction rather than by remembering to clear it. */
   widget: WidgetView;
+  /** The mention picker and the picks waiting above the composer, flattened
+   *  for binding (`aria-mentions.ts`). Derived from the core's mention model on
+   *  the way out of EVERY action — see `gated`. */
+  mention: MentionView;
   /** The photos waiting in the composer to go with the next message.
    *
    *  A PROJECTION, not a field the reducers maintain: the worker holds the chips
@@ -295,6 +317,18 @@ export interface AriaChatLabels {
    *  all — it carries no Wix app binding to sign the chat-service call with.
    *  See `isWixAccountUnreachable`, and note what it is NOT: a signed-out user. */
   unavailable?: Resolvable<string>;
+  /** The mention picker's copy. See `MentionLabels`. */
+  mentionTitle?: Resolvable<string>;
+  mentionNoProviders?: Resolvable<string>;
+  mentionNoItems?: Resolvable<string>;
+  mentionFailed?: Resolvable<string>;
+  /** Shown when THIS host cannot reach the provider service at all — the
+   *  service is native-only (see the chat client), so on the web preview the
+   *  picker says so instead of pretending the site has nothing to mention. */
+  mentionUnavailable?: Resolvable<string>;
+  /** Shown when one provider's items could not be fetched. Takes the
+   *  category's label. */
+  mentionItemsFailed?: (category: string) => string;
   /** Attachment copy — see `AriaChatOptions.attachments`. Chip states: */
   attachUploading?: Resolvable<string>;
   attachFailed?: Resolvable<string>;
@@ -674,6 +708,20 @@ export function withSpoken(bubbles: AriaBubble[]): AriaBubble[] {
     : bubbles.map((b) => (typeof b.spoken === "string" ? b : { ...b, spoken: spokenOf(b.who, b.content) }));
 }
 
+/** The line a bubble shows for what its turn mentioned: each MENTION
+ *  reference's label, `@`-prefixed. Only `source: "mention"` counts — the
+ *  service also stores references of other kinds (a reply-to, page context),
+ *  and those are not something the owner picked. */
+export function refsLine(refs: MessageReference[] | undefined): string {
+  const labels: string[] = [];
+  for (const r of refs ?? []) {
+    if (r?.source !== "mention") continue;
+    const label = typeof r.label === "string" ? r.label.trim() : "";
+    if (label) labels.push(`@${label}`);
+  }
+  return labels.join(" · ");
+}
+
 /** A bubble's words and its attachment line, with its collapse flag.
  *
  *  A turn that is ONLY attachments carries the line as its content instead of
@@ -688,10 +736,14 @@ function withAttachments(content: string, names: readonly string[]): { content:
 }
 
 /** A greeting or optimistic bubble: no links, all slots defaulted. `attached`
- *  names the files an optimistic USER bubble is being sent with. */
-export function plainBubble(id: string, role: string, who: string, content: string, attached: readonly string[] = []): AriaBubble {
+ *  names the files an optimistic USER bubble is being sent with, and `refs` is
+ *  its mention line, already formatted. */
+export function plainBubble(
+  id: string, role: string, who: string, content: string, attached: readonly string[] = [], refs = "",
+): AriaBubble {
   const a = withAttachments(content, attached);
-  return { id, role, who, notUser: role !== "USER", notAria: role === "USER", spoken: spokenOf(who, a.content), ...linkFieldsOf("", role), ...a };
+  return { id, role, who, notUser: role !== "USER", notAria: role === "USER", spoken: spokenOf(who, a.content),
+    refs, refsHidden: !refs, ...linkFieldsOf("", role), ...a };
 }
 
 /** Server transcript → bubbles. USER text is literal; ASSISTANT replies are
@@ -732,11 +784,14 @@ export function toBubbles(
       // not something the service is known to send, and naming files on it
       // would claim Aria sent them.
       const attached = role === "USER" ? attachmentsOf(m).map((a) => a.fileName) : [];
-      const build = () => bubbleOf(id, role, who, raw, writing, attached);
-      // Attachments are part of the key: they are not in the text, so a row
-      // keyed on text alone could serve a bubble naming the wrong files.
+      // A USER turn only: an owner mentions things, the assistant does not.
+      const refs = role === "USER" ? refsLine(m.references) : "";
+      const build = () => bubbleOf(id, role, who, raw, writing, attached, refs);
+      // Attachments and mentions are part of the key: neither is in the text, so
+      // a row keyed on text alone could serve a bubble naming the wrong files or
+      // the wrong picks.
       const b = memo
-        ? memo.row(id, raw, `${role}\u0000${who}\u0000${writing ? "w" : ""}\u0000${attached.join("\u0001")}`, build)
+        ? memo.row(id, raw, `${role}\u0000${who}\u0000${writing ? "w" : ""}\u0000${attached.join("\u0001")}\u0000${refs}`, build)
         : build();
       if (b) out.push(b);
     }
@@ -761,7 +816,7 @@ export type BubbleMemo = RowMemo<AriaBubble | null>;
 export const createBubbleMemo = (): BubbleMemo => createRowMemo<AriaBubble | null>();
 
 function bubbleOf(
-  id: string, role: string, who: string, raw: string, writing: boolean, attached: readonly string[] = [],
+  id: string, role: string, who: string, raw: string, writing: boolean, attached: readonly string[] = [], refs = "",
 ): AriaBubble | null {
   // Only assistant turns carry envelopes; a user's own text is literal, and
   // scanning it would let an owner who typed `<<…>>` erase their own message.
@@ -786,6 +841,8 @@ function bubbleOf(
     notUser: role !== "USER",
     notAria: role === "USER",
     spoken: spokenOf(who, a.content),
+    refs,
+    refsHidden: !refs,
     ...linkFieldsOf(prose, role),
     ...a,
   };
@@ -838,14 +895,14 @@ export function argText(arg: AriaActionArg): string {
  *  vanish mid-turn. */
 export function reconcile(
   server: AriaBubble[], pending: string, pendingAfter: number, youName = "You", pendingId = "",
-  pendingAttached: readonly string[] = [],
+  pendingAttached: readonly string[] = [], pendingRefs = "",
 ): { messages: AriaBubble[]; pending: string } {
   if (!pending) return { messages: server, pending: "" };
   if (countRole(server, "USER") > pendingAfter) return { messages: server, pending: "" };
   // `pendingId` is empty only for state persisted before ids were minted; a
   // fixed fallback still keeps that one row stable across ticks.
   const id = pendingId || `${LOCAL_ID_PREFIX}pending`;
-  return { messages: [...server, plainBubble(id, "USER", youName, pending, pendingAttached)], pending };
+  return { messages: [...server, plainBubble(id, "USER", youName, pending, pendingAttached, pendingRefs)], pending };
 }
 
 /** How many turns of one role the transcript holds. Counted over BUBBLES rather
@@ -1178,6 +1235,23 @@ export interface AriaChatCore {
   widgetPick(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
   /** Answer one QUESTIONNAIRE question. */
   widgetAnswer(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Open the mention picker at the category level, listing the site's
+   *  installed providers the first time (per business). `undefined` when the
+   *  business switched while the list was being fetched. */
+  mentionOpen(s: AriaChatState): Promise<AriaChatState | undefined>;
+  /** Close it. Picks already made stay above the composer. */
+  mentionClose(s: AriaChatState): AriaChatState;
+  /** From a provider's items back to the categories. */
+  mentionBack(s: AriaChatState): AriaChatState;
+  /** Browse one provider (`arg.id` / `arg.value` is its key). Resolves to
+   *  `undefined` when a later picker action superseded it — see `mentionSeq`. */
+  mentionProvider(s: AriaChatState, arg?: AriaActionArg): Promise<AriaChatState | undefined>;
+  /** Search the provider being browsed. Same `undefined` rule. */
+  mentionQuery(s: AriaChatState, arg?: AriaActionArg): Promise<AriaChatState | undefined>;
+  /** Pick one item (`arg.id` is its row id) — a chip above the composer. */
+  mentionPick(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Drop one chip (`arg.id` is the chip id). */
+  mentionRemove(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
   /** Pick (or take) a photo and start uploading it. Returns as soon as the chip
    *  exists — the upload reports back through `attachmentSettled`. The source is
    *  the arg (`"camera"`, or `{ source: "camera" }`); anything else is the
@@ -1255,12 +1329,112 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const historyKeyFor = (site: string) => scopedKey(o.historyKey, site);
   const localHistory = o.localHistory !== false;
 
+  // -------------------------------------------------------------------------
+  // Mentions
+  // -------------------------------------------------------------------------
+
+  const mentionLabels = (): MentionLabels => ({
+    title: res(o.labels?.mentionTitle ?? "Mention"),
+    noProviders: res(o.labels?.mentionNoProviders ?? "There's nothing on this site to mention yet."),
+    noItems: res(o.labels?.mentionNoItems ?? "Nothing found."),
+    providersFailed: res(o.labels?.mentionFailed ?? "Couldn't load what you can mention."),
+    unavailable: res(o.labels?.mentionUnavailable ?? "Mentions aren't available here."),
+  });
+  const itemsFailedText = (category: string): string =>
+    o.labels?.mentionItemsFailed?.(category) ?? `Couldn't load ${category}.`;
+
+  /** The picker, and the picks waiting to be sent — kept HERE, outside the
+   *  reducer state, and painted onto every action's result by `gated`.
+   *
+   *  A latch for the reason `draft` is one. Reducers are pure functions of the
+   *  state handed to them, and the poll ladder keeps a `tick` in the air for
+   *  much of a screen's life: a tick that read its snapshot BEFORE the owner
+   *  opened the picker would, on resolving, write the closed picker back —
+   *  the panel snapping shut under their finger. Painting the model on the way
+   *  out of every action, the tick included, makes the latest pick win no
+   *  matter which action carries it.
+   *
+   *  What that costs: the model is not persisted, so a worker that is torn
+   *  down and re-booted comes back with the picker closed and no chips. A pick
+   *  is a draft the owner has not sent, exactly like the composer text. */
+  let mentionModel: MentionModel = emptyMentionModel();
+  let mentionViewNow: MentionView = mentionView(mentionModel, mentionLabels());
+  const setMention = (next: MentionModel): void => {
+    mentionModel = next;
+    mentionViewNow = mentionView(next, mentionLabels());
+  };
+  /** Bumped by every picker transition that makes an in-flight item query
+   *  stale: a newer search, another provider, Back, Close, a pick, a new chat,
+   *  a business switch. A query compares on resolving and stands down. */
+  let mentionSeq = 0;
+  /** Chip ids. Minted rather than derived from the provider key and item id,
+   *  neither of which is guaranteed to be safe inside a component id. */
+  let pickSeq = 0;
+
+  /** A business switch drops the providers AND the picks: a product of the
+   *  previous business is not something to mention to this one. */
+  const mentionSite = (): void => {
+    const site = siteOf();
+    if (mentionModel.site === site) return;
+    mentionSeq += 1;
+    setMention({ ...emptyMentionModel(), site });
+  };
+
+  /** Which sentence a failed provider call gets. The service is native-only, so
+   *  a host that cannot reach it is told so plainly — never shown an empty
+   *  list, which would read as "this site has nothing to mention". */
+  const mentionFailure = (e: unknown, fallback: string): string => {
+    const msg = String((e as Error)?.message ?? e ?? "");
+    return isWixAccountUnreachable(e) || msg.includes("absolute_urls_not_allowed")
+      ? mentionLabels().unavailable
+      : fallback;
+  };
+
+  const mentionArg = (arg?: AriaActionArg): string =>
+    typeof arg === "string" ? arg.trim() : firstString(arg?.id, arg?.optionValue, arg?.value, arg?.text);
+
+  /** One provider page into rows. Row ids are positional — the item id is
+   *  kept beside them for the pick — and a picture is only shown from a Wix
+   *  media host, the same rule the widget images follow. */
+  const itemRows = (provider: MentionProvider, items: ReturnType<typeof itemsOf>): MentionItemRow[] => {
+    const seen = new Set<string>();
+    const rows: MentionItemRow[] = [];
+    for (const it of items) {
+      if (seen.has(it.id)) continue;
+      seen.add(it.id);
+      const pic = provider.showsImage && isWixMediaHost(hostOf(it.imageUrl)) ? it.imageUrl : "";
+      rows.push({ id: `i${rows.length}`, itemId: it.id, title: it.title, subtitle: it.subtitle,
+        subtitleHidden: !it.subtitle, pictureUrl: pic, pictureHidden: !pic });
+    }
+    return rows;
+  };
+
+  /** Ask one provider for a page. Resolves to `undefined` — leave the state
+   *  alone — when a later picker transition superseded it. */
+  const fetchItems = async (s: AriaChatState, provider: MentionProvider, q: string, seq: number): Promise<AriaChatState | undefined> => {
+    const query: ItemsQuery = {
+      ...(q ? { search: q } : {}),
+      ...(provider.paging === "CURSOR" ? { cursorPaging: { limit: MENTION_PAGE_SIZE } }
+        : provider.paging === "OFFSET" ? { paging: { limit: MENTION_PAGE_SIZE, offset: 0 } } : {}),
+    };
+    let items: MentionItemRow[] = [];
+    let failed = "";
+    try {
+      items = itemRows(provider, itemsOf(await queryItems(provider.key, query)));
+    } catch (e) {
+      failed = mentionFailure(e, itemsFailedText(provider.label));
+    }
+    if (seq !== mentionSeq) return undefined;
+    setMention({ ...mentionModel, items, itemsLoading: false, itemsFailed: failed });
+    return committed ?? s;
+  };
+
   const initialState: AriaChatState = {
     status: "loading", statusText: "", error: "", input: "", copyNote: "", replyActionsHidden: true,
-    messages: [], prompts: [], _convId: "", _siteId: "", _pending: "", _pendingAttach: [],
+    messages: [], prompts: [], _convId: "", _siteId: "", _pending: "", _pendingRefs: "", _pendingAttach: [],
     _pendingAfter: 0, _pendingId: "", _replyAfter: 0, _srvUsers: 0, _srvAssistants: 0,
     _abortId: "", _turnId: "", stopHidden: true, ok: false,
-    widget: NO_WIDGET,
+    widget: NO_WIDGET, mention: mentionViewNow,
     attachments: [], attachmentsHidden: true,
   };
 
@@ -1422,8 +1596,11 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
    *  A latch rather than state, for the same reason `inFlightSend` is one: it is
    *  a transient recovery hint about one failed attempt, not something that
    *  should survive a reload or be persisted with the transcript. Keyed by
-   *  conversation AND content so it can only ever re-trigger the exact turn it
-   *  was recorded for.
+   *  conversation, content AND the references (mentions) the turn was stored
+   *  with, so it can only ever re-trigger the exact turn it was recorded for: the
+   *  same words retried with other picks are a new turn, and re-triggering the
+   *  stored one would answer about the old picks and then clear the new chips as
+   *  if they had been sent.
    *
    *  It also has to EXPIRE, and cannot do so on its own clock. A trigger whose
    *  RESPONSE was lost — a timeout, a reset — failed here while succeeding at the
@@ -1432,7 +1609,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
    *  owner's next identical question instead, which is quieter and worse. The
    *  expiry is therefore a question asked of the SERVER at reuse time — see
    *  `turnAnswered` — rather than anything inferred from local counts. */
-  let stalledTurn: { convId: string; content: string; userMessageId: string } | null = null;
+  let stalledTurn: { convId: string; content: string; refsKey: string; userMessageId: string } | null = null;
 
   /** A monotonic turn epoch, bumped by every TURN BOUNDARY: a successful `stop`,
    *  the start of a `send`, and a `newChat`.
@@ -1792,12 +1969,25 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const withDraft = (next: AriaChatState, since: number): AriaChatState =>
     draftSeq === since || draft === next.input ? next : { ...next, input: draft };
 
-  async function send(s: AriaChatState, content: string, attached: readonly AriaAttachmentChip[] = []): Promise<AriaChatState> {
+  async function send(
+    s: AriaChatState, content: string, attached: readonly AriaAttachmentChip[] = [], withPicks = true,
+  ): Promise<AriaChatState> {
     // A new turn is a turn boundary: any tick still parked on the PREVIOUS
     // turn's transcript read must stand down rather than write its snapshot over
     // this one. Bump before the first await so an in-flight tick is already stale
     // by the time it resolves.
     turnSeq += 1;
+    // The picks above the composer ride WITH this turn, as references beside
+    // the text — never as tokens inside it. Read once, here: a chip the owner
+    // adds while this send is in the air belongs to the NEXT turn, and only the
+    // ones actually sent are cleared below.
+    mentionSite();
+    const sentPicks = withPicks ? mentionModel.picks : [];
+    const references = sentPicks.map((p) => mentionReference({ id: p.itemId, title: p.label }, p.category));
+    // What this turn's references ARE, for `stalledTurn`'s identity. `data` names
+    // the item and its category; the order is the owner's, and so is the turn's.
+    const refsKey = references.map((r) => r.data ?? "").join("\u0000");
+    const refs = refsLine(references);
     // Only chips whose bytes have LANDED travel; `submit` refuses to get here
     // with any other kind, and this filter is the second lock on that door.
     const riding = attached.filter((c) => c.state === "ready" && !!c.ref);
@@ -1824,13 +2014,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       localId = minted.id;
     }
     const optimistic: AriaBubble[] = [
-      ...s.messages.filter((b) => b.id !== localId), plainBubble(localId, "USER", you(), content, attachedNames),
+      ...s.messages.filter((b) => b.id !== localId), plainBubble(localId, "USER", you(), content, attachedNames, refs),
     ];
     const base: AriaChatState = {
       // `copyNote: ""` — a Copy confirmation belongs to the moment, and a new
       // turn ends it. Left in place it would sit under the next reply saying
       // "Copied" about text the owner copied several turns ago.
-      ...s, prompts: [], input: "", error: "", copyNote: "",
+      ...s, prompts: [], input: "", error: "", copyNote: "", _pendingRefs: refs,
       // The PREVIOUS turn's handles must not survive into this one: aborting by
       // a stale id would abandon a reply that has already been read, and waiting
       // on a stale turn id would look for an answer that already exists. Both
@@ -1891,7 +2081,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // send is about (`supersedes`)? And if so, is that turn still worth
       // re-triggering (`stalled`)?
       latch = stalledTurn;
-      supersedes = !!latch && latch.convId === convId && latch.content === content;
+      supersedes = !!latch && latch.convId === convId && latch.content === content && latch.refsKey === refsKey;
       // …and only while it is still UNANSWERED, which is ASKED rather than
       // inferred. A trigger whose response was lost failed here while succeeding
       // at the service, so the answer arrives anyway and the id now names a
@@ -1937,9 +2127,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       } else {
         answer = await sendMessage(convId, content, {
           origin,
-          // Omitted rather than `[]` when there are none, so a plain text turn
-          // is byte-for-byte what it was before attachments existed.
+          // Each omitted rather than `[]` when there are none, so a plain text
+          // turn is byte-for-byte what it was before attachments and mentions.
           ...(attachments.length ? { attachments } : {}),
+          ...(references.length ? { messageReferences: references } : {}),
         });
         abortId = userMessageIdOf(answer);
       }
@@ -1988,6 +2179,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // away a turn this send never touched.
       if (supersedes && stalledTurn === latch) stalledTurn = null;
       retriedId = "";
+      // Delivered, so its chips are spent — the stored turn carries them now,
+      // and on a re-trigger it already did. Only THESE chips: one added during
+      // the send is waiting for the next turn. A FAILED send keeps them all,
+      // so the retry sends what the owner picked.
+      if (sentPicks.length) {
+        setMention({ ...mentionModel, picks: mentionModel.picks.filter((p) => !sentPicks.includes(p)) });
+      }
       // A conversation minted just now starts empty, so the marks taken above
       // from the PREVIOUS conversation's counts would be ahead of it and its
       // first reply would never read as new — the same stranded "typing…" this
@@ -2043,7 +2241,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       const storedId = (e as { storedUserMessageId?: unknown })?.storedUserMessageId;
       const keptId = typeof storedId === "string" && storedId ? storedId : retriedId;
       stalledTurn = convId && keptId
-        ? { convId, content, userMessageId: keptId }
+        ? { convId, content, refsKey, userMessageId: keptId }
         // Nothing stored by this attempt. Drop the latch only if it is the one
         // this send was working on and is still the one we captured; otherwise it
         // belongs to another turn and must survive.
@@ -2089,7 +2287,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
    *  action rather than maintained inside each of them: `stopHidden` is a pure
    *  function of two other fields, and eight reducers each remembering to set it
    *  is eight chances for the control to be shown when there is nothing to stop
-   *  — or, worse, hidden while a reply the owner wants to abandon runs on. */
+   *  — or, worse, hidden while a reply the owner wants to abandon runs on.
+   *
+   *  It also paints the mention picker (see `mentionModel`), and for the same
+   *  reason: every action's result passes through here, so this is the one
+   *  place a stale snapshot cannot sneak an old picker back onto the screen.
+   *  Both edits are made only when something changed, so a reducer that
+   *  returns the state untouched still returns the SAME object. */
   let committed: AriaChatState | null = null;
   let commits = 0;
   /** A result as the runtime stores it: the one-shot directives it strips on
@@ -2102,6 +2306,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     return rest as AriaChatState;
   };
   const gated = (s: AriaChatState): AriaChatState => {
+    mentionSite();
     const hidden = !(turnInFlight(s) && !!s._abortId);
     // The reply actions follow the same rule for the same reason: a derived
     // flag, recomputed on every action's way out, so no reducer can forget it.
@@ -2118,9 +2323,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     seedChips(actioned);
     for (const id of [...chipBytes.keys()]) if (!chips.some((c) => c.id === id)) chipBytes.delete(id);
     const attachmentsHidden = chips.length === 0;
-    const out = actioned.attachments === chips && actioned.attachmentsHidden === attachmentsHidden
+    let out = actioned.attachments === chips && actioned.attachmentsHidden === attachmentsHidden
       ? actioned
       : { ...actioned, attachments: chips, attachmentsHidden };
+    if (out.mention !== mentionViewNow) out = { ...out, mention: mentionViewNow };
     // Every state the runtime commits passes through here (an `undefined`
     // result commits nothing and skips it), so this is the newest committed
     // state — what `copyMessage` puts its note on when other actions landed
@@ -2387,6 +2593,12 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // A fresh conversation is a turn boundary too: a tick parked on the OLD
       // conversation's transcript must not reconcile it over the new greeting.
       turnSeq += 1;
+      // A fresh chat drops its drafts, the picks included — the same way it
+      // empties the composer. The provider list is kept: it belongs to the
+      // business, not to the conversation.
+      mentionSeq += 1;
+      setMention({ ...mentionModel, open: false, provider: null, query: "", items: [], itemsLoading: false,
+        itemsFailed: "", picks: [] });
       // ➕ discards the draft (`input: ""` below), and the photos are part of the
       // draft. An upload still running settles into nothing: its chip is gone.
       chipsSeeded = true;
@@ -2459,7 +2671,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
         // reply go unnoticed and pinned the ladder fast forever. Safe to return
         // `s` here: the guard above proved this tick is still current.
         if (!raw.length) return s;
-        const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you(), s._pendingId, s._pendingAttach ?? []);
+        const { messages, pending } = reconcile(server, s._pending, s._pendingAfter, you(), s._pendingId, s._pendingAttach ?? [], s._pendingRefs);
         // …but still never PAINT nothing over something. `messages` is only
         // adopted when it has content: a transcript that renders empty leaves
         // the screen as it was (the greeting, or the last good turn) while the
@@ -2563,6 +2775,97 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       };
     },
 
+    // --- Mentions -----------------------------------------------------------
+    //
+    // Every one of these edits the mention MODEL and returns a state for
+    // `gated` to paint it onto — see `mentionModel` for why the model lives
+    // outside the reducer state.
+
+    mentionOpen: async (s) => {
+      mentionSite();
+      const m = mentionModel;
+      mentionSeq += 1;
+      const atCategories = { ...m, open: true, provider: null, query: "", items: [], itemsLoading: false, itemsFailed: "" };
+      // Listed once per business. A failed list is asked again: the failure
+      // may have been the network, and the next open is the retry.
+      if (m.providers !== null) { setMention(atCategories); return s; }
+      if (m.providersLoading) { setMention(atCategories); return s; }
+      const site = m.site;
+      setMention({ ...atCategories, providersLoading: true, providersFailed: "" });
+      let providers: MentionProvider[] | null = null;
+      let failed = "";
+      try {
+        providers = allowlisted(providersOf(await listInstalledProviders()));
+      } catch (e) {
+        failed = mentionFailure(e, mentionLabels().providersFailed);
+      }
+      // A switch during the request already reset the model for the new
+      // business; this answer belongs to the old one.
+      if (mentionModel.site !== site) return undefined;
+      setMention({ ...mentionModel, providers, providersLoading: false, providersFailed: failed });
+      return committed ?? s;
+    },
+
+    mentionClose: (s) => {
+      if (!mentionModel.open) return s;
+      mentionSeq += 1;
+      setMention({ ...mentionModel, open: false, provider: null, query: "", items: [], itemsLoading: false, itemsFailed: "" });
+      return s;
+    },
+
+    mentionBack: (s) => {
+      if (!mentionModel.provider) return s;
+      mentionSeq += 1;
+      setMention({ ...mentionModel, provider: null, query: "", items: [], itemsLoading: false, itemsFailed: "" });
+      return s;
+    },
+
+    mentionProvider: async (s, arg) => {
+      mentionSite();
+      const key = mentionArg(arg);
+      const provider = mentionModel.open ? (mentionModel.providers ?? []).find((p) => p.key === key) : undefined;
+      if (!provider) return s;
+      const seq = ++mentionSeq;
+      setMention({ ...mentionModel, provider, query: "", items: [], itemsLoading: true, itemsFailed: "" });
+      return fetchItems(s, provider, "", seq);
+    },
+
+    mentionQuery: async (s, arg) => {
+      const provider = mentionModel.provider;
+      if (!mentionModel.open || !provider) return s;
+      // Trimmed: a search, where surrounding space is noise. Unlike the
+      // composer, nothing is lost — the field keeps what was typed.
+      const q = typeof arg === "string" ? arg.trim() : firstString(arg?.value, arg?.text);
+      // The same search again is only worth re-asking when it failed.
+      if (q === mentionModel.query && !mentionModel.itemsFailed && !mentionModel.itemsLoading) return s;
+      const seq = ++mentionSeq;
+      setMention({ ...mentionModel, query: q, itemsLoading: true, itemsFailed: "" });
+      return fetchItems(s, provider, q, seq);
+    },
+
+    mentionPick: (s, arg) => {
+      const provider = mentionModel.provider;
+      const itemId = mentionArg(arg);
+      const item = provider ? mentionModel.items.find((i) => i.itemId === itemId) : undefined;
+      if (!provider || !item) return s;
+      const already = mentionModel.picks.some((p) => p.providerKey === provider.key && p.itemId === item.itemId);
+      const picks = already ? mentionModel.picks : [...mentionModel.picks,
+        { id: `m${++pickSeq}`, providerKey: provider.key, itemId: item.itemId, label: item.title, category: provider.label }];
+      // A pick closes the picker: the owner came to point at one thing, and
+      // the chip above the composer is where they now look.
+      mentionSeq += 1;
+      setMention({ ...mentionModel, picks, open: false, provider: null, query: "", items: [], itemsLoading: false, itemsFailed: "" });
+      return s;
+    },
+
+    mentionRemove: (s, arg) => {
+      const id = mentionArg(arg);
+      const picks = mentionModel.picks.filter((p) => p.id !== id);
+      if (picks.length === mentionModel.picks.length) return s;
+      setMention({ ...mentionModel, picks });
+      return s;
+    },
+
     widgetToggle: (s, arg) => {
       const value = optionValue(arg);
       if (!value) return s;
@@ -2900,7 +3203,9 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       try {
         // `send` directly: it is the one send path, and `submit` with no
         // argument would read the composer instead of sending the retry.
-        return await send(s, REGENERATE_TEXT);
+        // Without the picks: they are a draft for the owner's NEXT message,
+        // not part of asking for this answer again.
+        return await send(s, REGENERATE_TEXT, [], false);
       } finally {
         regenerating = false;
       }
@@ -2930,6 +3235,13 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     widgetRespond: (s, arg) => impl.widgetRespond(s, arg).then(gated),
     widgetPrimary: (s) => impl.widgetPrimary(s).then(gated),
     widgetSecondary: (s) => impl.widgetSecondary(s).then(gated),
+    mentionOpen: (s) => impl.mentionOpen(s).then((r) => (r ? gated(r) : r)),
+    mentionClose: (s) => gated(impl.mentionClose(s)),
+    mentionBack: (s) => gated(impl.mentionBack(s)),
+    mentionProvider: (s, arg) => impl.mentionProvider(s, arg).then((r) => (r ? gated(r) : r)),
+    mentionQuery: (s, arg) => impl.mentionQuery(s, arg).then((r) => (r ? gated(r) : r)),
+    mentionPick: (s, arg) => gated(impl.mentionPick(s, arg)),
+    mentionRemove: (s, arg) => gated(impl.mentionRemove(s, arg)),
     attach: (s, arg) => impl.attach(s, arg).then(gated),
     attachmentSettled: (s, arg) => gated(impl.attachmentSettled(s, arg)),
     removeAttachment: (s, arg) => gated(impl.removeAttachment(s, arg)),