@wix/himalaya-cli 0.960.0 → 0.962.0

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

@@ -42,6 +42,10 @@ import {
   type ConversationSummary,
 } from "@himalaya/wix-genie-chat";
 import { proseOfParts, scanEnvelopes, stripHidden } from "./aria-widgets.js";
+import { isWebUrl } 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";
 
 // ---------------------------------------------------------------------------
 // Shapes
@@ -143,6 +147,13 @@ export interface AriaChatState {
    *  POP the screen. A chat composer must stay put, so the whole surface leaves
    *  this false and the bound message list simply re-renders. */
   ok: boolean;
+  /** The response widget the assistant is currently asking with, flattened for
+   *  binding (`aria-widget-view.ts`). `kind: "NONE"` collapses the region.
+   *
+   *  Derived, never accumulated: it is recomputed from the server transcript
+   *  every time the transcript is, which is what makes "one active widget"
+   *  true by construction rather than by remembering to clear it. */
+  widget: WidgetView;
   /** Transient host directives — a poll cadence to install, and a navigation to
    *  perform. The runtime strips both before storing the state, so they are
    *  never persisted and never re-fire when the state is spread. */
@@ -188,6 +199,12 @@ export interface AriaChatLabels {
   /** Status line after the owner stopped a reply. Sits in the NEUTRAL slot:
    *  they asked for it, so nothing went wrong. */
   stopped?: Resolvable<string>;
+  /** Shown under a picker once the owner has chosen as many options as the
+   *  service allows. Takes the limit, because "pick up to 3" is the whole of
+   *  the information. */
+  selectionLimit?: (max: number) => string;
+  /** Shown under a questionnaire while a required answer is missing. */
+  answersIncomplete?: string;
   /** Shown instead of a raw transport error when this HOST cannot reach Wix at
    *  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. */
@@ -195,6 +212,19 @@ export interface AriaChatLabels {
 }
 
 export interface AriaChatOptions {
+  /** Mount the generic card for an unrecognised kind in this `WorkerSubtree`
+   *  slot.
+   *
+   *  Omit it and an unrecognised kind degrades to prose, which is what a
+   *  screen NOT listed in `workerSubtreeScreens` must keep doing — the
+   *  descriptor validator rejects the node otherwise. */
+  subtree?: SubtreeSlot;
+
+  /** Ask the chat-service for an async job's state — one of `initialized`,
+   *  `processing`, `finished`, `failed`. Optional: a host that does not supply
+   *  it renders an ASYNC_TOOL's opening message and never advances it, which is
+   *  strictly better than showing a spinner that can never stop. */
+  asyncJobState?: (jobId: string) => Promise<string>;
   greeting: Resolvable<string>;
   prompts: Resolvable<AriaPromptChip[]>;
   labels?: AriaChatLabels;
@@ -237,7 +267,39 @@ export interface AriaChatOptions {
  *  action passes a POSITIONAL string (`id: "$item.text"` baked into the
  *  descriptor); the standard `tier5.<svc>.<action>` path passes an object. One
  *  normalizer rather than two forks of every action. */
-export type AriaActionArg = string | { message?: string; text?: string; value?: string; id?: string; url?: string; intent?: string } | undefined;
+/** `value` is typed `unknown` deliberately: `SelectionControl.onChange` puts
+ *  its new BOOLEAN there on iOS and Android, and the native marshaller merges
+ *  args over params — so anything reading it must cope with a non-string.
+ *  `optionValue` is the key a caller should use when it means the option. */
+export type AriaActionArg = string | { message?: string; text?: string; value?: unknown; optionValue?: string; id?: string; url?: string; intent?: string } | undefined;
+
+/** The first of these fields that is actually a non-empty string.
+ *
+ *  `value` is `unknown` because `SelectionControl.onChange` puts its new
+ *  BOOLEAN there on iOS and Android and the marshaller merges args over
+ *  params. Every reader therefore has to narrow — `.trim()` on a boolean
+ *  throws, which is how a mis-wired toggle took the whole action down rather
+ *  than merely selecting the wrong row. One helper so there is one place to
+ *  get that right, instead of five `?? ""` chains that each look fine. */
+export function firstString(...candidates: unknown[]): string {
+  for (const c of candidates) {
+    if (typeof c === "string" && c.trim()) return c.trim();
+  }
+  return "";
+}
+
+/** The first candidate that is a string, KEPT VERBATIM.
+ *
+ *  The trimming sibling above is right for an option value, a query or an
+ *  answer — all of which are identifiers or searches where surrounding space
+ *  is noise. It is wrong for anything the owner is still typing: the composer
+ *  reducer runs on every keystroke, so trimming there eats the space between
+ *  two words the instant it is typed and turns "hello world" into
+ *  "helloworld". Only submission normalizes chat text. */
+export function firstStringRaw(...candidates: unknown[]): string {
+  for (const c of candidates) if (typeof c === "string") return c;
+  return "";
+}
 
 // ---------------------------------------------------------------------------
 // Pure helpers (exported for unit tests)
@@ -378,6 +440,24 @@ export function isWixHost(host: string): boolean {
   return host === "wix.com" || host.endsWith(".wix.com") || host === "wixsite.com" || host.endsWith(".wixsite.com");
 }
 
+/** Hosts an option PICTURE may be loaded from.
+ *
+ *  Deliberately a different list from `isWixHost`, which answers "may a LINK
+ *  label stay silent about where it goes". `static.wixstatic.com` is where
+ *  every Wix-hosted image actually lives, so judging pictures by the link list
+ *  blanked the images the service really sends — the catalogue's MULTI_SELECT
+ *  thumbnails among them.
+ *
+ *  The two lists must stay separate rather than merge: a CDN is a fine place
+ *  to fetch a picture from and a poor thing to let a button's label imply. */
+export function isWixMediaHost(host: string): boolean {
+  if (!PLAIN_HOST.test(host)) return false;
+  return isWixHost(host)
+    || host === "wixstatic.com" || host.endsWith(".wixstatic.com")
+    || host === "wixmp.com" || host.endsWith(".wixmp.com")
+    || host === "wix-pages.com" || host.endsWith(".wix-pages.com");
+}
+
 /** Shown in place of a host when an `http(s)` link's host cannot be
  *  established. Deliberately not domain-shaped: it has to read as "this could
  *  not be checked", never as a site the owner might think they recognize.
@@ -517,7 +597,7 @@ export function isDuplicateSend(s: { _pending: string }, content: string): boole
 export function argText(arg: AriaActionArg): string {
   if (typeof arg === "string") return arg.trim();
   if (!arg) return "";
-  return (arg.message ?? arg.text ?? arg.value ?? arg.intent ?? arg.id ?? "").trim();
+  return firstString(arg.message, arg.text, arg.value, arg.intent, arg.id);
 }
 
 /** Reconcile the optimistic bubble against a freshly fetched server transcript.
@@ -765,6 +845,38 @@ export interface AriaChatCore {
    *  that moved during the abort makes this snapshot stale, and committing it
    *  would end a turn the owner has since started. */
   stop(s: AriaChatState): Promise<AriaChatState | undefined>;
+  /** Tapping the active widget's primary / secondary footer button.
+   *
+   *  The url is read from STATE rather than bound into the action's params.
+   *  `$item.` is the binding form an action param is built for; the widget
+   *  region is `$service:`-bound and has no item, and the worker already holds
+   *  the value anyway — so the descriptor names the action and nothing else,
+   *  which is also one less place for a model-supplied url to travel through. */
+  widgetPrimary(s: AriaChatState): Promise<AriaChatState>;
+  widgetSecondary(s: AriaChatState): Promise<AriaChatState>;
+  /** Toggle one option of a MULTI_SELECT-style widget. Synchronous: it is a
+   *  state edit, and making it async would put a turn boundary where there is
+   *  no network call. */
+  widgetToggle(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Choose exactly one, replacing whatever was chosen (RADIO_BUTTON). */
+  widgetSelectOne(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Send a widget button's `respondText`, with the selection substituted in.
+   *  Reuses the composer's send — there is deliberately no second send path. */
+  widgetRespond(s: AriaChatState, arg?: AriaActionArg): Promise<AriaChatState>;
+  /** AUTOCOMPLETE typing. Filters in the worker — there is no autocomplete
+   *  component to filter for us. */
+  widgetQuery(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Pick a suggestion, honouring the payload's own `selectionType`.
+   *
+   *  A descriptor cannot branch on a value, and the two reducers mean
+   *  opposite things — `widgetSelectOne` REPLACES the selection — so wiring
+   *  the row to either one directly is wrong for half the payloads. Tapping a
+   *  second suggestion under `selectionType: "multi"` silently dropped the
+   *  first. The mode is known where the payload is, so the choice belongs
+   *  here. */
+  widgetPick(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
+  /** Answer one QUESTIONNAIRE question. */
+  widgetAnswer(s: AriaChatState, arg?: AriaActionArg): AriaChatState;
 }
 
 const POLL_ID = "aria-turn";
@@ -785,6 +897,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
   const typingText = () => res(o.labels?.typing ?? `${assistant()} is typing…`);
   const slowText = () => res(o.labels?.slow ?? `${assistant()} is taking a while…`);
   const stoppedText = () => res(o.labels?.stopped ?? "Stopped.");
+  const answersIncompleteText = () =>
+    o.labels?.answersIncomplete ?? "Answer the required questions to continue.";
+  const limitReachedText = (max: number) =>
+    o.labels?.selectionLimit?.(max) ?? `You can choose up to ${max}.`;
   // States the fact and stops. It deliberately gives no instruction, because
   // there is none the owner could follow: they are signed in, and the thing that
   // is missing is the app's own Wix binding. "Here" is doing real work — it says
@@ -803,6 +919,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     messages: [], prompts: [], _convId: "", _siteId: "", _pending: "",
     _pendingAfter: 0, _replyAfter: 0, _srvUsers: 0, _srvAssistants: 0,
     _abortId: "", _turnId: "", stopHidden: true, ok: false,
+    widget: NO_WIDGET,
   };
 
   /** One create at a time, per site.
@@ -835,6 +952,21 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
    *  passed in — the only place a concurrent tap is visible is here. */
   let inFlightSend: string | null = null;
 
+  /** A widget send is in the air.
+   *
+   *  A LATCH, not the `submitting` field beside it, and the distinction is the
+   *  whole point: a flag set on the state an action RETURNS does not exist
+   *  until that action resolves, so a second dispatch arriving during the await
+   *  reads the state from before and sails past. Measured — two different
+   *  option buttons tapped in the same tick both started a turn.
+   *
+   *  `inFlightSend` next door guards the composer the same way, but keyed by
+   *  CONTENT: two taps of one option are identical text and it catches them.
+   *  Two taps of DIFFERENT options are different text, so only this catches
+   *  those. `submitting` stays on the state because the descriptor needs
+   *  something to disable a button with; it is the shadow, not the guard. */
+  let widgetSending = false;
+
   /** A turn the server STORED but never got asked to answer.
    *
    *  Sending is two calls: persist, then trigger. When the second fails, the
@@ -921,9 +1053,53 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
 
   /** Fold a freshly read server transcript into the observed-count marks.
    *  Takes the RAW messages, not the bubbles — see `countTurns`. */
-  const observed = (msgs: ConversationMessage[]) => ({
+  /** Carry the owner's SELECTIONS across a rebuild.
+   *
+   *  `observed` runs on every transcript rebuild, including __HIMI_APP_NAME__'s idle
+   *  poll — so a widget that is still on screen was re-derived from the
+   *  payload, and the payload only knows `isPreselected`. An owner could tick
+   *  three boxes, wait for the poll, and watch them silently revert before
+   *  reaching Continue.
+   *
+   *  Reconciled only when it is plainly the SAME ask: same kind, same option
+   *  values in the same order. Anything else is a new question and starts
+   *  from what the service sent. */
+  const carrySelection = (next: WidgetView, prev?: WidgetView): WidgetView => {
+    if (!prev || prev.hidden || next.hidden) return next;
+    if (prev.kind !== next.kind) return next;
+    if (prev.options.length !== next.options.length) return next;
+    for (let i = 0; i < next.options.length; i++) {
+      if (prev.options[i].value !== next.options[i].value) return next;
+    }
+    if (!prev.options.some((o, i) => o.selected !== next.options[i].selected)) return next;
+    const options = next.options.map((o, i) => ({ ...o, selected: prev.options[i].selected }));
+    return reselect({ ...next, options }, options);
+  };
+
+  const observed = (msgs: ConversationMessage[], prev?: WidgetView) => ({
     _srvUsers: countTurns(msgs, "USER"),
     _srvAssistants: countTurns(msgs, "ASSISTANT"),
+    // Derived HERE, with the counts, because this is the one expression every
+    // transcript rebuild already spreads — load, resume, tick and both newChat
+    // arms. That is what makes the widget impossible to leave stale: a rebuild
+    // that forgot to clear it would also have to have forgotten the counts,
+    // which the reply-detection depends on. `observed([])` (new chat) yields
+    // NO_WIDGET for free.
+    // Content is normalized HERE, not in the view: `messageText` decodes the
+    // `{ text: … }` shape the service also sends (treated as empty before,
+    // so those widgets never appeared at all), and `stripHidden` removes
+    // `<HIDDEN>` spans — which are transcript-only, and were promoting hidden
+    // envelopes into live interactive cards. The transcript path already did
+    // both; the widget path did neither.
+    widget: carrySelection(
+      activeWidgetOf(
+        msgs.map((m) => ({ role: m.role, content: stripHidden(messageText(m)) })),
+        disclosedLabel,
+        o.subtree,
+        (url) => isWixMediaHost(hostOf(url)),
+      ),
+      prev,
+    ),
   });
 
   const greetingOnly = (): AriaBubble[] => [plainBubble(GREETING_ID, "ASSISTANT", assistant(), res(o.greeting))];
@@ -983,10 +1159,10 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // the last BUBBLE stalled this loop on exactly that reply, the same way it
       // stalled `tick`.
       if (repliedTo(raw, s._turnId) ?? countTurns(raw, "ASSISTANT") > s._replyAfter) {
-        return { ...s, status: "ready", _convId: convId, messages: bubbles, prompts: [], input: "", statusText: "", error: "", _pending: "", ...observed(raw), ok: false };
+        return { ...s, status: "ready", _convId: convId, messages: bubbles, prompts: [], input: "", statusText: "", error: "", _pending: "", ...observed(raw, s.widget), ok: false };
       }
     }
-    return { ...s, status: "ready", _convId: convId, messages: server, input: "", statusText: slowText(), _pending: "", ...observed(seen), ok: false };
+    return { ...s, status: "ready", _convId: convId, messages: server, input: "", statusText: slowText(), _pending: "", ...observed(seen, s.widget), ok: false };
   }
 
   /** Send + wait, by whichever transport this consumer configured. */
@@ -1024,6 +1200,11 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
       // counting `messages` would mark the turn one assistant reply ahead and
       // the real answer would never register as new.
       _pendingAfter: s._srvUsers, _replyAfter: s._srvAssistants, ok: false,
+      // A new question retires the previous one's controls IMMEDIATELY, rather
+      // than at the next tick. Leaving them up for a second or two invites a
+      // tap that answers a question the owner has already moved past — the same
+      // reason a scrollback widget keeps its prose and loses its controls.
+      widget: NO_WIDGET,
     };
     inFlightSend = content;
     // Held outside the try so a FAILED send still reports the conversation it
@@ -1234,6 +1415,117 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     return s.stopHidden === hidden ? s : { ...s, stopHidden: hidden };
   };
 
+  /** Ask the service how an async job is getting on.
+   *
+   *  Folded into the existing `tick` rather than armed as a SECOND `_poll`, and
+   *  that is a constraint rather than a preference: `PollDirective` has no stop
+   *  verb, so a second timer could be started and never cancelled — it would
+   *  outlive the widget, the turn and the conversation, and keep asking about a
+   *  job nobody is looking at. Riding the chat's own ladder means the job stops
+   *  being polled exactly when the widget stops existing, which is the
+   *  behaviour the acceptance list asks for and the only one this directive can
+   *  actually deliver.
+   *
+   *  It also costs nothing extra: the ladder is already fast while a turn is in
+   *  flight, which is when a job is running. */
+  const readJobState = async (jobId: string): Promise<string> => {
+    if (!o.asyncJobState) return "";
+    try {
+      return (await o.asyncJobState(jobId)) || "";
+    } catch {
+      // A failed read is not a failed job. Saying "failed" on one dropped
+      // request would tell the owner their work was lost when it is still
+      // running; the next tick asks again.
+      return "";
+    }
+  };
+
+  /** Advance the active ASYNC_TOOL widget, if there is one with a job to ask
+   *  about. Returns the widget unchanged in every other case. */
+  const withJobProgress = async (w: WidgetView): Promise<WidgetView> => {
+    if (w.kind !== "ASYNC_TOOL" || !w.asyncJobId || !w.asyncRunning) return w;
+    const state = await readJobState(w.asyncJobId);
+    if (!state || state === w.asyncState) return w;
+    return asyncAdvanced(w, state);
+  };
+
+  /** Open a widget button's destination.
+   *
+   *  Deliberately the SAME path a transcript link takes — `resolveEntity` first
+   *  so an entity we can render natively becomes a `_nav` (and gets the host's
+   *  linkable-target check), external otherwise. A widget url is no more
+   *  trusted than a link inside a reply; both are model output, and giving the
+   *  widget its own opener would be a second place to forget that.
+   *
+   *  A button with no url does nothing rather than erroring: the descriptor
+   *  hides those, so reaching here means the state changed under a tap already
+   *  in flight. */
+  /** A widget button's destination is MODEL-INFLUENCED, and reachable by
+   *  prompt injection through content this owner does not control. The
+   *  transcript's own links are already restricted to `http(s)` by the
+   *  extractor that finds them; a widget url arrives straight off the payload
+   *  and reached the system opener after nothing but a `trim()`.
+   *
+   *  That is a bigger gap than it looks: the opener takes ANY scheme, so a
+   *  payload could name `tel:`, `sms:`, a `wix://` deep link, or a custom
+   *  scheme registered by some other app on the device. Host disclosure
+   *  changes the LABEL; it does not stop the navigation.
+   *
+   *  So: an in-app entity first (that path never leaves the app), then
+   *  `http(s)` only. Anything else is dropped rather than opened. Dropping is
+   *  right rather than cautious — there is no widget in the catalogue whose
+   *  button needs a non-web scheme, so anything that asks for one is either a
+   *  service change we should implement deliberately or an attack. */
+  const openWidgetUrl = async (s: AriaChatState, url: string): Promise<AriaChatState> => {
+    const target = url.trim();
+    if (!target) return s;
+    const entity = o.resolveEntity?.(target) ?? null;
+    if (entity) return navigate(s, entity);
+    if (!isWebUrl(target)) return s;
+    if (o.openLink) { try { await o.openLink(target); } catch { /* best-effort */ } }
+    return s;
+  };
+
+  /** The value an option action names. Accepts the bare string and the object
+   *  form, as every other action here does — the two hosts dispatch differently
+   *  and a reducer that only understood one silently did nothing on the other. */
+  /** Which option an action names.
+   *
+   *  `optionValue` is read BEFORE `value`, and non-strings are ignored, because
+   *  `SelectionControl.onChange` puts its new boolean in `args.value` on iOS
+   *  and Android and the native marshaller merges args over params. So a
+   *  toggle wired through `value` arrived as `true`/`false` on device while
+   *  working on web — and `.trim()` on a boolean THROWS, so the row did not
+   *  merely mis-select, it took the action down. Web-only testing cannot see
+   *  this; the control's own contract is what gives it away. */
+  const optionValue = (arg?: AriaActionArg): string =>
+    typeof arg === "string" ? arg.trim() : firstString(arg?.optionValue, arg?.value, arg?.id, arg?.text);
+
+  /** Re-derive everything that follows from which options are selected.
+   *
+   *  One function rather than three call sites, because `limitReached`,
+   *  `primaryDisabled` and the helper line are each a pure function of the
+   *  selection and the payload — and a toggle that updated two of the three is
+   *  the shape of bug that leaves a button enabled over an empty selection. */
+  const reselect = (w: WidgetView, options: WidgetOptionRow[]): WidgetView => {
+    const chosen = options.filter((o) => o.selected).length;
+    const limitReached = w.maxSelected > 0 && chosen >= w.maxSelected;
+    // Only says anything once the owner is actually against the limit. A line
+    // that is always there is noise; one that appears at the moment of refusal
+    // explains the refusal.
+    const limitText = limitReached ? limitReachedText(w.maxSelected) : "";
+    const disabled = w.submitting || (w.requiresSelection && chosen === 0);
+    return {
+      ...w,
+      options,
+      limitReached,
+      limitText,
+      limitTextHidden: !limitText,
+      primaryDisabled: disabled,
+      primaryEnabled: !disabled,
+    };
+  };
+
   const impl: AriaChatCore = {
     initialState,
 
@@ -1259,7 +1551,7 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
           const bubbles = toBubbles(raw, assistant(), you());
           const resumed = bubbles.length ? bubbles : greetingOnly();
           return { ...s, status: "ready", _convId: resumeId, _siteId: site, _pending: "", statusText: "", error: "",
-            messages: resumed, ...observed(raw), prompts: promptsFor(resumed, promptList()) };
+            messages: resumed, ...observed(raw, s.widget), prompts: promptsFor(resumed, promptList()) };
         } catch { /* expired or unreachable — fall through to a fresh one */ }
       }
       // Opening a screen runs `load` more than once — the bundle self-kicks at
@@ -1301,7 +1593,11 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     },
 
     typing: (s, arg) => {
-      const next = typeof arg === "string" ? arg : (arg?.value ?? arg?.text ?? arg?.message ?? "");
+      // Narrowed but NOT trimmed. `value` may be a boolean — assigning that
+      // to the draft would put "true" in the box — but this runs on every
+      // keystroke, so trimming would delete the space between two words as
+      // soon as the owner typed it.
+      const next = typeof arg === "string" ? arg : firstStringRaw(arg?.value, arg?.text, arg?.message);
       // Recorded even when the value is unchanged, because the counter is about
       // "did an edit happen", and a keystroke that retypes the same character
       // still happened.
@@ -1419,12 +1715,16 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
           status: replied ? "ready" : s.status,
           messages: painted,
           _pending: pending,
-          ...observed(raw),
+          ...observed(raw, s.widget),
           prompts: promptsFor(painted, promptList()),
           statusText: replied ? "" : s.statusText,
         };
+        // The async job rides this same tick — see `withJobProgress`. Done
+        // AFTER the transcript rebuild, so a widget that has just been retired
+        // by a new answer is never polled for.
+        const withJob = { ...next, widget: await withJobProgress(next.widget) };
         // Slow the ladder the moment the turn is over; leave it alone otherwise.
-        return replied && wasFast ? cadence(next, o.poll.idleMs, o.poll.fastMs) : next;
+        return replied && wasFast ? cadence(withJob, o.poll.idleMs, o.poll.fastMs) : withJob;
       } catch {
         // A read that THREW is exactly as stale as one that resolved: if a turn
         // boundary moved on while it was in flight, returning `s` merges the
@@ -1439,6 +1739,153 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     // A tapped action link. An entity we can render natively becomes a `_nav`
     // directive (the host applies the same linkable-target check an authored
     // `himi.open` gets); anything else opens externally.
+    widgetPick: (s, arg) =>
+      s.widget.selectionType === "multi" ? impl.widgetToggle(s, arg) : impl.widgetSelectOne(s, arg),
+
+    widgetQuery: (s, arg) => {
+      const q = typeof arg === "string" ? arg.trim() : firstString(arg?.value, arg?.text);
+      const w = s.widget;
+      const needle = q.toLowerCase();
+      // Match on everything the owner can SEE. Matching only `title` makes a
+      // subtitle that says "Downtown branch" unsearchable, which reads as the
+      // filter being broken rather than as a deliberate scope.
+      const suggestions = !needle
+        ? w.options
+        : w.options.filter((o) =>
+            `${o.title} ${o.subtitle} ${o.text}`.toLowerCase().includes(needle));
+      return {
+        ...s,
+        widget: {
+          ...w,
+          query: q,
+          suggestions,
+          suggestionsEmpty: suggestions.length === 0,
+          // Typed something and got nothing is a different state from having
+          // typed nothing at all, and says something different to the owner.
+          noMatches: !!needle && suggestions.length === 0,
+        },
+      };
+    },
+
+    widgetAnswer: (s, arg) => {
+      const qid = (typeof arg === "string" ? arg : (arg?.id ?? "")).trim();
+      const answer = typeof arg === "string" ? "" : firstString(arg?.value, arg?.text);
+      if (!qid) return s;
+      const questions = s.widget.questions.map((q) =>
+        q.id === qid
+          ? { ...q, answer, answerHidden: !answer, missing: q.required && !answer }
+          : q);
+      if (questions === s.widget.questions) return s;
+      const incomplete = questions.some((q) => q.missing);
+      return {
+        ...s,
+        widget: {
+          ...s.widget,
+          questions,
+          answersIncomplete: incomplete,
+          // Only says anything while something is actually missing.
+          answersText: incomplete ? answersIncompleteText() : "",
+          answersTextHidden: !incomplete,
+          primaryDisabled: s.widget.submitting || incomplete,
+          primaryEnabled: !(s.widget.submitting || incomplete),
+        },
+      };
+    },
+
+    widgetToggle: (s, arg) => {
+      const value = optionValue(arg);
+      if (!value) return s;
+      const current = s.widget.options;
+      const target = current.find((o) => o.value === value);
+      if (!target) return s;
+      // Turning one OFF is always allowed, limit or not: the limit is a ceiling
+      // on how many may be chosen, never a floor, and refusing to deselect
+      // would trap an owner who hit it.
+      if (!target.selected && s.widget.limitReached) return s;
+      const options = current.map((o) => (o.value === value ? { ...o, selected: !o.selected } : o));
+      return { ...s, widget: reselect(s.widget, options) };
+    },
+
+    widgetSelectOne: (s, arg) => {
+      const value = optionValue(arg);
+      if (!value) return s;
+      if (!s.widget.options.some((o) => o.value === value)) return s;
+      // Replaces rather than accumulates, and the limit does not apply: one is
+      // never more than a ceiling of one or more.
+      const options = s.widget.options.map((o) => ({ ...o, selected: o.value === value }));
+      return { ...s, widget: reselect(s.widget, options) };
+    },
+
+    widgetRespond: async (s, arg) => {
+      // Which button. The three that can send are the widget's two footer
+      // buttons and any one option's own button; an option names itself by
+      // value, the footers by keyword.
+      const which = optionValue(arg) || "primary";
+      const w = s.widget;
+      // A second tap while the first send is in the air. The composer refuses
+      // this through `isDuplicateSend` on the CONTENT; a widget button has to
+      // refuse on the ACTION too, because two taps of the same option produce
+      // identical content and the second would otherwise look like a retry of
+      // a send that had already failed.
+      if (widgetSending) return s;
+
+      const option = w.options.find((o) => o.value === which);
+      const template = option
+        ? option.respondText
+        : which === "secondary" ? w.secondaryRespondText : w.primaryRespondText;
+      if (!template) return s;
+
+      // What the owner actually chose. An option's own button answers with
+      // ITSELF even when nothing is ticked — tapping "Select" on a row IS the
+      // selection — while a footer button speaks for the accumulated set.
+      const selected = option && !option.selected
+        ? [option.title || option.value]
+        : w.options.filter((o) => o.selected).map((o) => o.title || o.value);
+      const content = substituteSelection(template, selected).trim();
+      if (!content) return s;
+      if (duplicate(s, content)) return s;
+
+      // Mark in-flight BEFORE the await so a second dispatch sees it. The
+      // widget is not cleared here: `send` paints the owner's message
+      // optimistically and the next transcript rebuild derives the widget
+      // afresh, which retires it. Clearing it here as well would be a second
+      // place deciding when a widget ends.
+      const sending: AriaChatState = {
+        ...s,
+        widget: { ...w, submitting: true, primaryDisabled: true, primaryEnabled: false },
+      };
+      widgetSending = true;
+      let next: AriaChatState;
+      try {
+        next = await send(sending, content);
+      } finally {
+        widgetSending = false;
+      }
+      // A FAILED send keeps the widget and the selection, so the owner can tap
+      // again rather than lose what they picked. `send` reports failure through
+      // the error slot while leaving the turn un-started.
+      return next.error
+        ? { ...next, widget: reselect({ ...w, submitting: false }, w.options) }
+        : next;
+    },
+
+    // A footer button is EITHER a link or a reply, and the view makes it
+    // visible for both: `primaryHidden` is false when there is a label and
+    // either a url or a `respondText`. Opening the url unconditionally
+    // therefore made every response-only footer inert — the whole of
+    // VISUAL_DISPLAY, TODO_PLAN and PREMIUM_UPSELL, which is most of what
+    // these two buttons are for.
+    //
+    // The url wins when both are present: a button that names a destination
+    // should go there, and `respondText` beside it is the fallback the
+    // service sends for clients that cannot open one.
+    widgetPrimary: (s) => s.widget.primaryUrl
+      ? openWidgetUrl(s, s.widget.primaryUrl)
+      : impl.widgetRespond(s, { value: "primary" }),
+    widgetSecondary: (s) => s.widget.secondaryUrl
+      ? openWidgetUrl(s, s.widget.secondaryUrl)
+      : impl.widgetRespond(s, { value: "secondary" }),
+
     openLink: async (s, arg) => {
       const url = typeof arg === "string" ? arg.trim() : (arg?.url ?? arg?.id ?? "").trim();
       if (!url) return s;
@@ -1525,6 +1972,16 @@ export function createAriaChat(o: AriaChatOptions): AriaChatCore {
     tick: (s) => impl.tick(s).then((r) => (r ? gated(r) : r)),
     openLink: (s, arg) => impl.openLink(s, arg).then(gated),
     stop: (s) => impl.stop(s).then((r) => (r ? gated(r) : r)),
+    // Synchronous, like `typing`: a selection edit makes no network call, so
+    // gating it is a plain call rather than a `.then`.
+    widgetToggle: (s, arg) => gated(impl.widgetToggle(s, arg)),
+    widgetSelectOne: (s, arg) => gated(impl.widgetSelectOne(s, arg)),
+    widgetPick: (s, arg) => gated(impl.widgetPick(s, arg)),
+    widgetQuery: (s, arg) => gated(impl.widgetQuery(s, arg)),
+    widgetAnswer: (s, arg) => gated(impl.widgetAnswer(s, arg)),
+    widgetRespond: (s, arg) => impl.widgetRespond(s, arg).then(gated),
+    widgetPrimary: (s) => impl.widgetPrimary(s).then(gated),
+    widgetSecondary: (s) => impl.widgetSecondary(s).then(gated),
   };
 }