@ggui-ai/iframe-runtime 0.11.0 → 0.12.0

package/dist/mcp-app-iframe-host.js

@@ -77,8 +77,13 @@ export function mountMcpAppIframe(container, opts) {
     iframe.style.maxWidth = dims.maxWidth !== undefined ? `${dims.maxWidth}px` : '100%';
     if (dims.maxHeight !== undefined)
         iframe.style.maxHeight = `${dims.maxHeight}px`;
-    iframe.style.border = '1px solid #e5e5e5';
-    iframe.style.borderRadius = '8px';
+    // Round-6 doctrine (ggui#589 @6e15724a1, kit C1 grade): the helper
+    // paints CONTAINMENT ONLY — silhouette (border/radius) belongs to
+    // the embedding host's own chrome, tokens to the theme. The former
+    // 1px #e5e5e5 / radius-8 here was the same ungoverned-chrome class
+    // the RN helper shipped, surfaced by the host-helper catalog's
+    // first-party run (ggui#600 OPEN FINDING, closed here).
+    iframe.style.border = 'none';
     iframe.style.display = 'block';
     container.appendChild(iframe);
     // Cache contentWindow — on detach, `iframe.contentWindow` is null

package/dist/react-renderer.d.ts

@@ -81,6 +81,28 @@ export interface ReactRootMountOptions {
     readonly appTheme?: {
         readonly mode: 'light' | 'dark';
         readonly cssVariables: Record<string, string>;
+        /**
+         * The REGISTERED base ladder, delivered over the wire (ggui#598-C
+         * runtime theme registration — see protocol's `appThemeSchema`).
+         * BOTH modes' resolved variable sets ride the envelope; when
+         * present, the mode-selected set REPLACES the compiled ladder
+         * block (`getScopedThemeCss`/`getScopedCssTokens`) at the base
+         * position of the #573 precedence above — delivery changes WHERE
+         * the ladder's bytes come from, never WHICH layer wins. Mode
+         * selection reuses the mount's already-resolved `themeMode` (one
+         * projection — no second mode resolution here), and a mode switch
+         * re-paints from the retained other set with no network activity.
+         * Values are injection-safe by the wire schema — never
+         * re-validated here; serialization is key-sorted for byte-stable
+         * output. `documentHash` is the registration's identity (joins a
+         * 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>>;
+        };
     };
     /**
      * Host-announced palette, already translated onto `--ggui-*` tokens

package/dist/react-renderer.js

@@ -31,7 +31,7 @@
  */
 import React, { Component, createElement, Fragment, } from 'react';
 import { createRoot } from 'react-dom/client';
-import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
+import { stripMarkers, rewriteImports, getScopedThemeCss, getScopedCssTokens, assembleDeliveredThemeCss, getThemeCss, getCssTokens, } from '@ggui-ai/design/rendering';
 import { hoistImports, loadModule, loadModuleInline, probeUrlModuleLoad, } from '@ggui-ai/design/module-loader';
 /**
  * Document-lifetime verdict: URL-scheme module loading (`blob:` main
@@ -314,9 +314,25 @@ export async function mountReactRoot(container, opts) {
         }
     }
     function renderTree(opts) {
-        let themeCss = opts.themeId
-            ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
-            : getScopedCssTokens(scopeClass, opts.themeMode);
+        // Delivered base ladder (ggui#598-C): when the slice theme carries
+        // `base`, the mode-selected set REPLACES the compiled ladder block
+        // at the base position — same precedence slot, different byte
+        // source. Mode selection reuses the already-resolved `themeMode`
+        // (one projection; absent means light — the same default
+        // `getScopedThemeCss` applies). Both sets stay retained on the
+        // options, so a mode-switch re-render picks the other ladder from
+        // memory — never the network.
+        const deliveredBase = opts.appTheme?.base;
+        let themeCss = deliveredBase !== undefined
+            ? // Design-package assembler (ggui#598-C, injection-review flag 1):
+                // the delivered ladder gets the SAME scaffolding the compiled
+                // 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)
+            : opts.themeId
+                ? getScopedThemeCss(opts.themeId, scopeClass, opts.themeMode)
+                : getScopedCssTokens(scopeClass, opts.themeMode);
         if (opts.hostPalette) {
             // Host palette = the fallback layer (ggui#572, #573 ruling):
             // after the base scoped block so it can repaint at all (the base

package/dist/render-item.d.ts

@@ -51,10 +51,19 @@ export interface RenderItemOptions {
      * so the renderer injects the `--ggui-*` overrides + `color-scheme` at
      * `:root`. Sourced from the bootstrap's `_meta["ai.ggui/render"].theme`.
      * A structural subset of protocol's `AppTheme` (`name` is display-only).
+     * `base` is the delivered registered ladder (ggui#598-C) — forwarded
+     * verbatim; the renderer injects the mode-selected set in place of
+     * the compiled ladder block (see
+     * {@link ReactRootMountOptions.appTheme}).
      */
     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>>;
+        };
     };
     /**
      * Host-announced palette, pre-mapped onto `--ggui-*` tokens by the

package/dist/runtime.js

@@ -28,6 +28,7 @@
 // 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';
@@ -48,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';
@@ -213,7 +214,16 @@ export function hostAnnouncedThemeMode() {
  *   `buildOpts` inside `bootSequence`.
  */
 export function resolveMountThemeMode(meta) {
-    return meta.themeMode ?? meta.theme?.mode ?? hostAnnouncedThemeMode();
+    // 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):
@@ -235,7 +245,12 @@ export function resolveMountThemeMode(meta) {
  *   `buildOpts` inside `bootSequence`.
  */
 export function resolveMountThemeId(meta) {
-    return meta.themeId ?? meta.theme?.name;
+    // 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
@@ -1630,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.
@@ -1698,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);
@@ -1908,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',
@@ -3404,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

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.11.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/preview-a2ui": "0.11.0",
-    "@ggui-ai/live-channel": "0.11.0",
-    "@ggui-ai/gadgets": "0.11.0",
-    "@ggui-ai/design": "0.11.0",
-    "@ggui-ai/protocol": "0.11.0",
-    "@ggui-ai/wire": "0.11.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"