@ggui-ai/iframe-runtime 0.24.0 → 0.26.0

package/dist/react-renderer.d.ts

@@ -31,6 +31,21 @@
  */
 import React, { type ReactNode } from 'react';
 import type { AppTheme } from '@ggui-ai/protocol/wire';
+import type { RenderFailurePhase } from '@ggui-ai/protocol/render-failure';
+/** Test hook: shorten the no-commit deadline; `null` restores the default. */
+export declare function __setNoCommitDeadlineForTest(ms: number | null): void;
+/**
+ * The boundary's give-up, named (ggui#1679): what the component threw on
+ * its terminal catch, the phase — `mount` when the component had never
+ * committed, `update` when a painted card's re-render threw — and the
+ * boundary's catch count at that moment (the retry included: 2 today). The
+ * runtime reports it to the server in exactly these terms.
+ */
+export interface RenderFailure {
+    readonly error: Error;
+    readonly phase: RenderFailurePhase;
+    readonly catches: number;
+}
 export interface ReactRootMountOptions {
     /**
      * GguiSession whose componentCode + props drive the mount. Only
@@ -98,6 +113,13 @@ export interface ReactRootMountOptions {
     /** `fill` — the root is the whole canvas: no silhouette, fills the page (ggui#1041; from the host's `displayMode`). */
     readonly fit?: 'fill';
     readonly onError?: (error: Error) => void;
+    /**
+     * The error boundary's give-up (ggui#1679): fires once per terminal catch,
+     * beside `onError`, with the phase and the catch count the runtime reports
+     * to the server. Not fired for an eval failure — a module that does not
+     * load is "no component" (ggui#1103), not a component that threw.
+     */
+    readonly onRenderFailure?: (failure: RenderFailure) => void;
     /**
      * Children injected BETWEEN the mount DOM (scope + CSS) and the
      * evaluated component element. The caller's render dispatcher

package/dist/react-renderer.js

@@ -29,7 +29,7 @@
  * `React.createElement` + `React.Fragment` directly so the renderer's
  * TypeScript config doesn't need a JSX runtime plumbing.
  */
-import React, { Component, createElement, Fragment, } from 'react';
+import React, { Component, createElement, Fragment, useEffect, } from 'react';
 import { createRoot } from 'react-dom/client';
 import { postObservabilityToParent } from './observability.js';
 import { trackThemeFontFaces } from './host-fonts.js';
@@ -69,6 +69,39 @@ function makeScopeClass() {
  * re-sanitize here.
  */
 // =============================================================================
+// Paint probe (ggui#1104) — the blanks a HELD component can still produce.
+// =============================================================================
+/**
+ * How long a render may go without committing before it is named a
+ * `no-commit` blank. A healthy commit lands within a frame or two of
+ * `root.render`; a component that suspends with no Suspense boundary never
+ * commits at all, and until now that blank said nothing on any channel.
+ */
+const NO_COMMIT_DEADLINE_MS = 5_000;
+let noCommitDeadlineMs = NO_COMMIT_DEADLINE_MS;
+/** Test hook: shorten the no-commit deadline; `null` restores the default. */
+export function __setNoCommitDeadlineForTest(ms) {
+    noCommitDeadlineMs = ms ?? NO_COMMIT_DEADLINE_MS;
+}
+/**
+ * Rendered inside the scope; its PASSIVE effect runs once the whole commit is
+ * done, refs included. (A layout effect would not do: layout effects run
+ * child-first, before the parent scope `<div>`'s ref is attached, so the
+ * probe would read no scope and misname a healthy mount `detached`.) Renders
+ * nothing itself.
+ */
+function CommitProbe(props) {
+    useEffect(() => {
+        props.onCommit();
+    });
+    return null;
+}
+const HELD_BLANK_DETAIL = {
+    'rendered-nothing': 'the component rendered no element',
+    detached: 'the tree committed into a scope that is no longer in the document (another mount took the container)',
+    'no-commit': 'the tree did not commit (a component that suspends with no Suspense boundary never commits)',
+};
+// =============================================================================
 // Error boundary — port of RCR's internal ErrorBoundary (L68–203).
 // =============================================================================
 const AUTO_RETRY_LIMIT = 1;
@@ -80,9 +113,23 @@ class RcrErrorBoundary extends Component {
         autoRetrying: false,
     };
     retryTimer = null;
+    // Whether the children have ever committed (ggui#1679): a commit with no
+    // error held is the component painting. A boundary whose children never
+    // committed fails in `mount`; one whose painted children throw on a later
+    // render fails in `update`. The boundary is re-keyed on new code, so a
+    // replaced component starts over at `mount`.
+    childrenCommitted = false;
     static getDerivedStateFromError(error) {
         return { error };
     }
+    componentDidMount() {
+        if (this.state.error === null)
+            this.childrenCommitted = true;
+    }
+    componentDidUpdate() {
+        if (this.state.error === null)
+            this.childrenCommitted = true;
+    }
     componentDidCatch(error, _info) {
         const nextCount = this.state.catchCount + 1;
         this.setState({ catchCount: nextCount });
@@ -93,6 +140,13 @@ class RcrErrorBoundary extends Component {
             }, AUTO_RETRY_DELAY);
             return;
         }
+        // The give-up, named first (ggui#1679) — the phase and the count are the
+        // boundary's facts — then the host's own hook, unchanged.
+        this.props.onRenderFailure?.({
+            error,
+            phase: this.childrenCommitted ? 'update' : 'mount',
+            catches: nextCount,
+        });
         this.props.onError?.(error);
     }
     componentWillUnmount() {
@@ -212,6 +266,52 @@ export async function mountReactRoot(container, opts) {
     let currentOpts = opts;
     let currentCode = null;
     let currentComponent = null;
+    // ggui#1104 — the paint probe's state. `heldAtRender` is whether the render
+    // being committed carried a component (when it did not, ggui#1103's
+    // `reportNoComponent` has already named the blank). A blank is reported
+    // once per episode: `blankReported` resets when a commit shows paint.
+    let scopeEl = null;
+    let committedOnce = false;
+    let heldAtRender = false;
+    let blankReported = false;
+    let commitTimer = null;
+    function reportHeldBlank(where, reason) {
+        if (blankReported)
+            return;
+        blankReported = true;
+        // eslint-disable-next-line no-console -- operator-visible failure signal
+        console.warn(`[ggui] mountReactRoot: the ${where} painted nothing (${reason}) — ${HELD_BLANK_DETAIL[reason]}`);
+        try {
+            postObservabilityToParent({ kind: 'component-empty', where, reason });
+        }
+        catch {
+            // Best-effort seam, as in reportNoComponent: never turn a blank into a throw.
+        }
+    }
+    const setScopeEl = (el) => {
+        scopeEl = el;
+    };
+    const onCommit = () => {
+        if (commitTimer !== null) {
+            clearTimeout(commitTimer);
+            commitTimer = null;
+        }
+        const where = committedOnce ? 'update' : 'mount';
+        committedOnce = true;
+        if (!heldAtRender)
+            return;
+        const scope = scopeEl;
+        if (scope === null || !scope.isConnected) {
+            reportHeldBlank(where, 'detached');
+            return;
+        }
+        const painted = Array.from(scope.children).some((child) => child.tagName !== 'STYLE');
+        if (painted) {
+            blankReported = false;
+            return;
+        }
+        reportHeldBlank(where, 'rendered-nothing');
+    };
     async function evaluate(code) {
         // 0. If code is a URL (S3 presigned), fetch the bytes first.
         //    Matches RCR's first-step URL-fetch guard verbatim.
@@ -382,10 +482,22 @@ export async function mountReactRoot(container, opts) {
         // The scope `<div>` + inline `<style>` + error-boundary-wrapped
         // children match RCR L376–383. `key={currentCode?.length}` mirrors
         // RCR's "reset boundary when code changes" heuristic.
-        root.render(createElement('div', { className: scopeClass }, createElement('style', null, themeCss), createElement(RcrErrorBoundary, {
+        root.render(createElement('div', { className: scopeClass, ref: setScopeEl }, createElement('style', null, themeCss), createElement(RcrErrorBoundary, {
             key: currentCode?.length ?? 0,
             ...(opts.onError ? { onError: opts.onError } : {}),
-        }, createElement(Fragment, null, wrapped))));
+            ...(opts.onRenderFailure ? { onRenderFailure: opts.onRenderFailure } : {}),
+        }, createElement(Fragment, null, wrapped)), createElement(CommitProbe, { onCommit })));
+        // ggui#1104 — a held component must commit. Armed only when this render
+        // carries one; the probe's commit disarms it.
+        heldAtRender = currentComponent !== null;
+        if (commitTimer !== null)
+            clearTimeout(commitTimer);
+        commitTimer = heldAtRender
+            ? setTimeout(() => {
+                commitTimer = null;
+                reportHeldBlank(committedOnce ? 'update' : 'mount', 'no-commit');
+            }, noCommitDeadlineMs)
+            : null;
     }
     /**
      * The mount painted NOTHING (ggui#1103). `wrapped` is `null` whenever the
@@ -484,6 +596,9 @@ export async function mountReactRoot(container, opts) {
             }
         },
         unmount() {
+            if (commitTimer !== null)
+                clearTimeout(commitTimer);
+            commitTimer = null;
             root.unmount();
             container.replaceChildren();
         },

package/dist/registry-subscribe.d.ts

@@ -1,8 +1,8 @@
 import type { AckPayload } from '@ggui-ai/protocol/wire';
 import type { ConnectionStatus } from '@ggui-ai/protocol/transport/websocket';
 import type { McpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
-import type { AnyTransportHandle, ChannelLogger, ChannelRegistry, RegistryPollingOptions, RegistrySseOptions, WsTransportHandle } from '@ggui-ai/live-channel';
-import { type ProtocolErrorEmitter } from './protocol-error.js';
+import type { AnyTransportHandle, ChannelLogger, ChannelRegistry, FrameClassifier, RegistryPollingOptions, RegistrySseOptions, WsTransportHandle } from '@ggui-ai/live-channel';
+import { type AuthFailureCode, type ProtocolErrorEmitter } from './protocol-error.js';
 import type { ObservabilityEmitter } from './observability.js';
 /**
  * Result of a successful handshake — the live typed transport handle
@@ -25,11 +25,31 @@ export interface RegistrySubscribeHandle {
      * absent entirely (exact-optional).
      */
     readonly ack?: AckPayload;
+    /**
+     * The auth-class code the server refused the subscribe with before any
+     * ack (ggui#1496). The refusal failed the WS rung, and the ladder in
+     * `handle` goes on demoting; the caller keeps it, so that a view which
+     * refreshes its credential can dispose it when the new ladder takes
+     * over. Absent on an accepted bind. The typed auth `ProtocolError` has
+     * already been emitted.
+     */
+    readonly refused?: SubscribeRefusal;
+}
+/** A pre-ack auth-class refusal, with the server's message when it sent one. */
+export interface SubscribeRefusal {
+    readonly code: AuthFailureCode;
+    readonly message?: string;
 }
 /**
  * Caller-provided callbacks. The runtime's `bootSequence` owns the
  * concrete implementations; tests pass mocks via the `connectFn` seam.
  */
+/** A post-ack `error` frame's payload, as the server sent it (ggui#1424). */
+export interface PostAckErrorPayload {
+    readonly code: string;
+    readonly message?: string;
+    readonly details?: unknown;
+}
 export interface ConnectViaRegistryOptions {
     /**
      * GguiSession slice (`McpAppAiGguiRenderMeta`) — the live-channel
@@ -90,6 +110,15 @@ export interface ConnectViaRegistryOptions {
      * coherent by the time the resubscribe-ack arrives.
      */
     readonly onResubscribeAck?: (ack: AckPayload) => void;
+    /**
+     * ggui#1424 — every `error` frame that arrives AFTER the handshake
+     * settled, as sent. Pre-ack errors keep their classification path (the
+     * handshake's refusal / upgrade handling) and never reach this. The
+     * runtime reads a server refusal of a spent one-shot here (the channel
+     * door's CONTRACT_VIOLATION frame with a violation at
+     * `actionSpec.<name>.oneShot`) and shows the action as done.
+     */
+    readonly onPostAckError?: (payload: PostAckErrorPayload) => void;
     /**
      * Registry-level polling descriptor (R6). When supplied, the live-
      * channel's `FailoverHandle` uses this as its polling fallback when
@@ -129,7 +158,29 @@ export interface ConnectViaRegistryOptions {
      * behavior on console-less sandboxed hosts reaches the server.
      */
     readonly logger?: ChannelLogger;
+    /**
+     * The bound transport, as soon as `bind()` resolves (ggui#1496), before
+     * any ack or refusal settles the handshake. A caller that may need to
+     * dispose a ladder whose handshake never settles (a socket that never
+     * opens, demoting to its bridge) takes the handle here.
+     */
+    readonly onBound?: (handle: AnyTransportHandle) => void;
 }
+/**
+ * The iframe's verdict on channel frames for the WebSocket retry budget
+ * (ggui#1496), handed to every `ChannelRegistry` the runtime builds.
+ *
+ * - An `ack` is an accepted subscription, so the budget resets. It no
+ *   longer resets when a socket merely opens: a socket the server opens
+ *   and then refuses at subscribe used to reset it on every attempt, so
+ *   the transport never reached `'failed'` and the failover never moved.
+ * - An `error` whose code is a {@link PRE_ACK_AUTH_CODES} member is a
+ *   refusal no retry of the same credential can fix (the subscribe is
+ *   rebuilt from the same `wsToken` each attempt), so the transport
+ *   fails at once and the ladder moves to its next rung. The same list
+ *   classifies the handshake's typed error, so the two cannot drift.
+ */
+export declare const classifyChannelFrame: FrameClassifier;
 /**
  * Open the WS via the registry, send subscribe (composed by the
  * registry's `subscribeFrameBuilder`), await the first `ack`. Resolves

package/dist/registry-subscribe.js

@@ -110,6 +110,35 @@ const PRE_ACK_AUTH_CODES = new Set([
 function isAuthFailureCode(code) {
     return PRE_ACK_AUTH_CODES.has(code);
 }
+/**
+ * The iframe's verdict on channel frames for the WebSocket retry budget
+ * (ggui#1496), handed to every `ChannelRegistry` the runtime builds.
+ *
+ * - An `ack` is an accepted subscription, so the budget resets. It no
+ *   longer resets when a socket merely opens: a socket the server opens
+ *   and then refuses at subscribe used to reset it on every attempt, so
+ *   the transport never reached `'failed'` and the failover never moved.
+ * - An `error` whose code is a {@link PRE_ACK_AUTH_CODES} member is a
+ *   refusal no retry of the same credential can fix (the subscribe is
+ *   rebuilt from the same `wsToken` each attempt), so the transport
+ *   fails at once and the ladder moves to its next rung. The same list
+ *   classifies the handshake's typed error, so the two cannot drift.
+ */
+export const classifyChannelFrame = (frame) => {
+    if (frame.type === 'ack')
+        return 'accepted';
+    if (frame.type !== 'error')
+        return undefined;
+    const payload = frame.payload;
+    if (typeof payload === 'object' &&
+        payload !== null &&
+        'code' in payload &&
+        typeof payload.code === 'string' &&
+        isAuthFailureCode(payload.code)) {
+        return 'refused-terminal';
+    }
+    return undefined;
+};
 /**
  * Map a pre-ack `error` frame onto a non-UPGRADE_REQUIRED ProtocolError.
  * {@link PRE_ACK_AUTH_CODES} → `'auth'`; every other code → `'protocol'`
@@ -217,15 +246,15 @@ export function connectViaRegistry(opts) {
         opts.registry.register({
             type: 'error',
             onMessage: (payload) => {
-                // Post-ack error frames are NOT handled here — the runtime
-                // doesn't currently route post-ack `error` frames through a
-                // registered handler (they used to surface via the legacy
-                // `onMessage` callback; B3b drops that channel since
-                // post-ack errors are rare + the host inspector logs them
-                // through the typed ProtocolError emitter).
-                if (settled)
-                    return;
                 const errPayload = payload;
+                // Post-ack error frames go to the caller as sent (ggui#1424): the
+                // runtime reads the channel door's refusal of a spent one-shot
+                // there. Before that they reached nothing (B3b had dropped the
+                // legacy `onMessage` channel as rare).
+                if (settled) {
+                    opts.onPostAckError?.(errPayload);
+                    return;
+                }
                 const upgrade = liftUpgradeRequiredFromError(errPayload);
                 if (upgrade !== null) {
                     settled = true;
@@ -241,6 +270,17 @@ export function connectViaRegistry(opts) {
                 }
                 settled = true;
                 emitProtocolError(classifyPreAckError(errPayload));
+                if (isAuthFailureCode(errPayload.code)) {
+                    // An auth-class refusal fails the WS rung (the classifier's
+                    // verdict) and the ladder demotes; resolve with the handle so
+                    // the caller keeps it (ggui#1496).
+                    refusalState.refusal = {
+                        code: errPayload.code,
+                        ...(errPayload.message !== undefined ? { message: errPayload.message } : {}),
+                    };
+                    refusalState.onRefused?.();
+                    return;
+                }
                 reject(new Error(errPayload.message ?? errPayload.code));
             },
         });
@@ -248,6 +288,8 @@ export function connectViaRegistry(opts) {
         // payload to the bind continuation without sharing a mutable
         // local with the outer Promise body.
         const ackResolverState = { payload: null, onAck: null };
+        // Same hand-off for a pre-ack auth-class refusal (ggui#1496).
+        const refusalState = { refusal: null, onRefused: null };
         const mappedStatusCallback = (status) => {
             // `connecting` is the initial state from WSTransport — first
             // surfaced concurrent with `start()`. Subsequent `connecting`
@@ -312,6 +354,7 @@ export function connectViaRegistry(opts) {
             ...(opts.bridge !== undefined ? { bridge: opts.bridge } : {}),
         })
             .then((bound) => {
+            opts.onBound?.(bound);
             if (!hasTrio) {
                 // Bridge-only bind — no subscribe handshake, no ack. The
                 // polling facade reports 'open' immediately (mapped to
@@ -334,6 +377,18 @@ export function connectViaRegistry(opts) {
                 return;
             }
             const wsHandle = bound;
+            // A refusal that landed while bind was resolving settles now;
+            // one that lands later settles through its continuation.
+            const refusal = refusalState.refusal;
+            if (refusal !== null) {
+                resolve({ handle: wsHandle, refused: refusal });
+                return;
+            }
+            refusalState.onRefused = () => {
+                const late = refusalState.refusal;
+                if (late !== null)
+                    resolve({ handle: wsHandle, refused: late });
+            };
             // If we already received the ack while bind was resolving,
             // settle the outer Promise now.
             if (ackResolverState.payload !== null) {

package/dist/render-failure-report.d.ts

@@ -0,0 +1,15 @@
+import type { GguiReportRenderFailureInput } from '@ggui-ai/protocol';
+import type { RenderFailure } from './react-renderer.js';
+/** The slice of a tool caller the reporter needs: the bridge's `(name, arguments)`. */
+export type RenderFailureCallTool = (name: string, args: GguiReportRenderFailureInput) => Promise<unknown>;
+export interface RenderFailureReporter {
+    /** Report the boundary's give-up. Idempotent per session: the second call is a no-op. */
+    readonly report: (failure: RenderFailure) => void;
+    /** Whether this session's one report has been sent (or attempted). */
+    readonly reported: () => boolean;
+}
+export declare function createRenderFailureReporter(opts: {
+    readonly sessionId: string;
+    readonly appId: string;
+    readonly callTool: RenderFailureCallTool;
+}): RenderFailureReporter;

package/dist/render-failure-report.js

@@ -0,0 +1,61 @@
+/**
+ * The runtime's render-failure report (ggui#1679) — the emit half of
+ * `ggui_runtime_report_render_failure` (ggui#1609; SPEC §4.9).
+ *
+ * When the card's error boundary gives up — its retry exhausted, on the first
+ * paint or on a later re-render — the runtime tells the server once, for the
+ * session it renders. The report carries ids and counts only: the session and
+ * app ids the boot envelope named, the phase, the thrown value's class name
+ * under the tool's own pattern ({@link renderFailureErrorName}: never a
+ * message, a stack, props or component source) and the boundary's catch
+ * count, clamped to the tool's bound.
+ *
+ * Obligations (SPEC §4.9, runtime side):
+ *
+ *   - **At most one report per session.** The first terminal failure is the
+ *     one reported; a card that fails again, in the other phase or after a
+ *     re-mount, sends nothing more. The flag is spent when the call is MADE,
+ *     not when it is answered, so a report that fails is never resent: a
+ *     relay carries no per-session limiter, and one relayed call per session
+ *     is the bound.
+ *   - **Nothing the visitor sees changes.** The call is fire-and-forget; a
+ *     refusal, a tool-not-found from a server that predates the tool, or a
+ *     network loss is dropped in silence. No toast, no doorbell, no retry.
+ *
+ * The call site is {@link bridgeCallToolVia}'s `tools/call` over the host
+ * relay, so the request carries the view proof the server records against
+ * (`_meta["ai.ggui/view"]`, ggui#1415); an unproven report is answered `ok`
+ * and recorded nowhere, by the server's own rule.
+ */
+// The pure-const subpath, never the package root: the root would pull the
+// whole zod schema module into the card runtime's bundle (ggui#1679, +34 KB).
+import { RENDER_FAILURE_MAX_CATCHES, renderFailureErrorName } from '@ggui-ai/protocol/render-failure';
+export function createRenderFailureReporter(opts) {
+    let spent = false;
+    const report = (failure) => {
+        if (spent)
+            return;
+        spent = true;
+        const args = {
+            sessionId: opts.sessionId,
+            appId: opts.appId,
+            phase: failure.phase,
+            errorName: renderFailureErrorName(failure.error),
+            catches: Math.min(Math.max(1, Math.trunc(failure.catches)), RENDER_FAILURE_MAX_CATCHES),
+        };
+        let call;
+        try {
+            call = opts.callTool('ggui_runtime_report_render_failure', args);
+        }
+        catch {
+            // A caller that throws synchronously (no App bridge bound) is the
+            // same outcome as a refused call: not reported, nothing shown.
+            return;
+        }
+        void call.catch(() => {
+            // Dropped by design (SPEC §4.9): a report never changes what the
+            // visitor sees, and a failed one is never retried.
+        });
+    };
+    return { report, reported: () => spent };
+}

package/dist/render-item.d.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 import type { AppTheme, GguiSession } from '@ggui-ai/protocol/wire';
 import type { GguiSessionSeedInput } from './types.js';
 import { type BuiltWireConfig } from '@ggui-ai/wire';
+import { type RenderFailure } from './react-renderer.js';
 import type { StreamBus } from './wire-config.js';
 export interface RenderItemOptions {
     /** The render to mount. */
@@ -12,7 +13,9 @@ export interface RenderItemOptions {
      *  today's DynamicComponent fallback when no GguiRender parent is
      *  present). The config carries the card's `actionSpent` source
      *  (ggui#1223), and the component mounts inside `ActionSpentContext` too,
-     *  so `useActionSpent` reads the one-shot guard's own spent set. */
+     *  so `useActionSpent` reads the one-shot guard's own spent set; likewise
+     *  `actionPending` inside `ActionPendingContext` (ggui#1398), so
+     *  `useActionPending` reads the card's in-flight dispatches. */
     readonly scopedWireConfig: BuiltWireConfig | null;
     /** Shared stream bus — provisional renderer subscribes to
      *  `_ggui:preview` for this render. */
@@ -72,6 +75,8 @@ export interface RenderItemOptions {
     readonly hostPalette?: Readonly<Record<string, string>>;
     readonly cssOverrides?: string;
     readonly onError?: (err: Error) => void;
+    /** The boundary's give-up, forwarded to the React mount (ggui#1679; see {@link ReactRootMountOptions.onRenderFailure}). */
+    readonly onRenderFailure?: (failure: RenderFailure) => void;
     /**
      * Optional outer wrapper applied AROUND the GguiWireProvider — used
      * by `bootProduction` to install the `<ContextStateHost>` provider

package/dist/render-item.js

@@ -39,7 +39,7 @@
  */
 import { createElement } from 'react';
 import { GguiWireProvider } from '@ggui-ai/wire';
-import { ActionSpentContext } from '@ggui-ai/wire/internal';
+import { ActionPendingContext, ActionSpentContext } from '@ggui-ai/wire/internal';
 import { mountReactRoot } from './react-renderer.js';
 import { mountProvisional, } from './provisional-renderer.js';
 import { mountMcpAppIframe, } from './mcp-app-iframe-host.js';
@@ -189,6 +189,7 @@ export async function mountRender(container, opts) {
             // without it, and every served hello composed as an inline card.
             ...(currentOpts.fit !== undefined ? { fit: currentOpts.fit } : {}),
             ...(currentOpts.onError !== undefined ? { onError: currentOpts.onError } : {}),
+            ...(currentOpts.onRenderFailure !== undefined ? { onRenderFailure: currentOpts.onRenderFailure } : {}),
             renderWrapper: wrapInScopedProvider,
         });
         currentKind = 'react';
@@ -214,7 +215,10 @@ export async function mountRender(container, opts) {
             ? mountedComponent
             : createElement(GguiWireProvider, {
                 config,
-                children: createElement(ActionSpentContext.Provider, { value: config.actionSpent, children: mountedComponent }),
+                children: createElement(ActionSpentContext.Provider, {
+                    value: config.actionSpent,
+                    children: createElement(ActionPendingContext.Provider, { value: config.actionPending, children: mountedComponent }),
+                }),
             });
         return currentOpts.wrapOuter !== undefined
             ? currentOpts.wrapOuter(wireWrapped)
@@ -265,6 +269,7 @@ export async function mountRender(container, opts) {
                     ...(next.cssOverrides !== undefined ? { cssOverrides: next.cssOverrides } : {}),
                     ...(next.fit !== undefined ? { fit: next.fit } : {}),
                     ...(next.onError !== undefined ? { onError: next.onError } : {}),
+                    ...(next.onRenderFailure !== undefined ? { onRenderFailure: next.onRenderFailure } : {}),
                     renderWrapper: wrapInScopedProvider,
                 });
                 return;

package/dist/runtime-telemetry.d.ts

@@ -10,38 +10,48 @@
  * them over the host's `tools/call` postMessage bridge, the one
  * carrier a CSP jail cannot block.
  *
- * What flows through it:
- *   - `record()` calls from the boot sequence (path decisions, status
- *     transitions, doorbell rings);
- *   - the live-channel's OWN diagnostics via {@link channelLogger} —
- *     a `ChannelLogger` facade that forwards every
- *     `channel_failover_swap` / `channel_polling_*` / SSE event the
- *     transports already emit. Tapping the logger means ZERO new
- *     instrumentation inside `@ggui-ai/live-channel`.
+ * Two batches, never mixed in one call (#1383):
+ *   - HEALTH — which rung the card booted on, its connection status,
+ *     whether its doorbell rang, which transport failed. Event names and
+ *     the card's own ids only: each health kind pins the one `detail`
+ *     shape it admits (none | id | booleans), and a detail outside that
+ *     shape is left off the event, never sent free. A host may admit this
+ *     vocabulary and nothing else, judging a batch whole; keeping the
+ *     other events out of it means they can never cost it the doorbell
+ *     ring.
+ *   - DIAGNOSTIC — the gesture trail and the ladder's finer story (the
+ *     credential renewals, stream restarts, a live channel's end). Its
+ *     details are codes, enums, numbers and ids, never free text: no
+ *     intent strings, no error messages, no URLs.
+ *   {@link RUNTIME_TELEMETRY_KINDS} is the one table of kinds, and
+ *   `record` takes only its kinds, so a new emit site is a new table row.
  *
  * Posture: bounded, fire-and-forget, diagnostics-only.
- *   - Buffer caps at the protocol's per-batch limit; overflow drops
- *     the OLDEST entries (the tail of a failure story beats its
+ *   - Each batch buffers up to the protocol's per-batch limit; overflow
+ *     drops the OLDEST entries (the tail of a failure story beats its
  *     preamble).
  *   - First flush is delayed (~4s) so one batch carries the whole
- *     boot+ladder story; later flushes throttle.
- *   - A hard per-session flush cap bounds host load; flush failures
- *     are swallowed (a diagnostics channel must never cause the
- *     symptoms it reports).
+ *     boot+ladder story; later flushes throttle. The health batch
+ *     flushes first.
+ *   - Each batch has its own per-session flush cap (health 8, diagnostic
+ *     4), so refused diagnostic flushes never starve the health batch;
+ *     flush failures are swallowed (a diagnostics channel must never
+ *     cause the symptoms it reports).
  */
 import type { ChannelLogger } from '@ggui-ai/live-channel';
+import { type RuntimeTelemetryKind } from '@ggui-ai/protocol/runtime-telemetry';
 /** Narrow slice of `App.callServerTool` the sink needs. */
 export type TelemetryCallTool = (args: {
     name: string;
     arguments: Record<string, unknown>;
 }) => Promise<unknown>;
 export interface TelemetrySink {
-    /** Append one event; schedules a (throttled) flush. */
-    record(kind: string, detail?: string): void;
+    /** Append one event to its kind's batch; schedules a (throttled) flush. */
+    record(kind: RuntimeTelemetryKind, detail?: string): void;
     /**
      * `ChannelLogger` facade for the live-channel bind — every event the
-     * transports emit lands in the buffer verbatim (event name = kind,
-     * fields JSON = detail).
+     * transports emit lands in the health batch by name, with no detail
+     * (the transports' fields carry URLs and error messages).
      */
     readonly channelLogger: ChannelLogger;
     /** Cancel timers; buffered-but-unflushed events are dropped. */