@ggui-ai/iframe-runtime 0.25.0 → 0.26.0

package/dist/react-renderer.js

@@ -113,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 });
@@ -126,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() {
@@ -464,6 +485,7 @@ export async function mountReactRoot(container, opts) {
         root.render(createElement('div', { className: scopeClass, ref: setScopeEl }, createElement('style', null, themeCss), createElement(RcrErrorBoundary, {
             key: currentCode?.length ?? 0,
             ...(opts.onError ? { onError: opts.onError } : {}),
+            ...(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.

package/dist/registry-subscribe.d.ts

@@ -2,7 +2,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, FrameClassifier, RegistryPollingOptions, RegistrySseOptions, WsTransportHandle } from '@ggui-ai/live-channel';
-import { type ProtocolErrorEmitter } from './protocol-error.js';
+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,6 +158,13 @@ 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

package/dist/registry-subscribe.js

@@ -246,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;
@@ -270,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));
             },
         });
@@ -277,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`
@@ -341,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
@@ -363,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. */
@@ -74,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

@@ -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';
@@ -268,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. */

package/dist/runtime-telemetry.js

@@ -1,24 +1,58 @@
+import { RUNTIME_TELEMETRY_KINDS, } from '@ggui-ai/protocol/runtime-telemetry';
 import { RUNTIME_TELEMETRY_MAX_EVENTS } from '@ggui-ai/protocol/wire';
 const FIRST_FLUSH_DELAY_MS = 4_000;
 const FLUSH_THROTTLE_MS = 8_000;
-const MAX_FLUSHES_PER_SESSION = 12;
+const MAX_HEALTH_FLUSHES_PER_SESSION = 8;
+const MAX_DIAGNOSTIC_FLUSHES_PER_SESSION = 4;
 const MAX_DETAIL_CHARS = 500;
+/** The kind vocabulary (`@ggui-ai/protocol/runtime-telemetry`, ggui#1381), indexed by kind. */
+const SPEC_BY_KIND = new Map(RUNTIME_TELEMETRY_KINDS.map((s) => [s.kind, s]));
+const ID_DETAIL = /^[A-Za-z0-9_.:-]{1,128}$/;
+function isBooleansObject(detail) {
+    let parsed;
+    try {
+        parsed = JSON.parse(detail);
+    }
+    catch {
+        return false;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return false;
+    const values = Object.values(parsed);
+    return values.length > 0 && values.every((v) => typeof v === 'boolean');
+}
+/** The detail a kind may carry, or `undefined` when its shape does not admit this one. */
+function admittedDetail(spec, detail) {
+    if (detail === undefined || spec === undefined)
+        return undefined;
+    switch (spec.detail) {
+        case 'none':
+            return undefined;
+        case 'id':
+            return ID_DETAIL.test(detail) ? detail : undefined;
+        case 'booleans':
+            return detail.length <= MAX_DETAIL_CHARS && isBooleansObject(detail) ? detail : undefined;
+        case 'fields':
+            return detail.slice(0, MAX_DETAIL_CHARS);
+    }
+}
 export function createTelemetrySink(opts) {
     const bootAt = Date.now();
-    const buffer = [];
-    let flushes = 0;
+    const batches = {
+        health: { events: [], flushes: 0, maxFlushes: MAX_HEALTH_FLUSHES_PER_SESSION },
+        diagnostic: { events: [], flushes: 0, maxFlushes: MAX_DIAGNOSTIC_FLUSHES_PER_SESSION },
+    };
+    const order = ['health', 'diagnostic'];
     let timer = null;
     let disposed = false;
     let firstFlushDone = false;
-    const flush = () => {
-        timer = null;
-        if (disposed || buffer.length === 0)
-            return;
-        if (flushes >= MAX_FLUSHES_PER_SESSION)
+    const canFlush = (b) => batches[b].events.length > 0 && batches[b].flushes < batches[b].maxFlushes;
+    const send = (b) => {
+        if (!canFlush(b))
             return;
-        flushes += 1;
-        firstFlushDone = true;
-        const events = buffer.splice(0, buffer.length);
+        const batch = batches[b];
+        batch.flushes += 1;
+        const events = batch.events.splice(0, batch.events.length);
         void opts
             .callTool({
             name: 'ggui_runtime_telemetry',
@@ -29,39 +63,44 @@ export function createTelemetrySink(opts) {
             // cause the failures it exists to report.
         });
     };
+    const flush = () => {
+        timer = null;
+        if (disposed)
+            return;
+        firstFlushDone = true;
+        for (const b of order)
+            send(b);
+    };
     const scheduleFlush = () => {
         if (disposed || timer !== null)
             return;
-        if (flushes >= MAX_FLUSHES_PER_SESSION)
+        if (!order.some(canFlush))
             return;
         timer = setTimeout(flush, firstFlushDone ? FLUSH_THROTTLE_MS : FIRST_FLUSH_DELAY_MS);
     };
-    const record = (kind, detail) => {
+    const append = (kind, detail) => {
         if (disposed)
             return;
-        if (buffer.length >= RUNTIME_TELEMETRY_MAX_EVENTS)
-            buffer.shift();
-        buffer.push({
+        const spec = SPEC_BY_KIND.get(kind);
+        // An unlisted kind (a caller past the types) travels as diagnostic, and without its detail.
+        const batch = batches[spec?.batch ?? 'diagnostic'];
+        if (batch.events.length >= RUNTIME_TELEMETRY_MAX_EVENTS)
+            batch.events.shift();
+        const kept = admittedDetail(spec, detail);
+        batch.events.push({
             at: Math.max(0, Date.now() - bootAt),
             kind: kind.slice(0, 64),
-            ...(detail !== undefined ? { detail: detail.slice(0, MAX_DETAIL_CHARS) } : {}),
+            ...(kept !== undefined ? { detail: kept } : {}),
         });
         scheduleFlush();
     };
-    const fieldsToDetail = (fields) => {
-        try {
-            return JSON.stringify(fields).slice(0, MAX_DETAIL_CHARS);
-        }
-        catch {
-            return '[unserializable]';
-        }
-    };
+    const onChannelEvent = (event) => append(event, undefined);
     return {
-        record,
+        record: (kind, detail) => append(kind, detail),
         channelLogger: {
-            info: (event, fields) => record(event, fieldsToDetail(fields)),
-            warn: (event, fields) => record(event, fieldsToDetail(fields)),
-            debug: (event, fields) => record(event, fieldsToDetail(fields)),
+            info: onChannelEvent,
+            warn: onChannelEvent,
+            debug: onChannelEvent,
         },
         dispose() {
             disposed = true;