@tai42/studio-sdk 20.0.0 → 21.0.0

package/src/components/fleet-report.tsx

@@ -14,8 +14,8 @@
  * framing and points the operator back at re-running the deregister, because a
  * reload would re-attach the very server being detached — the wrong remediation.
  *
- * A `converged` summary (every worker applied, or a lone-worker local-only change)
- * renders NOTHING — the calling surface shows its own success. A `degraded` summary
+ * A `converged` summary (every worker applied, or a lone-worker local-only change) with
+ * no worker awaiting a respawn renders NOTHING — the calling surface shows its own success. A `degraded` summary
  * (the bus was reached but a sibling did not confirm) or an `unreachable` summary (the
  * bus itself failed) renders a loud `role="alert"` panel naming the honest per-worker
  * outcomes: `failed` / `missing` / `departed` / `timed_out` / `resyncing` / `recycling` /
@@ -23,6 +23,10 @@
  * server-supplied string (a worker name, an error/detail message) renders as escaped
  * React text, never an HTML sink.
  *
+ * Whatever the status, a worker whose reload named recycle-class settings awaiting a
+ * respawn is listed in a warning status panel beside it: the reload applied every other
+ * change, and those settings take effect only when that worker restarts.
+ *
  * Every state — the headline and each worker's outcome — is a `tai-status` line: an
  * icon MARK plus a word LABEL, with the tone color only reinforcing them, so the
  * report is readable without color perception.
@@ -30,6 +34,7 @@
 import type {
   FleetFailureOutcome,
   FleetReportSummary,
+  FleetWorkerAwaitingRespawn,
   FleetWorkerFailure,
 } from '@tai42/api-client';
 import type { ReactNode } from 'react';
@@ -74,9 +79,10 @@ const OUTCOME_STATUS: Record<FleetFailureOutcome, StatusTone> = {
 };
 
 /**
- * Render a fleet broadcast's failure state. Returns `null` for a converged/absent
- * report (nothing to warn about) so callers can always mount it unconditionally
- * beside their own success line.
+ * Render a fleet broadcast's failure state and its workers awaiting a respawn. Returns
+ * `null` for an absent report or a converged one with no worker awaiting a respawn
+ * (nothing to warn about) so callers can always mount it unconditionally beside their
+ * own success line.
  */
 export interface FleetReportProps {
   readonly summary: FleetReportSummary | null;
@@ -193,8 +199,50 @@ function DegradedReport({
   );
 }
 
-export function FleetReport({ summary, action = 'save' }: FleetReportProps): ReactNode {
-  if (summary === null || summary.status === 'converged') return null;
+/**
+ * The panel for workers whose reload named recycle-class settings awaiting a respawn:
+ * the reload applied everything else, and these take effect only when the worker
+ * restarts. Guidance the operator acts on, not a failure, so it is a warning status
+ * rather than an alert.
+ */
+function AwaitingRespawnReport({
+  awaiting,
+}: {
+  readonly awaiting: readonly FleetWorkerAwaitingRespawn[];
+}): ReactNode {
+  const count = awaiting.length;
+  return (
+    <div role="status" className="tai-warn-state tai-stack tai-stack-2">
+      <strong className="tai-status tai-status-warn">
+        <AlertTriangleIcon />
+        {`${String(count)} worker${count === 1 ? ' needs' : 's need'} a restart to apply some settings`}
+      </strong>
+      <p>
+        These settings changed in the stored environment after the worker started. The reload
+        applied every other change; these take effect only when the worker restarts. Restart it
+        through your deployment&rsquo;s supervisor (on a bare server, restart the server).
+      </p>
+      <ul className="tai-stack tai-stack-2">
+        {awaiting.map((worker) => (
+          <li key={worker.name} className="tai-row">
+            <span className="tai-mono">{worker.name}</span>
+            <span className="tai-muted">waits for a restart:</span>
+            <span className="tai-mono">{worker.keys.join(', ')}</span>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+function FailureReport({
+  summary,
+  action,
+}: {
+  readonly summary: FleetReportSummary;
+  readonly action: FleetAction;
+}): ReactNode {
+  if (summary.status === 'converged') return null;
 
   // Only a saved config change carries the "Change saved" framing; a reload or a
   // deregister saved nothing.
@@ -218,3 +266,14 @@ export function FleetReport({ summary, action = 'save' }: FleetReportProps): Rea
     />
   );
 }
+
+export function FleetReport({ summary, action = 'save' }: FleetReportProps): ReactNode {
+  if (summary === null) return null;
+  if (summary.status === 'converged' && summary.awaiting.length === 0) return null;
+  return (
+    <>
+      <FailureReport summary={summary} action={action} />
+      {summary.awaiting.length > 0 ? <AwaitingRespawnReport awaiting={summary.awaiting} /> : null}
+    </>
+  );
+}

package/src/components/json-tree-model.ts

@@ -1,7 +1,8 @@
 /**
  * The bounded-traversal model behind `JsonTree`: container inspection, the paged
  * child slice, path identity, and the open-state computation for the depth
- * default, expand-all and collapse-all baselines. Pure — no React, no DOM.
+ * default, expand-all and collapse-all baselines and the caller's named paths.
+ * Pure — no React, no DOM.
  */
 import { isRecord } from '../guards';
 
@@ -71,8 +72,30 @@ export function childPath(parent: string, name: string): string {
   return parent === '' ? segment : `${parent}/${segment}`;
 }
 
-/** The default open state a call site's `defaultExpanded` selects. */
-export type Baseline = 'depth' | 'expanded' | 'collapsed';
+/**
+ * The identities of every container a caller's named paths open: each path is a
+ * list of keys from the root (an array item named by its index), and the root,
+ * every container along the path and the one it ends at are all opened.
+ */
+export function namedOpenPaths(paths: readonly (readonly string[])[]): ReadonlySet<string> {
+  const open = new Set<string>();
+  for (const segments of paths) {
+    let path = '';
+    open.add(path);
+    for (const segment of segments) {
+      path = childPath(path, segment);
+      open.add(path);
+    }
+  }
+  return open;
+}
+
+/**
+ * The open state the nodes start from: the three a call site's `defaultExpanded`
+ * selects (the depth-guarded default, expand-all, collapsed), and `closed`, the
+ * reader's collapse-all, which also shuts the caller's named paths.
+ */
+export type Baseline = 'depth' | 'expanded' | 'collapsed' | 'closed';
 
 export function initialBaseline(defaultExpanded: boolean | undefined): Baseline {
   if (defaultExpanded === true) return 'expanded';
@@ -119,21 +142,26 @@ export function expandedOpenPaths(root: unknown): ReadonlySet<string> {
 }
 
 /**
- * Whether a node is open, from the baseline and the reader's own toggles. An
- * explicit toggle always wins; otherwise the baseline decides — the depth-guarded
- * default opens through {@link AUTO_EXPAND_DEPTH}, expand-all opens the budgeted
- * breadth-first set, collapse-all opens nothing.
+ * Whether a node is open, from the baseline, the caller's named paths and the
+ * reader's own toggles. An explicit toggle always wins; the reader's collapse-all
+ * opens nothing; otherwise a node on a named path is open beside any baseline a call
+ * site selects, and the baseline decides the rest — a collapsed baseline opens
+ * nothing else, the depth-guarded default opens through {@link AUTO_EXPAND_DEPTH},
+ * expand-all opens the budgeted breadth-first set.
  */
 export function computeOpen(
   baseline: Baseline,
   overrides: ReadonlyMap<string, boolean>,
   expandedPaths: ReadonlySet<string> | null,
+  namedPaths: ReadonlySet<string>,
   path: string,
   depth: number,
 ): boolean {
   const override = overrides.get(path);
   if (override !== undefined) return override;
-  if (baseline === 'expanded') return expandedPaths?.has(path) ?? false;
+  if (baseline === 'closed') return false;
+  if (namedPaths.has(path)) return true;
   if (baseline === 'collapsed') return false;
+  if (baseline === 'expanded') return expandedPaths?.has(path) ?? false;
   return depth <= AUTO_EXPAND_DEPTH;
 }

package/src/components/json-tree.tsx

@@ -12,6 +12,8 @@
  *   renders no children. `defaultExpanded` overrides per call site.
  * - Expand-all opens breadth-first only until {@link AUTO_EXPAND_NODE_BUDGET} nodes
  *   render and never past {@link MAX_AUTO_DEPTH}; a node beyond either opens on click.
+ * - `openPaths` opens exactly the containers along the paths a caller names, at any
+ *   depth, beside the baseline; collapse-all and the reader's toggles close them.
  * - A container over {@link PAGE_SIZE} children renders one page plus a "show more".
  * - Copy-whole and copy-node write JSON to the clipboard; a refused write shows an alert.
  *
@@ -30,6 +32,7 @@ import {
   expandedOpenPaths,
   initialBaseline,
   isContainer,
+  namedOpenPaths,
   PAGE_SIZE,
 } from './json-tree-model';
 import { COPY_LABEL, CopyButton, JsonNode } from './json-tree-nodes';
@@ -44,6 +47,13 @@ export interface JsonTreeProps {
    * opens through {@link AUTO_EXPAND_DEPTH} and collapses everything below.
    */
   readonly defaultExpanded?: boolean;
+  /**
+   * Paths whose containers open beside the baseline, at any depth: each path lists
+   * the keys from the root (an array item by its index, as a string), and the root,
+   * every container along it and the one it ends at open. The reader's own toggle
+   * still wins, and collapse-all closes them like every other node.
+   */
+  readonly openPaths?: readonly (readonly string[])[];
   /** The region's accessible name, applied only while the pane actually scrolls. */
   readonly label?: string;
 }
@@ -51,7 +61,15 @@ export interface JsonTreeProps {
 /** The region's name when the caller supplies none. */
 const DEFAULT_LABEL = 'JSON';
 
-export function JsonTree({ data, defaultExpanded, label }: JsonTreeProps): ReactElement {
+/** The paths a tree without `openPaths` opens beside its baseline. */
+const NO_PATHS: readonly (readonly string[])[] = [];
+
+export function JsonTree({
+  data,
+  defaultExpanded,
+  openPaths = NO_PATHS,
+  label,
+}: JsonTreeProps): ReactElement {
   const [baseline, setBaseline] = useState<Baseline>(() => initialBaseline(defaultExpanded));
   const [overrides, setOverrides] = useState<ReadonlyMap<string, boolean>>(() => new Map());
 
@@ -76,10 +94,12 @@ export function JsonTree({ data, defaultExpanded, label }: JsonTreeProps): React
     [baseline, data],
   );
 
+  const namedPaths = useMemo(() => namedOpenPaths(openPaths), [openPaths]);
+
   const isOpen = useCallback(
     (path: string, depth: number): boolean =>
-      computeOpen(baseline, overrides, expandedPaths, path, depth),
-    [baseline, overrides, expandedPaths],
+      computeOpen(baseline, overrides, expandedPaths, namedPaths, path, depth),
+    [baseline, overrides, expandedPaths, namedPaths],
   );
 
   const setOpen = useCallback((path: string, open: boolean): void => {
@@ -107,7 +127,7 @@ export function JsonTree({ data, defaultExpanded, label }: JsonTreeProps): React
     setOverrides(new Map());
   };
   const collapseAll = (): void => {
-    setBaseline('collapsed');
+    setBaseline('closed');
     setOverrides(new Map());
   };
 

package/src/components/select.tsx

@@ -42,6 +42,12 @@ interface SelectSharedProps {
    * the visible text out of the accessible name (WCAG 2.5.3).
    */
   readonly 'aria-label'?: string;
+  /**
+   * IDREFs of elements that describe the trigger. An enclosing `Field` owns entries
+   * in the same list (its description and error), so the two are concatenated,
+   * caller's first, exactly as the text inputs do.
+   */
+  readonly 'aria-describedby'?: string;
 }
 
 /** The FLAT listbox: one ungrouped run of options. */
@@ -93,8 +99,12 @@ export function Select(props: SelectArgs) {
     disabled,
     name,
     'aria-label': ariaLabel,
+    'aria-describedby': ownDescribedBy,
   } = props;
   const field = useFieldControl();
+  const describedBy = [ownDescribedBy, field['aria-describedby']].filter(
+    (id): id is string => id !== undefined,
+  );
   // Untyped JavaScript is the only caller that reaches this. Rendering one list
   // and dropping the other would lose every entry in the discarded one silently,
   // and an empty listbox reads as "there is nothing to choose".
@@ -118,7 +128,7 @@ export function Select(props: SelectArgs) {
         // for>`, and `aria-label` outranks a native label — emitting both would
         // discard the visible text the field renders.
         aria-label={field.id === undefined ? ariaLabel : undefined}
-        aria-describedby={field['aria-describedby']}
+        aria-describedby={describedBy.length > 0 ? describedBy.join(' ') : undefined}
         aria-invalid={field['aria-invalid']}
       >
         <RadixSelect.Value placeholder={placeholder} />

package/src/components/served-media.tsx

@@ -12,6 +12,7 @@
  * url is a loud blocked notice, its text React-escaped, never a live attribute.
  * There is no `dangerouslySetInnerHTML` here.
  */
+import type { ServedConstants } from '@tai42/api-client';
 import type { CSSProperties, ReactNode } from 'react';
 import { useState } from 'react';
 
@@ -20,24 +21,29 @@ import { Badge } from './badge';
 import { isSafeHttpUrl } from './primitives';
 
 /**
- * The served-media route: media is stored by reference and served from the API
- * origin at `MEDIA_ROUTE_PREFIX + <id>`, where the id is 43 urlsafe-base64 chars
- * (32 random bytes). A record carries it as a RELATIVE url of exactly that shape —
- * the platform's own media reference, resolved to the API base at render time
+ * The served-media grammar the contract publishes, read from the injected client
+ * (`useApi().constants`): the served route prefix and the stored-media id pattern. Media is
+ * stored by reference and served from the API origin at `MEDIA_ROUTE_PREFIX + <id>`; a record
+ * carries it as a RELATIVE url of exactly that shape, resolved to the API base at render time
  * ({@link resolveMediaSrc}), not assumed same-origin as the SPA page.
  */
-const MEDIA_ROUTE_PREFIX = '/api/interactions/media/';
-const MEDIA_ID = /^[A-Za-z0-9_-]{43}$/;
+export type ServedMediaGrammar = {
+  readonly [K in keyof Pick<ServedConstants, 'MEDIA_ROUTE_PREFIX' | 'MEDIA_ID_PATTERN'>]: string;
+};
 
 /**
  * Whether `url` is the platform's own served-media reference: a relative
- * `MEDIA_ROUTE_PREFIX + <id>` with a well-formed 43-char urlsafe-base64 id. A served
+ * `MEDIA_ROUTE_PREFIX + <id>` whose id matches `MEDIA_ID_PATTERN` whole. A served
  * reference is same-origin to the API base ({@link resolveMediaSrc}) and leaks no page
  * context on load, so a sink with no per-element referrer control (`<audio>`/`<video>`,
  * where `referrerPolicy` is not a valid attribute) admits ONLY this form.
  */
-export function isServedMediaUrl(url: string): boolean {
-  return url.startsWith(MEDIA_ROUTE_PREFIX) && MEDIA_ID.test(url.slice(MEDIA_ROUTE_PREFIX.length));
+export function isServedMediaUrl(url: string, grammar: ServedMediaGrammar): boolean {
+  const prefix = grammar.MEDIA_ROUTE_PREFIX;
+  return (
+    url.startsWith(prefix) &&
+    new RegExp(`^${grammar.MEDIA_ID_PATTERN}$`).test(url.slice(prefix.length))
+  );
 }
 
 /**
@@ -55,9 +61,17 @@ export function isServedMediaUrl(url: string): boolean {
  * item. The gate keys on the reference form; {@link resolveMediaSrc} joins an
  * admitted reference to the API base for the actual load.
  */
-export function isRenderableMediaSrc(url: string, allowDataImage = false): boolean {
+export function isRenderableMediaSrc(
+  url: string,
+  grammar: ServedMediaGrammar,
+  allowDataImage = false,
+): boolean {
   const isHttpsUrl = isSafeHttpUrl(url) && new URL(url).protocol === 'https:';
-  return isHttpsUrl || (allowDataImage && url.startsWith('data:image/')) || isServedMediaUrl(url);
+  return (
+    isHttpsUrl ||
+    (allowDataImage && url.startsWith('data:image/')) ||
+    isServedMediaUrl(url, grammar)
+  );
 }
 
 /**
@@ -69,8 +83,8 @@ export function isRenderableMediaSrc(url: string, allowDataImage = false): boole
  * relative, which is correct; a configured base's trailing slash is stripped so the
  * join never double-slashes.
  */
-export function resolveMediaSrc(url: string, baseUrl: string): string {
-  return isServedMediaUrl(url) ? `${baseUrl.replace(/\/+$/, '')}${url}` : url;
+export function resolveMediaSrc(url: string, baseUrl: string, grammar: ServedMediaGrammar): string {
+  return isServedMediaUrl(url, grammar) ? `${baseUrl.replace(/\/+$/, '')}${url}` : url;
 }
 
 // -- styles ------------------------------------------------------------------
@@ -150,9 +164,9 @@ export function MediaImage({
   // url rendered at this same position gets a fresh load attempt instead of inheriting
   // a stale failure notice.
   const [failedUrl, setFailedUrl] = useState<string | null>(null);
-  const { baseUrl } = useApi();
+  const { baseUrl, constants } = useApi();
 
-  if (!isRenderableMediaSrc(url, allowDataImage)) {
+  if (!isRenderableMediaSrc(url, constants, allowDataImage)) {
     if (renderNotice !== undefined) return renderNotice('blocked', url);
     return (
       <div role="alert" data-testid="media-item-blocked" style={blockedStyle}>
@@ -175,7 +189,7 @@ export function MediaImage({
   return (
     <div style={itemStyle}>
       <img
-        src={resolveMediaSrc(url, baseUrl)}
+        src={resolveMediaSrc(url, baseUrl, constants)}
         alt={caption ?? altFallback}
         referrerPolicy="no-referrer"
         style={imageStyle}
@@ -187,3 +201,123 @@ export function MediaImage({
     </div>
   );
 }
+
+// -- document item -----------------------------------------------------------
+
+const chipStyle: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 'var(--tai-space-2)',
+};
+
+const labelStyle: CSSProperties = {
+  wordBreak: 'break-all',
+};
+
+export interface MediaDocumentProps {
+  readonly url: string;
+  /** The download label: the item's filename or caption, or the caller's default. */
+  readonly label: string;
+  /** Render the notice shown when the url fails the src gate. */
+  readonly renderNotice: (url: string) => ReactNode;
+}
+
+/**
+ * One document: a labelled download affordance. The served route sends
+ * `Content-Disposition: attachment` for documents, so the anchor `download`-hints and
+ * opens in a new tab; `rel="noreferrer"` stops the Studio URL leaking to the media
+ * host. A url that fails {@link isRenderableMediaSrc} is the caller's notice, never a
+ * live href.
+ */
+export function MediaDocument({ url, label, renderNotice }: MediaDocumentProps): ReactNode {
+  const { baseUrl, constants } = useApi();
+  if (!isRenderableMediaSrc(url, constants)) return renderNotice(url);
+  return (
+    <div style={chipStyle} data-testid="media-document">
+      <Badge variant="neutral">Document</Badge>
+      <a
+        href={resolveMediaSrc(url, baseUrl, constants)}
+        target="_blank"
+        rel="noreferrer"
+        download
+        title={label}
+        style={labelStyle}
+      >
+        {label}
+      </a>
+    </div>
+  );
+}
+
+// -- audio / video item ------------------------------------------------------
+
+const audioStyle: CSSProperties = {
+  width: '100%',
+};
+
+const videoStyle: CSSProperties = {
+  maxWidth: '100%',
+  maxHeight: '320px',
+  width: 'auto',
+  height: 'auto',
+  borderRadius: 'var(--tai-radius-md)',
+  border: '1px solid var(--tai-color-border)',
+};
+
+export interface MediaPlayerProps {
+  readonly kind: 'audio' | 'video';
+  readonly url: string;
+  /** The player's accessible label. */
+  readonly label: string;
+  /**
+   * Render the notice shown when no player is displayed: `state` is `'blocked'` when
+   * the url is not a served reference and `'failed'` when it fails to LOAD.
+   */
+  readonly renderNotice: (state: 'blocked' | 'failed', url: string) => ReactNode;
+}
+
+/**
+ * A native `<audio>`/`<video controls>` player. `referrerPolicy` is not a valid
+ * attribute on `<audio>`/`<video>`, so a remote load has no per-element referrer
+ * control; the player therefore admits ONLY the platform's own served-media reference
+ * ({@link isServedMediaUrl}: same-origin, leaking no page URL to a media host), and any
+ * other url, a bare `https:` one included, is the caller's notice. The load-failure
+ * flag keys on the url that failed so a new url at the same position gets a fresh load.
+ */
+export function MediaPlayer({ kind, url, label, renderNotice }: MediaPlayerProps): ReactNode {
+  const [failedUrl, setFailedUrl] = useState<string | null>(null);
+  const { baseUrl, constants } = useApi();
+
+  if (!isServedMediaUrl(url, constants)) return renderNotice('blocked', url);
+  if (failedUrl === url) return renderNotice('failed', url);
+
+  const src = resolveMediaSrc(url, baseUrl, constants);
+  const onError = (): void => {
+    setFailedUrl(url);
+  };
+  return (
+    <div style={itemStyle}>
+      {kind === 'audio' ? (
+        // eslint-disable-next-line jsx-a11y/media-has-caption -- a media item carries no caption track
+        <audio
+          controls
+          src={src}
+          aria-label={label}
+          onError={onError}
+          style={audioStyle}
+          data-testid="media-audio"
+        />
+      ) : (
+        // eslint-disable-next-line jsx-a11y/media-has-caption -- a media item carries no caption track
+        <video
+          controls
+          src={src}
+          aria-label={label}
+          onError={onError}
+          style={videoStyle}
+          data-testid="media-video"
+        />
+      )}
+    </div>
+  );
+}

package/src/env-markers.ts

@@ -0,0 +1,70 @@
+/**
+ * The `!ENV ${VAR[:default]}` manifest marker grammar the platform reads: a string leaf
+ * that begins with the `!ENV ` prefix (the tag and exactly one space) references an
+ * environment variable by name, never its value. A variable name carries no `{`, `}` or
+ * `:`; an optional `:default` follows it.
+ */
+
+/** The prefix that makes a string leaf an `!ENV` marker. */
+export const ENV_MARKER_PREFIX = '!ENV ';
+
+/** A leaf that is exactly one reference: group 1 the name, group 2 the optional default. */
+const SINGLE_REF = /^!ENV \$\{([^}{:]+)(?::([^}]+))?\}$/;
+
+/** Every reference inside a marker leaf's expression. */
+const ANY_REF = /\$\{([^}{:]+)(?::[^}]+)?\}/g;
+
+/** The reference of a single-reference marker leaf. */
+export interface EnvRef {
+  readonly key: string;
+  /** The `:default` text (without the leading colon); absent for a bare reference. */
+  readonly default?: string;
+}
+
+/** The reference of `value` when it is exactly `!ENV ${KEY}` or `!ENV ${KEY:default}`, else `null`. */
+export function parseEnvMarker(value: unknown): EnvRef | null {
+  if (typeof value !== 'string') return null;
+  const match = SINGLE_REF.exec(value);
+  if (match === null) return null;
+  const key = match[1] ?? '';
+  const defaultText = match[2];
+  return defaultText === undefined ? { key } : { key, default: defaultText };
+}
+
+/**
+ * The marker referencing `key`, carrying `defaultValue` when given. Throws when
+ * {@link parseEnvMarker} would not read the marker back as `(key, defaultValue)`: a name is
+ * non-empty and carries no `{`, `}` or `:`; a default is non-empty and carries no `}`.
+ */
+export function formatEnvMarker(key: string, defaultValue?: string): string {
+  const marker =
+    defaultValue === undefined
+      ? `${ENV_MARKER_PREFIX}\${${key}}`
+      : `${ENV_MARKER_PREFIX}\${${key}:${defaultValue}}`;
+  const parsed = parseEnvMarker(marker);
+  if (parsed?.key !== key || parsed.default !== defaultValue) {
+    throw new Error(
+      `var ${JSON.stringify(key)} with default ${JSON.stringify(defaultValue)} cannot be written as an !ENV marker: a name is non-empty without '{', '}' or ':', a default is non-empty without '}'`,
+    );
+  }
+  return marker;
+}
+
+/** Every variable name any marker leaf anywhere under `value` references. */
+export function collectEnvRefs(value: unknown): Set<string> {
+  const refs = new Set<string>();
+  const walk = (node: unknown): void => {
+    if (typeof node === 'string') {
+      if (!node.startsWith(ENV_MARKER_PREFIX)) return;
+      for (const match of node.slice(ENV_MARKER_PREFIX.length).matchAll(ANY_REF)) {
+        if (match[1] !== undefined) refs.add(match[1]);
+      }
+    } else if (Array.isArray(node)) {
+      for (const item of node) walk(item);
+    } else if (typeof node === 'object' && node !== null) {
+      for (const nested of Object.values(node)) walk(nested);
+    }
+  };
+  walk(value);
+  return refs;
+}

package/src/hooks/interactions-stream.ts

@@ -75,7 +75,7 @@ function requiredFieldsValid(
 
 /**
  * The optional fields, each rejected only when PRESENT with the wrong type: an
- * absent value stays absent (or takes its schema default on assembly). `media`
+ * absent value takes its schema default (`null`, or `false` for `sensitive`) on assembly. `media`
  * items stay unknown by design — each is validated per item by the renderer.
  */
 function optionalFieldsValid(obj: Record<string, unknown>): boolean {
@@ -100,12 +100,14 @@ function buildInteraction(obj: Record<string, unknown> & RequiredFrameFields): I
     created_at: obj.created_at,
     timeout_at: obj.timeout_at,
     sensitive: typeof obj.sensitive === 'boolean' ? obj.sensitive : false,
-    ...(typeof obj.server_verified === 'boolean' ? { server_verified: obj.server_verified } : {}),
-    ...(typeof obj.channel === 'string' ? { channel: obj.channel } : {}),
-    ...(typeof obj.recipient === 'string' ? { recipient: obj.recipient } : {}),
-    ...(typeof obj.origin === 'string' ? { origin: obj.origin } : {}),
-    ...(typeof obj.audience === 'string' ? { audience: obj.audience } : {}),
-    ...(Array.isArray(obj.media) ? { media: obj.media } : {}),
+    server_verified: typeof obj.server_verified === 'boolean' ? obj.server_verified : null,
+    channel: typeof obj.channel === 'string' ? obj.channel : null,
+    recipient: typeof obj.recipient === 'string' ? obj.recipient : null,
+    origin: typeof obj.origin === 'string' ? obj.origin : null,
+    audience: typeof obj.audience === 'string' ? obj.audience : null,
+    // The items stay unvalidated here: the renderer validates each one, so one malformed
+    // item is a per-item notice rather than a dropped frame.
+    media: Array.isArray(obj.media) ? (obj.media as Interaction['media']) : null,
   };
 }