@ggui-ai/iframe-runtime 0.10.0 → 0.12.0

package/dist/runtime.js

@@ -28,10 +28,12 @@
 // schema-defining dependency initializes (see zod-jitless.ts).
 import './zod-jitless.js';
 import { MCP_APP_BOOTSTRAP_FAILED_TYPE, MCP_APP_RENDERER_READY_TYPE, parseMcpAppAiGguiRenderMeta, readGguiShellEnvelope, } from '@ggui-ai/protocol/integrations/mcp-apps';
+import { effectiveThemeId, effectiveThemeMode, } from '@ggui-ai/protocol/integrations/theme-binding';
 import { extractLocatorFromToolResult, parseMetaFromGlobal, parseMetaFromToolResult, validateMeta, } from './meta-parse.js';
 import { projectHostContext } from '@ggui-ai/protocol';
 import { App, PostMessageTransport } from '@modelcontextprotocol/ext-apps';
 import { applyHostContextStyling, attachListener as attachHostContextListener, seed as seedHostContext, } from './host-context-emitter.js';
+import { mapHostPaletteToGguiVars } from './host-palette-bridge.js';
 import { buildRootWireConfig, StreamBus, } from './wire-config.js';
 import { createChannelTransportRouter, } from './channel-transport.js';
 import { RelayIncapableError } from './relay-incapability.js';
@@ -47,7 +49,7 @@ import { loadCompiledValidatorsFromUrl } from './compiled-validators.js';
 import { mountRender, } from './render-item.js';
 import { fromBootstrapFailure, } from './protocol-error.js';
 import { postObservabilityToParent, } from './observability.js';
-import { mountUiFeedbackChrome } from './ui-feedback-chrome.js';
+import { ACTION_TOAST_Z_INDEX, mountUiFeedbackChrome } from './ui-feedback-chrome.js';
 import { hostCanReceiveMessages, hostCanRelayToolCalls, hostCapabilitiesCaptured, setHostCapabilities, } from './host-capabilities.js';
 import { makeLifecycleEvent, postLifecycleToParent, } from './lifecycle.js';
 import { contextSlotLastValues, createContextStateHost, installContextRegistry, reemitLastContextValues, } from './context-observer.js';
@@ -87,7 +89,7 @@ function dispatchDrainAck(payload) {
 // App-class plumbing (Phase 1.19b.3). The renderer used to roll its own
 // JSON-RPC pump (a closure-scoped `makeJsonRpcCaller` for the single
 // `ui/initialize` request + a module-level `ensurePostRpcToParentListener`
-// for `tools/call` and a `installPostMountListener` for inbound
+// for `tools/call` and a `installPersistentToolResultListener` for inbound
 // `ui/notifications/tool-result`). Every one of those was a hand-rolled
 // reimplementation of a primitive `@modelcontextprotocol/ext-apps`'s
 // `App` class already ships — drift across them produced the Reading-B
@@ -186,6 +188,94 @@ export function hostAnnouncedThemeMode() {
     const theme = currentApp?.getHostContext()?.theme;
     return theme === 'light' || theme === 'dark' ? theme : undefined;
 }
+/**
+ * Resolve the mount's base-stylesheet color mode from the slice, with
+ * the host as the final fallback (ggui#589, completing the ggui#551
+ * precedence ruling — "slice wins, host is the fallback, absent ≠
+ * light"):
+ *
+ *   stamped `themeMode`  >  `theme.mode` (the slice theme OBJECT)  >
+ *   host-announced theme  >  undefined
+ *
+ * The middle leg is the ggui#589 fix: a render envelope carrying a
+ * per-app theme (`theme: {mode, cssVariables}`) but no top-level
+ * `themeMode` is still a slice-stamped mode opinion — before this,
+ * the base token ladder ignored it and painted the LIGHT token set
+ * under a dark overlay whenever the host (correctly, per the
+ * adapter-boundary doctrine in the native host helpers) announced no
+ * `hostContext.theme`: a light skeleton in a dark skin. The theme
+ * object's own `mode` already drove `color-scheme`; now it also
+ * selects the ladder.
+ *
+ * `undefined` still means "no opinion anywhere" — the renderer's
+ * default applies; never coerced to `'light'`.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export function resolveMountThemeMode(meta) {
+    // The CLIENT projection of the protocol's normative theme-binding
+    // total order (@ggui-ai/protocol/integrations/theme-binding,
+    // ggui#598 leg 4) — the server stamps via the sibling projection and
+    // the protocol's composition-law test pins that the two compose
+    // without rank drift.
+    return effectiveThemeMode({
+        stamped: meta.themeMode,
+        sessionSidecar: meta.theme?.mode,
+        hostAnnounced: hostAnnouncedThemeMode(),
+    });
+}
+/**
+ * Resolve the mount's base-theme id from the slice (ggui#589 ask 3):
+ *
+ *   stamped `themeId`  >  `theme.name` (the slice theme OBJECT's name)
+ *   >  undefined (renderer default ladder)
+ *
+ * The name leg makes a slice theme whose `name` matches a REGISTERED
+ * theme id select that theme as the BASE token ladder — the overlay's
+ * cssVariables still apply above it, so the base carries the full
+ * brand ramp coverage a sparse overlay cannot (the "only the mapped
+ * vars carry brand" store-frame class). An unregistered name is
+ * harmless by construction: `getScopedThemeCss` falls back to the
+ * default theme, which is byte-identical to the no-themeId path
+ * (`getScopedCssTokens` ≡ `getScopedThemeCss(default)`), so a slice
+ * naming its theme "My Custom" renders exactly as before.
+ *
+ * @internal — exported for unit tests; production caller is
+ *   `buildOpts` inside `bootSequence`.
+ */
+export function resolveMountThemeId(meta) {
+    // Client projection of the normative theme-binding order — see
+    // resolveMountThemeMode above.
+    return effectiveThemeId({
+        stamped: meta.themeId,
+        sidecarName: meta.theme?.name,
+    });
+}
+/**
+ * The host's announced palette, read from the connected App's
+ * pre-merged hostContext and translated onto `--ggui-*` tokens by the
+ * host-palette bridge. `undefined` when no App is connected, the host
+ * sent no `styles.variables`, or nothing in it maps/survives
+ * sanitization — callers spread-skip the option, exactly like
+ * {@link hostAnnouncedThemeMode}.
+ *
+ * This is the palette input leg of host-theme adaptation (ggui#572,
+ * the color analog of #551's mode leg above): the spec `--color-*`
+ * variables land as inline custom properties on `<html>` via the
+ * canonical ext-apps helper, but nothing ggui renders consumes that
+ * vocabulary, and the scoped token block shadows root inheritance
+ * anyway — so without this mapping a host palette repaints nothing.
+ * `buildOpts` threads it onto the mount options; the renderer merges
+ * it as the fallback layer BENEATH the slice's own theme (ggui#573
+ * ruling: slice wins, host fallback).
+ *
+ * @internal — exported for unit tests (`setCurrentApp` injects the
+ *   App); production caller is `buildOpts` inside `bootSequence`.
+ */
+export function hostAnnouncedPalette() {
+    return mapHostPaletteToGguiVars(currentApp?.getHostContext()?.styles?.variables);
+}
 /**
  * @internal — exported for unit tests to reset module state between
  * scenarios.
@@ -314,6 +404,14 @@ export async function bootSequence(opts) {
     const toolResultPromise = opts.preResolvedMeta !== undefined
         ? Promise.resolve(null)
         : awaitToolResultMetaFromApp(app, toolResultTimeoutMs);
+    // Persistent re-mount listener — ALSO pre-connect (ggui#586). On a
+    // Tier-1/preResolved boot the one-shot listener above is skipped,
+    // which made the post-mount installation the FIRST toolresult
+    // registration — after the handshake, tripping the ext-apps timing
+    // notice and leaning on SDK replay for correctness. Registering here
+    // covers every boot path; arrivals before a renderer publishes
+    // `applyRender` no-op inside the listener.
+    installPersistentToolResultListener(app);
     const initResult = await connectApp(app, transport);
     if (!initResult.ok) {
         setStatus(refs, `ui/initialize failed: ${initResult.message}`, 'error');
@@ -1259,17 +1357,19 @@ function awaitToolResultMeta(timeoutMs) {
     });
 }
 /**
- * Module-level guard for the App-mediated post-mount toolresult
- * re-listener. Ensures exactly one persistent
- * `app.addEventListener('toolresult', …)` registration even across
- * re-mounts (e.g. an agent fires a second `ggui_render` and the
- * listener re-applies through the published `applyRender`).
+ * Per-App guard for the persistent toolresult re-listener. Ensures
+ * exactly one `app.addEventListener('toolresult', …)` registration per
+ * App instance even across re-mounts (e.g. an agent fires a second
+ * `ggui_render` and the listener re-applies through the published
+ * `applyRender`). Keyed by App — not a module boolean — so a fresh App
+ * (a re-booted document in tests; production is single-tenant per
+ * iframe) always gets its own registration, never a stale latch.
  */
-let postMountListenerInstalled = false;
+const persistentToolResultListenerApps = new WeakSet();
 /**
  * Module-level handle to the active renderer's `applyRender`, published
  * by `bootProduction`'s `setup()` once the renderer is built. The
- * module-level {@link installPostMountListener} resolves this to re-mount
+ * module-level {@link installPersistentToolResultListener} resolves this to re-mount
  * on a host-re-emitted tool-result WITHOUT a fresh boot — no second mount,
  * no second WS. This is the no-WS live-re-render channel for
  * spec-compliant MCP-Apps hosts (claude.ai / ChatGPT / Claude Desktop)
@@ -1281,8 +1381,8 @@ let postMountListenerInstalled = false;
 let activeApplyRender = null;
 /**
  * Module-level guard for {@link installAnchorClickInterceptor}. Same
- * rationale as {@link postMountListenerInstalled}: re-mounts are
- * triggered by `installPostMountListener`, and stacking capture-phase
+ * rationale as {@link persistentToolResultListenerApps}: re-mounts are
+ * triggered by `installPersistentToolResultListener`, and stacking capture-phase
  * click listeners across re-mounts would multiply the audit envelopes
  * that fire on a single click.
  */
@@ -1545,9 +1645,11 @@ export function emitAudit(args) {
  * Returns `'success'` when the handler said `ok:true`. Returns
  * `'fallback'` for any other outcome — pipe missing
  * (`PIPE_NOT_FOUND`), envelope rejected (`INVALID_ACTION_KIND`),
- * relay error, no host relay wired, or any unexpected shape. The
- * iframe-runtime then falls through to `ui/message` so the gesture
- * still reaches the agent on its next turn.
+ * relay error, no host relay wired, or any unexpected shape. On
+ * `'fallback'` the gesture was NOT enqueued and is dropped with local
+ * feedback only (toast / #440 latch) — no `ui/message` fires (the
+ * doorbell is success-path-only: there is nothing to point it at), and
+ * no alternate transport is attempted today (ggui#599's open leg).
  */
 /**
  * Unwrap the payload record of a relayed submit-action tool result.
@@ -1613,6 +1715,16 @@ function isRelayShapedFailure(resp) {
  * consumer" — the doorbell rings. Shares {@link submitActionPayload}
  * with {@link classifySubmitActionResponse} so both reads agree on
  * which envelope tier carries the payload.
+ *
+ * RELAY CONTRACT (ggui#603): this read only works when the host's
+ * `tools/call` relay threads the server's tool result VERBATIM — the
+ * `consumerPresent` marker rides `structuredContent` on the real
+ * result. A relay that wraps or synthesizes the response silently
+ * strips the marker, and every healthy gesture then misclassifies as
+ * "agent not listening" (a persistent `action_required` toast per
+ * gesture). Verbatim threading is the same obligation that keeps
+ * `_meta` alive on `resources/read` relays; a conformance vector for
+ * it is tracked on ggui#603.
  */
 function extractConsumerPresent(resp) {
     const inner = submitActionPayload(resp);
@@ -1823,7 +1935,7 @@ function showActionToast(text, kind, onDismiss) {
             'bottom:16px',
             'left:50%',
             'transform:translateX(-50%)',
-            'z-index:2147483647',
+            `z-index:${ACTION_TOAST_Z_INDEX}`,
             'pointer-events:auto',
             'max-width:90%',
             'padding:8px 14px',
@@ -2813,7 +2925,7 @@ export function requestDisplayModeInParent(args) {
  * or honor an upstream `defaultPrevented` from a higher-priority
  * handler.
  *
- * Idempotent: re-mounts (via `installPostMountListener`) call this
+ * Idempotent: re-mounts (via `installPersistentToolResultListener`) call this
  * helper again; the {@link anchorClickInterceptInstalled} guard makes
  * subsequent calls a no-op.
  */
@@ -2954,15 +3066,26 @@ export function __resetInterceptorsForTest() {
     fullscreenInterceptInstalled = false;
 }
 /**
- * Install a persistent `app.addEventListener('toolresult', …)` listener
- * that catches `ui/notifications/tool-result` notifications arriving
- * AFTER the initial mount. Each new tool-result that carries a
- * different bootstrap (different sessionId / codeUrl / kind) triggers
- * a re-mount through the published `applyRender`. This closes the boot-only-
+ * Install the persistent `app.addEventListener('toolresult', …)`
+ * listener that catches `ui/notifications/tool-result` notifications
+ * arriving at ANY point in the document's life. Each tool-result that
+ * carries a different bootstrap (different sessionId / codeUrl / kind)
+ * triggers a re-mount through the published `applyRender`; arrivals
+ * before a renderer publishes `applyRender` no-op safely (and do NOT
+ * latch the dedupe key — see below). This closes the boot-only-
  * listener gap that prevented live re-render when an agent issued
  * a second `ggui_render` to the same render-resource.
  *
- * Idempotent: subsequent calls no-op via {@link postMountListenerInstalled}.
+ * REGISTRATION TIMING (ggui#586): called by `bootSequence` BEFORE
+ * `app.connect(transport)` — on a Tier-1/preResolved boot the one-shot
+ * Tier-2 listener never registers, so this used to be the FIRST
+ * `toolresult` registration and landed post-handshake (the ext-apps
+ * `_assertHandlerTiming` notice a guuey production render surfaced).
+ * The SDK's replay made that harmless; pre-registering removes the
+ * dependence on replay entirely.
+ *
+ * Idempotent per App: repeat calls with the same App no-op via
+ * {@link persistentToolResultListenerApps}.
  *
  * Why module-level vs scoped to a single mount: re-mounts re-apply
  * through `applyRender` while the listener stays live, and the
@@ -2972,17 +3095,13 @@ export function __resetInterceptorsForTest() {
  * Spec-canonical (post-Phase-1.19b.3): the previous hand-rolled
  * `window.addEventListener('message', …)` is gone; App handles every
  * inbound `ui/notifications/tool-result` envelope and dispatches via
- * its event system. Per-iframe single-tenancy means the App handle
- * comes from `getCurrentApp()` — set by `bootSequence`'s connect
- * path before this helper runs.
+ * its event system. The App handle is passed by the boot path
+ * directly (pre-connect, so `getCurrentApp()` is not yet set).
  */
-function installPostMountListener() {
-    if (postMountListenerInstalled)
+function installPersistentToolResultListener(app) {
+    if (persistentToolResultListenerApps.has(app))
         return;
-    const app = getCurrentApp();
-    if (app === null)
-        return; // pre-connect; caller bug, swallow safely
-    postMountListenerInstalled = true;
+    persistentToolResultListenerApps.add(app);
     let lastMetaKey = null;
     app.addEventListener('toolresult', (params) => {
         const meta = extractMetaFromToolResult(params);
@@ -3020,15 +3139,21 @@ function installPostMountListener() {
         ].join('|');
         if (key === lastMetaKey)
             return;
-        lastMetaKey = key;
         // Re-mount through the EXISTING renderer's `applyRender` (published
         // module-level by bootProduction's setup) — NOT a fresh boot. One
         // mount surface, one WS; the prior stale-closure / second-WS race
         // (the #290 root cause) is structurally impossible. Project the new
         // tool-result meta into a seed and re-apply it.
+        //
+        // The apply-null check runs BEFORE the dedupe key latches (ggui#586
+        // ordering): now that this listener registers pre-connect, the
+        // BOOT-path tool-result also flows through here while no renderer
+        // is published yet — latching its key then would silently dedupe a
+        // legitimate post-mount re-broadcast of the same envelope.
         const apply = activeApplyRender;
         if (apply === null)
             return; // no renderer published yet — no-op safely
+        lastMetaKey = key;
         void buildGguiSessionSeedInput(meta).then((seed) => {
             if (seed === null)
                 return;
@@ -3306,20 +3431,30 @@ async function bootProduction(opts) {
                     }
                 },
             };
-            // Spec-canonical outbound dispatch. The WS pipe is for streamSpec
-            // subscriptions ONLY (inbound `ggui_emit` fanout + `props_update` +
-            // `render` + `data` + `drain_ack` + `channel_payload`).
-            // Outbound user actions go through the MCP-Apps host relay per
-            // spec §401: postMessage `tools/call:ggui_runtime_submit_action`
-            // to the parent → `AppRenderer.onCallTool` → sample agent's
-            // `/relay/tools-call` → ggui MCP server →
-            // `createGguiSubmitActionHandler.append` → `pendingEventConsumer`
-            // → `ggui_consume` wakes the agent. The server's WS
-            // `handleInboundAction` writes to the render ledger only — no
-            // downstream consumer — so the WS action path silently drops
-            // clicks. `routeDispatch` is the shared named-export helper
-            // (production + tests exercise the same code path); threading it
-            // here keeps LIVE-mode on the canonical dispatch pipeline.
+            // Spec-canonical outbound dispatch: user actions go through the
+            // MCP-Apps host relay (SPEC §4.7): postMessage
+            // `tools/call:ggui_runtime_submit_action` to the parent →
+            // `AppRenderer.onCallTool` → host's MCP client → ggui MCP server
+            // → `createGguiSubmitActionHandler.append` → `pendingEventConsumer`
+            // → `ggui_consume` wakes the agent. NOTE (truth, ggui#596 +
+            // adversarial-cycle correction): the server's WS ingress
+            // dual-writes accepted `data:submit` frames onto the consume pipe
+            // ONLY when the live channel is composed with a
+            // `pendingEventConsumer` — which `createGguiServer` threads for
+            // DEFAULT-handlers compositions only (a custom `handlers` list
+            // drains its own pipe; bridging the channel onto an instance
+            // nobody drains would buffer gestures into the void — see the
+            // hoist note in server.ts). The hosted pod IS a custom-handlers
+            // caller: on it, a WS gesture lands on the retained ledger only
+            // and never reaches the agent. Any WS action fallback (ggui#599's
+            // open design leg) therefore requires the server/pod bridge
+            // FIRST — it is a capability gap on that composition today. The WS pipe otherwise carries
+            // streamSpec subscriptions (inbound `ggui_emit` fanout +
+            // `props_update` + `render` + `data` + `drain_ack` +
+            // `channel_payload`). `routeDispatch` is the shared named-export
+            // helper (production + tests exercise the same code path);
+            // threading it here keeps LIVE-mode on the canonical dispatch
+            // pipeline.
             // Single mounted render — populated by `applyRender` on the first
             // render frame. The wire config + data channel handler read it
             // through `currentRender`-returning thunks so they always see the
@@ -3461,13 +3596,21 @@ async function bootProduction(opts) {
                         !('createdAt' in render)
                         ? { codeModuleUrl: meta.codeModuleUrl }
                         : {}),
-                    ...(meta.themeId !== undefined ? { themeId: meta.themeId } : {}),
-                    // Mode: the slice's stamped `themeMode` (every operator layer
-                    // resolves into it) wins; when absent, the HOST's announced
-                    // theme fills the gap (ggui#551 — see `hostAnnouncedThemeMode`).
-                    // Absent-in-slice means "no operator opinion", not "light".
+                    // Base-theme ladder (ggui#589 ask 3 — see `resolveMountThemeId`):
+                    // stamped themeId > the slice theme object's NAME (a
+                    // registered name binds the full brand base; unregistered
+                    // names fall back to the default ladder, byte-identical to
+                    // the no-themeId path).
                     ...(() => {
-                        const themeMode = meta.themeMode ?? hostAnnouncedThemeMode();
+                        const themeId = resolveMountThemeId(meta);
+                        return themeId !== undefined ? { themeId } : {};
+                    })(),
+                    // Mode ladder (ggui#551 + #589 — see `resolveMountThemeMode`):
+                    // stamped `themeMode` > the slice theme OBJECT's `mode` >
+                    // host-announced theme. Absent everywhere means "no opinion",
+                    // not "light".
+                    ...(() => {
+                        const themeMode = resolveMountThemeMode(meta);
                         return themeMode !== undefined ? { themeMode } : {};
                     })(),
                     // Per-app theme overlay (St3 M2.2). Threaded straight from the
@@ -3477,6 +3620,15 @@ async function bootProduction(opts) {
                     // `color-scheme` at `:root`. THEME IS COMPONENT-ONLY — system
                     // cards theme via the SystemCardHost/ThemeProvider path.
                     ...(meta.theme !== undefined ? { appTheme: meta.theme } : {}),
+                    // Host palette: always threaded when the host announced one —
+                    // unlike mode there is no either/or gate here, because the
+                    // precedence is CSS document order inside the scoped block
+                    // (base < hostPalette < appTheme, ggui#572/#573: slice wins,
+                    // host fallback), not a value-level ?? fallback.
+                    ...(() => {
+                        const hostPalette = hostAnnouncedPalette();
+                        return hostPalette !== undefined ? { hostPalette } : {};
+                    })(),
                     ...(wrapOuter !== undefined ? { wrapOuter } : {}),
                 };
             };
@@ -3500,17 +3652,17 @@ async function bootProduction(opts) {
                 }
                 await renderHandle.update(buildOpts(render));
             };
-            // Publish `applyRender` module-level + install the persistent
-            // post-mount tool-result listener. On a host-re-emitted tool-result
-            // (claude.ai re-broadcast; the Anthropic-SDK-strips-_meta refetch),
-            // the listener re-mounts through THIS `applyRender` — no fresh boot,
-            // no second WS. The no-WS live-re-render channel; for WS hosts the
-            // render-frame handler already covers re-render, so it's a
-            // redundant-safe fallback (guarded by the sessionId pin + liveTrio
-            // dedupe). Runs only on the production renderer path (tests that
-            // drive bootSequence without a renderer never reach setup()).
+            // Publish `applyRender` module-level. The persistent tool-result
+            // listener is ALREADY registered — `bootSequence` installs it
+            // pre-connect (ggui#586) — and reads this slot dynamically, so
+            // publishing here is what arms it. On a host-re-emitted
+            // tool-result (claude.ai re-broadcast; the
+            // Anthropic-SDK-strips-_meta refetch), the listener re-mounts
+            // through THIS `applyRender` — no fresh boot, no second WS. The
+            // no-WS live-re-render channel; for WS hosts the render-frame
+            // handler already covers re-render, so it's a redundant-safe
+            // fallback (guarded by the sessionId pin + liveTrio dedupe).
             activeApplyRender = applyRender;
-            installPostMountListener();
             // Validator context — A2UI default for `_ggui:preview`; no
             // bootstrap-supplied overrides today (the
             // `extraReservedValidators` injection slot is reserved for a

package/dist/ui-feedback-chrome.d.ts

@@ -1,4 +1,20 @@
 import type { ObservabilityEmitter } from './observability.js';
+/**
+ * Stacking contract between the two body-appended runtime layers
+ * (ggui#603): the feedback chrome must sit strictly ABOVE the action
+ * toast. The persistent `action_required` toast parks
+ * `pointer-events:auto` at fixed bottom-center — the same region this
+ * chrome occupies — and is re-armed per gesture; without this order an
+ * armed toast eats every tap aimed at the feedback controls. The toast
+ * remains dismissable on its own uncovered area (it accepts the click
+ * anywhere on itself), so partial occlusion costs it nothing.
+ *
+ * Single source: `runtime.ts`'s toast reads {@link ACTION_TOAST_Z_INDEX};
+ * this module applies {@link UI_FEEDBACK_CHROME_Z_INDEX} to the chrome
+ * container. The test suite pins the relationship, not the numbers.
+ */
+export declare const UI_FEEDBACK_CHROME_Z_INDEX = 2147483647;
+export declare const ACTION_TOAST_Z_INDEX = 2147483646;
 export interface UiFeedbackChromeOptions {
     /**
      * Observability sink the card emits `ui-feedback` events into.

package/dist/ui-feedback-chrome.js

@@ -36,6 +36,22 @@
  * gate passes.
  */
 import { createElement } from 'react';
+/**
+ * Stacking contract between the two body-appended runtime layers
+ * (ggui#603): the feedback chrome must sit strictly ABOVE the action
+ * toast. The persistent `action_required` toast parks
+ * `pointer-events:auto` at fixed bottom-center — the same region this
+ * chrome occupies — and is re-armed per gesture; without this order an
+ * armed toast eats every tap aimed at the feedback controls. The toast
+ * remains dismissable on its own uncovered area (it accepts the click
+ * anywhere on itself), so partial occlusion costs it nothing.
+ *
+ * Single source: `runtime.ts`'s toast reads {@link ACTION_TOAST_Z_INDEX};
+ * this module applies {@link UI_FEEDBACK_CHROME_Z_INDEX} to the chrome
+ * container. The test suite pins the relationship, not the numbers.
+ */
+export const UI_FEEDBACK_CHROME_Z_INDEX = 2147483647;
+export const ACTION_TOAST_Z_INDEX = 2147483646;
 /**
  * Mount the in-iframe UI-feedback affordance, or do nothing.
  *
@@ -69,6 +85,10 @@ export async function mountUiFeedbackChrome(doc, opts) {
     doc.querySelector('[data-ggui-ui-feedback-chrome]')?.remove();
     const container = doc.createElement('div');
     container.setAttribute('data-ggui-ui-feedback-chrome', '');
+    // Win the stacking race against the action toast (ggui#603 — see
+    // the constants' docblock above).
+    container.style.position = 'relative';
+    container.style.zIndex = String(UI_FEEDBACK_CHROME_Z_INDEX);
     doc.body.appendChild(container);
     const root = reactDomClient.createRoot(container);
     root.render(createElement(cardMod.UiFeedbackCard, {

package/dist/wire-config.d.ts

@@ -95,9 +95,13 @@ export interface BuildRootWireConfigOptions {
      *
      * The default WS-frame send reaches the agent only on servers whose
      * live channel bridges WS `data:submit` actions onto the same
-     * pending-events pipe (first-party `createGguiServer` does — see
-     * `GguiSessionChannelOptions.pendingEventConsumer`); it remains the
-     * seam tests and direct-WS callers exercise.
+     * pending-events pipe. First-party `createGguiServer` bridges it
+     * ONLY when composed with DEFAULT handlers (`opts.handlers`
+     * undefined); a custom `handlers` list drains its own pipe, so the
+     * channel deliberately does not bridge — the hosted pod is such a
+     * caller, and on it a WS gesture lands on the retained ledger only.
+     * See `GguiSessionChannelOptions.pendingEventConsumer`. The default
+     * send remains the seam tests and direct-WS callers exercise.
      *
      * Called AFTER outbound validation passes. Receives the validated
      * {@link ActionEnvelope}; caller extracts payload.action +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/iframe-runtime",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "The iframe-local ggui runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the ggui design system so generated component code has a single seam to read from.",
   "keywords": [
     "ggui",
@@ -36,12 +36,12 @@
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "zod": "^4.3.6",
-    "@ggui-ai/design": "0.10.0",
-    "@ggui-ai/gadgets": "0.10.0",
-    "@ggui-ai/live-channel": "0.10.0",
-    "@ggui-ai/protocol": "0.10.0",
-    "@ggui-ai/preview-a2ui": "0.10.0",
-    "@ggui-ai/wire": "0.10.0"
+    "@ggui-ai/design": "0.12.0",
+    "@ggui-ai/live-channel": "0.12.0",
+    "@ggui-ai/gadgets": "0.12.0",
+    "@ggui-ai/preview-a2ui": "0.12.0",
+    "@ggui-ai/protocol": "0.12.0",
+    "@ggui-ai/wire": "0.12.0"
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0"