@wix/himalaya-cli 0.960.0 → 0.962.0

package/templates/yoga-studio-owner/tier5-src/_shared/aria-widget-view.ts

@@ -0,0 +1,722 @@
+// The active response widget, flattened into something a descriptor can bind
+// to.
+//
+// `aria-widget-kinds.ts` turns a scanned envelope into a
+// `NormalizedWidget`. That model is shaped for CODE — nested objects, a typed
+// `extra` bag, `null` for an absent button. A descriptor cannot read any of
+// that: `$service:` resolves a path to a SCALAR, and `$item.` substitutes whole
+// prop values only, so a row whose field is missing renders as nothing at all.
+//
+// This module is the adapter between the two. Everything it produces is either
+// a scalar or an array of all-scalar rows, every field is always present, and
+// every collapsible element carries its own `*Hidden` boolean — the same shape
+// the transcript bubbles already use for their three link slots.
+
+import type { NormalizedWidget, WidgetKind } from "./aria-widget-model.js";
+import { composeGenericCard } from "./aria-generic-widget.js";
+import { normalizeWidget } from "./aria-widget-kinds.js";
+import { scanEnvelopes, widgetsOfParts } from "./aria-widgets.js";
+
+/** Just enough of a transcript row to find the active widget in. Declared here
+ *  rather than imported from `aria-chat.ts` so this module has no dependency on
+ *  it at all — see `Disclose` below for why that matters. */
+export interface WidgetSourceMessage {
+  role?: string;
+  content?: unknown;
+}
+
+/** How a button's label is rendered when it carries an off-Wix destination.
+ *
+ *  Passed IN rather than imported, and the reason is mechanical: `aria-chat.ts`
+ *  imports this module to build its state, so importing `disclosedLabel` back
+ *  out of it would close a runtime cycle through the bundler. Injection keeps
+ *  the single implementation — the caller hands over the very same
+ *  `disclosedLabel` the transcript's link rows use — while leaving this module
+ *  standalone and testable without booting the chat core. */
+export type Disclose = (link: { label: string; url: string }) => string;
+
+/** What the region keys on. The widget kinds, plus the one state that is not a
+ *  widget: nothing to show, region collapsed. */
+export type WidgetCase = WidgetKind | "NONE";
+
+/** Every case the descriptor must carry, in a fixed order.
+ *
+ *  Exported so the `FragmentSlot` and the test that pins it read the SAME list
+ *  rather than two hand-kept copies — a case the union has and the descriptor
+ *  does not is a widget that renders nothing, silently. */
+export const WIDGET_CASES: readonly WidgetCase[] = [
+  "SINGLE_SELECT", "MULTI_SELECT", "SINGLE_SELECT_BUTTON", "RADIO_BUTTON", "PLANS",
+  "PREMIUM_UPSELL", "VISUAL_DISPLAY", "AUTOCOMPLETE", "ITEMS_SELECTION", "QUESTIONNAIRE",
+  "CHART", "TODO_PLAN", "ASYNC_TOOL", "OAUTH_REQUIRED", "UNKNOWN", "NONE",
+];
+
+/** One body row of a display widget. All-scalar, every field present: this is
+ *  `$item.`-templated, and a row missing a field substitutes as nothing. */
+export interface WidgetRow {
+  id: string;
+  title: string;
+  subtitle: string;
+  /** `true` when `subtitle` is empty, so the row collapses its second line
+   *  instead of leaving a gap. `$item.` cannot express "hide when empty". */
+  subtitleHidden: boolean;
+}
+
+/** One selectable option, flattened for binding.
+ *
+ *  Same rule as `WidgetRow` and for the same reason: `$item.` substitutes whole
+ *  prop values, so every field is present and scalar or the row renders as
+ *  nothing at all. `selected` is a boolean the worker owns — a `$service:`
+ *  binding is a read-only snapshot, so a checkbox reads it and writes through a
+ *  `widgetToggle` dispatch rather than mutating anything itself. */
+export interface WidgetOptionRow {
+  id: string;
+  value: string;
+  title: string;
+  subtitle: string;
+  subtitleHidden: boolean;
+  text: string;
+  textHidden: boolean;
+  pictureUrl: string;
+  pictureHidden: boolean;
+  /** The per-option button's label, already host-disclosed. */
+  buttonLabel: string;
+  buttonHidden: boolean;
+  /** PLANS' benefit list, joined — an array cannot ride on a templated row. */
+  listText: string;
+  listHidden: boolean;
+  selected: boolean;
+  /** This option's own button `respondText`, before substitution. Carried on
+   *  the row because the row is what a tap identifies. */
+  respondText: string;
+}
+
+/** One slice of a CHART. `value` is a RAW magnitude, never a percentage: the
+ *  renderer computes each share, because one handed percentages that do not sum
+ *  to 100 cannot draw them honestly. */
+export interface WidgetSlice {
+  label: string;
+  value: number;
+}
+
+/** One step of a TODO_PLAN, shaped for `Timeline`. */
+export interface WidgetStep {
+  id: string;
+  title: string;
+  subtitle: string;
+  /** `Timeline` draws a completed entry differently. */
+  done: boolean;
+}
+
+/** The active widget, as the screen reads it. */
+export interface WidgetView {
+  kind: WidgetCase;
+  /** `true` when there is nothing to show. The whole region is hidden on this
+   *  rather than on `kind === "NONE"`, because a descriptor cannot compare —
+   *  `hiddenWhen` binds a boolean and nothing else. It is what keeps the region
+   *  from leaving a gap in the transcript when the assistant is just talking. */
+  hidden: boolean;
+  /** Prose. For PREMIUM_UPSELL this is the body under `title`. */
+  text: string;
+  textHidden: boolean;
+  title: string;
+  titleHidden: boolean;
+  bottomText: string;
+  bottomTextHidden: boolean;
+  badge: string;
+  badgeHidden: boolean;
+  imageUrl: string;
+  imageHidden: boolean;
+  /** Footer buttons, already host-disclosed (see `discloseButton`). */
+  primaryLabel: string;
+  primaryHidden: boolean;
+  primaryUrl: string;
+  /** The footer buttons' `respondText`, before substitution. */
+  primaryRespondText: string;
+  secondaryRespondText: string;
+  secondaryLabel: string;
+  secondaryHidden: boolean;
+  secondaryUrl: string;
+  rows: WidgetRow[];
+  /** The selectable options. Separate from `rows`, which is VISUAL_DISPLAY's
+   *  body sections — the catalogue sends BOTH at once, so conflating them
+   *  silently drops one. */
+  options: WidgetOptionRow[];
+  /** How many options may be chosen at once, `0` for no limit. Enforced in the
+   *  worker: no component carries a selection-count prop, so this cannot be
+   *  declared in the descriptor. */
+  maxSelected: number;
+  /** `true` once the limit is reached, so further options can be disabled. */
+  limitReached: boolean;
+  /** The line explaining why, empty when there is nothing to explain. */
+  limitText: string;
+  limitTextHidden: boolean;
+  /** The payload said the primary button needs a selection
+   *  (`disableIfNothingSelected`). Kept as its own field because
+   *  `primaryDisabled` is derived and has to be recomputed on every toggle —
+   *  a derived value cannot also be its own input. */
+  requiresSelection: boolean;
+  /** `true` when the primary button must not be tappable — either
+   *  `requiresSelection` with nothing chosen, or a send in flight. */
+  primaryDisabled: boolean;
+  /** Its exact inverse, carried rather than computed, because a descriptor
+   *  cannot negate: `hiddenPath` binds a boolean and there is no `not`. The
+   *  live button hides on `primaryDisabled` and the greyed twin hides on this,
+   *  so exactly one of the two is ever on screen. */
+  primaryEnabled: boolean;
+  /** A send started from a widget button is in flight. */
+  submitting: boolean;
+
+  // --- CHART ---------------------------------------------------------------
+  /** `$service:`-bound, and it has to be: `DonutChart.slices_path` and
+   *  `ChartSeries.values_path` are SERVICE-ONLY, so a chart cannot live in a
+   *  templated row. That constraint is why the widget region exists at all.
+   *  <!-- platform-lint-ok: a property of the two native decoders, not of every surface --> */
+  slices: WidgetSlice[];
+  /** The raw magnitudes, for the non-pie chart kinds. */
+  values: number[];
+  /** `"pie"` draws a `DonutChart` at `thickness: 0`; anything else is a
+   *  `Chart`. Carried as a boolean as well, because a descriptor cannot
+   *  compare strings. */
+  chartIsPie: boolean;
+  /** Hide the pie. A dedicated flag because `chartIsSeries` is NOT its
+   *  negation: an EMPTY chart is neither, so hiding each component on the
+   *  other's flag left both on screen as blank boxes. */
+  chartPieHidden: boolean;
+  chartSeriesHidden: boolean;
+  chartEmptyHidden: boolean;
+  /** Hide the async spinner. `asyncUntracked` is not the right flag: a TRACKED
+   *  job that reaches `finished` or `failed` still has an id, so hiding on
+   *  untracked left a terminal job spinning forever. */
+  asyncSpinnerHidden: boolean;
+  /** Hide the provider spinner. Separate from `itemsErrorHidden`, which is
+   *  TRUE while loading and FALSE after a failure — using it hid the spinner
+   *  exactly when it was needed and showed it beside the error. */
+  itemsLoadingHidden: boolean;
+  chartIsSeries: boolean;
+  chartKind: string;
+  chartEmpty: boolean;
+  description: string;
+  descriptionHidden: boolean;
+
+  // --- TODO_PLAN -----------------------------------------------------------
+  steps: WidgetStep[];
+  stepsEmpty: boolean;
+  /** 0–1. `Timeline` shows WHICH steps are done; this says how far along the
+   *  whole plan is, which a list of ticks does not answer at a glance. */
+  progress: number;
+  progressText: string;
+
+  // --- ASYNC_TOOL ----------------------------------------------------------
+  asyncJobId: string;
+  /** The job's last known state. Kept so a tick can tell "no change" from
+   *  "not asked yet" without a second field. */
+  asyncState: string;
+  /** The message for the job's CURRENT state, already chosen from
+   *  `statusMessages` — a descriptor cannot pick between four strings. */
+  asyncMessage: string;
+  /** `true` while the job is still running, so the spinner shows. */
+  asyncRunning: boolean;
+  /** A job with no id: the status messages are still worth showing, but there
+   *  is nothing to poll for, so it never spins. */
+  asyncUntracked: boolean;
+  /** The four status lines, kept so a later state change can pick a different
+   *  one without re-parsing the payload. */
+  extraStatusMessages: Record<string, string>;
+
+  // --- AUTOCOMPLETE --------------------------------------------------------
+  /** What the owner has typed. There is no autocomplete component anywhere in
+   *  the proto — `TextFieldProps.suggestions` is the OS keyboard strip, not a
+   *  dropdown — so this is a composition: `SearchField` → worker filter → a
+   *  `$service:`-bound list that collapses when empty. */
+  query: string;
+  /** The options that survive `query`. A separate array from `options`, so
+   *  filtering never destroys what the service sent. */
+  suggestions: WidgetOptionRow[];
+  suggestionsEmpty: boolean;
+  /** `true` when a query is typed and matches nothing — which is a different
+   *  state from "nothing typed yet", and reads differently to the owner. */
+  noMatches: boolean;
+  /** `single` or `multi`. */
+  selectionType: string;
+
+  // --- QUESTIONNAIRE -------------------------------------------------------
+  questions: WidgetQuestion[];
+  questionsEmpty: boolean;
+  /** `true` while any `required` question is unanswered. The submit is gated
+   *  on it — there is no cross-field validation in `Validation`, so "every
+   *  required question has an answer" has to be worked out here. */
+  answersIncomplete: boolean;
+  answersText: string;
+  answersTextHidden: boolean;
+
+  // --- ITEMS_SELECTION -----------------------------------------------------
+  providerKey: string;
+  /** The provider query is in flight. */
+  itemsLoading: boolean;
+  /** It failed. The chat stays usable; only the widget says so. */
+  itemsError: string;
+  itemsErrorHidden: boolean;
+  itemsEmpty: boolean;
+
+  // --- UNKNOWN --------------------------------------------------------------
+  /** A generic card composed by the worker for a widget kind this build does
+   *  not recognise, as a JSON string for a `WorkerSubtree` slot.
+   *
+   *  Empty for every KNOWN kind — those have a real `FragmentSlot` case — and
+   *  empty too when the composer could not build one it is sure of. Empty is
+   *  not a special case the descriptor has to test for: an empty string fails
+   *  validation, and a failed validation renders the declared fallback, which
+   *  is the plain prose card. The fail-closed path and the nothing-to-show
+   *  path are the same path. */
+  treeJson: string;
+}
+
+/** One question of a QUESTIONNAIRE, flattened. `$item.`-templated, so every
+ *  field is present and scalar. */
+export interface WidgetQuestion {
+  id: string;
+  title: string;
+  subtitle: string;
+  subtitleHidden: boolean;
+  /** `single-select`, `multi-select`, `text`, … as the service spells it. */
+  type: string;
+  required: boolean;
+  /** `true` when `required` and nothing chosen or typed. */
+  missing: boolean;
+  /** The chosen option's title, or the typed text. Empty when unanswered. */
+  answer: string;
+  answerHidden: boolean;
+  /** The free-text escape hatch, per question. */
+  freePlaceholder: string;
+  freeHidden: boolean;
+}
+
+/** Nothing to show. The region binds this and collapses. */
+export const NO_WIDGET: WidgetView = {
+  kind: "NONE",
+  hidden: true,
+  text: "", textHidden: true,
+  title: "", titleHidden: true,
+  bottomText: "", bottomTextHidden: true,
+  badge: "", badgeHidden: true,
+  imageUrl: "", imageHidden: true,
+  primaryLabel: "", primaryHidden: true, primaryUrl: "", primaryRespondText: "",
+  secondaryLabel: "", secondaryHidden: true, secondaryUrl: "", secondaryRespondText: "",
+  rows: [],
+  options: [], maxSelected: 0, limitReached: false, requiresSelection: false,
+  limitText: "", limitTextHidden: true,
+  primaryDisabled: false, primaryEnabled: true, submitting: false,
+  slices: [], values: [], chartIsPie: false, chartIsSeries: false, chartKind: "",
+  chartPieHidden: true, chartSeriesHidden: true, chartEmptyHidden: true,
+  asyncSpinnerHidden: true, itemsLoadingHidden: true,
+  chartEmpty: true, description: "", descriptionHidden: true,
+  steps: [], stepsEmpty: true, progress: 0, progressText: "",
+  asyncJobId: "", asyncState: "", asyncMessage: "", asyncRunning: false, asyncUntracked: false,
+  extraStatusMessages: {},
+  query: "", suggestions: [], suggestionsEmpty: true, noMatches: false, selectionType: "",
+  questions: [], questionsEmpty: true, answersIncomplete: false,
+  answersText: "", answersTextHidden: true,
+  providerKey: "", itemsLoading: false, itemsError: "", itemsErrorHidden: true, itemsEmpty: true,
+  treeJson: "",
+};
+
+/** A button's label as the owner should see it.
+ *
+ *  A widget-borne url is model-influenced content and the label beside it is
+ *  too — nothing makes them agree, which is the shape of a phishing link. This
+ *  reuses `disclosedLabel` from the transcript's link rows rather than adding a
+ *  second URL check: that one already survives the two defeats it was
+ *  hardened against (a backslash ending the authority, and `endsWith` being a
+ *  string
+ *  test) and renders an unreadable authority as "unknown site" instead of
+ *  silently. A second implementation is a second thing to get wrong.
+ *
+ *  A button with no url is left alone: there is no destination to disclose. */
+function discloseButton(disclose: Disclose, label: string, url: string): string {
+  return url ? disclose({ label, url }) : label;
+}
+
+/** One option, flattened. `selected` is passed in because it is worker state
+ *  rather than anything the payload said — except on the first build, where the
+ *  service's `isPreselected` seeds it. */
+function optionRow(
+  o: {
+    value: string; title: string; subtitle: string; text: string;
+    pictureUrl: string; buttonLabel: string; actionUrl: string; listText: string;
+    respondText: string;
+  },
+  i: number,
+  selected: boolean,
+  disclose: Disclose,
+  /** May this option's picture be loaded? A different question from the link
+   *  disclosure beside it — see `isWixMediaHost`. */
+  allowPicture: (url: string) => boolean,
+  /** UNKNOWN kinds synthesize a missing `respondText` from the row's own
+   *  label — see `viewOf`. Known kinds must NOT: an absent template there is
+   *  a payload bug for a shape that has a real case, and inventing one would
+   *  hide it. */
+  genericFallback = false,
+): WidgetOptionRow {
+  // An option's PICTURE is a url off the wire like any other, and this is the
+  // one the epic's acceptance list calls out. It is not a label, so there is
+  // nothing to disclose INTO — an off-Wix picture is dropped rather than
+  // annotated, because a decorative image cannot carry its own provenance and
+  // a silently-loaded remote asset is a tracking pixel with extra steps.
+  // Judged by `allowPicture` — the MEDIA list — rather than by the link
+  // discloser. `static.wixstatic.com` is where every Wix-hosted image lives,
+  // so asking the link question about it blanked the pictures the service
+  // really sends.
+  const pictureUrl = o.pictureUrl && allowPicture(o.pictureUrl) ? o.pictureUrl : "";
+  // Via `discloseButton`, NOT `disclose` directly: an option button usually has
+  // no url at all (it sends `respondText`), and disclosing an empty url appends
+  // "(unknown site)" to a button that goes nowhere. That reads as a phishing
+  // warning on the ordinary path and devalues the annotation on the path that
+  // needs it.
+  const buttonLabel = discloseButton(disclose, o.buttonLabel, o.actionUrl);
+
+  // An option's two display lines.
+  //
+  // The service uses `subtitle` and `text` as ALTERNATES, never together:
+  // AUTOCOMPLETE and PLANS send `subtitle`, while SINGLE_SELECT, MULTI_SELECT
+  // and RADIO_BUTTON send `text`. A row that binds only `subtitle` therefore
+  // drops the descriptive line for three of the fourteen kinds — and a
+  // RADIO_BUTTON option, which may carry `text` and no `title` at all, renders
+  // as an empty row. So fold here rather than in each case's composition: the
+  // raw `text` is still exported below for anything that wants both.
+  const hasTitle = !!o.title;
+  const rowTitle = hasTitle ? o.title : (o.text || o.subtitle);
+  const rowSubtitle = hasTitle
+    ? (o.subtitle || o.text)
+    : (o.text && o.subtitle ? o.subtitle : "");
+  return {
+    id: `o${i}`,
+    value: o.value,
+    title: rowTitle,
+    subtitle: rowSubtitle, subtitleHidden: !rowSubtitle,
+    text: o.text, textHidden: !o.text,
+    pictureUrl, pictureHidden: !pictureUrl,
+    buttonLabel, buttonHidden: !buttonLabel,
+    listText: o.listText, listHidden: !o.listText,
+    selected,
+    respondText: o.respondText
+      || (genericFallback ? (o.title || o.text || o.subtitle || o.value) : ""),
+  };
+}
+
+/** Does this url belong to a host the discloser leaves alone?
+ *
+ *  `disclosedLabel` answers "what should the owner read", which for an on-Wix
+ *  destination is the label unchanged. Feeding it a sentinel and checking
+ *  whether it came back untouched is how a caller asks the same question
+ *  without a second host check — the thing the epic's security section forbids
+ *  writing twice. */
+function isDisclosedSame(disclose: Disclose, url: string): boolean {
+  const probe = "\u0000wix-probe";
+  return disclose({ label: probe, url }) === probe;
+}
+
+/** Re-derive an ASYNC_TOOL widget for a new job state.
+ *
+ *  Separate from `viewOf` because it runs on a LIVE widget rather than a fresh
+ *  payload — the status messages were parsed once and only the state moves. */
+export function asyncAdvanced(w: WidgetView, state: string): WidgetView {
+  const msgs = (w.extraStatusMessages ?? {}) as Record<string, string>;
+  const running = state === "initialized" || state === "processing";
+  return {
+    ...w,
+    asyncState: state,
+    asyncMessage: msgs[state] || w.asyncMessage,
+    asyncRunning: running,
+    // Recomputed here too: a terminal job keeps its id, so a spinner hidden
+    // on trackedness alone would never stop.
+    asyncSpinnerHidden: !running,
+  };
+}
+
+/** Turn a normalized widget into the flat view the descriptor binds. */
+/** Where the generic UNKNOWN card is mounted, when the app mounts one.
+ *
+ *  Optional because the second app that mounts Aria has not adopted the
+ *  subtree — `config.workerSubtreeScreens` is per screen, and a descriptor
+ *  that is not on the allowlist rejects the node outright. Absent means "the
+ *  prose card, as before". */
+export interface SubtreeSlot { slotId: string; service: string }
+
+export function viewOf(
+  w: NormalizedWidget,
+  disclose: Disclose,
+  subtree?: SubtreeSlot,
+  /** Defaults to the link discloser, which is what every caller did before the
+   *  media list existed — wrong for pictures, but never MORE permissive. */
+  allowPicture: (url: string) => boolean = (url) => isDisclosedSame(disclose, url),
+): WidgetView {
+  const extra = w.extra as Record<string, unknown>;
+  const title = typeof extra.title === "string" ? extra.title : "";
+  // Through the SAME media check as an option's picture. Counting `imageUrl`
+  // towards renderability made an image-only VISUAL_DISPLAY reachable, and the
+  // descriptor binds this path straight into an `Image` — so an off-Wix url
+  // here is a remote asset fetched on sight, which is a tracking pixel with
+  // extra steps. The option rows have been gated since #2605; this path had
+  // never been reachable on its own before, which is exactly why it was easy
+  // to widen without noticing.
+  const rawImageUrl = typeof extra.imageUrl === "string" ? extra.imageUrl : "";
+  const imageUrl = rawImageUrl && allowPicture(rawImageUrl) ? rawImageUrl : "";
+
+  const sections = Array.isArray(extra.sections) ? (extra.sections as Record<string, unknown>[]) : [];
+  const rows: WidgetRow[] = sections.map((sec, i) => {
+    const subtitle = typeof sec.subtitle === "string" ? sec.subtitle : "";
+    return {
+      // A stable id per row. Index-based on purpose: a section has no id of its
+      // own, and the list is rebuilt wholesale on every tick, so there is
+      // nothing for a content-derived key to preserve.
+      id: `s${i}`,
+      title: typeof sec.title === "string" ? sec.title : "",
+      subtitle,
+      subtitleHidden: !subtitle,
+    };
+  });
+
+  const maxSelected = typeof extra.maxSelected === "number" ? extra.maxSelected : 0;
+  // `isPreselected` seeds the selection, so the row's `selected` starts true
+  // for exactly the options the service marked.
+  const options: WidgetOptionRow[] = w.options.map((o, i) => optionRow(o, i, o.preselected, disclose, allowPicture, w.kind === "UNKNOWN"));
+
+  // CHART. `pieSlices` is the only shape the catalogue sends, but `chartType`
+  // decides the component: a pie is a `DonutChart` at zero thickness, anything
+  // else a `Chart` over the same magnitudes.
+  const rawSlices = Array.isArray(extra.slices) ? (extra.slices as { label?: unknown; value?: unknown }[]) : [];
+  const slices: WidgetSlice[] = rawSlices.map((sl) => ({
+    label: typeof sl.label === "string" ? sl.label : "",
+    value: typeof sl.value === "number" && Number.isFinite(sl.value) ? sl.value : 0,
+  }));
+  const chartKind = typeof extra.chartType === "string" ? extra.chartType : "";
+  // "doughnut" is the spelling the reference catalogue uses; "donut" is the
+  // component's. Accepting only the component's spelling classified the real
+  // payload as a SERIES and drew it as bars.
+  const isPie = !chartKind || chartKind === "pie" || chartKind === "donut" || chartKind === "doughnut";
+  const description = typeof extra.description === "string" ? extra.description : "";
+
+  // TODO_PLAN. `status` is the service's word; `done` is what `Timeline` draws.
+  const rawItems = Array.isArray(extra.items) ? (extra.items as { label?: unknown; status?: unknown }[]) : [];
+  const steps: WidgetStep[] = rawItems.map((it, i) => {
+    const status = typeof it.status === "string" ? it.status : "";
+    return {
+      id: `p${i}`,
+      title: typeof it.label === "string" ? it.label : "",
+      subtitle: status,
+      done: /^(done|complete|completed|finished|success)$/i.test(status),
+    };
+  });
+  const doneCount = steps.filter((p) => p.done).length;
+
+  // ASYNC_TOOL. Four messages, one state — the descriptor cannot choose, so the
+  // choice is made here.
+  const msgs = (extra.statusMessages ?? {}) as Record<string, unknown>;
+  const asyncJobId = typeof extra.asyncJobId === "string" ? extra.asyncJobId : "";
+  const jobState = typeof extra.asyncState === "string" ? extra.asyncState : "initialized";
+  const pick = (k: string): string => (typeof msgs[k] === "string" ? (msgs[k] as string) : "");
+  const asyncMessage = pick(jobState) || pick("initialized") || pick("processing");
+  const asyncRunning = !!asyncJobId && (jobState === "initialized" || jobState === "processing");
+
+  // QUESTIONNAIRE. Every label arrived wrapped (`{text: …}`) and the normalizer
+  // unwrapped them; this only flattens for binding.
+  const rawQs = Array.isArray(extra.questions) ? (extra.questions as Record<string, unknown>[]) : [];
+  const questions: WidgetQuestion[] = rawQs.map((q, i) => {
+    const sub = typeof q.subtitle === "string" ? q.subtitle : "";
+    const free = typeof q.freeFormatPlaceholder === "string" ? q.freeFormatPlaceholder : "";
+    const required = q.required === true;
+    return {
+      id: `q${i}`,
+      title: typeof q.title === "string" ? q.title : "",
+      subtitle: sub, subtitleHidden: !sub,
+      type: typeof q.type === "string" ? q.type : "",
+      required,
+      // Nothing is answered on arrival, so a required question starts missing.
+      missing: required,
+      answer: "", answerHidden: true,
+      freePlaceholder: free, freeHidden: !free,
+    };
+  });
+
+  const providerKey = typeof extra.providerKey === "string" ? extra.providerKey : "";
+
+  const primaryUrl = w.primary?.externalUrl ?? "";
+  const secondaryUrl = w.secondary?.externalUrl ?? "";
+  // An UNKNOWN kind is the one case where a MISSING `respondText` must not
+  // make a control inert.
+  //
+  // `widgetRespond` needs a template and returns the state untouched when
+  // there is none — correct for a KNOWN kind, where an absent template is a
+  // payload bug for a shape that has a real case. But the generic card mints a
+  // button for every option precisely because an option the owner cannot
+  // choose is decoration, and a future kind has no reason to carry the
+  // template field read today. Without this the generic card rendered
+  // perfectly and every control did nothing, which looks exactly like it
+  // working.
+  //
+  // The synthesized template is the label itself, which is what `<SELECTED>`
+  // substitution produces for the known kinds anyway.
+  const generic = w.kind === "UNKNOWN";
+  const primaryRespondText = (w.primary?.respondText ?? "")
+    || (generic ? (w.primary?.label ?? "") : "");
+  const secondaryRespondText = (w.secondary?.respondText ?? "")
+    || (generic ? (w.secondary?.label ?? "") : "");
+  const primaryLabel = w.primary ? discloseButton(disclose, w.primary.label, primaryUrl) : "";
+  const secondaryLabel = w.secondary ? discloseButton(disclose, w.secondary.label, secondaryUrl) : "";
+
+  // Hoisted out of the object literal below so `renderable` can see it. It
+  // was computed inline, so naming it in the guard was a ReferenceError that
+  // took the whole `tick` down — the turn never ended and the poll ladder
+  // stayed pinned fast. `aria-chat.test.ts` caught it; nothing in the widget
+  // suites would have, because they never run a turn.
+  const treeJson = subtree && w.kind === "UNKNOWN"
+    ? composeGenericCard(w, {
+        slotId: subtree.slotId,
+        service: subtree.service,
+        allowPicture,
+      })
+    : "";
+
+  // A payload we could not read normalizes to an EMPTY `UNKNOWN`, and an
+  // empty card is not nothing: the `Card` keeps its padding and background,
+  // so the region rendered as a blank box with a gap where a widget should
+  // be. Nothing renderable means nothing rendered.
+  // EVERY field the descriptor can draw. `title` (prose and plan cards),
+  // `imageUrl` (VISUAL_DISPLAY) and `description` (CHART) were missing, so a
+  // title-only upsell or an image-only display — both valid — collapsed even
+  // though they had something to show. Hiding a widget that has content is a
+  // worse failure than the blank card this guard exists to prevent, so the
+  // list has to match what the descriptor renders, not what I remembered.
+  const renderable = !!(w.text || w.bottomText || w.badge || title || imageUrl
+    || description || options.length || primaryLabel || secondaryLabel
+    || sections.length || slices.length || steps.length || questions.length
+    || asyncMessage || treeJson);
+
+  return {
+    kind: w.kind,
+    hidden: !renderable,
+    options,
+    maxSelected,
+    limitReached: maxSelected > 0 && options.filter((o) => o.selected).length >= maxSelected,
+    limitText: "", limitTextHidden: true,
+    requiresSelection: !!w.primary?.disableIfEmpty,
+    // A widget arrives with nothing chosen unless the service preselected, so
+    // a `disableIfNothingSelected` primary starts disabled.
+    primaryDisabled: !!w.primary?.disableIfEmpty && !options.some((o) => o.selected),
+    primaryEnabled: !(!!w.primary?.disableIfEmpty && !options.some((o) => o.selected)),
+    slices,
+    values: slices.map((sl) => sl.value),
+    chartIsPie: w.kind === "CHART" && isPie && slices.length > 0,
+    chartIsSeries: w.kind === "CHART" && !isPie && slices.length > 0,
+    chartPieHidden: !(w.kind === "CHART" && isPie && slices.length > 0),
+    chartSeriesHidden: !(w.kind === "CHART" && !isPie && slices.length > 0),
+    chartKind,
+    chartEmpty: w.kind === "CHART" && slices.length === 0,
+    chartEmptyHidden: !(w.kind === "CHART" && slices.length === 0),
+    description, descriptionHidden: !description,
+    steps,
+    stepsEmpty: w.kind === "TODO_PLAN" && steps.length === 0,
+    progress: steps.length ? doneCount / steps.length : 0,
+    progressText: steps.length ? `${doneCount} of ${steps.length} done` : "",
+    asyncJobId,
+    asyncState: asyncJobId ? jobState : "",
+    asyncMessage,
+    asyncRunning,
+    // A job the service never named. The status messages still say something
+    // useful, so this renders them — it just never spins and never polls.
+    asyncUntracked: w.kind === "ASYNC_TOOL" && !asyncJobId,
+    // The spinner follows RUNNING, not trackedness.
+    asyncSpinnerHidden: !asyncRunning,
+    query: "",
+    // Nothing typed yet means every option is a suggestion.
+    suggestions: options,
+    suggestionsEmpty: options.length === 0,
+    noMatches: false,
+    selectionType: typeof extra.selectionType === "string" ? extra.selectionType : "",
+    questions,
+    questionsEmpty: w.kind === "QUESTIONNAIRE" && questions.length === 0,
+    answersIncomplete: questions.some((q) => q.missing),
+    answersText: "", answersTextHidden: true,
+    providerKey,
+    // An ITEMS_SELECTION arrives with NO rows — they come from the provider —
+    // so it starts loading rather than starting empty.
+    itemsLoading: w.kind === "ITEMS_SELECTION" && !!providerKey,
+    itemsLoadingHidden: !(w.kind === "ITEMS_SELECTION" && !!providerKey),
+    itemsError: "", itemsErrorHidden: true,
+    itemsEmpty: w.kind === "ITEMS_SELECTION" && options.length === 0,
+    // Only for a kind we do not know. A known kind has a real case, and RFC
+    // 0046 sends enumerable variants to `FragmentSlot`.
+    treeJson,
+    extraStatusMessages: Object.fromEntries(
+      Object.entries(msgs).filter((kv): kv is [string, string] => typeof kv[1] === "string"),
+    ),
+    submitting: false,
+    text: w.text, textHidden: !w.text,
+    title, titleHidden: !title,
+    bottomText: w.bottomText, bottomTextHidden: !w.bottomText,
+    badge: w.badge, badgeHidden: !w.badge,
+    imageUrl, imageHidden: !imageUrl,
+    // Shown only when there is a LABEL to read and a DESTINATION to go to.
+    //
+    // The label half is obvious: the service does send `{mobileAction:{…}}`
+    // with nothing written on it, and a control with an empty title is a tap
+    // target the owner cannot read.
+    //
+    // The destination half is a scope decision, and a deliberate visible gap. A
+    // button whose only payload is `respondText` needs the send-back loop, which
+    // is #2606; until that lands, painting it would put up a control that does
+    // nothing when tapped. This repo's own rule for the Aria header is "no dead
+    // controls", and a button that looks live and is not is worse than one that
+    // is not there yet. #2606 removes the `&& url` and the buttons appear.
+    // #2605 hid a button that had nothing to DO. Now that `respondText` can be
+    // sent, having something to SAY counts too — which is the `&& url` that
+    // issue said this one would remove.
+    primaryLabel, primaryHidden: !(primaryLabel && (primaryUrl || primaryRespondText)), primaryUrl,
+    primaryRespondText,
+    secondaryLabel, secondaryHidden: !(secondaryLabel && (secondaryUrl || secondaryRespondText)), secondaryUrl,
+    secondaryRespondText,
+    rows,
+  };
+}
+
+/** The widget the screen should be showing, read off the server transcript.
+ *
+ *  The LAST assistant turn's last envelope, and nothing else. Two decisions
+ *  behind that, both from the epic:
+ *
+ *  - **One at a time.** The assistant asks one question per turn, and
+ *    `FragmentSlot` binds one case path. A widget scrolled into history keeps
+ *    its prose (#2603 already put that in the bubble) and loses its controls,
+ *    which is correct: a stale questionnaire you can still submit is a bug.
+ *  - **Assistant turns only.** A user's own text is literal — scanning it would
+ *    let an owner who typed `<<…>>` inject a widget into their own chat.
+ *
+ *  Answers `NO_WIDGET` for an empty transcript, so a new chat collapses the
+ *  region without anything having to remember to clear it. */
+export function activeWidgetOf(
+  msgs: WidgetSourceMessage[],
+  disclose: Disclose,
+  subtree?: SubtreeSlot,
+  allowPicture?: (url: string) => boolean,
+): WidgetView {
+  // ONLY the newest message is consulted. This used to walk backwards past
+  // `USER` rows and empty assistant placeholders looking for a widget, which
+  // is wrong in the one state __HIMI_APP_NAME__ is in most often: between persisting
+  // the owner's message and the reply arriving, the newest row IS the owner's
+  // message — so the scan skipped it, found the PREVIOUS assistant turn, and
+  // repainted the controls for the question that had just been superseded.
+  // `send` deliberately clears the widget; the very next poll put it back.
+  //
+  // A widget belongs to the turn that asked it. If the newest turn is the
+  // owner's, or is a placeholder with nothing in it yet, then nothing is being
+  // asked right now — and that is what NO_WIDGET means.
+  const m = msgs[msgs.length - 1];
+  if (!m || (m.role || "ASSISTANT") === "USER") return NO_WIDGET;
+  const raw = typeof m.content === "string" ? m.content : "";
+  if (!raw) return NO_WIDGET;
+  const found = widgetsOfParts(scanEnvelopes(raw, 0, true).parts);
+  if (!found.length) return NO_WIDGET;
+  // A turn with several envelopes shows the LAST, matching "one at a time"
+  // and the reading order — the final ask is the live one.
+  return viewOf(normalizeWidget(found[found.length - 1]), disclose, subtree, allowPicture);
+}