@ggui-ai/iframe-runtime 0.24.0 → 0.26.0

package/dist/index.d.ts

@@ -32,12 +32,12 @@
  * Those are the renderer's INTERNAL runtime contract and should not
  * become a load-bearing public API.
  */
-export type { McpAppAiGguiMetaParseFailureReason, McpAppAiGguiMetaParseResult, } from './types.js';
+export type { HeldCredential, McpAppAiGguiMetaParseFailureReason, McpAppAiGguiMetaParseResult, ViewRoot, } from './types.js';
 export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 export type { RendererBootFailureReason, RendererBootFailedMessage, } from './runtime.js';
 export type { ProtocolError, ProtocolErrorEmitter, BootstrapFailureReason, } from './protocol-error.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, FontFaceBlockedEvent, AppThemeInvalidEvent, AppThemeMemberStrippedEvent, ActionSpecInvalidEvent, ActionSpecMemberStrippedEvent, SpentOneShotsInvalidEvent, ThemeReinjectFailedEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, ComponentEmptyEvent, OneShotUnenforceableEvent, UnknownObservabilityEvent, } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, FontFaceBlockedEvent, AppThemeInvalidEvent, AppThemeMemberStrippedEvent, ActionSpecInvalidEvent, ActionSpecMemberStrippedEvent, SpentOneShotsInvalidEvent, ThemeReinjectFailedEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, ComponentEmptyEvent, OneShotUnenforceableEvent, ActionRefusedEvent, UnknownObservabilityEvent, } from './observability.js';
 export { isObservabilityMessage, isRelayDeadTapEvent, isRelayIncapabilityEvent, postObservabilityToParent, } from './observability.js';
 export type { LifecycleEmitter } from './lifecycle.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/ladders.d.ts

@@ -0,0 +1,77 @@
+import type { ChannelHandler, ChannelLogger, WsTransportHandle } from '@ggui-ai/live-channel';
+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 { CredentialController, ExpirySource, RefreshOutcome } from './credential-controller.js';
+import { type BuildBridgePollingOptions, type SequenceCursor } from './events-polling.js';
+import { type ConnectFn, type RegistrySubscribeHandle, type PostAckErrorPayload } from './registry-subscribe.js';
+import type { StreamSeqTracker } from './stream-seq.js';
+import type { HeldCredential } from './types.js';
+import type { ObservabilityEmitter } from './observability.js';
+import type { ProtocolErrorEmitter } from './protocol-error.js';
+/** What one ladder is bound with. */
+export interface LadderSpec {
+    /** The credential its token-bearing rungs carry; `undefined` on a trio-less bind. */
+    readonly credential: HeldCredential | undefined;
+    readonly sseUrl: string | undefined;
+    readonly pollingUrl: string | undefined;
+}
+/** Why the live channel ended (R4): the confirmation that fired. */
+export type LiveChannelEnd = {
+    readonly confirmation: 'relay-refusal';
+    readonly code: number;
+} | {
+    readonly confirmation: 'session-not-found';
+    readonly after: 'a-successful-pull' | 'a-second-not-found';
+};
+export interface LadderSetOptions {
+    /** The boot meta: identity (`sessionId`, `appId`) and the slice fields `connectFn` passes through. */
+    readonly meta: McpAppAiGguiRenderMeta;
+    /** The handlers every ladder delivers through, shared by all of them. */
+    readonly handlers: readonly ChannelHandler[];
+    /** The shared ledger cursor; `undefined` when the view has no fallback rung. */
+    readonly cursor: SequenceCursor | undefined;
+    /** The view's stream cursor, read into a rebuilt ladder's `fromSeq`. */
+    readonly streamSeq: StreamSeqTracker | undefined;
+    readonly controller: CredentialController | null;
+    readonly connectFn: ConnectFn;
+    /** The host relay the bridge rung pulls through; `undefined` → no bridge rung. */
+    readonly bridgeCallTool: BuildBridgePollingOptions['callTool'] | undefined;
+    /** Status of the ACTIVE ladder. */
+    readonly onStatus: (status: ConnectionStatus) => void;
+    /** Every ack after the boot's first one, from the ladder holding data (a re-snapshot to apply). */
+    readonly onAck: (ack: AckPayload) => void;
+    /** Every post-ack `error` frame, as sent (ggui#1424): the runtime reads a spent-one-shot refusal there. */
+    readonly onPostAckError?: (payload: PostAckErrorPayload) => void;
+    /** Each refresh a ladder asked for, and what it got. */
+    readonly onRefresh?: (source: ExpirySource, outcome: RefreshOutcome) => void;
+    /** An ack showed the server's stream counter restarted (a new epoch, or a count below the view's cursor), and the cursor was forgotten. */
+    readonly onStreamRestart?: (streamSeq: number | undefined, streamEpoch: string | undefined) => void;
+    /** The runtime's registry of relay refusal codes that confirm the host cannot relay `tools/call`. */
+    readonly isConfirmedRelayRefusalCode: (code: number) => boolean;
+    /** The live channel ended (R4); every ladder is already disposed. */
+    readonly onEnded: (end: LiveChannelEnd) => void;
+    readonly logger?: ChannelLogger;
+    readonly onProtocolError?: ProtocolErrorEmitter;
+    readonly onObserve?: ObservabilityEmitter;
+    /** Test seams, passed to every ladder's registry. */
+    readonly webSocketFactory?: (url: string) => WebSocket;
+    readonly eventSourceFactory?: (url: string) => EventSource;
+    readonly fetchImpl?: typeof fetch;
+    /** Test seam for the bridge-entry expiry check. */
+    readonly now?: () => number;
+}
+export interface LadderSet {
+    /** Bind the boot ladder. The caller handles its first ack, or its refusal. */
+    connectBoot(spec: LadderSpec): Promise<RegistrySubscribeHandle>;
+    /**
+     * The boot ladder's first refresh, when it reported an expiry; `undefined`
+     * when it reported none. A WS frame is classified in the same task that
+     * dispatches it, so a `BOOTSTRAP_EXPIRED` refusal has already asked for its
+     * refresh by the time `connectBoot` resolves with it.
+     */
+    bootRefresh(): Promise<RefreshOutcome> | undefined;
+    /** Send on the active ladder's WS, when it has one. */
+    send(msg: Parameters<WsTransportHandle['send']>[0]): void;
+}
+export declare function createLadderSet(opts: LadderSetOptions): LadderSet;

package/dist/ladders.js

@@ -0,0 +1,383 @@
+/**
+ * The view's live channel across credentials (ggui#1496 part B, R3).
+ *
+ * A LADDER is one registry bound with one credential: WS → SSE → HTTP
+ * polling → bridge. The boot binds the first; when the view adopts a
+ * refreshed credential, a new ladder is built beside the old one, and this
+ * module owns the hand-over:
+ *
+ * - **Data.** The new ladder becomes the data holder when it starts reading
+ *   from the resume point: its WS subscribe (which carries `fromSeq`, the
+ *   view's stream cursor), its SSE open, or its first polling or bridge
+ *   read of the shared ledger cursor. From then on the old ladder's
+ *   deliveries drop, and its writes to the ledger cursor are no-ops
+ *   (rev 2.1), so every ledger event after the resume point is applied
+ *   once, by whichever ladder carries it. A lagging old ladder can
+ *   therefore never overwrite the new ack's snapshot with older props.
+ *   Stream envelopes are also deduped on their `seq` by the `data` handler.
+ * - **Status and send** follow the ACTIVE ladder. It switches at the new
+ *   ladder's first token-rung acceptance (a WS or SSE ack, or a polling
+ *   `ok`), or when the new ladder reaches its bridge rung. The old ladder
+ *   is disposed at that switch, so only one bridge loop runs at a time.
+ * - **Expiry** is reported to the credential controller from three places:
+ *   a WS `BOOTSTRAP_EXPIRED` frame (the only auth code that triggers), the
+ *   first polling `410` whose body is not a replay horizon, and entering
+ *   the bridge rung while the ladder's credential is past `expiresAt`. An
+ *   adopted credential builds the next ladder.
+ *
+ * A new ladder omits WS when the one it replaces left WS without ever
+ * receiving a frame (the never-opened fail-fast): a jailed socket would
+ * only fail again.
+ *
+ * **An honest end (R4).** The bridge pulls are the one place the view can
+ * learn that its live channel cannot come back, and they are the only
+ * input (a refused refresh is quiet). A pull the host's relay refuses with
+ * a confirmed code, or a `session_not_found` that is confirmed — the first
+ * after an earlier successful pull, or the second in a row — ends the live
+ * channel: every ladder is disposed, which stops the bridge loop, and the
+ * caller is told which confirmation fired. Anything else keeps its backoff.
+ */
+import { ChannelRegistry } from '@ggui-ai/live-channel';
+import { buildBridgePolling, buildEventsPolling, } from './events-polling.js';
+import { classifyChannelFrame, } from './registry-subscribe.js';
+import { domainErrorCodeOf, isErrorToolResult } from './tool-result-error.js';
+const REPLAY_HORIZON_PASSED = 'REPLAY_HORIZON_PASSED';
+function errorCodeOf(frame) {
+    if (frame.type !== 'error')
+        return undefined;
+    const payload = frame.payload;
+    if (typeof payload !== 'object' || payload === null)
+        return undefined;
+    const code = Reflect.get(payload, 'code');
+    return typeof code === 'string' ? code : undefined;
+}
+/** Whether a 410 body is the ledger's replay-horizon answer (read from a clone, so the transport's own read is untouched). */
+async function isReplayHorizon(response) {
+    try {
+        const parsed = JSON.parse(await response.text());
+        return (typeof parsed === 'object' &&
+            parsed !== null &&
+            Reflect.get(parsed, 'reason') === REPLAY_HORIZON_PASSED);
+    }
+    catch {
+        // Not JSON: the expired-token answer is plain text.
+        return false;
+    }
+}
+export function createLadderSet(opts) {
+    const now = opts.now ?? Date.now;
+    const baseFetch = opts.fetchImpl ?? ((input, init) => globalThis.fetch(input, init));
+    let nextId = 0;
+    const built = new Map();
+    let ended = false;
+    /** R4: dispose every ladder (the bridge loop stops with its ladder) and say why. */
+    const end = (why) => {
+        if (ended)
+            return;
+        ended = true;
+        for (const ladder of ladders) {
+            ladder.disposed = true;
+            if (ladder.handle !== undefined)
+                void ladder.handle.dispose();
+        }
+        ladders = [];
+        opts.onEnded(why);
+    };
+    /** Read one bridge pull's answer for R4: a confirmed ending, or nothing (its backoff stands). */
+    const classifyPull = (ladder, answer) => {
+        if ('error' in answer) {
+            const error = answer.error;
+            const code = typeof error === 'object' && error !== null ? Reflect.get(error, 'code') : undefined;
+            if (typeof code === 'number' && opts.isConfirmedRelayRefusalCode(code))
+                end({ confirmation: 'relay-refusal', code });
+            return;
+        }
+        if (domainErrorCodeOf(answer.result) === 'session_not_found') {
+            ladder.notFoundStreak += 1;
+            if (ladder.pulled)
+                end({ confirmation: 'session-not-found', after: 'a-successful-pull' });
+            else if (ladder.notFoundStreak >= 2)
+                end({ confirmation: 'session-not-found', after: 'a-second-not-found' });
+            return;
+        }
+        if (!isErrorToolResult(answer.result)) {
+            ladder.pulled = true;
+            ladder.notFoundStreak = 0;
+        }
+    };
+    let ladders = [];
+    let active;
+    let holder;
+    let newest;
+    /** The newest ladder takes the data when it starts reading from the resume point. */
+    const claim = (ladder) => {
+        if (ladder.rebuilt && ladder === newest && holder !== ladder && !ladder.disposed)
+            holder = ladder;
+    };
+    /** Hand status, send and data to `ladder`, and dispose every other one. */
+    const switchTo = (state) => {
+        const ladder = built.get(state);
+        if (ladder === undefined || active === ladder || ladder.disposed)
+            return;
+        const others = ladders.filter((l) => l !== ladder);
+        ladders = [ladder];
+        active = ladder;
+        holder = ladder;
+        for (const old of others) {
+            old.disposed = true;
+            if (old.handle !== undefined)
+                void old.handle.dispose();
+        }
+        if (ladder.lastStatus !== undefined)
+            opts.onStatus(ladder.lastStatus);
+    };
+    const accept = (ladder) => {
+        if (ladder.disposed)
+            return;
+        if (ladder.spec.credential !== undefined)
+            opts.controller?.markAccepted(ladder.spec.credential);
+        switchTo(ladder);
+    };
+    /** An ack's `streamSeq` below the view's stream cursor means the server's counter restarted. */
+    const readStreamSeq = (ack) => {
+        if (opts.streamSeq?.observeAck(ack.streamSeq, ack.streamEpoch) === true) {
+            opts.onStreamRestart?.(ack.streamSeq, ack.streamEpoch);
+        }
+    };
+    const onAck = (ladder, ack) => {
+        accept(ladder);
+        if (holder !== ladder)
+            return;
+        // Before the replay that follows the ack is applied.
+        readStreamSeq(ack);
+        opts.onAck(ack);
+    };
+    const reportExpired = async (ladder, source) => {
+        const credential = ladder.spec.credential;
+        const controller = opts.controller;
+        if (controller === null || credential === undefined || ladder.disposed || ended)
+            return;
+        const pending = controller.onExpired(credential, source);
+        if (ladder.refresh === undefined)
+            ladder.refresh = pending;
+        const outcome = await pending;
+        opts.onRefresh?.(source, outcome);
+        if (outcome.kind === 'adopted')
+            rebind(ladder, outcome.credential, source);
+    };
+    const build = (spec, rebuilt, omitWs) => {
+        const hasWs = spec.credential !== undefined && !omitWs;
+        const ladder = {
+            id: nextId++,
+            spec,
+            rebuilt,
+            hasWs,
+            handle: undefined,
+            disposed: false,
+            wsFrameSeen: false,
+            bridgeEntered: false,
+            polling410Seen: false,
+            lastStatus: undefined,
+            refresh: undefined,
+            pulled: false,
+            notFoundStreak: 0,
+        };
+        const classifyFrame = (frame) => {
+            ladder.wsFrameSeen = true;
+            if (errorCodeOf(frame) === 'BOOTSTRAP_EXPIRED')
+                void reportExpired(ladder, 'ws');
+            return classifyChannelFrame(frame);
+        };
+        const fetchImpl = async (input, init) => {
+            const response = await baseFetch(input, init);
+            if (response.ok) {
+                accept(ladder);
+            }
+            else if (response.status === 410 && !ladder.polling410Seen) {
+                ladder.polling410Seen = true;
+                if (!(await isReplayHorizon(response.clone())))
+                    void reportExpired(ladder, 'polling');
+            }
+            return response;
+        };
+        const registry = new ChannelRegistry({
+            subscribeFrameBuilder: () => {
+                claim(ladder);
+                const wsToken = ladder.spec.credential?.wsToken;
+                const fromSeq = ladder.rebuilt ? opts.streamSeq?.last() : undefined;
+                // `fromEpoch` rides only beside `fromSeq` (ggui#1531): it names the generation that count is in.
+                const fromEpoch = fromSeq !== undefined ? opts.streamSeq?.epoch() : undefined;
+                return {
+                    type: 'subscribe',
+                    payload: {
+                        sessionId: opts.meta.sessionId,
+                        appId: opts.meta.appId,
+                        ...(wsToken !== undefined ? { wsToken } : {}),
+                        ...(fromSeq !== undefined ? { fromSeq } : {}),
+                        ...(fromEpoch !== undefined ? { fromEpoch } : {}),
+                    },
+                };
+            },
+            classifyFrame,
+            fetchImpl,
+            ...(opts.webSocketFactory !== undefined ? { webSocketFactory: opts.webSocketFactory } : {}),
+            ...(opts.eventSourceFactory !== undefined ? { eventSourceFactory: opts.eventSourceFactory } : {}),
+        });
+        for (const handler of opts.handlers) {
+            registry.register({
+                type: handler.type,
+                onMessage: (payload) => (holder === ladder ? handler.onMessage(payload) : undefined),
+            });
+        }
+        const complete = Object.assign(ladder, { registry });
+        built.set(ladder, complete);
+        ladders.push(complete);
+        newest = complete;
+        return complete;
+    };
+    /** The ledger cursor as `ladder` sees it: shared reads; writes only while it holds the data. */
+    const cursorView = (ladder, shared) => ({
+        get: () => {
+            claim(ladder);
+            return shared.get();
+        },
+        advance: (seq) => {
+            if (holder === ladder)
+                shared.advance(seq);
+        },
+        reset: (seq) => {
+            if (holder === ladder)
+                shared.reset(seq);
+        },
+    });
+    const connectOptions = (ladder) => {
+        const { spec } = ladder;
+        const shared = opts.cursor;
+        const view = shared !== undefined ? cursorView(ladder, shared) : undefined;
+        const credential = spec.credential;
+        const { wsUrl: _wsUrl, wsToken: _wsToken, expiresAt: _expiresAt, sseUrl: _sse, pollingUrl: _polling, ...identity } = opts.meta;
+        const meta = {
+            ...identity,
+            ...(ladder.hasWs && credential !== undefined
+                ? { wsUrl: credential.wsUrl, wsToken: credential.wsToken }
+                : {}),
+            ...(credential?.expiresAt !== undefined ? { expiresAt: credential.expiresAt } : {}),
+        };
+        const sse = spec.sseUrl !== undefined && view !== undefined
+            ? {
+                url: spec.sseUrl,
+                initialSinceSequence: () => view.get(),
+                ...(ladder.rebuilt && opts.streamSeq !== undefined
+                    ? { fromSeq: opts.streamSeq.last, fromEpoch: opts.streamSeq.epoch }
+                    : {}),
+                onSequence: (seq) => view.advance(seq),
+            }
+            : undefined;
+        const polling = spec.pollingUrl !== undefined && view !== undefined
+            ? buildEventsPolling({ baseUrl: spec.pollingUrl, cursor: view })
+            : undefined;
+        const callTool = opts.bridgeCallTool;
+        const bridge = callTool !== undefined && view !== undefined
+            ? buildBridgePolling({
+                callTool: async (name, args) => {
+                    enterBridge(ladder);
+                    let result;
+                    try {
+                        result = await callTool(name, args);
+                    }
+                    catch (error) {
+                        classifyPull(ladder, { error });
+                        throw error;
+                    }
+                    classifyPull(ladder, { result });
+                    return result;
+                },
+                sessionId: opts.meta.sessionId,
+                cursor: view,
+            })
+            : undefined;
+        return {
+            meta,
+            registry: ladder.registry,
+            ...(opts.logger !== undefined ? { logger: opts.logger } : {}),
+            ...(opts.onProtocolError !== undefined ? { onProtocolError: opts.onProtocolError } : {}),
+            ...(opts.onObserve !== undefined ? { onObserve: opts.onObserve } : {}),
+            onStatusChange: (status) => {
+                ladder.lastStatus = status;
+                if (ladder === active)
+                    opts.onStatus(status);
+            },
+            onResubscribeAck: (ack) => onAck(ladder, ack),
+            ...(opts.onPostAckError !== undefined ? { onPostAckError: opts.onPostAckError } : {}),
+            onBound: (handle) => {
+                ladder.handle = handle;
+                if (ladder.disposed)
+                    void handle.dispose();
+            },
+            ...(sse !== undefined ? { sse } : {}),
+            ...(polling !== undefined ? { polling } : {}),
+            ...(bridge !== undefined ? { bridge } : {}),
+        };
+    };
+    /** The ladder's first bridge pull: it has left its token rungs (R3 (b), fact 8). */
+    const enterBridge = (ladder) => {
+        if (ladder.bridgeEntered)
+            return;
+        ladder.bridgeEntered = true;
+        switchTo(ladder);
+        const expiresAt = ladder.spec.credential?.expiresAt;
+        if (expiresAt !== undefined && Date.parse(expiresAt) <= now())
+            void reportExpired(ladder, 'bridge');
+    };
+    // The handle arrives through `onBound` as soon as the ladder is bound;
+    // the settled result carries the same one, for a `connectFn` that
+    // reports none earlier.
+    const bind = async (ladder) => {
+        const result = await opts.connectFn(connectOptions(ladder));
+        if (ladder.handle === undefined) {
+            ladder.handle = result.handle;
+            if (ladder.disposed)
+                void result.handle.dispose();
+        }
+        return result;
+    };
+    const rebind = (from, credential, source) => {
+        if (ended)
+            return;
+        // A jailed socket that never delivered a frame would only fail again.
+        const omitWs = source !== 'ws' && from.hasWs && !from.wsFrameSeen;
+        const ladder = build({ credential, sseUrl: credential.sseUrl, pollingUrl: credential.pollingUrl }, true, omitWs);
+        void bind(ladder).then((result) => {
+            if (result.ack !== undefined)
+                onAck(ladder, result.ack);
+            // A refusal before acceptance: the ladder demotes on its own and
+            // takes over when it reaches its bridge rung. Its credential is
+            // never refreshed again unaccepted (the loop guard).
+        }, () => {
+            // UPGRADE_REQUIRED or a bind failure: nothing takes over, and the
+            // old ladder keeps the view.
+        });
+    };
+    let bootLadder;
+    return {
+        async connectBoot(spec) {
+            const ladder = build(spec, false, false);
+            bootLadder = ladder;
+            active = ladder;
+            holder = ladder;
+            const result = await bind(ladder);
+            if (result.ack !== undefined) {
+                readStreamSeq(result.ack);
+                if (spec.credential !== undefined)
+                    opts.controller?.markAccepted(spec.credential);
+            }
+            return result;
+        },
+        bootRefresh: () => bootLadder?.refresh,
+        send(msg) {
+            const handle = active?.handle;
+            if (handle !== undefined && handle.kind === 'ws')
+                handle.send(msg);
+        },
+    };
+}

package/dist/meta-parse.js

@@ -53,6 +53,7 @@
 import { PUBLIC_ENV_APP_KEY_RE } from '@ggui-ai/protocol/wire';
 import { parseMcpAppAiGguiRenderMeta, } from '@ggui-ai/protocol/integrations/mcp-apps';
 import { postObservabilityToParent } from './observability.js';
+import { viewRootOf } from './view-root.js';
 /**
  * Type guard — true iff `value` is a non-null, non-array plain object.
  */
@@ -189,16 +190,26 @@ function projectPublicEnv(raw) {
 function projectMeta(meta, hasStaticContent) {
     let expiresAt = meta.expiresAt;
     let dropLiveCreds = false;
+    let held;
     if (expiresAt !== undefined) {
         const ts = Date.parse(expiresAt);
         if (Number.isNaN(ts)) {
             return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
         }
         if (ts <= Date.now()) {
-            // Expired — only hard-fail when no static content is present.
-            // With static content, mount the UI without live mode.
-            if (!hasStaticContent) {
-                return { ok: false, reason: 'EXPIRED_BOOTSTRAP' };
+            // Expired: the live trio leaves the meta, so nothing subscribes with
+            // a dead token, and comes back as `held`, so the view can refresh it
+            // through its host (ggui#1496). Without static content the slice is
+            // still EXPIRED_BOOTSTRAP, now carrying what a refresh needs.
+            if (isNonEmptyString(meta.wsUrl) && isNonEmptyString(meta.wsToken)) {
+                held = {
+                    wsToken: meta.wsToken,
+                    wsUrl: meta.wsUrl,
+                    expiresAt,
+                    ...(meta.sseUrl !== undefined ? { sseUrl: meta.sseUrl } : {}),
+                    ...(meta.pollingUrl !== undefined ? { pollingUrl: meta.pollingUrl } : {}),
+                    origin: 'root',
+                };
             }
             dropLiveCreds = true;
             expiresAt = undefined;
@@ -290,7 +301,14 @@ function projectMeta(meta, hasStaticContent) {
         ...(meta.codeB64 !== undefined ? { codeB64: meta.codeB64 } : {}),
         ...(meta.kind !== undefined ? { kind: meta.kind } : {}),
     };
-    return { ok: true, meta: projected };
+    if (dropLiveCreds && !hasStaticContent) {
+        // Live-only and expired. `held` is always set here: validateMeta admits a
+        // live-only slice only with a live trio.
+        if (held === undefined)
+            return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
+        return { ok: false, reason: 'EXPIRED_BOOTSTRAP', meta: projected, held };
+    }
+    return { ok: true, meta: projected, ...(held !== undefined ? { held } : {}) };
 }
 /**
  * Validate an {@link McpAppAiGguiRenderMeta} slice. Enforces mode
@@ -326,10 +344,22 @@ export function validateMeta(meta) {
     if (!hasLive && !hasStaticContent) {
         return { ok: false, reason: 'MALFORMED_BOOTSTRAP' };
     }
+    // The view key root (ggui#1415) is read from the slice as delivered,
+    // before the projection drops an expired live pair: a view proves with the
+    // root the server issued whether or not the credential beside it is still
+    // live. It rides beside the meta, never inside it.
+    const viewRoot = viewRootOf(meta);
+    const withRoot = viewRoot !== undefined ? { viewRoot } : {};
     const result = projectMeta(meta, hasStaticContent);
-    if (!result.ok)
-        return result;
-    return { ok: true, meta: result.meta };
+    if (!result.ok) {
+        return result.reason === 'EXPIRED_BOOTSTRAP' ? { ...result, ...withRoot } : result;
+    }
+    return {
+        ok: true,
+        meta: result.meta,
+        ...(result.held !== undefined ? { held: result.held } : {}),
+        ...withRoot,
+    };
 }
 /**
  * The wire parser refused the slice's `theme` (ggui#987 §3.4): report it

package/dist/observability.d.ts

@@ -33,7 +33,7 @@ import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
  *
  * @public
  */
-export type ObservabilityEvent = SchemaVersionMismatchEvent | FontFaceBlockedEvent | AppThemeInvalidEvent | AppThemeMemberStrippedEvent | ActionSpecInvalidEvent | ActionSpecMemberStrippedEvent | OneShotUnenforceableEvent | SpentOneShotsInvalidEvent | ThemeReinjectFailedEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | ComponentEmptyEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | FontFaceBlockedEvent | AppThemeInvalidEvent | AppThemeMemberStrippedEvent | ActionSpecInvalidEvent | ActionSpecMemberStrippedEvent | OneShotUnenforceableEvent | ActionRefusedEvent | SpentOneShotsInvalidEvent | ThemeReinjectFailedEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | ComponentEmptyEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -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.
@@ -402,6 +408,27 @@ export interface OneShotUnenforceableEvent {
     readonly renderId: string;
     readonly actionName: string;
 }
+/**
+ * A dispatch the card's own action spec refused (ggui#1536): the outbound
+ * contract check found the envelope outside the contract, so nothing was
+ * sent and the visitor's tap did nothing. `violations` name each failure by
+ * its field path and, when a schema keyword produced it, that keyword, never
+ * by value: the data is the visitor's input. Posted per refused dispatch, at
+ * most ten per render; the tenth carries `capped: true` and later ones are
+ * not posted.
+ *
+ * @public
+ */
+export interface ActionRefusedEvent {
+    readonly kind: 'action-refused';
+    readonly renderId: string;
+    readonly actionName: string;
+    readonly violations: ReadonlyArray<{
+        readonly field: string;
+        readonly keyword?: string;
+    }>;
+    readonly capped?: true;
+}
 /**
  * The render slice carried a `spentOneShots` the wire schema refused
  * (ggui#1223): the parser dropped it, and the card mounted with only its