@wix/himalaya-cli 0.960.0 → 0.962.0

package/templates/retail-store-owner/tier5-src/_shared/aria-generic-widget.ts

@@ -0,0 +1,251 @@
+// A widget type that did not exist when this shipped, rendered anyway.
+//
+// The assistant service can ship a new widget kind any day. Left alone, an
+// unrecognised kind degrades to plain prose — safe, but it throws away the
+// options and buttons the payload carried. Eight of the fourteen known kinds
+// share one skeleton (`text` + `options[]` + buttons), so a GENERIC renderer
+// can present a future kind usefully without knowing what it is.
+//
+// This is the one place `WorkerSubtree` is the right tool. The rule elsewhere
+// is that a variant you can enumerate belongs in a `FragmentSlot` case, and
+// every known kind has one. A kind nobody could enumerate when the screen was
+// authored is the exception: a `FragmentSlot` cannot hold a case that did not
+// exist yet.
+//
+// FAIL-CLOSED IS THE WHOLE DESIGN. The host validates the entire tree before
+// decoding it, and ANY violation — an unlisted type, a budget overrun, a bad
+// id, an action outside the allowlist — rejects the whole value and renders
+// the declared fallback. There is no partial render, so this file returns ""
+// for "I could not compose something I am sure of" and lets the prose card
+// take over. Returning a tree that is nearly right is the one outcome worse
+// than returning none.
+//
+// Follows `himi-owner-lite-ask/blocks.ts`, which solved this shape first: the
+// worker decides the layout, copy is sanitized, and nothing off the wire ever
+// becomes STRUCTURE.
+
+import type { NormalizedWidget, WidgetOption } from "./aria-widget-model.js";
+
+/** Minimal structural type. A worker bundle cannot import the screen-authoring
+ *  helpers — those run where screens are built, not in the worker — so it
+ *  hand-rolls its nodes. */
+interface Node {
+  id: string;
+  body: { package: "himalaya"; type: string; props: Record<string, unknown> };
+}
+
+/** The safe types this composer emits. A SUBSET of the platform's 19, and it
+ *  must stay a subset of the descriptor's `allowedTypes` — the two are checked
+ *  against each other in the tests, because a perfectly good tree is rejected
+ *  wholesale when they drift. */
+export const GENERIC_TYPES = ["Card", "VStack", "HStack", "Text", "Badge", "Image", "Spacer", "Button", "Divider"] as const;
+
+/** What a future kind needing a chart or text entry gets instead.
+ *
+ *  `Chart`, `DonutChart`, `TextField`, `Form`, `LazyList`, `ListItem`,
+ *  `Timeline`, `Grid` and `SearchField` are ALL absent from the platform-safe
+ *  list, so such a kind cannot be rendered generically at all. It falls back to
+ *  prose until it is given a real case — and the copy says so rather than
+ *  pretending the owner has seen everything. */
+export const GENERIC_UNSUPPORTED_NOTE = "This needs the latest app version to show in full.";
+
+/** The slot the Aria widget region mounts the generic card in.
+ *
+ *  Exported because BOTH sides must agree: the descriptor names it as the
+ *  `WorkerSubtree` node's id, and the worker prefixes every node id with
+ *  `wsub.<slotId>.`. If the two ever disagree the entire tree is rejected with
+ *  `id_violation` and every unknown widget silently becomes prose — which
+ *  looks exactly like the feature working as designed. One constant, so they
+ *  cannot drift. */
+export const WIDGET_SUBTREE_SLOT = "ariaWidget";
+
+/** Longest literal copy rendered from a payload. Same ceiling as `blocks.ts`. */
+const MAX_COPY = 240;
+
+/** Sanitize LITERAL copy off the wire.
+ *
+ *  The host validates a worker-built tree's shape, not its prop VALUES, so a
+ *  structurally perfect payload can still carry machine noise into the card.
+ *  A model that degenerates mid-answer leaks its own reasoning as one long
+ *  underscore-joined run, and two cheap signals catch that: absurd length, and
+ *  long runs with no whitespace. Rejected copy returns "" so the caller DROPS
+ *  that node rather than rendering it. */
+export function cleanCopy(raw: unknown): string {
+  if (typeof raw !== "string") return "";
+  const text = raw.trim();
+  if (!text || text.length > MAX_COPY) return "";
+  let longest = 0;
+  for (const word of text.split(/\s+/)) longest = Math.max(longest, word.length);
+  if (longest > 40) return "";
+  return text;
+}
+
+export interface GenericCardOptions {
+  /** The `WorkerSubtree` slot. Every id must be prefixed `wsub.<slotId>.` or
+   *  the whole tree is rejected with `id_violation` — that is the RFC's
+   *  provenance mechanism, so a worker-authored action cannot be mistaken for
+   *  an ordinary UI tap. */
+  slotId: string;
+  /** The worker service name, for `tier5.<service>.<action>` ids. Passed in
+   *  rather than hardcoded, because more than one app mounts this chat and
+   *  each names its service differently. */
+  service: string;
+  /** Whether an option's picture may be loaded. Supplied by the caller so the
+   *  host check stays in one place — a decorative image cannot carry its own
+   *  provenance, and a silently-loaded remote asset is a tracking pixel with
+   *  extra steps. */
+  allowPicture?: (url: string) => boolean;
+  /** Node ceiling. Defaults below the platform's 200 so the composer refuses
+   *  before the validator has to. */
+  maxNodes?: number;
+  /** Byte ceiling, likewise below the platform's 65 536. */
+  maxBytes?: number;
+}
+
+const DEFAULT_MAX_NODES = 180;
+const DEFAULT_MAX_BYTES = 60_000;
+
+/** Compose a generic card for a widget kind we do not recognise.
+ *
+ *  Returns the tree as a JSON string, or "" when it cannot compose one it is
+ *  sure of — no options AND no prompt, or a payload that would breach a
+ *  budget. "" means "render the prose fallback", which is a good outcome, not
+ *  an error.
+ *
+ *  Budgets are checked against the COMPOSED tree rather than guessed from the
+ *  option count, and breaching one returns "" rather than dropping rows. A
+ *  truncated picker is indistinguishable from a complete one, so an owner
+ *  choosing from it cannot tell that the option they wanted was removed. */
+export function composeGenericCard(w: NormalizedWidget, opts: GenericCardOptions): string {
+  const { slotId, service } = opts;
+  const maxNodes = opts.maxNodes ?? DEFAULT_MAX_NODES;
+  const maxBytes = opts.maxBytes ?? DEFAULT_MAX_BYTES;
+  const allowPicture = opts.allowPicture ?? (() => false);
+
+  const id = (local: string) => `wsub.${slotId}.${local}`;
+  const node = (local: string, type: string, props: Record<string, unknown>): Node =>
+    ({ id: id(local), body: { package: "himalaya", type, props } });
+  // Every action is the SAME worker action with different params. The id is
+  // what the policy allowlists, so keeping it to one keeps the allowlist to one
+  // entry — the smallest surface a future payload can reach.
+  const respond = (value: string) => ({ actionId: `tier5.${service}.widgetRespond`, params: { value } });
+
+  const prompt = cleanCopy(w.text);
+  const badge = cleanCopy(w.badge);
+  const bottom = cleanCopy(w.bottomText);
+
+  const rows: Node[] = [];
+  w.options.forEach((o: WidgetOption, i: number) => {
+    const title = cleanCopy(o.title) || cleanCopy(o.text);
+    // Same alternation the known kinds use: the service writes `subtitle` or
+    // `text`, never both, so the second line is whichever survived the title.
+    const sub = cleanCopy(o.title) ? (cleanCopy(o.subtitle) || cleanCopy(o.text)) : cleanCopy(o.subtitle);
+    if (!title && !sub) return;      // an empty row is worse than a missing one
+    const value = typeof o.value === "string" ? o.value : "";
+    if (!value) return;              // nothing to send back; the row would be inert
+
+    const line: Node[] = [];
+    const pic = typeof o.pictureUrl === "string" ? o.pictureUrl : "";
+    if (pic && allowPicture(pic)) {
+      line.push(node(`pic.${i}`, "Image", {
+        url: pic, width: 40, height: 40, shape: "rounded", contentMode: "fill",
+        contentDescription: title || sub,
+      }));
+    }
+    const stack: Node[] = [node(`t.${i}`, "Text", { text: title || sub, style: "body", maxLines: 2 })];
+    if (title && sub) stack.push(node(`s.${i}`, "Text", { text: sub, style: "footnote", color: "textSecondary", maxLines: 2 }));
+    line.push(node(`rt.${i}`, "VStack", { spacing: 2, children: stack }));
+    line.push(node(`sp.${i}`, "Spacer", {}));
+
+    const label = cleanCopy(o.buttonLabel);
+    // A row with no button of its own is still tappable through a button we
+    // mint: an option the owner cannot choose is decoration. `Chip` and
+    // `SelectionControl` are on the safe list too, but a button reads the same
+    // on every one of iOS, Android, macOS, Web and React Native, and this card
+    // exists precisely because nobody has designed for this kind yet.
+    line.push(node(`pick.${i}`, "Button", {
+      title: label || "Choose", style: "secondary", size: "sm", action: respond(value),
+    }));
+
+    rows.push(node(`row.${i}`, "HStack", { spacing: 10, children: line }));
+  });
+
+  // Nothing worth showing. The prose card already says what the reply said.
+  if (!prompt && rows.length === 0) return "";
+
+  const body: Node[] = [];
+  if (badge) body.push(node("badge", "Badge", { text: badge }));
+  if (prompt) body.push(node("prompt", "Text", { text: prompt, style: "body" }));
+  if (rows.length) {
+    body.push(node("rule", "Divider", {}));
+    body.push(...rows);
+  }
+  if (bottom) body.push(node("bottom", "Text", { text: bottom, style: "footnote", color: "textSecondary", maxLines: 3 }));
+
+  const footer: Node[] = [];
+  const primaryLabel = cleanCopy(w.primary?.label);
+  if (primaryLabel) {
+    footer.push(node("primary", "Button", { title: primaryLabel, style: "primary", action: respond("primary") }));
+  }
+  const secondaryLabel = cleanCopy(w.secondary?.label);
+  if (secondaryLabel) {
+    footer.push(node("secondary", "Button", { title: secondaryLabel, style: "secondary", action: respond("secondary") }));
+  }
+  if (footer.length) {
+    footer.push(node("fsp", "Spacer", {}));
+    body.push(node("footer", "HStack", { spacing: 8, children: footer }));
+  }
+
+  // Said out loud, because an owner on an older build should know the card is
+  // a stand-in rather than the whole thing.
+  body.push(node("note", "Text", { text: GENERIC_UNSUPPORTED_NOTE, style: "caption", color: "textSecondary", maxLines: 2 }));
+
+  const tree = node("card", "Card", {
+    children: [node("stack", "VStack", { spacing: 8, children: body })],
+  });
+
+  if (countNodes(tree) > maxNodes) return "";
+  const json = JSON.stringify(tree);
+  if (utf8Length(json) > maxBytes) return "";
+  return json;
+}
+
+/** UTF-8 byte length, counted by hand.
+ *
+ *  NOT `new TextEncoder()`: it does not exist on JavaScriptCore, which is the
+ *  engine this worker runs on for iOS and macOS, and the bundler does not
+ *  polyfill it — so the reference throws before any work is done. The budget
+ *  check would have taken the whole card down on the two platforms hardest to
+ *  notice it on.
+ *
+ *  The host measures the same string with a real encoder, so this has to agree
+ *  with it exactly rather than approximate: 1 byte below U+0080, 2 below
+ *  U+0800, 4 for a surrogate PAIR (one astral character, consuming both code
+ *  units), 3 otherwise. */
+export function utf8Length(s: string): number {
+  let bytes = 0;
+  for (let i = 0; i < s.length; i++) {
+    const code = s.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff && i + 1 < s.length) {
+      const next = s.charCodeAt(i + 1);
+      // A well-formed pair is one astral character: four bytes, two units.
+      if (next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i++; }
+      // A LONE high surrogate is not a character. `JSON.stringify` escapes it
+      // to `\udXXX`, so it cannot reach here from this composer — but this
+      // function is exported, and answering 3 keeps it in step with what an
+      // encoder does with the replacement character it would emit.
+      else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+/** Every node in the tree, counted the way the validator counts them. */
+function countNodes(n: Node): number {
+  let total = 1;
+  const children = (n.body.props as { children?: unknown }).children;
+  if (Array.isArray(children)) for (const c of children) total += countNodes(c as Node);
+  return total;
+}

package/templates/retail-store-owner/tier5-src/_shared/aria-widget-kinds.ts

@@ -0,0 +1,332 @@
+// Turning a scanned envelope into a `NormalizedWidget`.
+//
+// Eight of the fourteen kinds are the shared skeleton and need no code of their
+// own; the rest each reshape one or two fields. The whole file is pure and
+// total: `normalizeWidget` answers for ANY input, including a payload that is
+// not JSON, a `data` that is an array, and a widget name nobody has shipped yet.
+
+import type { WidgetPayload } from "./aria-widgets.js";
+import type { NormalizedWidget, WidgetKind, WidgetOption } from "./aria-widget-model.js";
+import {
+  badgeTextOf,
+  boolAt,
+  buttonAt,
+  emptyWidget,
+  objectAt,
+  objectsAt,
+  optionsOf,
+  stringAt,
+  textAt,
+  textOf,
+} from "./aria-widget-model.js";
+
+/** Wire name → kind. Thirteen of the fourteen carry a `_WIDGET` suffix and
+ *  `OAUTH_REQUIRED` does not, so this is a table rather than a string trim — and
+ *  a table is what we want anyway: an unrecognised name must fall to `UNKNOWN`,
+ *  and trimming a suffix would silently invent a kind out of whatever the
+ *  service sent next. */
+//
+// `Object.create(null)` rather than a plain literal: a plain object inherits
+// from `Object.prototype`, so `KIND_BY_NAME["toString"]` is a FUNCTION and
+// `?? "UNKNOWN"` never fires. A service that ships a widget called `toString`,
+// `constructor` or `valueOf` — or an attacker who can influence the name — got
+// back an inherited member as the "kind" instead of the forward-compatible
+// fallback. A null-prototype table has nothing to inherit.
+const KIND_BY_NAME: Record<string, WidgetKind> = Object.assign(Object.create(null) as Record<string, WidgetKind>, {
+  SINGLE_SELECT_WIDGET: "SINGLE_SELECT",
+  MULTI_SELECT_WIDGET: "MULTI_SELECT",
+  SINGLE_SELECT_BUTTON_WIDGET: "SINGLE_SELECT_BUTTON",
+  RADIO_BUTTON_WIDGET: "RADIO_BUTTON",
+  PLANS_WIDGET: "PLANS",
+  PREMIUM_UPSELL_WIDGET: "PREMIUM_UPSELL",
+  VISUAL_DISPLAY_WIDGET: "VISUAL_DISPLAY",
+  AUTOCOMPLETE_WIDGET: "AUTOCOMPLETE",
+  ITEMS_SELECTION_WIDGET: "ITEMS_SELECTION",
+  QUESTIONNAIRE_WIDGET: "QUESTIONNAIRE",
+  CHART_WIDGET: "CHART",
+  TODO_PLAN_WIDGET: "TODO_PLAN",
+  ASYNC_TOOL_WIDGET: "ASYNC_TOOL",
+  OAUTH_REQUIRED: "OAUTH_REQUIRED",
+});
+
+/** The kind for a wire name, or `"UNKNOWN"`. Exported for the descriptor work
+ *  by the screen builder, which needs the same mapping without re-parsing a
+ *  payload. */
+export function kindOfName(name: string): WidgetKind {
+  return KIND_BY_NAME[name] ?? "UNKNOWN";
+}
+
+/** The eight-kind shared skeleton: text, bottom text, badge, options, buttons. */
+function skeleton(kind: WidgetKind, d: Record<string, unknown> | null): NormalizedWidget {
+  return {
+    kind,
+    text: stringAt(d, "text"),
+    bottomText: stringAt(d, "bottomText"),
+    badge: badgeTextOf(d),
+    options: optionsOf(d),
+    primary: buttonAt(d, "primaryButton"),
+    secondary: buttonAt(d, "secondaryButton"),
+    extra: {},
+  };
+}
+
+/** One `sections[{title,subtitle}]` row of a VISUAL_DISPLAY.
+ *
+ *  Sections are NOT options, and the distinction is load-bearing: the reference
+ *  catalogue's visual-display entry carries both at once — three `sections`
+ *  describing the product, and one `options` entry that is a selectable variant
+ *  card with its own nested sections and button. An earlier draft of this file
+ *  folded sections into `options` when `options` was empty, which read fine
+ *  against a simpler fixture and silently DROPPED all three sections against
+ *  this one. They are different axes, so they get different fields.
+ *
+ *  `textButton` is read but only its label and respondText: the section button
+ *  is the send-back loop's, and sections render as static rows. */
+interface WidgetSection {
+  title: string;
+  subtitle: string;
+  buttonLabel: string;
+  respondText: string;
+}
+
+function sectionsOf(d: Record<string, unknown> | null): WidgetSection[] {
+  return objectsAt(d, "sections").map((s) => {
+    const b = objectAt(s.textButton);
+    return {
+      title: stringAt(s, "title"),
+      subtitle: stringAt(s, "subtitle"),
+      buttonLabel: stringAt(b, "label"),
+      respondText: stringAt(b, "respondText"),
+    };
+  });
+}
+
+/** One widget, normalized. Never throws.
+ *
+ *  Three ways in, and all three end somewhere renderable:
+ *
+ *  - a known kind with readable `data` → its normalizer;
+ *  - an unknown NAME → `UNKNOWN` carrying whatever `text` the payload had, so
+ *    the owner still reads the assistant's sentence;
+ *  - `data` that is absent, not JSON, or not an object → `UNKNOWN` with empty
+ *    text. There is nothing to show, and the region collapses rather than
+ *    painting a blank card. */
+export function normalizeWidget(p: WidgetPayload): NormalizedWidget {
+  const kind = kindOfName(p.name);
+
+  // Read `data` defensively. A payload whose JSON is corrupt is not an error
+  // path worth surfacing — the envelope already survived a scanner built to
+  // tolerate exactly this, and the screen's job is to keep rendering.
+  let d: Record<string, unknown> | null = null;
+  if (p.dataJson) {
+    try {
+      d = objectAt(JSON.parse(p.dataJson));
+    } catch {
+      d = null;
+    }
+  }
+
+  // An unreadable payload cannot even yield prose. Report UNKNOWN and let the
+  // region collapse — note this also catches a KNOWN name whose data is broken,
+  // which is deliberate: a SINGLE_SELECT with no options is not a widget, it is
+  // a card with nothing to tap.
+  if (!d) return emptyWidget("UNKNOWN");
+
+  const base = skeleton(kind, d);
+
+  switch (kind) {
+    // The eight that are the skeleton, unchanged.
+    case "SINGLE_SELECT":
+    case "SINGLE_SELECT_BUTTON":
+    case "RADIO_BUTTON":
+      return base;
+
+    case "PLANS":
+      // Each plan's benefit list, with its icons. `optionsOf` already joined
+      // the labels into `listText` for the templated row; this keeps the
+      // structured form for whoever renders the icons.
+      return {
+        ...base,
+        extra: {
+          lists: objectsAt(d, "options").map((opt) =>
+            objectsAt(opt, "list").map((item) => ({
+              text: textOf(item),
+              icon: stringAt(objectAt(item.icon), "name"),
+              iconColor: stringAt(objectAt(item.icon), "color"),
+            })),
+          ),
+        },
+      };
+
+    case "AUTOCOMPLETE":
+      // `single` vs `multi`. Without it the host cannot tell a one-choice
+      // autocomplete from a many-choice one, and picks the wrong submit
+      // behaviour for half of them.
+      return { ...base, extra: { selectionType: stringAt(d, "selectionType") } };
+
+    case "MULTI_SELECT":
+      // `optionLayout` decides thumbnail vs list rows; `footerButtonsAsColumn`
+      // stacks the footer. Both are layout hints the picker reads, so they ride in
+      // `extra` rather than widening the shared shape.
+      return {
+        ...base,
+        extra: {
+          optionLayout: stringAt(d, "optionLayout"),
+          footerButtonsAsColumn: boolAt(d, "footerButtonsAsColumn"),
+          // A selection CEILING. The reference catalogue only shows it on
+          // ITEMS_SELECTION, but it is a generic multi-select constraint and
+          // nothing in the wire format restricts it to one kind — reading it
+          // here costs a line and not reading it would silently ignore a limit
+          // the service had set. Enforced in the worker: no component carries
+          // a selection-count prop, so it cannot be declared.
+          maxSelected: numberAt(d, "maxSelected"),
+        },
+      };
+
+    case "PREMIUM_UPSELL":
+      // The only kind whose headline is `title` rather than `text`. Both are
+      // kept: `title` leads, `text` is the body, and flattening them would lose
+      // the upsell's own heading.
+      return { ...base, extra: { title: stringAt(d, "title") } };
+
+    case "VISUAL_DISPLAY":
+      // `sections` and `options` are independent and can both be present — see
+      // `sectionsOf`. Options stay options; sections ride in `extra`.
+      return {
+        ...base,
+        extra: {
+          // Two spellings, both live: the catalogue entry is named "…legacy
+          // image", which is the older bare-string `image` beside the newer
+          // `{url}` object. Trying the object first means a payload carrying
+          // both takes the structured one.
+          imageUrl: stringAt(objectAt(d.image), "url") || stringAt(d, "image"),
+          sectionsLayout: stringAt(d, "sectionsLayout"),
+          sections: sectionsOf(d),
+        },
+      };
+
+    case "ITEMS_SELECTION":
+      // Carries no options of its own — the rows are fetched later from
+      // `providerKey`. All this can do is record the handle.
+      return {
+        ...base,
+        extra: { providerKey: stringAt(d, "providerKey"), maxSelected: numberAt(d, "maxSelected") },
+      };
+
+    case "QUESTIONNAIRE":
+      // A questionnaire with no questions is in the catalogue on purpose. It
+      // normalizes to an empty list rather than UNKNOWN: the kind is known and
+      // its buttons may still be meaningful, and the picker decides what an empty
+      // one looks like.
+      return {
+        ...base,
+        extra: {
+          // Every label here is `{ text: … }` rather than a bare string — this
+          // kind is alone in that, and reading it with the scalar reader gave a
+          // questionnaire with the right number of questions and nothing
+          // written on any of them.
+          questions: objectsAt(d, "questions").map((q) => ({
+            type: stringAt(q, "type"),
+            required: boolAt(q, "required"),
+            title: textAt(q, "title"),
+            subtitle: textAt(q, "subtitle"),
+            options: optionsOf(q),
+            // The "or type your own" affordance, and it is PER QUESTION rather
+            // than per widget — only the multi-select one carries it in the
+            // catalogue. Its label is nested twice (`placeholder.text`).
+            // Dropping it removed the only answer some questions accept.
+            freeFormatType: stringAt(objectAt(q.freeFormatOption), "type"),
+            freeFormatPlaceholder: textAt(objectAt(q.freeFormatOption), "placeholder"),
+          })),
+        },
+      };
+
+    case "CHART":
+      return {
+        ...base,
+        extra: {
+          chartType: stringAt(d, "chartType"),
+          description: stringAt(d, "description"),
+          slices: objectsAt(d, "pieSlices").map((s) => ({
+            label: stringAt(s, "label"),
+            value: numberAt(s, "value"),
+          })),
+        },
+      };
+
+    case "TODO_PLAN":
+      return {
+        ...base,
+        extra: {
+          title: stringAt(d, "title"),
+          items: objectsAt(d, "items").map((i) => ({
+            label: stringAt(i, "label"),
+            status: stringAt(i, "status"),
+          })),
+        },
+      };
+
+    case "ASYNC_TOOL":
+      // The catalogue ships one WITHOUT a job id. It stays ASYNC_TOOL with an
+      // empty id rather than degrading to UNKNOWN: the status messages are the
+      // useful part, and they are shown while declining to poll for a job with
+      // cannot name.
+      return {
+        ...base,
+        extra: {
+          asyncJobId: stringAt(d, "asyncJobId"),
+          statusMessages: statusMessagesOf(objectAt(d.statusMessages)),
+        },
+      };
+
+    case "OAUTH_REQUIRED":
+      // Both are URLs, and both stay RAW here. They are disclosed through the
+      // existing helper; normalizing is not vetting.
+      return {
+        ...base,
+        extra: {
+          authorizationUrl: stringAt(d, "authorizationUrl"),
+          serverUrl: stringAt(d, "serverUrl"),
+        },
+      };
+
+    case "UNKNOWN":
+    default:
+      // A name we do not know, but a payload we could read.
+      //
+      // Read as the SHARED SKELETON rather than text alone. Eight of the
+      // fourteen known kinds are that skeleton, so it is the best available
+      // guess at what an unknown fifteenth carries — and it is only a guess,
+      // which is why the generic composer sanitizes every field and drops
+      // whatever it cannot use.
+      //
+      // Reading more is safe because every reader is TOTAL: a payload whose
+      // `options` is a string, a number or absent yields an empty array, not
+      // a throw. The cost of guessing wrong is a card with fewer rows; the
+      // cost of not guessing is the prose-only degradation this replaces.
+      return skeleton("UNKNOWN", d);
+  }
+}
+
+/** A finite number, or `0`. `NaN` and the infinities are excluded because they
+ *  reach a chart axis and a selection limit, and both misbehave quietly there. */
+function numberAt(o: Record<string, unknown> | null, key: string): number {
+  if (!o) return 0;
+  const v = o[key];
+  if (typeof v === "number" && Number.isFinite(v)) return v;
+  if (typeof v === "string") {
+    const n = Number(v);
+    if (Number.isFinite(n) && v.trim() !== "") return n;
+  }
+  return 0;
+}
+
+/** The four async-tool status lines, each defaulting to `""`. */
+function statusMessagesOf(o: Record<string, unknown> | null): Record<string, string> {
+  return {
+    initialized: stringAt(o, "initialized"),
+    processing: stringAt(o, "processing"),
+    finished: stringAt(o, "finished"),
+    failed: stringAt(o, "failed"),
+  };
+}