@ggui-ai/iframe-runtime 0.23.0 → 0.25.0

package/dist/observability.d.ts

@@ -296,14 +296,20 @@ export interface RelayDeadTapEvent {
     readonly appId?: string;
 }
 /**
- * The mount painted NOTHING (ggui#1103): the renderer held no component,
- * so the scope element carries only its stylesheet — a blank card, with no
- * error boundary to catch anything (the boundary wraps a null child). The
- * host is told which mount moment it was and why, because a card that
- * renders nothing is invisible on every other channel: `reason: 'no-code'`
- * is a payload that carried no component code, `'eval-failed'` a module
- * that threw while evaluating. Names the moment only — never the code, the
- * props or the error text, which stay in the operator-visible console line.
+ * The mount painted NOTHING. The host is told which mount moment it was and
+ * why, because a card that renders nothing is invisible on every other
+ * channel. Two reasons are a renderer that held no component (ggui#1103), so
+ * the scope carries only its stylesheet and no error boundary engages:
+ * `'no-code'` is a payload that carried no component code, `'eval-failed'` a
+ * module that threw while evaluating. Three are a component that WAS held
+ * and still painted nothing (ggui#1104): `'rendered-nothing'` — the tree
+ * committed and the scope holds no element; `'detached'` — the tree
+ * committed into a scope no longer in the document (another mount took the
+ * container); `'no-commit'` — the tree never committed within the renderer's
+ * deadline (a component that suspends with no Suspense boundary). Names the
+ * moment only — never the code, the props or the error text, which stay in
+ * the operator-visible console line. A host MUST treat an unknown reason as
+ * a blank of unknown cause.
  *
  * @public
  */
@@ -311,8 +317,8 @@ export interface ComponentEmptyEvent {
     readonly kind: 'component-empty';
     /** Which lifecycle moment painted nothing. */
     readonly where: 'mount' | 'update';
-    /** Why the renderer held no component. */
-    readonly reason: 'no-code' | 'eval-failed';
+    /** Why the moment painted nothing (see above). */
+    readonly reason: 'no-code' | 'eval-failed' | 'rendered-nothing' | 'detached' | 'no-commit';
 }
 /**
  * Catch-all branch for event kinds the host's typings don't recognize.

package/dist/react-renderer.d.ts

@@ -31,6 +31,8 @@
  */
 import React, { type ReactNode } from 'react';
 import type { AppTheme } from '@ggui-ai/protocol/wire';
+/** Test hook: shorten the no-commit deadline; `null` restores the default. */
+export declare function __setNoCommitDeadlineForTest(ms: number | null): void;
 export interface ReactRootMountOptions {
     /**
      * GguiSession whose componentCode + props drive the mount. Only

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;
@@ -212,6 +245,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 +461,21 @@ 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))));
+        }, 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 +574,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,7 +1,7 @@
 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 { AnyTransportHandle, ChannelLogger, ChannelRegistry, FrameClassifier, RegistryPollingOptions, RegistrySseOptions, WsTransportHandle } from '@ggui-ai/live-channel';
 import { type ProtocolErrorEmitter } from './protocol-error.js';
 import type { ObservabilityEmitter } from './observability.js';
 /**
@@ -130,6 +130,21 @@ export interface ConnectViaRegistryOptions {
      */
     readonly logger?: ChannelLogger;
 }
+/**
+ * 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'`

package/dist/render-item.d.ts

@@ -1,7 +1,7 @@
 import type { ReactNode } from 'react';
 import type { AppTheme, GguiSession } from '@ggui-ai/protocol/wire';
 import type { GguiSessionSeedInput } from './types.js';
-import { type WireConfig } from '@ggui-ai/wire';
+import { type BuiltWireConfig } from '@ggui-ai/wire';
 import type { StreamBus } from './wire-config.js';
 export interface RenderItemOptions {
     /** The render to mount. */
@@ -10,8 +10,12 @@ export interface RenderItemOptions {
      *  `buildRootWireConfig(...)` (see `wire-config.ts`). `null` ⇒ the
      *  component mounts without a wire provider (standalone — matches
      *  today's DynamicComponent fallback when no GguiRender parent is
-     *  present). */
-    readonly scopedWireConfig: WireConfig | null;
+     *  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; 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. */
     readonly streamBus: StreamBus;

package/dist/render-item.js

@@ -39,6 +39,7 @@
  */
 import { createElement } from 'react';
 import { GguiWireProvider } from '@ggui-ai/wire';
+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';
@@ -208,9 +209,16 @@ export async function mountRender(container, opts) {
      * mount. When absent, the wire provider is the only wrapper.
      */
     function wrapInScopedProvider(mountedComponent) {
-        const wireWrapped = currentOpts.scopedWireConfig === null
+        const config = currentOpts.scopedWireConfig;
+        const wireWrapped = config === null
             ? mountedComponent
-            : createElement(GguiWireProvider, { config: currentOpts.scopedWireConfig, children: mountedComponent });
+            : createElement(GguiWireProvider, {
+                config,
+                children: createElement(ActionSpentContext.Provider, {
+                    value: config.actionSpent,
+                    children: createElement(ActionPendingContext.Provider, { value: config.actionPending, children: mountedComponent }),
+                }),
+            });
         return currentOpts.wrapOuter !== undefined
             ? currentOpts.wrapOuter(wireWrapped)
             : wireWrapped;

package/dist/runtime.d.ts

@@ -37,6 +37,7 @@ import type { GadgetPackageRegistry } from './globals.js';
 import { StreamBus } from './wire-config.js';
 import { type ChannelTransportRouter } from './channel-transport.js';
 import { ChannelRegistry } from '@ggui-ai/live-channel';
+import { type TelemetrySink } from './runtime-telemetry.js';
 import { type ConnectFn } from './registry-subscribe.js';
 import { type StatusRefs } from './status-dom.js';
 import { type RendererValidatorContext } from './validation.js';
@@ -92,12 +93,10 @@ export declare function setCurrentApp(app: App): void;
  * the spec's `'light' | 'dark'` literals (dropped, never guessed —
  * the same tolerant posture as `projectHostContext`).
  *
- * This is the INPUT leg of host-theme adaptation
- * (rnd/gen-ui/beauty/experiments/002-host-theme-adaptation.md, ggui#551):
+ * This is the INPUT leg of host-theme adaptation (ggui#551):
  * `hostContext.theme` alone reaches only `data-theme` +
  * `color-scheme` via `applyDocumentTheme` — nothing in the token
- * pipeline keys off it, so a dark host painted the light ladder
- * (host-fit 46.0 vs 87.7 with the dark ladder, probe `cc728a8eb`).
+ * pipeline keys off it, so a dark host painted the light ladder.
  * Under ggui#987 §4 the embedding host OWNS runtime mode: when it
  * announces one, `buildOpts` paints it over every stamped opinion; the
  * stamped layers decide only when the host is silent. Read live from
@@ -609,19 +608,6 @@ export declare function readPendingToolResultLocator(): string | null;
  * gone, no envelope) — the caller's other tiers still decide.
  */
 export declare function resolveMetaViaReadDoor(app: App, locator: string): Promise<McpAppAiGguiRenderMeta | null>;
-/**
- * Render a submit-action's `data` payload as a short inline string
- * for embedding in a `ui/message` consent prompt. Goal: human-
- * readable, not a JSON dump. Falls back to truncated JSON for
- * nested values so the prompt doesn't drop information silently.
- *
- * Exported for unit-testing — an earlier implementation returned `''`
- * for primitive payloads (strings/numbers/booleans), which silently
- * vaporised the chip's actual text from the consent prompt and made
- * the LLM think every dispatch was a contentless "Please proceed
- * with **<intent>**" request.
- */
-export declare function formatSubmitActionDataInline(data: unknown): string;
 /**
  * Fire a single canonical action envelope (`tools/call
  * ggui_runtime_submit_action`) carrying the typed `{kind, payload, …}` shape
@@ -683,6 +669,49 @@ interface ToastLiveRegions {
  * @internal — exported for unit tests.
  */
 export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
+/**
+ * Lightweight toast UX surface for dispatched actions. Renders a
+ * fixed-position element at the bottom of the iframe so the user
+ * gets immediate visual feedback that their gesture was registered
+ * — "→ Sending action: archive" → "✓ Queued — agent will react"
+ * (or "💬 Sent to chat" on ui/message fallback).
+ *
+ * Without this, the iframe is silent during dispatch. User clicks
+ * and waits, with no way to distinguish "click was received but the
+ * agent is busy" from "click was lost". Especially load-bearing in
+ * the consume-pipe vs ui/message dual-path era — the toast tells
+ * the user which path the gesture actually took.
+ *
+ * Direct DOM (not React-managed) because:
+ *  - Works during boot before React mounts.
+ *  - Doesn't interfere with the component tree the generator owns.
+ *  - Survives React mount transitions inside the iframe.
+ *
+ * Single global toast (per iframe). Auto-dismisses after 2.5s on
+ * `success` / `fallback` outcomes. A successful dispatch draws nothing
+ * here (ggui#1444): its "sending" is spoken only (see
+ * {@link GESTURE_COPY}).
+ *
+ * The visible element is only half the surface (ggui#447). Every
+ * message is also spoken through {@link ensureToastAnnouncer}'s live
+ * regions, and the element itself is hidden from the accessibility
+ * tree so the sentence is not read twice. The one exception is
+ * `action_required`, the only toast the user must OPERATE: it re-enters
+ * the tree as a named button with a tab stop, because a dismissal that
+ * needs a mouse is a dismissal some users cannot perform.
+ *
+ * @internal — runtime-layer concern.
+ */
+/**
+ * The `label` an action declares on the render's `actionSpec`, trimmed, or
+ * `undefined` when the render declares none (or is a system / MCP-Apps
+ * render, which carries no actionSpec). By contract the label is the
+ * control's own copy, so it is the one name for a tap a visitor may read
+ * (see {@link GESTURE_COPY}).
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function declaredActionLabel(render: GguiSession | GguiSessionSeedInput | null, actionName: string): string | undefined;
 /**
  * Boot-time reset of the relay latch (ggui#670 Phase 3). A latch
  * standing from a prior mount in a re-booted document is closed through
@@ -694,6 +723,12 @@ export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions |
  */
 export declare function resetRelayLatchForBoot(): void;
 /** @internal — exported for unit tests to reset module state. */
+/**
+ * Test-only: install the telemetry sink the runtime records into (normally
+ * set once at boot), so a test can observe the events a code path posts.
+ * `null` restores the no-sink state.
+ */
+export declare function __setTelemetrySinkForTest(sink: TelemetrySink | null): void;
 export declare function __resetRelayNoticeForTest(): void;
 /**
  * Dispatch a submit-action via the empirically-validated bridge
@@ -714,6 +749,8 @@ export declare function dispatchSubmitAction(args: {
     readonly data: unknown;
     readonly sessionId: string;
     readonly appId: string;
+    /** The action's declared `label`, when it has one — see {@link GESTURE_COPY}. */
+    readonly label?: string;
 }): void;
 /**
  * Channel-transport router's `tools/call` invoker (ggui#440) —
@@ -809,6 +846,8 @@ export declare function routeDispatch(args: {
         readonly appId: string;
     };
     readonly dispatchToolName: string;
+    /** The action's declared `label` (visitor copy by contract), when it has one. */
+    readonly label?: string;
 }): void;
 /**
  * `ui/open-link` direct dispatch helper — used by the anchor-click