@ggui-ai/iframe-runtime 0.13.0 → 0.15.0

package/dist/index.d.ts

@@ -37,7 +37,7 @@ export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './m
 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, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayIncapabilityEvent, UnknownObservabilityEvent, } from './observability.js';
-export { postObservabilityToParent } from './observability.js';
+export type { ObservabilityEvent, ObservabilityEmitter, ObservabilityMessage, SchemaVersionMismatchEvent, SubscribeFailedEvent, ChannelTransportPickedEvent, ChannelTransportFallbackEvent, ChannelTransportResubscribedEvent, ChannelPollDegradedEvent, ChannelPollRecoveredEvent, UiFeedbackEvent, RelayDeadTapEvent, RelayIncapabilityEvent, RelayLatchTrigger, 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/index.js

@@ -1,4 +1,4 @@
 export { parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 export { defaultProtocolErrorEmitter, fromBootstrapFailure, fromClientContractViolation, fromTransportFailure, fromAuthFailure, fromUpgradeRequired, fromUnknown, } from './protocol-error.js';
-export { postObservabilityToParent } from './observability.js';
+export { isObservabilityMessage, isRelayDeadTapEvent, isRelayIncapabilityEvent, postObservabilityToParent, } from './observability.js';
 export { postLifecycleToParent, makeLifecycleEvent } from './lifecycle.js';

package/dist/meta-parse.js

@@ -50,7 +50,7 @@
  * At least one mode MUST be present. Half-live (wsUrl without wsToken)
  * is structurally rejected by the combiner.
  */
-import { PUBLIC_ENV_APP_KEY_RE } from '@ggui-ai/protocol';
+import { PUBLIC_ENV_APP_KEY_RE } from '@ggui-ai/protocol/wire';
 import { parseMcpAppAiGguiRenderMeta } from '@ggui-ai/protocol/integrations/mcp-apps';
 /**
  * Type guard — true iff `value` is a non-null, non-array plain object.

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 | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | UnknownObservabilityEvent;
+export type ObservabilityEvent = SchemaVersionMismatchEvent | SubscribeFailedEvent | ChannelTransportPickedEvent | ChannelTransportFallbackEvent | ChannelTransportResubscribedEvent | ChannelPollDegradedEvent | ChannelPollRecoveredEvent | UiFeedbackEvent | RelayIncapabilityEvent | RelayDeadTapEvent | UnknownObservabilityEvent;
 /**
  * Fired when the protocol-version handshake rejects the connection.
  * Parallel to `UpgradeRequiredError` — the host can choose to render
@@ -178,36 +178,122 @@ export interface UiFeedbackEvent {
     /** Tool that produced the render (e.g. `ggui_render`). */
     readonly toolName?: string;
 }
+/**
+ * The evidence that latched a relay dead zone:
+ *   - `'confirmed-refusal'` — the relay answered a declared refusal code
+ *     (helper-minted; outranks any positive advertisement) (ggui#599
+ *     cycle-2);
+ *   - `'advert-silent'` — the host never advertised `serverTools` and
+ *     the attempt failed relay-shaped;
+ *   - `'boot-failed'` — the mandatory `ui/initialize` handshake did not
+ *     complete (refused, timed out, or the transport failed), so
+ *     nothing can ever be delivered in this document (ggui#830). Not a
+ *     probe the runtime minted: the outcome of the one request every
+ *     session begins with — the strongest confirmed outcome there is.
+ *     It clears the only way a handshake failure can: the next boot's
+ *     close edge.
+ *
+ * The union is closed per renderer version; nothing in a host branches
+ * on the trigger (the first-party host passes it through untouched) —
+ * the edge is the fact, the trigger is why. A host that does branch on
+ * it should treat a value it does not know as "latched, reason
+ * unknown", never as "not latched".
+ *
+ * @public
+ */
+export type RelayLatchTrigger = 'confirmed-refusal' | 'advert-silent' | 'boot-failed';
 /**
  * Fired at the two transition edges of the renderer's
  * relay-incapability latch — the runtime's confirmed determination
  * that the host cannot relay `tools/call` to the MCP server:
  *
- *   - `'latched'` — a real user gesture just failed relay-shaped (no
- *     well-formed result envelope came back at all) on a host whose
- *     captured capability handshake never advertised `serverTools`.
+ *   - `'latched'` — a real user gesture just failed relay-shaped on a
+ *     host whose captured capability handshake never advertised
+ *     `serverTools`, or the relay answered a declared refusal code, or
+ *     the host refused `ui/initialize` itself (`'boot-failed'`,
+ *     ggui#830 — no gesture is needed to know nothing can be delivered).
  *     The runtime now treats relay as confirmed-unavailable: it shows
- *     one persistent explanation instead of a per-gesture error toast,
- *     and channel polls fail fast without a transport round-trip.
+ *     one persistent explanation, arms the dead-zone cue for every
+ *     later gesture, and channel polls fail fast without a transport
+ *     round-trip.
  *   - `'cleared'` — a later well-formed result envelope arrived
  *     (`ok:true` and `ok:false` alike — either proves the host relayed
- *     the call there and back), so the determination no longer holds;
- *     per-gesture feedback and channel transport attempts resume.
+ *     the call there and back), so the determination no longer holds.
+ *     Carries the dead zone's summary: how long it stood and how many
+ *     gestures were attempted inside it.
  *
- * Emitted once per edge, never per channel poll tick: repeated failing
- * gestures while latched emit nothing further, and the router's
- * fail-fast ticks emit nothing at all — the edges carry the full
- * information.
+ * Emitted once per edge, never per channel poll tick. Gestures
+ * attempted while latched are NOT silent on this stream: each one is a
+ * {@link RelayDeadTapEvent} (ggui#670 Phase 3) — one per real user
+ * gesture, never per tick — so a host can count dead taps and measure
+ * dead-tap-to-recovery without watching the render. A boot that finds
+ * a latch standing from a prior mount closes it with a `'cleared'`
+ * edge before the new session starts.
  *
- * Always emitted via the postMessage-to-parent default — the emission
- * sites live in module-level gesture-dispatch code outside the boot
- * graph, so they never flow through an injected `onObserve` sink.
+ * Always emitted via the postMessage-to-parent default, by rule — the
+ * gesture-dispatch emission sites run outside any given boot call, and
+ * the boot-graph site (the `boot-failed` edge, ggui#830) follows the
+ * same rule — so these edges never flow through an injected
+ * `onObserve` sink and a host reads every edge the same way.
  *
  * @public
  */
-export interface RelayIncapabilityEvent {
+export type RelayIncapabilityEvent = {
+    readonly kind: 'relay-incapability';
+    readonly state: 'latched';
+    readonly trigger: RelayLatchTrigger;
+    /** GguiSession id of the render, when the latching gesture carried one. */
+    readonly sessionId?: string;
+    /** App id of the render, when the latching gesture carried one. */
+    readonly appId?: string;
+} | {
     readonly kind: 'relay-incapability';
-    readonly state: 'latched' | 'cleared';
+    readonly state: 'cleared';
+    /** How long the dead zone stood, in milliseconds. */
+    readonly latchedForMs: number;
+    /**
+     * Gestures attempted inside the zone — equals the last
+     * {@link RelayDeadTapEvent} `ordinal` this edge closes (0 when
+     * none was attempted).
+     */
+    readonly deadTaps: number;
+    readonly sessionId?: string;
+    readonly appId?: string;
+};
+/**
+ * A user gesture attempted while the relay-incapability latch stands
+ * (ggui#670 Phase 3). The runtime never suppresses the attempt — the
+ * attempt is the self-heal sensor (ggui#443) — and presents it in the
+ * document (pulse, spoken cue, fallback toast); this event makes the
+ * attempt COUNTABLE by the host.
+ *
+ * Contract: exactly one per gesture whose UNDELIVERED outcome
+ * (relay-shaped failure or a declared refusal) lands while the latch
+ * stands — an in-flight gesture that raced the latching one counts;
+ * never emitted off-latch, and never from the channel
+ * router's fail-fast ticks. Counted at the outcome, not the tap: the
+ * gesture that latched the zone is the `'latched'` edge and the gesture
+ * that heals it is the `'cleared'` edge — neither is a dead tap.
+ * `ordinal` counts from 1 within one dead zone; the `'cleared'` edge
+ * reports the total as `deadTaps`. `latchAgeMs` is measured when the
+ * outcome lands. Hosts MUST tolerate the event being absent (an older
+ * renderer) — absence means no attempt was observed, not that none
+ * happened.
+ *
+ * @public
+ */
+export interface RelayDeadTapEvent {
+    readonly kind: 'relay-dead-tap';
+    /** The gesture's intent — the action name the component dispatched. */
+    readonly intent: string;
+    /** Milliseconds since the latch set. */
+    readonly latchAgeMs: number;
+    /** 1-based position of this attempt within the current dead zone. */
+    readonly ordinal: number;
+    /** The evidence that latched the zone this attempt landed in. */
+    readonly trigger: RelayLatchTrigger;
+    readonly sessionId?: string;
+    readonly appId?: string;
 }
 /**
  * Catch-all branch for event kinds the host's typings don't recognize.
@@ -245,6 +331,52 @@ export interface ObservabilityMessage {
  * @public
  */
 export type ObservabilityEmitter = (event: ObservabilityEvent) => void;
+/**
+ * Type guard for the `ggui:observe` envelope as it arrives on a host's
+ * `message` listener — narrows `event.data` to {@link ObservabilityMessage}.
+ * Read fields through the per-kind guards, never through
+ * `switch (event.kind)`: the union's open tail (`kind: string & {}`)
+ * keeps TypeScript from using `kind` as a discriminant, so a `case`
+ * body sees the whole union. Unknown kinds stay in that tail: hosts
+ * MUST ignore them, never throw.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   isObservabilityMessage,
+ *   isRelayDeadTapEvent,
+ *   isRelayIncapabilityEvent,
+ * } from '@ggui-ai/iframe-runtime/observability';
+ *
+ * window.addEventListener('message', ({ data, source }) => {
+ *   if (source !== iframe.contentWindow || !isObservabilityMessage(data)) return;
+ *   const { event } = data;
+ *   if (isRelayDeadTapEvent(event)) count(event.intent, event.latchAgeMs);
+ *   else if (isRelayIncapabilityEvent(event) && event.state === 'cleared') recovered(event.deadTaps);
+ *   // any other kind: ignore
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function isObservabilityMessage(value: unknown): value is ObservabilityMessage;
+/**
+ * Narrows to {@link RelayDeadTapEvent}. The union's open tail
+ * (`kind: string & {}`) keeps TypeScript from using `kind` as a
+ * discriminant, so `switch (event.kind)` never narrows across
+ * {@link ObservabilityEvent} — hosts read fields through the per-kind
+ * guards (first-consumer finding, ggui#670 Phase 3).
+ *
+ * @public
+ */
+export declare function isRelayDeadTapEvent(event: ObservabilityEvent): event is RelayDeadTapEvent;
+/**
+ * Narrows to {@link RelayIncapabilityEvent}; inside it `state`
+ * discriminates the `'latched'` / `'cleared'` edges normally.
+ *
+ * @public
+ */
+export declare function isRelayIncapabilityEvent(event: ObservabilityEvent): event is RelayIncapabilityEvent;
 /**
  * Default emitter — posts an {@link ObservabilityMessage} to
  * `window.parent`. Mirrors `postBootFailure` / `postRendererReady`

package/dist/observability.js

@@ -1,4 +1,63 @@
 import { MCP_APP_OBSERVE_TYPE } from '@ggui-ai/protocol/integrations/mcp-apps';
+/**
+ * Type guard for the `ggui:observe` envelope as it arrives on a host's
+ * `message` listener — narrows `event.data` to {@link ObservabilityMessage}.
+ * Read fields through the per-kind guards, never through
+ * `switch (event.kind)`: the union's open tail (`kind: string & {}`)
+ * keeps TypeScript from using `kind` as a discriminant, so a `case`
+ * body sees the whole union. Unknown kinds stay in that tail: hosts
+ * MUST ignore them, never throw.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   isObservabilityMessage,
+ *   isRelayDeadTapEvent,
+ *   isRelayIncapabilityEvent,
+ * } from '@ggui-ai/iframe-runtime/observability';
+ *
+ * window.addEventListener('message', ({ data, source }) => {
+ *   if (source !== iframe.contentWindow || !isObservabilityMessage(data)) return;
+ *   const { event } = data;
+ *   if (isRelayDeadTapEvent(event)) count(event.intent, event.latchAgeMs);
+ *   else if (isRelayIncapabilityEvent(event) && event.state === 'cleared') recovered(event.deadTaps);
+ *   // any other kind: ignore
+ * });
+ * ```
+ *
+ * @public
+ */
+export function isObservabilityMessage(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const probe = value;
+    if (probe.type !== MCP_APP_OBSERVE_TYPE)
+        return false;
+    if (typeof probe.event !== 'object' || probe.event === null)
+        return false;
+    return typeof probe.event.kind === 'string';
+}
+/**
+ * Narrows to {@link RelayDeadTapEvent}. The union's open tail
+ * (`kind: string & {}`) keeps TypeScript from using `kind` as a
+ * discriminant, so `switch (event.kind)` never narrows across
+ * {@link ObservabilityEvent} — hosts read fields through the per-kind
+ * guards (first-consumer finding, ggui#670 Phase 3).
+ *
+ * @public
+ */
+export function isRelayDeadTapEvent(event) {
+    return event.kind === 'relay-dead-tap';
+}
+/**
+ * Narrows to {@link RelayIncapabilityEvent}; inside it `state`
+ * discriminates the `'latched'` / `'cleared'` edges normally.
+ *
+ * @public
+ */
+export function isRelayIncapabilityEvent(event) {
+    return event.kind === 'relay-incapability';
+}
 /**
  * Default emitter — posts an {@link ObservabilityMessage} to
  * `window.parent`. Mirrors `postBootFailure` / `postRendererReady`

package/dist/provisional-renderer.d.ts

@@ -31,7 +31,7 @@
  *     while suspended, matching host-SDK behavior.
  */
 import React, { type ReactNode } from 'react';
-import type { StreamEnvelope } from '@ggui-ai/protocol';
+import type { StreamEnvelope } from '@ggui-ai/protocol/wire';
 export interface ProvisionalMount {
     /**
      * Feed a stream envelope. Ignores non-PREVIEW_CHANNEL envelopes

package/dist/react-renderer.d.ts

@@ -30,6 +30,7 @@
  * TypeScript config doesn't need a JSX runtime plumbing.
  */
 import React, { type ReactNode } from 'react';
+import type { AppTheme } from '@ggui-ai/protocol/wire';
 export interface ReactRootMountOptions {
     /**
      * GguiSession whose componentCode + props drive the mount. Only
@@ -98,11 +99,7 @@ export interface ReactRootMountOptions {
          * painted ladder to its registration record); the renderer
          * carries it but exposes no observability surface for it today.
          */
-        readonly base?: {
-            readonly documentHash: string;
-            readonly light: Readonly<Record<string, string>>;
-            readonly dark: Readonly<Record<string, string>>;
-        };
+        readonly base?: NonNullable<AppTheme['base']>;
     };
     /**
      * Host-announced palette, already translated onto `--ggui-*` tokens

package/dist/react-renderer.js

@@ -329,7 +329,15 @@ export async function mountReactRoot(container, opts) {
                 // ladder gets — base inherits, derived gradient/effect tokens
                 // (color-mix fallback split), box-sizing, font-inherit — from
                 // ONE shared builder, so the two paths cannot drift.
-                assembleDeliveredThemeCss(scopeClass, opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)
+                assembleDeliveredThemeCss(scopeClass, opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light, {
+                    // ggui#613 residual 2 — the two former v1 deltas ride:
+                    // the active mode's keyframes block + the frameless
+                    // silhouette suppression, both same-rule as compiled.
+                    keyframes: opts.themeMode === 'dark'
+                        ? deliveredBase.keyframes?.dark
+                        : deliveredBase.keyframes?.light,
+                    frameless: deliveredBase.frameless,
+                })
             : opts.themeId
                 ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
                 : getScopedCssTokens(scopeClass, opts.themeMode);
@@ -367,9 +375,17 @@ export async function mountReactRoot(container, opts) {
         // `ThemeProvider` so a Studio/Portal context with both runtime + RP
         // active doesn't double-stack.
         if (typeof document !== 'undefined') {
-            let rootCss = opts.themeId
-                ? getThemeCss(opts.themeId, opts.themeMode)
-                : getCssTokens(opts.themeMode);
+            // ggui#613 residual 5: under a DELIVERED base the body-chrome
+            // ladder is the delivered set too — mirroring the scoped ternary
+            // above — so the standalone viewer's body chrome and its tree
+            // content resolve the same values. Pre-fix this started from the
+            // compiled/default ladder regardless, and body chrome painted the
+            // default brand under a registered theme.
+            let rootCss = deliveredBase !== undefined
+                ? `:root{${toCssDecls(opts.themeMode === 'dark' ? deliveredBase.dark : deliveredBase.light)}}`
+                : opts.themeId
+                    ? getThemeCss(opts.themeId, opts.themeMode)
+                    : getCssTokens(opts.themeMode);
             if (opts.hostPalette) {
                 // BODY-CHROME ONLY, same as the appTheme `:root` append below —
                 // and beneath it, mirroring the scoped-block order (#573:

package/dist/registry-subscribe.d.ts

@@ -1,4 +1,4 @@
-import type { AckPayload } from '@ggui-ai/protocol';
+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';

package/dist/render-item.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-import type { GguiSession } from '@ggui-ai/protocol';
+import type { AppTheme, GguiSession } from '@ggui-ai/protocol/wire';
 import type { GguiSessionSeedInput } from './types.js';
 import { type WireConfig } from '@ggui-ai/wire';
 import type { StreamBus } from './wire-config.js';
@@ -59,11 +59,7 @@ export interface RenderItemOptions {
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
-        readonly base?: {
-            readonly documentHash: string;
-            readonly light: Readonly<Record<string, string>>;
-            readonly dark: Readonly<Record<string, string>>;
-        };
+        readonly base?: NonNullable<AppTheme['base']>;
     };
     /**
      * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the

package/dist/runtime-telemetry.js

@@ -1,4 +1,4 @@
-import { RUNTIME_TELEMETRY_MAX_EVENTS } from '@ggui-ai/protocol';
+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;

package/dist/runtime.d.ts

@@ -25,7 +25,7 @@
  * wrapper, which routes it to the host's `onError` callback.
  */
 import './zod-jitless.js';
-import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol';
+import type { DrainAckPayload, JsonValue, JsonObject, GguiSession } from '@ggui-ai/protocol/wire';
 import type { WebSocketMessage } from '@ggui-ai/protocol/transport/websocket';
 import { type McpAppAiGguiRenderMeta, type McpAppBootstrapFailedMessage, type McpAppRendererReadyMessage } from '@ggui-ai/protocol/integrations/mcp-apps';
 import type { GguiSessionSeedInput } from './types.js';
@@ -56,6 +56,15 @@ import { type LifecycleEmitter } from './lifecycle.js';
  */
 type DrainAckListener = (payload: DrainAckPayload) => boolean | void;
 export declare function subscribeDrainAck(listener: DrainAckListener): () => void;
+/**
+ * The `drain_ack` ingress — fans a frame out to subscribers until one
+ * claims it.
+ *
+ * @internal — exported for unit tests: a late ack for an earlier
+ * delivered gesture is the path that retires the standing relay notice
+ * without any user click (ggui#670 Phase 3, truth-2).
+ */
+export declare function dispatchDrainAck(payload: DrainAckPayload): void;
 export type ConnectAppResult = {
     readonly ok: true;
 } | {
@@ -270,10 +279,12 @@ export interface BootSequenceOptions {
      * entirely (matches the ProtocolError posture; the `<McpAppIframe>`
      * host wrapper decides whether to bind this via its `onObserve`
      * prop). Exception: `relay-incapability` events do NOT flow through
-     * this seam — they originate in module-level gesture-dispatch code
-     * outside the boot graph (it runs independently of any given boot
-     * call) and always ride the postMessage-to-parent default, whether
-     * or not this option is bound.
+     * this seam — by rule they always ride the postMessage-to-parent
+     * default, whether or not this option is bound: most emission sites
+     * are module-level gesture-dispatch code that runs independently of
+     * any given boot call, and the one inside the boot graph (the
+     * `boot-failed` edge, ggui#830) follows the same rule so a host reads
+     * every edge the same way.
      */
     readonly onObserve?: ObservabilityEmitter;
     /**
@@ -660,6 +671,16 @@ interface ToastLiveRegions {
  * @internal — exported for unit tests.
  */
 export declare function ensureToastAnnouncer(doc: Document): ToastLiveRegions | null;
+/**
+ * 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
+ * the ONE writer — the host gets its `cleared` edge with the zone's
+ * summary — and the prior mount's standing notice is removed rather
+ * than left describing a session that no longer exists.
+ *
+ * @internal — exported for unit tests.
+ */
+export declare function resetRelayLatchForBoot(): void;
 /** @internal — exported for unit tests to reset module state. */
 export declare function __resetRelayNoticeForTest(): void;
 /**
@@ -685,19 +706,22 @@ export declare function dispatchSubmitAction(args: {
 /**
  * Channel-transport router's `tools/call` invoker (ggui#440) —
  * iframe-polling transport, `tools/call` against the parent MCP host
- * via `app.callServerTool` (spec-canonical) when the App handle is
- * set; falls back to raw postMessage pre-handshake or in tests.
+ * via `app.callServerTool` (spec-canonical); with no App bound the
+ * call answers a code-less error envelope — never a raw postMessage.
  * Direct call (no LLM consent loop). Returns the tool's
  * structuredContent (or `content[0]` if that's where the payload
  * landed) as a `JsonValue`. On RPC error we throw — the router
  * catches and silently retries on the next tick.
  *
- * Once a REAL gesture has confirmed this host can't relay (the latch
- * above — set only after {@link dispatchSubmitAction} actually tried
- * and failed on a host with no `serverTools` advertised, with
- * capabilities already captured, AND the failure was relay-shaped —
- * not a well-formed `{ok:false}` result; see `isRelayShapedFailure`),
- * every subsequent poll will fail identically.
+ * Once this document has confirmed it cannot relay (the latch above —
+ * set through the ONE writer on exactly three paths: a REAL gesture
+ * that failed relay-shaped on a host that never advertised
+ * `serverTools`, with capabilities already captured (`advert-silent`);
+ * a declared refusal code answered under a positive advertisement
+ * (`confirmed-refusal`); or the host's own failure of the mandatory
+ * `ui/initialize` handshake, before any gesture (`boot-failed`,
+ * ggui#830) — never a well-formed `{ok:false}` result; see
+ * `isRelayShapedFailure`), every subsequent poll will fail identically.
  *
  * This guard does NOT stop the router's poll loop, and nothing here
  * should ever be written so that it could (ggui#443). It does two
@@ -723,10 +747,13 @@ export declare function dispatchSubmitAction(args: {
  * (ggui's own embed host pre-Task-2 is exactly this case) — silently
  * killing working channel polls forever. That is "absence of a
  * capability blocks an attempt", which the fail-safe constraint
- * forbids. The latch implies `!hostCanRelayToolCalls()` (it only
- * ever sets inside that guard), so testing it alone is sufficient —
- * a host that never fails a real gesture never latches, and its
- * channels keep working.
+ * forbids. The latch is set only by a CONFIRMED OUTCOME — a failed
+ * real gesture (the advert-silent leg, or a confirmed refusal under a
+ * positive advertisement, ggui#599 cycle-2) or a failed handshake
+ * (ggui#830), never by an advertisement's absence — so testing the
+ * latch alone is sufficient: a host that answers its handshake and
+ * never fails a real gesture never latches, and its channels keep
+ * working.
  *
  * Extracted to a named export (rather than an inline closure inside
  * `bootProduction`) so unit tests can drive it directly through the